Instalacja aplikacji CasaOS nie powiodła się: logi, DNS i porty

Eva Wong jest redaktorką techniczną i rezydentką majsterkowania w ZimaSpace. Jest geekiem od zawsze, z pasją do domowych laboratoriów i oprogramowania open source, a jej specjalnością jest przekładanie złożonych zagadnień technicznych na przystępne, praktyczne poradniki. Eva wierzy, że samodzielne hostowanie powinno sprawiać radość, a nie onieśmielać. Dzięki swoim samouczkom pomaga społeczności oswoić konfigurację sprzętu, od budowy pierwszego serwera NAS po opanowanie kontenerów Docker.

Błąd instalacji aplikacji w CasaOS zwykle objawia się jednym prostym komunikatem w interfejsie: sklep z aplikacjami się nie ładuje, przycisk instalacji aplikacji nie działa albo kontener pojawia się, ale nie otwiera. Rzeczywista przyczyna zwykle leży głębiej niż interfejs CasaOS. CasaOS zaprojektowano z myślą o instalowaniu aplikacji jednym kliknięciem i wdrażaniu aplikacji Docker, więc przyczyną nieudanej instalacji może być warstwa usług CasaOS, pobieranie obrazu Dockera, rozwiązywanie nazw DNS, czas systemowy, architektura procesora lub konflikt portów na hoście.

Najbezpieczniej jest nie instalować ponownie CasaOS w pierwszej kolejności. Zacznij od odczytania rzeczywistego błędu, a następnie sprawdzaj kolejne warstwy pojedynczo: logi, sieć i DNS, synchronizację czasu, architekturę procesora, porty oraz zgodność z Dockerem.

W skrócie: komunikat błędu CasaOS to tylko pierwszy objaw

Ogólny komunikat „nie udało się zainstalować” informuje, że CasaOS nie mogło ukończyć wdrożenia, ale nie wskazuje, która warstwa zawiodła. Katalog aplikacji mógł się nie załadować, Docker mógł nie pobrać obrazu, obraz może być niezgodny z architekturą procesora, port na hoście może być już zajęty albo kontener mógł się uruchomić, a następnie ulec awarii.

Instalacja aplikacji w CasaOS zależy zarówno od warstwy usług CasaOS, jak i środowiska Docker. Pobieranie obrazów Dockera może też zależeć od dostępu do rejestru, ustawień serwera proxy, niskiej przepustowości łącza i przekroczenia limitu czasu pobierania warstw.

Postępuj w tej kolejności:

# 1. Odczytaj logi usług CasaOS
journalctl -xeu casaos-app-management --no-pager
journalctl -u casaos -f

# 2. Sprawdź kontenery Dockera
docker ps -a

# 3. Odczytaj logi kontenera, który nie uruchomił się poprawnie
docker logs --tail 100 <container_name_or_id>

# 4. Sprawdź DNS i dostęp do rejestru
getent hosts github.com
getent hosts registry-1.docker.io

# 5. Sprawdź czas systemowy
timedatectl

# 6. Sprawdź architekturę procesora
uname -m

# 7. Sprawdź nasłuchujące porty
sudo ss -tulpn | grep LISTEN

Zacznij od logów, zanim zmienisz ustawienia

Logi to najszybszy sposób, by ustalić, czy problem dotyczy CasaOS, Dockera, sieci, obrazu czy aplikacji. Polecenie systemu Linux journalctl wyświetla wpisy z dziennika systemd, a jego opcja -u filtruje logi dla konkretnej jednostki usługi.

W CasaOS zacznij od logów usług:

journalctl -xeu casaos-app-management --no-pager
journalctl -u casaos -f

Następnie sprawdź Dockera. Polecenie Dockera docker logs pobiera logi kontenera, a opcja --follow pozwala śledzić nowe wpisy, gdy kontener jest uruchomiony.

docker ps -a
docker logs --tail 100 <container_name_or_id>
docker logs -f <container_name_or_id>

Czego szukasz:

