Nie udało się załadować aplikacji w CasaOS: rozwiązanie problemu z wersją interfejsu API platformy Docker

Jeśli sam CasaOS się wczytuje, ale sekcja Aplikacje wyświetla tylko komunikat „Nie udało się wczytać aplikacji, spróbuj ponownie później” po aktualizacji Dockera, przed zmianą uprawnień systemu plików sprawdź logi CasaOS App Management. W przypadku opisanym w społeczności IceWhale w listopadzie 2025 r. decydujący błąd nie dotyczył samego pulpitu: CasaOS App Management próbowało użyć API Dockera w wersji 1.43, podczas gdy Docker Engine 29.0.1 wymagał co najmniej wersji API 1.44.

Ten sam log zawierał również błędy uprawnień w katalogach /var/run/casaos, /var/log/casaosoraz /var/lib/casaos, ale odrzucenie żądania przez API Dockera było odrębnym problemem ze zgodnością, który uniemożliwiał CasaOS wyświetlanie informacji o kontenerach i aplikacjach. Opiekunowie CasaOS zaktualizowali później skrypt instalacyjny, aby działał z nowszymi wersjami Dockera i obsługiwał zgodność API, dlatego obecni użytkownicy powinni zacząć od zaktualizowanego instalatora CasaOS, zamiast trwale obniżać wersję Dockera.

Błąd, który wskazał rzeczywisty problem ze zgodnością

Autor oryginalnego wpisu zgłosił:

Odpowiedź demona:
wersja klienta 1.43 jest zbyt stara.
Minimalna obsługiwana wersja API to 1.44,
zaktualizuj klienta do nowszej wersji

Środowisko obejmowało:

Ubuntu Server;
Docker Engine 29.0.1;
Docker API 1.52;
CasaOS App Management utworzone w październiku 2024 r.

To wyjaśnia, dlaczego pulpit CasaOS nadal mógł się otwierać, podczas gdy sekcja Aplikacje nie działała: interfejs internetowy i usługa zarządzania aplikacjami oparta na Dockerze to różne warstwy.

Dlaczego aktualizacja Dockera mogła zepsuć listę aplikacji CasaOS

Docker Engine udostępnia wersjonowane API. Starsze klienty zarządzające zwykle mogą negocjować z nowszymi demonami, ale Docker stopniowo podnosi minimalną akceptowaną wersję API.

Aktualna dokumentacja Dockera wyjaśnia negocjowanie wersji API i informuje, że starsze wersje API są stopniowo wycofywane lub usuwane. Zobacz dokumentację interfejsu API Docker Engine.

W tym przypadku CasaOS App Management korzystało z API w wersji 1.43, podczas gdy demon Docker 29 odrzucał wszystko poniżej wersji 1.44. W rezultacie wyliczanie aplikacji kończyło się niepowodzeniem, zanim interfejs mógł wyświetlić ich listę.

Błędy uprawnień były rzeczywiste, ale nie oznaczały tej samej awarii

Logi zawierały również komunikaty takie jak:

open /var/run/casaos/app-management.url: odmowa dostępu
mkdir /var/lib/casaos/appstore/...tmp: odmowa dostępu
nie można zmienić nazwy pliku dziennika ... odmowa dostępu

Autor wcześniej utworzył odpowiednie katalogi CasaOS i dostosował ich uprawnienia, ale Sklep z aplikacjami nadal nie działał. Ten wynik jest istotny: szeroko zakrojone zmiany uprawnień nie mogły naprawić niezgodności interfejsu API Dockera.

Nie rekurencyjnie chmod 777 ani zmieniać właściciela w katalogach systemowych CasaOS tylko dlatego, że interfejs informuje o nieudanym wczytaniu aplikacji. Najpierw sprawdź dokładne logi.

Co społeczność zalecała w tamtym czasie

MjTech odpowiedział, że był to znany problem związany z platformą Docker, i wskazał autorowi rozwiązanie społeczności BigBear dotyczące błędów API platformy Docker w CasaOS.

W tamtym czasie do często stosowanych tymczasowych obejść należały:

obniżenie minimalnej wersji API platformy Docker akceptowanej przez demona za pomocą nadpisania konfiguracji systemd;
lub tymczasowo użyć starszej wersji platformy Docker, która nadal akceptowała API klienta CasaOS.

Te obejścia były wartościowe w listopadzie 2025 roku, ale nie powinny automatycznie stać się stałą procedurą na 2026 rok, ponieważ instalator CasaOS został później zaktualizowany.

CasaOS później zaktualizował instalator

W grudniu 2025 roku opiekun CasaOS poinformował na GitHubie, że skrypt instalacyjny został naprawiony tak, aby:

zainstalować najnowszą dostępną wersję Docker Engine zamiast starej wersji docelowej 24.0.7;
zastosować obsługę zgodności API platformy Docker dla nowszych wersji platformy Docker;
umożliwiać działanie usług CasaOS i wbudowanych aplikacji z nowoczesną platformą Docker.

Opiekun projektu wyraźnie stwierdził, że do naprawy wcześniejszego problemu z nieładującymi się aplikacjami platformy Docker można użyć czystej instalacji lub bieżącego skryptu instalacyjnego.

Aktualny kod źródłowy znajdziesz w skrypcie instalatora CasaOS.

Pierwsza aktualna poprawka: użyj zaktualizowanego instalatora CasaOS

CasaOS obecnie informuje:

curl -fsSL https://get.casaos.io | sudo bash

lub:

wget -qO- https://get.casaos.io | sudo bash

Przed uruchomieniem instalatora na istniejącym serwerze wykonaj kopię zapasową ważnych baz danych aplikacji i konfiguracji. Naprawa ma na celu zachowanie stanu CasaOS, ale serwer domowy nigdy nie powinien polegać na skrypcie naprawczym jako jedynym planie odzyskiwania.

