간단한 답변: Docker 업데이트 후 CasaOS에 갑자기 “Failed to load apps”가 표시된다면 CasaOS를 다시 설치하기 전에 Docker Engine API 버전을 확인하세요. Docker 29.0은 데몬의 최소 API를 v1.44로 높였고, 이로 인해 더 오래된 API를 요청하던 구버전 CasaOS App Management 클라이언트가 작동하지 않았습니다. 이후 Docker 29.3에서는 최소 버전이 다시 v1.40으로 낮아졌으므로, 적절한 해결 방법은 실제로 실행 중인 Docker 빌드에 따라 달라집니다.
먼저 Docker 버전을 확인하세요
실행:
docker 버전서버 버전과 API 버전 필드를 확인하세요. Docker의 Docker API 협상을 통해 클라이언트와 데몬이 공통 API 버전에 합의할 수 있지만, 데몬이 계속 허용하는 버전 범위 내에서만 가능합니다.
이 경계는 Docker 29에서 변경되었습니다. Docker 29.0은 데몬의 최소 API를 v1.44로 높였습니다. Docker 29.3.0에서는 최소 버전이 v1.40으로 낮아졌습니다. 따라서 Docker 29 API 하한은 버전에 따라 다릅니다.
| Docker 버전 | 최소 엔진 API | CasaOS에 의미하는 바 |
|---|---|---|
| 29.0.x–29.2.x | v1.44 | 이전 버전의 CasaOS App Management 클라이언트는 너무 오래된 버전으로 거부될 수 있습니다. |
| 29.3.0+ | v1.40 | 최초의 v1.44 기준은 더 이상 동일한 차단 요인이 아니므로, 오래된 우회 방법을 적용하기 전에 로그를 확인하세요. |
API 불일치가 실제 오류인지 확인하세요
모든 빈 App Store 화면이 Docker 29 호환성 문제라고 단정하지 마세요. 서비스 로그를 확인하세요.
journalctl -u casaos-app-management --no-pager -n 100핵심 오류는 다음과 같이 표시됩니다.
클라이언트 버전 1.43은 너무 오래되었습니다.
최소 지원 API 버전은 1.44입니다이 메시지는 UI 문제가 App Store 카탈로그 문제가 아니라 Docker API 호환성 문제로 인해 발생한다는 강력한 증거입니다. 여러 CasaOS 보고서에서 Docker 업그레이드 후 동일한 증상이 재현되었으며, 최초 보고된 Docker 업데이트 실패도 이에 해당합니다.
Docker 자체는 작동하는데 CasaOS가 중단될 수 있는 이유
CasaOS는 Docker Engine을 대체하지 않습니다. CasaOS 앱 관리 서비스는 Engine API를 통해 Docker와 통신합니다. CasaOS UI가 컨테이너를 조회하거나 생성하거나 관리하지 못하더라도 Docker 컨테이너는 정상적으로 실행 중일 수 있습니다.
따라서 다음과 같은 명령어는:
docker ps
docker imagesCasaOS에서 앱을 로드할 수 없다고 표시될 때에도 여전히 작동할 수 있습니다. Docker CLI와 CasaOS 앱 관리 서비스는 별도의 API 클라이언트이므로 반드시 동일한 API 버전을 요청하는 것은 아닙니다.
CasaOS와 Docker의 전반적인 관계는 CasaOS Docker 관리에 설명되어 있으며, 여기서 CasaOS는 Docker 기반 애플리케이션 위에 시각적 계층으로 사용됩니다.
API 재정의를 사용해 이전 Docker 29 설치 문제 해결
API v1.44가 여전히 필요한 Docker 29 빌드의 경우, systemd를 통해 데몬이 허용하는 최소 버전을 낮추는 방법이 테스트된 해결 방법 중 하나입니다. 보고된 CasaOS 호환성 수정은 다음을 사용합니다.
sudo systemctl edit docker.service추가:
[Service]
Environment=DOCKER_MIN_API_VERSION=1.24그런 다음 Docker를 다시 시작합니다:
sudo systemctl daemon-reload
sudo systemctl restart docker재정의를 확인합니다:
systemctl show docker | grep DOCKER_MIN_API_VERSION이는 호환성 재정의이며, 서버를 오래된 애플리케이션 스택에 무기한 유지해야 할 이유가 아닙니다. 이 설정은 이전 API 클라이언트가 데몬과 통신할 수 있도록 의도적으로 허용합니다.
현재 설치 프로그램에서 이미 문제가 해결되었는지 확인
이후 CasaOS 유지 관리자들은 설치 스크립트가 최신 Docker Engine을 설치하고 최신 버전에 대한 Docker API 호환성 재정의를 적용하도록 업데이트되었다고 보고했습니다. 해당 유지 관리자 업데이트는 설치 프로그램 호환성 업데이트에 나와 있습니다.
CasaOS 설치가 해당 변경 사항보다 이전 버전이라면, 수동 재정의를 계속 유지하는 것보다 현재 공식 설치 프로그램을 다시 실행하는 편이 더 깔끔할 수 있습니다. 기존 서버를 변경하기 전에 중요한 앱 데이터와 사용자 지정 구성을 백업하세요.
기존 해결 방법을 사용하지 말아야 하는 경우
만약 docker 버전 Docker 29.3 이상이고 최소 API가 이미 v1.40임을 나타낸다면 무작정 강제로 설정하지 마세요. DOCKER_MIN_API_VERSION=1.24. 먼저 CasaOS 앱 관리 로그를 확인하세요. 다른 오류에는 다른 해결 방법이 필요합니다.
예를 들어 DNS 오류, 레지스트리 접근 문제, 손상된 앱 메타데이터 또는 중지된 CasaOS 서비스로 인해 API 버전 문제가 없어도 앱 스토어가 비어 있는 것처럼 보일 수 있습니다.
수정 후 CasaOS 확인
Docker를 재시작한 후 세 계층을 모두 확인하세요.
-
Docker:
docker ps가 정상적으로 반환됩니다. -
CasaOS 서비스:
systemctl status casaos-app-management가 활성 상태이며 더 이상 API 불일치 오류를 기록하지 않습니다. - 웹 UI: 설치된 앱과 앱 스토어가 다시 로드됩니다.
Docker는 작동하지만 CasaOS 앱 관리가 계속 실패한다면 Docker를 재시작한 후 해당 서비스를 재시작하세요.
sudo systemctl restart casaos-app-management애플리케이션 스택을 비교하는 사용자라면 ZimaOS 앱 플랫폼에서 현재의 원클릭 앱 모델을 확인할 수 있습니다. Docker 및 CasaOS 테스트를 위한 소형 x86 머신을 찾는다면 ZimaBoard 2는 호환되는 운영 체제 중 하나로 CasaOS를 공식적으로 명시하고 있습니다.
FAQ
Docker 29는 항상 CasaOS를 중단시키나요?
아니요. Docker 29.0에서는 최소 Engine API가 v1.44로 올라갔지만, Docker 29.3.0에서는 v1.40으로 낮아졌습니다. 해결 방법을 선택하기 전에 정확한 Docker 버전과 CasaOS 로그를 확인하세요.
컨테이너가 계속 실행되는 이유는 무엇인가요?
컨테이너는 Docker Engine에서 관리합니다. CasaOS 앱 관리는 별도의 클라이언트입니다. 데몬과 기존 컨테이너가 계속 실행되는 동안에도 이 클라이언트의 API 연결은 실패할 수 있습니다.
Docker를 다운그레이드해야 하나요?
자동으로 그런 것은 아닙니다. API 재정의는 영향을 받는 Docker 29 설치 환경에서 효과적인 해결 방법이었으며, 이후 Docker 릴리스에서는 최소 API 버전이 다시 변경되었습니다. 호환성을 깔끔하게 복원할 수 없을 때 다운그레이드는 여러 선택지 중 하나일 뿐입니다.
이것이 동일한 문제임을 입증하는 로그는 무엇인가요?
Docker 클라이언트 API가 너무 오래되었으며 데몬에 API v1.44 이상이 필요하다는 오류가 표시되는지 확인하세요. 그런 증거가 없다면 Docker 29 문제라고 단정하지 말고 계속 문제를 해결하세요.