Wskazówka w logach Prawdopodobna przyczyna
no such host / błąd wyszukiwania DNS DNS lub rozwiązywanie nazw w sieci
przekroczono limit czasu połączenia Sieć, serwer proxy, zapora sieciowa, dostęp do rejestru lub niska przepustowość
Błąd certificate / TLS / x509 Czas systemowy, certyfikaty CA lub przechwytywanie połączeń HTTPS
błąd formatu pliku wykonywalnego Nieprawidłowa architektura procesora dla obrazu
port is already allocated / bind: address already in use Konflikt portu na hoście
minimalna obsługiwana wersja API Niezgodność API klienta Docker i demona Docker
Kontener natychmiast się zamyka Konfiguracja aplikacji, uprawnienia do woluminu, brakująca zmienna środowiskowa lub problem z obrazem

Zasada jest prosta: nie naprawiaj pięciu rzeczy naraz. Skopiuj pierwszy jednoznaczny wiersz błędu, a następnie przetestuj wskazaną warstwę.

Sprawdź DNS i dostęp do sieci

Jeśli App Store się nie ładuje lub instalacja kończy się niepowodzeniem podczas pobierania obrazu, przed zmianą ustawień CasaOS sprawdź DNS i dostęp do sieci zewnętrznej. Docker pobiera obrazy z rejestrów takich jak Docker Hub. Jeśli host CasaOS nie potrafi rozpoznać domen rejestru, pobieranie obrazów może się nie powieść, zanim kontener zostanie utworzony.

Zamiast używać wyłącznie ping, sprawdź rozpoznawanie nazw:

getent hosts github.com
getent hosts registry-1.docker.io
getent hosts hub.docker.com

Polecenie getent odpytuje bazy danych skonfigurowane za pośrednictwem Name Service Switch, w tym bazę hosts używaną do wyszukiwania nazw hostów. Jeśli te polecenia nic nie zwrócą, CasaOS może nie mieć dostępu do GitHub, Docker Hub ani niestandardowego katalogu aplikacji, nawet jeśli lokalny panel nadal się otwiera.

Następnie sprawdź konfigurację resolvera:

cat /etc/resolv.conf

W systemie Linux plik /etc/resolv.conf zawiera konfigurację resolvera używanego do obsługi DNS, a wpisy nameserver określają serwery DNS, z których ma korzystać resolver. Jeśli DNS nie działa prawidłowo, tymczasowa zmiana na stabilne publiczne resolvery może potwierdzić, czy to właśnie jest przyczyną problemu:

sudo nano /etc/resolv.conf

Przykład tymczasowego testu:

nameserver 1.1.1.1
nameserver 8.8.8.8

Nie poprzestawaj na stwierdzeniu „internet działa na moim laptopie”. CasaOS działa na serwerze, więc liczy się ścieżka DNS serwera.

Sprawdź czas systemowy, zanim obwinisz sklep z aplikacjami

Nieprawidłowy czas systemowy może powodować problemy z HTTPS i weryfikacją certyfikatów, które wyglądają na błędy sklepu z aplikacjami lub rejestru. Zanim zmienisz konfigurację Dockera lub CasaOS, sprawdź, czy zegar serwera pokazuje prawidłowy czas i czy synchronizacja czasu jest aktywna.

timedatectl

W wynikach poszukaj wierszy takich jak:

Zegar systemowy zsynchronizowany: tak
Usługa NTP: aktywna

Jeśli synchronizacja jest wyłączona, włącz ją:

sudo timedatectl set-ntp true

Po włączeniu tej funkcji odczekaj chwilę i ponownie uruchom timedatectl, zanim ponowisz instalację aplikacji CasaOS.

Sprawdź, czy architektura procesora odpowiada obrazowi aplikacji

CasaOS może działać na wielu platformach sprzętowych, w tym na urządzeniach x86-64 i ARM. Nie oznacza to jednak, że każda aplikacja Docker z każdego katalogu obsługuje każdą architekturę. Raspberry Pi, Orange Pi, minikomputer z ARM lub przerobiony box z Androidem mogą nie uruchomić obrazu utworzonego wyłącznie dla linux/amd64.

Sprawdź architekturę hosta:

uname -m
Wynik uname -m Typowe znaczenie
x86_64 AMD64 / x86-64
aarch64 ARM64
armv7l 32-bitowy ARM
i386 / i686 32-bitowy x86

Kod kontenera musi być zgodny z architekturą hosta, ponieważ kontenery współdzielą jądro hosta. Bez emulacji nie można uruchomić kontenera linux/amd64 na hoście arm64. Obrazy wieloplatformowe rozwiązują ten problem, udostępniając warianty takie jak linux/amd64 i linux/arm64 w ramach jednego obrazu.

