CasaOS Portainer 로컬 환경: Docker 29 복구 가이드

이 소스에는 서로 가까운 시기에 발생한 여러 문제가 포함되어 있으므로, 이를 단순한 “Portainer 버그” 하나로 다시 작성해서는 안 됩니다. 정리 전 시스템 드라이브의 여유 공간이 거의 없었고, Debian을 통해 Docker와 containerd가 주요 새 버전으로 업그레이드되었으며, 이전 Docker CLI 테스트는 Docker 29 데몬에서 거부되었습니다. Portainer에서는 Local 환경이 사라졌고, CasaOS에서는 계속 “앱 로딩 중”이 표시되었으며, 이후 발생한 부팅 문제로 대시보드가 거의 새로 설치한 것처럼 보였습니다.

소스의 어떤 답변도 최종적인 단일 원인을 확인하지 않습니다. 가장 안전한 해석은 여러 계층이 얽힌 복구 문제라는 것입니다. 먼저 기존 데이터를 보존한 다음, 어떤 부팅 디스크/루트 파일 시스템이 활성 상태인지, Docker 데이터 루트가 여전히 존재하는지, 데몬이 정상인지, Portainer와 CasaOS가 업그레이드된 Docker API와 호환되는지 확인해야 합니다.

시스템 디스크는 이미 심각한 공간 부족 상태였습니다

정리 전 사용자의 27GB 루트 파일 시스템에는 여유 공간이 약 1GB뿐이었습니다. 주요 사용처로는 Docker 오버레이 데이터, Jellyfin 메타데이터, 시스템 로그, 개발 패키지가 있었습니다.

여유 공간이 부족하면 Docker 이미지/컨테이너 작업, 데이터베이스, 로그, CasaOS 서비스가 예측할 수 없이 작동할 수 있습니다. 이후의 Docker API 문제와 관계없이 공간을 확보하는 작업은 필요했습니다.

호스트 업그레이드로 Docker가 28.x에서 29.0.0으로 변경되었습니다

Debian 패키지 기록에는 다음 항목의 업그레이드가 표시되었습니다.

docker-ce;
docker-ce-cli;
containerd.io;
Docker 루트리스 추가 구성 요소.

Docker Engine을 주요 버전으로 업그레이드하면 이전 API 클라이언트를 포함하거나 해당 클라이언트와 협상하는 관리 도구에서 호환성 문제가 드러날 수 있습니다.

소스에서는 실제 Docker API 버전 불일치가 확인되었습니다

Docker 24.0.5 CLI 컨테이너는 다음을 반환했습니다.

client version 1.43 is too old.
Minimum supported API version is 1.44

이 메시지는 적어도 하나의 이전 클라이언트가 업그레이드된 Docker 데몬과 더 이상 통신할 수 없었다는 직접적인 증거입니다. 이것만으로 Portainer가 정확히 해당 클라이언트 버전을 사용했다고 입증할 수는 없지만, API 호환성을 최우선으로 확인해야 할 이유가 됩니다.

Portainer에서 Local이 실행 중이라고 표시되었다가 사라진 것은 관리 계층의 증상입니다

소스에서는 /var/run/docker.sock을 대상으로 로컬 Docker 환경을 다시 만들려고 했지만 성공하지 못했습니다. Portainer 상태를 삭제하기 전에 다음을 확인하세요.

docker info
docker ps
ls -l /var/run/docker.sock

Docker CLI 자체는 작동하지만 Portainer만 작동하지 않는다면 Portainer 버전, API, 소켓 접근 권한에 집중하세요. Docker 자체가 실패한다면 먼저 데몬을 복구해야 합니다.

CasaOS에 “앱 로딩 중”이 표시된 것은 문제가 Portainer보다 광범위했음을 시사합니다

CasaOS도 애플리케이션 목록을 불러오는 데 어려움을 겪었습니다. Docker를 사용할 수 없거나, Docker API가 호환되지 않는 방식으로 변경되었거나, 데몬의 데이터 루트가 없거나, 부팅된 호스트가 더 이상 예상한 시스템 상태가 아닌 경우 이러한 문제가 발생할 수 있습니다.

이후 발생한 “올바른 부팅 장치를 선택하세요” 문제로 인해 복구 우선순위가 달라졌습니다

재시작 후 시스템은 정상적으로 부팅되지 않았고, 사용자가 부팅 선택을 변경한 뒤에야 다시 작동했습니다. 이후 CasaOS에는 앱이 없었지만 대용량 HDD는 계속 연결된 상태였습니다.

이는 다른 부팅 디스크/루트 파일 시스템이 선택되었거나 시스템 파티션/상태가 변경되었을 가능성을 제기합니다. 소스만으로는 어느 쪽인지 입증할 수 없습니다.

CasaOS를 재설치하기 전에 AppData를 보존하세요

사용자가 가장 중요하게 여긴 항목은 다음과 같습니다.

/home/casaos 프로젝트 파일;
AppData 아래의 Jellyfin 메타데이터;
HDD에 저장된 미디어 파일;
복구 가능한 Docker/CasaOS 구성.

Docker를 재설치하거나 초기화하기 전에 이러한 영구 데이터를 다른 디스크나 시스템에 복사하세요. 컨테이너를 다시 만드는 작업은 애플리케이션 데이터베이스와 메타데이터를 다시 만드는 것보다 대체로 쉽습니다.

무엇이 아직 참조되고 있는지 알기 전에는 Docker를 무분별하게 정리하지 마세요

이미지 정리를 통해 공간을 확보할 수는 있지만, 볼륨이나 데이터 루트 디렉터리를 삭제하면 보존하려는 애플리케이션 상태가 사라질 수 있습니다. 먼저 컨테이너, 볼륨, 바인드 마운트, AppData 경로를 확인하세요.

Debian 및 Docker 업데이트를 CasaOS 플랫폼의 일부로 취급하세요

CasaOS는 기본 Linux 호스트 위에서 작동합니다. 광범위한 apt upgrade는 CasaOS가 의존하는 Docker, 커널, systemd, 네트워킹, 스토리지 패키지를 업데이트할 수 있습니다. 정상적으로 작동하는 NAS에 주요 호스트 업그레이드를 적용하기 전에 신중하게 테스트하고 시스템 및 애플리케이션 백업을 유지하세요.

Portainer/CasaOS 복구 FAQ

소스에서 Docker 29만이 모든 문제를 일으켰다고 입증했나요?

아니요. 시스템의 여유 공간이 거의 없었고, 이후 부팅 장치/상태 문제도 발생했습니다.

Docker API 불일치가 확인되었나요?

예. API 1.43을 사용하는 Docker 24 CLI가 Docker 29 데몬에서 거부되었으며, 해당 데몬에는 최소 1.44가 필요했습니다.

AppData를 복사하기 전에 CasaOS를 재설치해야 하나요?

아니요. 디스크에 계속 접근할 수 있다면 먼저 중요한 AppData, 홈 디렉터리 파일, 미디어를 보존하세요.