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

Niepowodzenie instalacji aplikacji CasaOS zwykle wygląda jak prosty błąd w interfejsie: sklep z aplikacjami się nie ładuje, przycisk instalacji aplikacji nie działa lub kontener pojawia się, ale nigdy się nie otwiera. Prawdziwa przyczyna zwykle jest głębsza niż interfejs CasaOS. CasaOS jest zaprojektowany wokół instalacji aplikacji jednym kliknięciem i wdrażania aplikacji Docker, więc nieudana instalacja może wynikać z warstwy usługi CasaOS, pobierania obrazu Dockera, rozwiązywania DNS, czasu systemowego, architektury CPU lub konfliktów portów hosta.

Najbezpieczniejszym sposobem rozwiązywania problemów nie jest najpierw ponowna instalacja CasaOS. Zacznij od przeczytania prawdziwego błędu, a następnie testuj po kolei każdą warstwę: logi, sieć i DNS, synchronizację czasu, architekturę CPU, porty i zgodność Dockera.

Szybkie podsumowanie: komunikat o błędzie CasaOS to tylko pierwszy objaw

Ogólny komunikat „nie udało się zainstalować” informuje, że CasaOS nie mógł zakończyć wdrożenia, ale nie mówi, która warstwa zawiodła. Katalog aplikacji może się nie załadować, Docker może nie pobrać obrazu, obraz może nie pasować do architektury CPU, port hosta może być już zajęty lub kontener mógł się uruchomić, a następnie ulec awarii.

Instalacja aplikacji CasaOS zależy zarówno od warstwy usługi CasaOS, jak i środowiska Dockera. Pobieranie obrazów Dockera może być również utrudnione przez dostęp do rejestru, ustawienia proxy, połączenia o niskiej przepustowości oraz przekroczenia limitów czasu pobierania warstw.

Użyj tej kolejności:

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

# 2. Sprawdź kontenery Dockera
docker ps -a

# 3. Przeczytaj logi nieudanego kontenera
docker logs --tail 100 <container_name_or_id>

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

# 5. Sprawdź czas systemowy
timedatectl

# 6. Sprawdź architekturę CPU
uname -m

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

Zacznij od logów przed zmianą ustawień

Logi to najszybszy sposób na oddzielenie problemu CasaOS od problemu z Dockerem, siecią, obrazem lub aplikacją. Linux journalctl polecenie wyświetla wpisy z dziennika systemd, a jego -u opcja filtruje logi dla konkretnej jednostki usługi.

Dla CasaOS zacznij od logów na poziomie usługi:

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

Następnie sprawdź Dockera. Docker docker logs polecenie pobiera logi z kontenera, a --follow opcja może przesyłać nowe dane wyjściowe podczas działania kontenera.

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

Czego szukasz:

Wskazówka w logu	Prawdopodobny kierunek
brak takiego hosta / błąd wyszukiwania DNS	DNS lub rozwiązywanie sieciowe
przekroczono limit czasu połączenia	Sieć, proxy, zapora, dostęp do rejestru lub niska przepustowość
certyfikat / TLS / błąd x509	Czas systemowy, certyfikaty CA lub przechwytywanie HTTPS
exec format error	Nieprawidłowa architektura CPU dla obrazu
port jest już przydzielony / bind: adres jest już używany	Konflikt portu hosta
minimalna obsługiwana wersja API	Niezgodność API klienta / demona Dockera
Kontener natychmiast się zamyka	Konfiguracja aplikacji, uprawnienia wolumenu, brakująca zmienna środowiskowa lub problem z obrazem

Zasada jest prosta: nie naprawiaj pięciu rzeczy naraz. Skopiuj pierwszą wyraźną linię błędu, a następnie przetestuj warstwę, do której się odnosi.

Sprawdź DNS i dostęp do sieci

Jeśli sklep z aplikacjami się nie ładuje lub instalacja nie powiodła się podczas pobierania obrazu, sprawdź DNS i dostęp do sieci wychodzącej przed zmianą ustawień CasaOS. Docker pobiera obrazy z rejestrów takich jak Docker Hub. Jeśli host CasaOS nie może rozwiązać domen rejestru, pobieranie obrazów może się nie powieść, zanim kontener zostanie utworzony.