Jeśli w dziennikach widnieje exec format error, sprawdź na stronie obrazu lub w manifeście rejestru, czy obraz obsługuje ARM. Jeśli obraz nie obsługuje Twojej platformy, zmiana ustawień CasaOS tego nie naprawi. Potrzebujesz obrazu wieloarchitekturowego, innego tagu lub innej aplikacji.

Sprawdź, czy nie ma konfliktów portów, zanim ponownie zainstalujesz aplikację

Instalacja niektórych aplikacji CasaOS kończy się powodzeniem, ale aplikacja nadal się nie otwiera. W wielu przypadkach kontener został uruchomiony, ale port hosta był już zajęty lub został nieprawidłowo zmapowany.

Sprawdź aktywne porty nasłuchujące:

sudo ss -tulpn | grep LISTEN

Następnie porównaj wynik z ustawieniami portów aplikacji. Docker Compose definiuje ports jako mapowania między maszyną hosta a kontenerami, które umożliwiają dostęp z zewnątrz do usług działających wewnątrz kontenerów.

Typowe mapowanie wygląda tak:

ports:
  - "8080:80"
Element Znaczenie
8080 Port hosta: port odwiedzany w przeglądarce
80 Port kontenera: port, na którym aplikacja nasłuchuje wewnątrz kontenera

Jeśli inna usługa korzysta już z portu hosta 80, nie zmieniaj najpierw portu kontenera. Zmień port hosta na wolną wartość:

ports:
  - "8080:80"

Jest to szczególnie ważne w przypadku aplikacji takich jak odwrotne proxy, blokery reklam, panele kontrolne i serwery WWW, ponieważ często domyślnie używają portów 80, 443, 8080 lub 3000.

Praktyczna lista kontrolna dotycząca awarii aplikacji CasaOS

Skorzystaj z tej listy kontrolnej, zanim ponownie zainstalujesz CasaOS lub usuniesz kontenery.

Sprawdzenie Polecenie Dobry znak Zły znak
Dzienniki usługi CasaOS journalctl -xeu casaos-app-management --no-pager Proces instalacji przebiega prawidłowo lub wyświetla konkretny błąd Powtarzające się awarie usługi lub błąd API Dockera
Dzienniki CasaOS na żywo journalctl -u casaos -f Działania w interfejsie są widoczne w dziennikach Działanie w aplikacji kończy się niepowodzeniem bez komunikatu lub w pętli
Lista kontenerów Dockera docker ps -a Kontener został utworzony, a jego stan jest widoczny Brak kontenera lub jego ciągłe ponowne uruchamianie
Dzienniki kontenera docker logs --tail 100 <container> Aplikacja uruchamia się normalnie Błąd uruchomienia, uprawnień, konfiguracji lub architektury
Wyszukiwanie DNS getent hosts registry-1.docker.io Zwrócone adresy IP Brak wyników lub błąd wyszukiwania
Pobieranie obrazu docker pull <image>:<tag> Obrazy zostały pobrane Limit czasu, TLS, uwierzytelnianie lub brak zgodnego manifestu
Czas systemowy timedatectl Zegar jest zsynchronizowany, NTP jest aktywny Rozbieżność czasu lub nieaktywny NTP
Architektura uname -m Platforma obrazu jest zgodna Host ARM z obrazem przeznaczonym wyłącznie dla amd64
Porty sudo ss -tulpn | grep LISTEN Port hosta jest wolny Port jest już zajęty

Typowe wzorce awarii i ich najczęstsze przyczyny

Sklep z aplikacjami się nie ładuje

Jeśli sam Sklep z aplikacjami się nie ładuje, zacznij od sprawdzenia DNS i dostępu do sieci. Podczas normalnego korzystania z aplikacji CasaOS korzysta z zewnętrznych katalogów i źródeł obrazów, więc serwer musi móc odnaleźć te źródła i nawiązać z nimi połączenie.

Sprawdź:

getent hosts github.com
getent hosts registry-1.docker.io
timedatectl
journalctl -u casaos -f