Aktualne instrukcje instalacji są dostępne w repozytorium CasaOS na GitHubie.

Zweryfikuj błąd API przed zastosowaniem obejścia zgodności

Sprawdź platformę Docker:

docker version

Następnie sprawdź zarządzanie aplikacjami CasaOS:

sudo systemctl status casaos-app-management
sudo journalctl -u casaos-app-management --no-pager -n 100

Jeśli dziennik zawiera dokładnie:

wersja klienta 1.43 jest zbyt stara
Minimalna obsługiwana wersja API to 1.44

wtedy mamy do czynienia z tą samą klasą awarii API platformy Docker co w wątku źródłowym.

Jeśli w dzienniku zamiast tego widoczne są błędy braku miejsca na dysku, awarie DNS, zatrzymany demon platformy Docker, uszkodzony katalog sklepu z aplikacjami lub brakujące pliki, nie stosuj obejścia API tylko dlatego, że komunikat w interfejsie jest identyczny.

Informacje o historycznym obejściu zgodności API platformy Docker

Rozwiązania społeczności i obejścia z GitHuba podczas incydentu w 2025 roku dodały ustawienie środowiska systemd platformy Docker, które ponownie zezwalało na starsze wersje API klienta. Mogło to przywrócić listę aplikacji, gdy CasaOS nadal korzystał z API 1.43.

Zmienia to granicę zgodności demona Dockera. Traktuj to jako tymczasowy mechanizm zgodności dla potwierdzonej niezgodności między starym klientem a nowym demonem, a nie jako ogólne ustawienie CasaOS.

Aktualna dokumentacja Dockera wyjaśnia, że obsługa starszych wersji API z czasem się zmienia, i zaleca utrzymywanie aktualnych klientów zamiast stałego polegania na starych wersjach API.

Nie ustawiaj bezrefleksyjnie DOCKER_API_VERSION w CasaOS

Dockera DOCKER_API_VERSION zmienna wymusza użycie określonej wersji API przez klienta i wyłącza standardową negocjację API. Docker opisuje ją przede wszystkim jako rozwiązanie na wypadek konieczności użycia dokładnej wersji API lub do debugowania.

To coś innego niż skonfigurowanie nowszego demona Dockera tak, aby akceptował starsze API klienta CasaOS. Ustawienie dowolnej wartości API po stronie klienta może pogorszyć niezgodność.

Sprawdź również, czy Docker działa prawidłowo

sudo systemctl status docker
docker ps

Jeśli sam Docker jest zatrzymany, CasaOS nie może wyświetlić listy uruchomionych kontenerów niezależnie od wersji API.

Przed ponowną instalacją czegokolwiek sprawdź miejsce na dysku

Ten sam komunikat interfejsu „Nie udało się załadować aplikacji” pojawiał się w niezwiązanych ze sobą przypadkach CasaOS, gdy dysk systemowy był prawie pełny. Sprawdź:

df -h

Zapełniony główny system plików może uniemożliwić działanie logów, plików tymczasowych, aktualizacji App Store i stanu Dockera. Nie zakładaj, że każdy identyczny baner interfejsu ma tę samą przyczynę.

Bezpieczna kolejność rozwiązywania problemów

Potwierdź, że sam pulpit CasaOS się otwiera.
Sprawdź systemctl status docker oraz docker ps.
Sprawdź df -h.
Odczytaj casaos-app-management logi.
Jeśli log pokazuje niezgodność API 1.43/1.44, najpierw użyj aktualnej ścieżki instalacji/naprawy CasaOS.
Zastąpienie wersji API stosuj tylko wtedy, gdy niezgodność została potwierdzona, a aktualna ścieżka naprawy nie jest dostępna.
Nie zmieniaj ogólnie uprawnień do katalogów CasaOS bez dowodów.
Przed ponowną instalacją lub wprowadzaniem systemowych zmian w Dockerze wykonaj kopię zapasową danych aplikacji.

FAQ: komunikat „Nie udało się załadować aplikacji” w CasaOS

Dlaczego pulpit CasaOS działa, a aplikacje nie?

Interfejs użytkownika, usługi CasaOS, demon Dockera i CasaOS App Management to oddzielne komponenty. W opisanym przypadku błąd występował konkretnie podczas próby odpytywania Dockera przez App Management.

Czy Docker 29 był przyczyną w wątku źródłowym?

Logi źródłowe wykazały, że Docker 29.0.1 wymagał API 1.44, podczas gdy zainstalowany klient CasaOS App Management używał API 1.43. Ta niezgodność bezpośrednio uniemożliwiała wyświetlanie aplikacji.

Czy należy wykonać chmod na folderach CasaOS, aby naprawić stronę?

Nie bez dowodów. Oryginalny autor już zmienił uprawnienia, a mimo to nadal występował błąd API Dockera. Najpierw odczytaj dokładne logi usługi.

Czy należy obniżyć wersję Dockera?

Było to jedno z historycznych obejść. Później CasaOS zaktualizował instalator, aby obsługiwał zgodność z nowoczesnymi wersjami Dockera, dlatego przed wymuszeniem starszej wersji Dockera użyj aktualnej ścieżki naprawy/instalacji.

Czy komunikat „Nie udało się załadować aplikacji” zawsze oznacza niezgodność API Dockera?

Nie. Ten sam komunikat interfejsu może być wynikiem zatrzymania demona Docker, zapełnienia dysku, problemów z uprawnieniami, niepowodzeń zarządzania aplikacjami lub innych problemów z usługami. Log pozwala ustalić przyczynę.