Używaj testów rozwiązywania nazw zamiast tylko ping:

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

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

Następnie sprawdź konfigurację resolvera:

cat /etc/resolv.conf

Na Linuksie, /etc/resolv.conf to plik konfiguracyjny resolvera używany do DNS, a nameserver wpisy definiują, które serwery DNS powinien zapytać resolver. Jeśli DNS jest uszkodzony, tymczasowa zmiana na stabilne publiczne serwery może potwierdzić, czy to jest problem:

sudo nano /etc/resolv.conf

Przykładowy tymczasowy test:

nameserver 1.1.1.1
nameserver 8.8.8.8

Nie zatrzymuj się na „internet działa na moim laptopie”. CasaOS działa na serwerze, więc to ścieżka DNS serwera ma znaczenie.

Sprawdź czas systemowy zanim obwinisz sklep z aplikacjami

Nieprawidłowy czas systemowy może powodować błędy HTTPS i walidacji certyfikatów, które wyglądają jak awarie sklepu z aplikacjami lub rejestru. Przed zmianą konfiguracji Dockera lub CasaOS sprawdź, czy zegar serwera jest poprawny i czy synchronizacja czasu jest aktywna.

timedatectl

W wyjściu szukaj linii 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 poczekaj chwilę i uruchom ponownie timedatectl przed ponowną próbą instalacji aplikacji CasaOS.

Potwierdź, że architektura CPU odpowiada obrazowi aplikacji

CasaOS może działać na kilku platformach sprzętowych, w tym na urządzeniach x86-64 i ARM. To nie oznacza, że każda aplikacja Docker w każdym katalogu obsługuje każdą architekturę. Raspberry Pi, Orange Pi, mini płyta ARM lub przerobione urządzenie z Androidem mogą nie uruchomić obrazu zbudowanego tylko dla linux/amd64.

Sprawdź architekturę swojego hosta:

uname -m

uname -m wynik	Zwykłe znaczenie
x86_64	AMD64 / x86-64
aarch64	ARM64
armv7l	32-bitowego ARM
i386 / i686	32-bitowego x86

Kod kontenera musi być zgodny z architekturą hosta, ponieważ kontenery współdzielą jądro hosta. Bez emulacji nie można uruchomić linux/amd64 kontener na arm64 host. Obrazy wieloplatformowe rozwiązują to, dostarczając warianty takie jak linux/amd64 oraz linux/arm64 pod jednym obrazem.

Jeśli logi pokazują exec format error, sprawdź stronę obrazu lub manifest rejestru pod kątem wsparcia ARM. Jeśli obraz nie obsługuje twojej platformy, zmiana ustawień CasaOS tego nie naprawi. Potrzebujesz obrazu multi-arch, innego tagu lub innej aplikacji.

Sprawdź konflikty portów przed ponowną instalacją

Niektóre instalacje aplikacji CasaOS kończą się sukcesem, ale aplikacja nadal się nie otwiera. W wielu przypadkach kontener się uruchomił, ale port hosta był już zajęty lub błędnie 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 porty jako mapowania między maszyną hosta a kontenerami, a te mapowania umożliwiają zewnętrzny dostęp do usług działających wewnątrz kontenerów.

Typowe mapowanie wygląda tak:

porty:
  - "8080:80"

Część	Znaczenie
8080	Port hosta: pod którym odwiedza go przeglądarka
80	Port kontenera: na którym aplikacja nasłuchuje wewnątrz kontenera

Jeśli inna usługa już używa portu hosta 80, nie zmieniaj najpierw portu kontenera. Zmień port hosta na nieużywany:

porty:
  - "8080:80"

Jest to szczególnie ważne dla aplikacji takich jak reverse proxy, blokerów reklam, pulpitów nawigacyjnych i serwerów WWW, ponieważ często domyślnie używają portów 80, 443, 8080, lub 3000.

Praktyczna lista kontrolna błędów aplikacji CasaOS

Użyj tej listy kontrolnej przed ponowną instalacją CasaOS lub usuwaniem kontenerów.