Jeśli DNS nie działa, napraw konfigurację resolvera serwera. Jeśli DNS działa, ale pobieranie obrazów przez Dockera nie, sprawdź dostęp do rejestru oraz działanie serwera proxy lub zapory.

Instalacja aplikacji nie powiodła się podczas pobierania obrazu

Jeśli instalacja nie powiedzie się podczas pobierania obrazu, skopiuj dokładny komunikat błędu Dockera. Przetestuj ręcznie:

docker pull <image>:<tag>

Jeśli ręczne pobieranie kończy się błędem DNS lub przekroczeniem limitu czasu, problem nie dotyczy interfejsu CasaOS. Jeśli pojawia się błąd architektury lub brak pasującego manifestu, sprawdź platformę obrazu.

Aplikacja instaluje się, ale nie można jej otworzyć

Jeśli wygląda na to, że aplikacja jest zainstalowana, ale nie można jej otworzyć w przeglądarce, najpierw sprawdź porty. Nieprawidłowy lub zajęty port hosta może sprawiać wrażenie, że działający kontener nie działa.

Sprawdź:

docker ps
sudo ss -tulpn | grep LISTEN

Następnie sprawdź, czy aplikacja jest przypisana do portu hosta, pod którym próbujesz ją otworzyć.

Aplikacja uruchamia się i natychmiast zatrzymuje

Jeśli kontener istnieje, ale się zatrzymuje, sprawdź jego logi:

docker logs --tail 100 <container>

Sprawdź, czy nie brakuje zmiennych środowiskowych, czy ścieżki woluminów są prawidłowe oraz czy występują błędy bazy danych, uprawnień lub exec format error.

Logi wskazują błędy wersji API Dockera

Jeśli logi wskazują na niezgodność wersji API Dockera, nie zgaduj. Najpierw uruchom:

docker version

Problemy ze zgodnością wersji API Dockera należy traktować jako zaawansowany przypadek diagnostyczny. Nadpisanie ustawień API rozważaj tylko wtedy, gdy logi wyraźnie wskazują na niezgodność wersji API. Nie dodawaj nadpisania systemd tylko dlatego, że aplikacja raz się nie uruchomiła.

Problemy z Dockerem i uprawnieniami w aplikacjach CasaOS

Niektóre aplikacje zawodzą, ponieważ kontener został utworzony, ale nie ma oczekiwanego dostępu do woluminu, urządzenia lub ścieżki sieciowej. Często zdarza się tak, gdy użytkownicy instalują niestandardowe szablony, przenoszą dane aplikacji, montują dyski zewnętrzne lub ręcznie zmieniają foldery na hoście.

Sprawdź przypisane ścieżki i logi aplikacji:

docker inspect <container_name_or_id>
docker logs --tail 100 <container_name_or_id>

Sprawdź, czy występują:

  • brak folderu na hoście;
  • odmowa dostępu;
  • system plików tylko do odczytu;
  • nie można zainicjować bazy danych;
  • nie znaleziono pliku konfiguracyjnego;
  • brak ścieżki urządzenia;
  • użytkownik kontenera nie może zapisywać w zamontowanym woluminie.

Jeśli błąd wskazuje na problem z woluminem lub uprawnieniami, najpierw popraw ścieżkę lub uprawnienia. Ponowna instalacja aplikacji bez zmiany nieprawidłowej ścieżki zwykle powoduje ten sam błąd.

Błędy utrudniające diagnozowanie problemów z CasaOS

Błąd 1: ponowna instalacja aplikacji przed sprawdzeniem logów

Ponowna instalacja może ukryć pierwotny błąd i utworzyć zduplikowane kontenery, osierocone woluminy lub spowodować ponowne pobieranie obrazów. Najpierw sprawdź logi usług CasaOS i logi kontenerów Docker.

Błąd 2: naprawianie DNS bez sprawdzenia rozwiązywania nazw

Losowa zmiana ustawień DNS może utrudnić diagnozowanie problemu. Najpierw przetestuj rozwiązywanie nazw za pomocą getent hosts. Jeśli serwer nie może rozpoznać domen rejestru lub katalogu, zmień konfigurację resolvera.

Błąd 3: ignorowanie zgodności obrazów ARM i AMD64

