CasaOS 자체는 로드되지만 Docker 업데이트 후 Apps 섹션에 “앱을 불러오지 못했습니다. 나중에 다시 시도해 주세요”만 표시된다면, 파일 시스템 권한을 변경하기 전에 CasaOS App Management 로그를 확인하세요. 2025년 11월 IceWhale Community 사례에서 결정적인 오류는 대시보드 자체가 아니었습니다. CasaOS App Management가 Docker API 1.43을 사용하려고 했지만 Docker Engine 29.0.1은 최소 API 1.44를 요구했습니다.
같은 로그에는 다음 경로 아래의 권한 오류도 포함되어 있었습니다. /var/run/casaos, /var/log/casaos및 /var/lib/casaos였지만 Docker API 거부는 CasaOS가 컨테이너/앱 정보를 표시하지 못하게 한 별도의 호환성 문제였습니다. 이후 CasaOS 유지 관리자들은 최신 Docker 버전에서 작동하고 API 호환성을 처리하도록 설치 스크립트를 업데이트했으므로, 현재 사용자는 Docker를 영구적으로 다운그레이드하기보다 업데이트된 CasaOS 설치 프로그램부터 사용해야 합니다.
실제 호환성 문제를 밝혀낸 오류
원 작성자는 다음과 같이 보고했습니다.
데몬의 오류 응답:
클라이언트 버전 1.43은 너무 오래되었습니다.
지원되는 최소 API 버전은 1.44입니다.
클라이언트를 최신 버전으로 업그레이드하세요환경은 다음과 같았습니다.
- Ubuntu Server;
- Docker Engine 29.0.1;
- Docker API 1.52;
- 2024년 10월에 구축된 CasaOS App Management.
이 때문에 CasaOS 대시보드는 계속 열리는데 Apps 섹션만 작동하지 않을 수 있습니다. 웹 인터페이스와 Docker 기반 앱 관리 서비스는 서로 다른 계층이기 때문입니다.
Docker 업데이트로 CasaOS 앱 목록이 작동하지 않을 수 있는 이유
Docker Engine은 버전이 지정된 API를 제공합니다. 이전 관리 클라이언트는 일반적으로 최신 데몬과 협상할 수 있지만, Docker는 허용하는 최소 API 버전을 점진적으로 높여 왔습니다.
현재 Docker 문서에서는 API 버전 협상을 설명하며, 이전 API 버전이 점차 사용 중단되거나 제거되고 있다고 안내합니다. 자세한 내용은 Docker Engine API 문서를 참조하세요.
이 사례에서 CasaOS App Management는 API 1.43을 사용했지만 Docker 29 데몬은 1.44 미만의 버전을 거부했습니다. 그 결과 UI에서 앱 목록을 렌더링하기도 전에 앱 열거에 실패했습니다.
권한 오류는 실제 문제였지만 동일한 장애는 아니었습니다
로그에는 다음과 같은 메시지도 포함되어 있었습니다.
open /var/run/casaos/app-management.url: 권한이 거부됨
mkdir /var/lib/casaos/appstore/...tmp: 권한이 거부됨
로그 파일의 이름을 변경할 수 없음 ... 권한이 거부됨작성자는 이미 관련 CasaOS 디렉터리의 권한을 생성하고 조정했지만, App Store는 여전히 작동하지 않았습니다. 이 결과는 중요합니다. 광범위한 권한 변경으로는 Docker API 비호환 문제를 해결할 수 없었습니다.
재귀적으로 수행하지 마세요 chmod 777 또는 UI에 앱을 불러오지 못했다고 표시된다는 이유만으로 CasaOS 시스템 디렉터리 전체의 소유권을 변경하지 마세요. 먼저 정확한 로그를 확인하세요.
당시 커뮤니티가 권장한 방법
MjTech는 이것이 알려진 Docker 관련 문제라고 답변하며, CasaOS Docker API 오류에 대한 BigBear 커뮤니티 해결 방법을 작성자에게 안내했습니다.
당시 일반적인 임시 해결 방법은 다음과 같았습니다.
- systemd 재정의를 통해 데몬이 허용하는 최소 Docker API 버전을 낮춥니다.
- 또는 CasaOS 클라이언트 API를 여전히 허용하는 이전 Docker 릴리스를 임시로 사용합니다.
이러한 해결 방법은 2025년 11월에 유용했지만, CasaOS 설치 프로그램이 이후 업데이트되었으므로 2026년의 영구적인 절차로 자동 적용해서는 안 됩니다.
CasaOS는 이후 설치 프로그램을 업데이트했습니다
2025년 12월, CasaOS 관리자는 GitHub에서 설치 스크립트가 다음과 같이 작동하도록 수정되었다고 밝혔습니다.
- 기존 Docker 24.0.7을 대상으로 하는 대신 사용 가능한 최신 Docker Engine을 설치합니다.
- 최신 Docker 버전에 대한 Docker API 호환성 처리를 적용합니다.
- CasaOS 서비스와 기본 제공 애플리케이션이 최신 Docker에서 작동하도록 합니다.
관리자는 이전에 발생한 Docker 앱 로딩 문제를 새로 설치하거나 현재 설치 스크립트를 사용해 해결할 수 있다고 구체적으로 밝혔습니다.
현재 소스는 CasaOS 설치 스크립트에서 확인하세요.
현재 첫 번째 해결 방법: 업데이트된 CasaOS 설치 프로그램 사용
CasaOS에는 현재 다음과 같이 안내되어 있습니다.
curl -fsSL https://get.casaos.io | sudo bash또는:
wget -qO- https://get.casaos.io | sudo bash기존 서버에서 설치 프로그램을 실행하기 전에 중요한 애플리케이션 데이터베이스와 설정을 백업하세요. 이 복구 방법은 CasaOS 상태를 보존하도록 설계되었지만, 홈 서버는 복구 스크립트 하나에만 의존해서는 안 됩니다.
현재 설치 지침은 CasaOS GitHub 저장소에서 확인할 수 있습니다.
호환성 재정의를 적용하기 전에 API 오류 확인
Docker 확인:
docker version그런 다음 CasaOS 앱 관리를 확인하세요.
sudo systemctl status casaos-app-management
sudo journalctl -u casaos-app-management --no-pager -n 100로그에 다음 내용이 명시적으로 포함되어 있다면:
클라이언트 버전 1.43은 너무 오래되었습니다
지원되는 최소 API 버전은 1.44입니다그렇다면 원본 스레드와 동일한 Docker API 유형의 오류가 발생한 것입니다.
로그에 디스크 공간 부족 오류, DNS 오류, 중지된 Docker 데몬, 손상된 앱 스토어 카탈로그 또는 누락된 파일이 표시된다면, UI 메시지가 동일하다는 이유만으로 API 해결 방법을 적용하지 마세요.
과거 Docker API 호환성 재정의에 관하여
2025년 장애 당시 커뮤니티와 GitHub의 해결 방법으로 Docker systemd 환경 설정을 추가해 이전 클라이언트 API 버전을 다시 사용할 수 있게 했습니다. 이를 통해 CasaOS가 API 1.43을 계속 사용하는 동안 앱 목록을 복원할 수 있었습니다.
이 설정은 Docker 데몬의 호환성 경계를 변경합니다. 검증된 이전 클라이언트/최신 데몬 불일치에 대한 임시 호환성 수단으로만 취급하고, 일반적인 CasaOS 튜닝 설정으로 사용하지 마세요.
현재 Docker 문서에서는 레거시 API 지원이 시간이 지나면서 변경되며, 이전 API 버전에 영구적으로 의존하기보다 클라이언트를 최신 상태로 유지할 것을 권장합니다.
CasaOS에서 DOCKER_API_VERSION을 무작정 설정하지 마세요
Docker의 DOCKER_API_VERSION 변수는 클라이언트가 특정 API 버전을 사용하도록 강제하고 일반적인 API 협상을 비활성화합니다. Docker에서는 이를 주로 정확한 API 버전이 필요하거나 디버깅이 필요한 경우에 사용한다고 설명합니다.
이는 최신 Docker 데몬이 이전 CasaOS 클라이언트의 API를 허용하도록 만드는 것과는 다릅니다. 임의의 클라이언트 측 API 값을 설정하면 불일치가 더 악화될 수 있습니다.
Docker가 정상인지도 확인
sudo systemctl status docker
docker psDocker 자체가 중지되어 있으면 API 버전과 관계없이 CasaOS에서 실행 중인 컨테이너를 나열할 수 없습니다.
무언가를 재설치하기 전에 디스크 공간 확인
동일한 “Failed to load apps” UI 메시지는 시스템 디스크가 거의 가득 찬 관련 없는 CasaOS 사례에서도 나타났습니다. 다음을 확인하세요.
df -h루트 파일 시스템이 가득 차면 로그, 임시 파일, App Store 업데이트 및 Docker 상태에 문제가 생길 수 있습니다. 동일한 UI 배너가 항상 같은 원인으로 나타난다고 단정하지 마세요.
안전한 문제 해결 순서
- CasaOS 대시보드 자체가 열리는지 확인하세요.
- 확인
systemctl status docker및docker ps. - 확인
df -h. - 읽기
casaos-app-management로그. - 로그에 1.43/1.44 API 불일치가 표시되면 먼저 현재 CasaOS 설치 프로그램/복구 경로를 사용하세요.
- 불일치가 확인되고 현재의 복구 경로를 사용할 수 없는 경우에만 API 호환성 재정의를 사용하세요.
- 근거 없이 CasaOS 디렉터리의 권한을 광범위하게 완화하지 마세요.
- 재설치하거나 시스템 수준의 Docker를 변경하기 전에 앱 데이터를 백업하세요.
CasaOS 앱을 불러오지 못함 FAQ
Apps는 작동하지 않는데 CasaOS 대시보드는 왜 작동하나요?
UI, CasaOS 서비스, Docker 데몬, CasaOS App Management는 서로 별개의 구성 요소입니다. 원본 사례에서는 App Management가 Docker에 쿼리를 보낼 때 구체적으로 실패했습니다.
원본 스레드에서 Docker 29가 원인이었나요?
원본 로그에는 Docker 29.0.1이 API 1.44를 요구하는 반면, 설치된 CasaOS App Management 클라이언트는 API 1.43을 사용한다고 표시되어 있었습니다. 이 불일치로 인해 앱 목록을 직접 불러올 수 없었습니다.
페이지를 수정하려면 CasaOS 폴더에 chmod를 사용해야 하나요?
근거 없이 진행하지 마세요. 원래 작성자는 이미 권한을 수정했지만 Docker API 오류는 여전히 발생했습니다. 먼저 정확한 서비스 로그를 확인하세요.
Docker를 다운그레이드해야 하나요?
그것은 과거에 사용되던 해결 방법 중 하나였습니다. 이후 CasaOS는 최신 Docker 호환성을 지원하도록 설치 프로그램을 업데이트했으므로, 이전 Docker 버전을 강제로 설치하기 전에 현재의 복구/설치 경로를 사용하세요.
“Failed to load apps”가 항상 Docker API 불일치를 의미하나요?
아니요. 동일한 UI 메시지는 중지된 Docker 데몬, 디스크 공간 부족, 권한 문제, 앱 관리 실패 또는 기타 서비스 문제로 인해 나타날 수 있습니다. 정확한 원인은 로그를 통해 확인해야 합니다.