Sprawdź	Polecenie	Dobry znak	Zły znak
Logi usługi CasaOS	journalctl -xeu casaos-app-management --no-pager	Jasny przebieg instalacji lub konkretny błąd	Powtarzające się awarie usługi lub błąd API Dockera
Logi na żywo CasaOS	journalctl -u casaos -f	Akcje UI pojawiają się w logach	Akcja aplikacji kończy się bez komunikatu lub w pętli
Lista kontenerów Dockera	docker ps -a	Kontener utworzony i status widoczny	Kontener brakujący lub wielokrotnie się restartujący
Logi kontenera	docker logs --tail 100 <kontener>	Aplikacja uruchamia się normalnie	Błąd wyjścia, uprawnień, konfiguracji lub architektury
Wyszukiwanie DNS	getent hosts registry-1.docker.io	Zwrócone adresy IP	Brak wyniku lub błąd wyszukiwania
Pobieranie obrazu	docker pull <image>:<tag>	Pobieranie obrazu	Limit czasu, TLS, uwierzytelnianie lub brak pasującego manifestu
Czas systemowy	timedatectl	Zegar zsynchronizowany, NTP aktywne	Przesunięcie czasu lub NTP nieaktywne
Architektura	uname -m	Zgodność platformy obrazu	Host ARM z obrazem tylko amd64
Porty	sudo ss -tulpn | grep LISTEN	Port hosta nieużywany	Port już zajęty

Typowe wzorce błędów i co zwykle oznaczają

Sklep z aplikacjami się nie ładuje

Jeśli sam Sklep z aplikacjami się nie ładuje, zacznij od DNS i dostępu do sieci. CasaOS zależy od zewnętrznych katalogów i źródeł obrazów podczas normalnych procesów aplikacji, więc serwer musi móc rozwiązywać i osiągać te źródła.

Sprawdź:

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

Jeśli DNS zawodzi, napraw resolver serwera. Jeśli DNS działa, ale pobieranie Dockera się nie powiodło, przetestuj dostęp do rejestru oraz warunki proxy lub zapory.

Instalacja aplikacji nie powiodła się podczas pobierania obrazu

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

docker pull <image>:<tag>

Jeśli ręczne pobieranie kończy się błędami DNS lub przekroczenia czasu, problem nie leży w interfejsie CasaOS. Jeśli pojawia się błąd architektury lub brak pasującego manifestu, sprawdź platformę obrazu.

Aplikacja jest zainstalowana, ale nie można jej otworzyć

Jeśli aplikacja wydaje się zainstalowana, ale przeglądarka nie może jej otworzyć, najpierw sprawdź porty. Nieprawidłowy lub konfliktujący port hosta może sprawić, że działający kontener będzie wyglądał na uszkodzony.

Sprawdź:

docker ps
sudo ss -tulpn | grep LISTEN

Następnie sprawdź, czy aplikacja jest powiązana z portem hosta, który odwiedzasz.

Aplikacja uruchamia się i natychmiast zatrzymuje

Jeśli kontener istnieje, ale się zamyka, przeczytaj logi kontenera:

docker logs --tail 100 <kontener>

Szukaj brakujących zmiennych środowiskowych, nieprawidłowych ścieżek wolumenów, błędów bazy danych, błędów uprawnień lub exec format error.

Logi pokazują błędy wersji API Dockera

Jeśli logi wspominają o niezgodności wersji API Dockera, nie zgaduj. Najpierw uruchom:

docker version

Problemy z wersją API Dockera należy traktować jako zaawansowany przypadek rozwiązywania problemów. Rozważ nadpisanie API tylko wtedy, gdy logi wyraźnie pokazują niezgodność API. Nie dodawaj nadpisania systemd tylko dlatego, że aplikacja raz nie zadziałała.

Problemy z Dockerem i uprawnieniami w aplikacjach CasaOS

Niektóre aplikacje nie działają, ponieważ kontener został utworzony, ale nie ma oczekiwanego dostępu do wolumenu, urządzenia lub ścieżki sieciowej. To częste, gdy użytkownicy instalują niestandardowe szablony, przenoszą dane aplikacji, montują zewnętrzne dyski lub ręcznie zmieniają foldery hosta.

