이 글에는 겉보기에는 비슷하지만 보편적인 해결책이 하나로 통하지 않는 여러 Immich 오류 사례가 포함되어 있습니다. 원 게시자의 회색으로 비활성화된 Immich 앱은 sudo systemctl restart docker를 실행하자 즉시 복구되었습니다. 다른 사용자는 같은 명령을 실행했지만 여전히 Immich를 시작할 수 없었습니다. 이후 오류에는 호스트 포트 2283이 이미 할당되어 있음이 표시되었으며, 이는 작동하지 않는 Docker 데몬과는 다른 문제입니다.
핵심 교훈은 다음과 같습니다. 운영 체제를 업데이트한 후에는 먼저 Docker 자체에 문제가 있는지, 특정 Compose 프로젝트 하나에만 문제가 있는지, 아니면 오래된 컨테이너나 중복 컨테이너가 Immich에 필요한 포트를 이미 사용하고 있는지 확인해야 합니다.
먼저 Docker 서비스 상태 확인
777-Spider는 Docker가 정상적으로 실행되고 있는지 확인하라고 처음 권고했습니다. 이후 원 게시자는 Docker를 다시 시작했고 모든 것이 다시 작동한다고 보고했습니다.
Docker를 다시 시작하면 호스트의 모든 컨테이너에 영향을 주므로 신중하게 실행하고 다른 애플리케이션도 다시 시작될 수 있음을 예상해야 합니다.
Docker 재시작이 모든 Immich 문제를 해결한 것은 아님
Chris는 같은 Docker 재시작으로 다른 앱은 복구되었지만 Immich는 복구되지 않았다고 보고했습니다. 이는 systemctl restart docker를 확실한 해결책으로 간주해서는 안 된다는 직접적인 증거입니다.
한 오류에는 포트 2283이 이미 할당되었다고 명시되어 있었음
현재 동일한 문제가 발생했다면 무엇이 2283을 사용하고 있는지 확인한 후 삭제하거나 다시 생성해야 합니다. 오래된 Immich 컨테이너가 중복으로 존재하거나 Compose 프로젝트가 일부만 다시 생성된 경우 포트가 계속 점유될 수 있습니다.
Compose 앱 시작 실패는 애플리케이션 스택 오류
Docker에서 Paperless나 다른 앱은 정상적으로 실행되지만 Immich만 Compose 오류와 함께 실패한다면, 전체 운영 체제를 다시 설치하기보다 Immich 서비스 상태와 로그, 현재 Compose 정의를 확인해야 합니다.
재설치로 한 사용자는 해결했지만 시간과 데이터 재복사 비용이 발생함
Chris는 결국 Immich를 다시 설치하고 사진을 다시 복사했습니다. 또한 백업의 중요성을 명시적으로 경고했습니다. 이는 모든 사용자에게 확인된 해결책이 아니라 최후의 수단으로 사용자가 선택한 방법이었습니다.
재설치 전에 Immich AppData와 데이터베이스 보존
Immich의 상태는 사진 폴더만으로 구성되지 않습니다. 컨테이너나 볼륨을 삭제하기 전에 데이터베이스, 애플리케이션 설정 및 라이브러리 경로를 보존해야 합니다. 최신 ZimaOS에서는 중요한 앱 데이터가 일회용 컨테이너 외부에 저장됩니다.
현재 ZimaOS의 영구 앱 데이터 모델을 사용하세요.
이 문제를 현재 1.7.1 Immich 회귀 버그로 간주하지 말 것
이 글의 사례는 ZimaOS 1.5.4와 더 오래된 Immich 세대에 관한 것입니다. 현재 ZimaOS와 Immich v3는 상당히 최신 버전이므로, 2026년용 해결 방법을 적용하기 전에 현재 환경에서 정확히 동일한 오류가 재현되는지 확인해야 합니다.
데이터베이스 마이그레이션 후 Immich를 이전 버전으로 되돌리는 것은 위험할 수 있음
한 사용자는 이전 Immich 버전으로 되돌렸다고 말했습니다. 현재의 메이저 버전 업그레이드는 데이터베이스와 애플리케이션 상태를 마이그레이션할 수 있으므로, 단순히 이미지 태그를 이전 버전으로 변경하기보다 해당 Immich 릴리스의 안내에 따라 다운그레이드 지원 여부를 확인해야 합니다.
포트 충돌이 발생하면 기존 리스너를 확인해야 함
원본 오류에는 Docker가 이미 할당된 호스트 포트 2283에 바인딩할 수 없다고 명시되어 있습니다. 오래된 Immich 컨테이너가 계속 실행 중이거나, 두 번째 스택이 같은 포트를 사용하거나, 다른 서비스가 해당 포트에 매핑된 경우 이런 문제가 발생할 수 있습니다.
무엇이 현재 해당 포트와 연결되어 있는지 확인하고 어느 스택이 포트를 사용해야 하는지 결정하기 전에는 아무것도 삭제하지 마세요.
회색 앱 타일은 Immich 데이터 손실이 아니라 Docker 상태의 증상일 수 있음
원 게시자의 경우 Docker를 다시 시작하자 모든 앱이 복구되었습니다. 이는 회색으로 표시된 Immich 상태가 컨테이너 런타임 문제의 결과였으며, 사진 데이터베이스나 라이브러리가 삭제되었다는 증거가 아니었음을 의미합니다.
다른 참여자는 같은 재시작으로 Immich를 복구하지 못했습니다. 이는 UI에 나타난 증상만으로는 근본 원인을 진단하기에 충분하지 않다는 점을 보여 줍니다.
재설치 전에 Compose 오류 확인
“Compose 앱 시작 실패”는 포괄적인 오류 메시지일 뿐입니다. 실제로 유용한 정보는 underlying 서비스나 컨테이너 메시지에 있습니다. 예를 들면 포트 충돌, 누락된 볼륨, 데이터베이스 상태 점검 실패, 이미지 가져오기 문제, 잘못된 YAML 또는 권한 문제 등입니다.
스택을 다시 생성하기 전에 실패 로그를 보존하세요. 재설치하면 문제를 보여 주는 증거가 사라질 수 있습니다.
현재 Immich v3에서는 무작정 롤백하는 것이 더 위험함
Immich는 이후 주요 스키마 및 배포 변경을 거쳤습니다. 2026년에 한 사용자가 v1.x 릴리스를 롤백한 적이 있다는 이유만으로, 최신 v3 데이터베이스를 임의의 이전 이미지에서 실행해도 안전하다고 볼 수는 없습니다.
최신 Immich 마이그레이션 및 롤백 지침을 따르고, 메이저 버전을 변경하기 전에 검증된 데이터베이스와 라이브러리 백업을 보관하세요.
재설치가 필요하다면 먼저 영구 경로를 보존
사진 라이브러리, PostgreSQL 데이터, 설정, 머신러닝 및 캐시 경로, 현재 볼륨 매핑을 기록하세요. 일회용 컨테이너를 제거하는 것과 호스트의 영구 폴더를 삭제하는 것은 전혀 다릅니다.
성공적인 초기화 재설치는 의도한 영구 데이터를 다시 연결하거나 지원되는 백업 경로를 통해 복원해야 합니다. 유일한 사진 라이브러리를 처음부터 다시 복사해야 하는 상황이 되어서는 안 됩니다.
Immich 1.5.4 오류 FAQ
Docker를 다시 시작하면 원 게시자의 Immich 문제가 해결되었나요?
예.
해당 스레드의 모든 사용자에게도 문제가 해결되었나요?
아니요. 다른 사용자의 Immich는 계속 실패했고 이후 포트 2283 충돌이 표시되었습니다.
현재 사용자는 즉시 Immich를 다시 설치해야 하나요?
아니요. 먼저 Docker 서비스 상태, Compose 상태, 포트 사용 주체 및 영구 데이터를 확인하세요.