CasaOS może działać na urządzeniach ARM, ale nie każdy obraz aplikacji obsługuje ARM. Jeśli Twój host ma architekturę aarch64 lub armv7l, a obraz jest dostępny tylko dla amd64, instalacja może się nie powieść lub kontener może zakończyć działanie z błędem exec format error.

Błąd 4: Zmiana portów kontenera zamiast portów hosta

Jeśli dokumentacja aplikacji podaje, że kontener nasłuchuje na porcie 80, nie zmieniaj wewnętrznego portu kontenera, chyba że wiesz, że aplikacja to obsługuje. Zamiast tego zmień port hosta. Dzięki temu wewnętrzna usługa aplikacji będzie działać bez zmian, a konflikt na poziomie hosta zostanie uniknięty.

Jak bezpiecznie ponowić instalację

Po znalezieniu prawdopodobnej przyczyny ponów próbę w kontrolowany sposób:

  1. Zapisz dokładny komunikat o błędzie.
  2. Napraw tylko jedną warstwę.
  3. Uruchom ponownie powiązaną usługę tylko w razie potrzeby.
  4. Ponów instalację aplikacji.
  5. Obserwuj logi podczas ponawiania próby.
  6. Sprawdź, czy kontener istnieje.
  7. Sprawdź, czy port aplikacji nasłuchuje.
  8. Otwórz aplikację, używając prawidłowego adresu IP hosta i portu hosta.

Bezpieczna próba ponowienia może wyglądać tak:

journalctl -u casaos -f

W drugim terminalu:

docker ps -a
docker logs -f <container_name_or_id>

Następnie ponów próbę uruchomienia aplikacji w CasaOS. Dzięki temu za jednym razem zobaczysz działanie interfejsu, zachowanie usługi CasaOS i dane wyjściowe kontenera Dockera.

Najczęściej zadawane pytania

Dlaczego CasaOS informuje o niepowodzeniu instalacji aplikacji?

Ponieważ nie powiodła się jedna z warstw procesu instalacji. Przyczyną mogą być logi usług CasaOS, pobieranie obrazu Dockera, DNS, czas systemowy, architektura procesora, konflikty portów, uprawnienia lub zgodność z API Dockera. Zacznij od logów, a następnie przetestuj warstwę wskazaną przez pierwszy rzeczywisty błąd.

Jak sprawdzić logi instalacji aplikacji CasaOS?

Zacznij od:

journalctl -xeu casaos-app-management --no-pager
journalctl -u casaos -f

Następnie sprawdź Dockera:

docker ps -a
docker logs --tail 100 <container_name_or_id>

Dlaczego CasaOS nie może załadować sklepu z aplikacjami?

Najczęściej należy sprawdzić DNS, dostęp do sieci zewnętrznej, czas systemowy i logi usług CasaOS. Przetestuj DNS bezpośrednio na serwerze za pomocą getent hosts github.com i getent hosts registry-1.docker.io, a następnie sprawdź timedatectl i journalctl -u casaos -f.

Co oznacza exec format error w CasaOS?

Zwykle oznacza to, że obraz Dockera nie pasuje do architektury procesora. Na przykład host z procesorem ARM może próbować uruchomić obraz przeznaczony wyłącznie dla amd64. Sprawdź uname -m i upewnij się, że obraz obsługuje Twoją platformę.

Skąd mam wiedzieć, czy instalacja aplikacji CasaOS nie powiodła się z powodu konfliktu portów?

Sprawdź, które porty już nasłuchują:

sudo ss -tulpn | grep LISTEN

Następnie porównaj ten port z portem hosta aplikacji. Jeśli inna usługa już korzysta z tego samego portu hosta, zmień port hosta aplikacji na nieużywany, pozostawiając port kontenera zgodny z wymaganiami aplikacji.

Błąd instalacji aplikacji CasaOS łatwiej rozwiązać, gdy komunikat w interfejsie potraktujesz jako objaw, a nie przyczynę problemu. Najpierw sprawdź logi, a następnie zweryfikuj DNS, czas systemowy, architekturę, porty i zgodność z Dockerem, zanim ponownie zainstalujesz aplikację lub zmienisz ustawienia całego systemu.

Wsparcie i porady

Więcej do przeczytania

Get More Builds Like This

Stay in the Loop

Get updates from Zima - new products, exclusive deals, and real builds from the community.

Stay in the Loop preferences

We respect your inbox. Unsubscribe anytime.