Sprawdź mapowane ścieżki aplikacji i logi:

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

Szukaj:

• brak folderu hosta;
• odmowa dostępu;
• system plików tylko do odczytu;
• baza danych nie może się zainicjalizować;
• plik konfiguracyjny nie znaleziony;
• brak ścieżki urządzenia;
• użytkownik kontenera nie może zapisywać do zamontowanego wolumenu.

Gdy błąd wskazuje na problem z wolumenem lub uprawnieniami, najpierw napraw ścieżkę lub uprawnienia. Ponowna instalacja aplikacji bez zmiany złej ścieżki zwykle powoduje ten sam błąd.

Błędy, które utrudniają rozwiązywanie problemów z CasaOS

Błąd 1: Ponowna instalacja aplikacji przed przeczytaniem logów

Ponowna instalacja może ukryć pierwotny błąd i stworzyć duplikaty kontenerów, osierocone wolumeny lub powtarzające się pobieranie obrazów. Najpierw przeczytaj logi usługi CasaOS i logi kontenerów Dockera.

Błąd 2: Naprawianie DNS bez testowania rozwiązywania nazw

Losowa zmiana DNS może utrudnić rozwiązywanie problemów. Najpierw przetestuj rozwiązywanie za pomocą getent hosts. Jeśli serwer nie może rozwiązać domen rejestru lub katalogu, dostosuj konfigurację resolvera.

Błąd 3: Ignorowanie zgodności obrazów ARM vs AMD64

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

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

Jeśli dokumentacja aplikacji mówi, ż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. Pozwala to zachować wewnętrzne działanie usługi aplikacji, unikając konfliktu na poziomie hosta.

Jak bezpiecznie ponowić instalację

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

1. Zapisz dokładną wiadomość o błędzie.
2. Napraw tylko jedną warstwę.
3. Uruchom ponownie powiązaną usługę tylko jeśli to konieczne.
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ę z poprawnego adresu IP hosta i portu hosta.

Bezpieczne ponowne uruchomienie może wyglądać tak:

journalctl -u casaos -f

W innym terminalu:

docker ps -a
docker logs -f <container_name_or_id>

Następnie spróbuj ponownie aplikację w CasaOS. Daje to jednocześnie akcję UI, zachowanie usługi CasaOS i wyjście kontenera Dockera.

FAQ

Dlaczego CasaOS mówi, że instalacja aplikacji nie powiodła się?

Ponieważ jedna warstwa w łańcuchu instalacji zawiodła. Przyczyną mogą być logi usług CasaOS, pobieranie obrazu Dockera, DNS, czas systemowy, architektura CPU, konflikty portów, uprawnienia lub kompatybilność API Dockera. Zacznij od logów, potem testuj 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ęstsze kontrole to DNS, dostęp do sieci wychodzącej, czas systemowy i logi usług CasaOS. Przetestuj DNS bezpośrednio z serwera za pomocą getent hosts github.com oraz getent hosts registry-1.docker.io, następnie sprawdź timedatectl oraz journalctl -u casaos -f.

Co oznacza exec format error co oznacza w CasaOS?

Zazwyczaj oznacza to, że obraz Dockera nie pasuje do architektury twojego procesora. Na przykład host ARM może próbować uruchomić obraz tylko dla amd64. Sprawdź uname -m i potwierdź, czy obraz wspiera twoją platformę.

Skąd mam wiedzieć, czy aplikacja 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 to z portem hosta aplikacji. Jeśli inna usługa już używa tego samego portu hosta, zmień port hosta aplikacji na nieużywaną wartość, zachowując port kontenera zgodny z oczekiwaniami aplikacji.

Błąd instalacji aplikacji CasaOS staje się znacznie łatwiejszy do rozwiązania, gdy traktujesz komunikat UI jako objaw, a nie przyczynę źródłową. Najpierw przeczytaj logi, następnie zweryfikuj DNS, czas, architekturę, porty i kompatybilność Dockera, zanim ponownie zainstalujesz aplikację lub zmienisz ustawienia systemowe.