Immich는 ZimaOS 시스템 드라이브가 감당하도록 설계된 용량을 훨씬 초과하는 스토리지를 사용할 수 있습니다. 특히 휴대폰 업로드, 썸네일, 인코딩된 동영상, 머신러닝 모델, PostgreSQL 데이터베이스의 용량이 증가하기 시작하면 더욱 그렇습니다. IceWhale 커뮤니티의 원본 가이드는 2025년 4월 ZimaOS 사용자 지정 설치 중 일부 볼륨 매핑을 변경하여 이 문제를 해결했고, Immich 데이터를 ZimaOS 드라이브 대신 RAID 볼륨에 저장하도록 했습니다.
이 우회 방법은 컨테이너가 어떻게 연결되는지 이해하는 데 유용하지만, 현재의 보편적인 방법으로 간주해서는 안 됩니다. 이후 답변에서는 매핑을 변경한 뒤 설치 실패, 반복 재부팅, 비정상 상태의 PostgreSQL 컨테이너, 심지어 사진 업로드 손상까지 발생했다는 보고가 있었습니다. 또한 ZimaOS는 내장 마이그레이션 도구를 추가하고 개선했으며, 최신 Immich Docker Compose 릴리스에서는 호스트 측 변수(예: 다음과 같은 변수)를 사용합니다. UPLOAD_LOCATION 및 DB_DATA_LOCATION현재 시스템에서는 목적에 맞는 경우 먼저 ZimaOS에 내장된 마이그레이션 경로를 사용하고, 사용자 지정 Immich 스토리지 레이아웃이 꼭 필요한 경우에만 수동 볼륨 편집을 사용하세요.
2025년 원본 ZimaOS Immich 가이드에서 변경한 내용
커뮤니티 튜토리얼에서는 ZimaOS 사용자 지정 설치 또는 설치 후 앱의 설정 화면을 사용해 서비스 탭을 하나씩 확인했습니다. 목표는 Immich가 예상하는 컨테이너 측 경로는 유지하면서 영구 Immich 데이터를 더 큰 RAID 위치로 리디렉션하는 것이었습니다.
데이터베이스: 호스트 경로는 변경하고 컨테이너 경로는 유지
데이터베이스 탭에서 작성자는 ZimaOS 측 스토리지 위치를 RAID 경로로 변경하고 데이터베이스 디렉터리 접미사는 그대로 유지했습니다. 핵심 원칙은 컨테이너 내부의 오른쪽 경로를 다시 작성하지 않는 것입니다. 컨테이너 대상 위치를 변경하면 Immich 패키지 또는 Compose 구성에서 정의한 경로에 PostgreSQL 데이터가 있어야 하므로 서비스가 중단될 수 있습니다.
현재 Immich Docker Compose 문서에서는 다음을 통해 호스트 위치를 노출합니다. DB_DATA_LOCATIONImmich는 네트워크 공유가 PostgreSQL 데이터베이스에 지원되지 않는다는 점도 경고하므로, 데이터베이스는 SMB 또는 NFS 공유가 아닌 안정적인 로컬 연결 스토리지에 두어야 합니다.
머신 러닝: 필요한 경우에만 모델 캐시 경로 변경
원래 가이드에서는 컨테이너 측 캐시 경로는 그대로 둔 채 호스트 측 머신 러닝 모델 캐시도 다른 위치로 지정했습니다. 이 캐시를 옮기면 작은 시스템 디스크의 공간을 절약할 수 있지만, 다운로드한 모델은 일반적으로 다시 생성할 수 있으므로 사진 라이브러리와 데이터베이스를 보호하는 것만큼 중요하지는 않습니다.
Immich 서버: 가장 주의해야 할 볼륨 섹션
Immich 서버 탭은 작성자가 가장 쉽게 설정을 망가뜨릴 수 있다고 느낀 부분이었습니다. 업로드 및 기타 영속 미디어 디렉터리가 RAID 저장소를 사용하도록 추가 호스트 매핑을 구성했습니다. 해당 스레드에서는 컨테이너 측 경로는 함부로 변경하지 말고, 의도한 호스트 측 위치만 변경해야 한다는 점을 반복해서 강조합니다.
원래 안내에서는 Redis 탭의 저장소를 변경할 필요가 없었습니다. 이는 모든 볼륨 항목에 일괄적으로 검색 및 바꾸기를 적용해서는 안 되는 또 다른 이유입니다. Immich 서비스마다 영속성 요구 사항이 다르기 때문입니다.
현재 시스템에서는 먼저 ZimaOS 데이터 마이그레이션 사용
이후 논의에서 가장 중요한 업데이트는 이제 ZimaOS가 전용 마이그레이션 작업 흐름을 제공한다는 점입니다. 해당 스레드의 IceWhale 팀 답변에서는 앱 데이터를 수동으로 복사하면 오류가 발생할 수 있다고 구체적으로 경고했으며, 대부분의 경우 마이그레이션 기능을 사용할 것을 권장했습니다.
현재 ZimaOS 데이터 마이그레이션 가이드에는 이동할 수 있는 저장소 카테고리로 Docker 이미지, Docker 애플리케이션 데이터, 사용자 데이터베이스의 세 가지가 나열되어 있습니다. 일반적인 경로는 다음과 같습니다.
- 설정 > 데이터 마이그레이션을 엽니다.
- 이동하려는 저장소 카테고리를 선택합니다.
- 위치 수정을 선택합니다.
- 대상 디스크 또는 저장 공간을 선택합니다.
- 경고를 검토하고 마이그레이션을 시작한 다음 완료 보고서가 표시될 때까지 기다립니다.
이 내장 마이그레이션은 단순히 Docker 애플리케이션 데이터를 ZimaOS 시스템 드라이브에서 분리하려는 경우 더 나은 출발점입니다. 또한 수동으로 이동한 후 경로, 권한 또는 심볼릭 링크가 일관되지 않은 상태로 남을 가능성도 줄여 줍니다.
Immich는 SSD에 설치하고 사진은 RAID에 저장하려면 어떻게 해야 하나요?
이후 스레드에서 더 실용적인 장기 레이아웃에 관한 질문이 제기되었습니다. 애플리케이션과 성능에 민감한 구성 요소는 SSD에 두고, 대용량 사진 라이브러리는 RAID에 두는 방식입니다. 원 작성자는 이 분할 구성을 테스트하지 않았으므로, 해당 스레드 자체에서는 검증된 ZimaOS 설정 방법을 제공하지 않습니다.
현재 Immich 문서에는 적절한 레이아웃을 정의하는 데 도움이 되는 두 가지 개념이 있습니다. 업로드된 Immich 미디어의 경우 공식 Docker Compose 구성은 다음을 사용합니다. UPLOAD_LOCATION 미디어 저장소의 호스트 경로로 사용합니다. Immich가 관리하는 업로드 영역으로 가져오지 않고 기존 사진 컬렉션을 색인하도록 하려면 Immich의 외부 라이브러리를 사용할 수 있습니다.
현재 표준 Immich Compose 배포에서 관련 환경 변수는 개념적으로 다음과 같습니다.
UPLOAD_LOCATION=/path/to/large-media-storage
DB_DATA_LOCATION=/path/to/local-database-storage이 경로를 이전 ZimaOS 앱 정의에 그대로 붙여 넣지 마세요. 먼저 설치된 정확한 Immich 패키지에서 사용하는 Compose 또는 사용자 지정 설치 구성을 확인하세요. 현재 Immich 공식 Compose 파일은 다음을 마운트합니다. ${UPLOAD_LOCATION} 서버 컨테이너에 연결하며, ${DB_DATA_LOCATION} PostgreSQL로 연결하지만, 이전 릴리스와 커뮤니티 패키지는 내부 대상 경로가 다를 수 있습니다.
최신 공식 정보는 Immich Docker Compose 설치 가이드 및 Immich 외부 라이브러리 가이드를 참조하세요.
수동 볼륨 변경으로 Immich가 고장 날 수 있는 이유
사용자들이 스토리지 매핑을 변경한 후 발생한 여러 실패 사례가 답변에 나타납니다. 한 참여자는 처음에 앱이 고장 났다고 보고했지만, 나중에는 여러 번 재부팅한 후 정상적으로 작동하기 시작했다고 말했습니다. 또 다른 사용자는 반복적인 실험으로 Immich가 고장 났고 휴대폰에서 업로드한 사진 중 일부가 손상되었다고 했습니다. 이후에는 PostgreSQL 서비스가 비정상 상태가 되는 설치 실패가 반복되었다는 보고도 있었습니다.
이러한 보고만으로 단일 공통 버그가 입증되는 것은 아닙니다. 하지만 저장소 마이그레이션을 단순한 경로 변경이 아니라 데이터 무결성 작업으로 처리해야 하는 이유는 보여 줍니다. 확인해 볼 만한 일반적인 원인은 다음과 같습니다.
- 잘못된 컨테이너 대상 경로: 호스트 경로는 사용자 지정할 수 있지만, 컨테이너 내부 경로는 해당 Immich 배포에서 요구하는 경로와 일치해야 합니다.
- 권한: 대상 위치는 파일을 소유한 컨테이너 사용자 또는 서비스가 쓸 수 있어야 합니다.
- 데이터베이스 배치: PostgreSQL에는 안정적인 로컬 저장소가 필요하며, 지원되지 않는 네트워크 공유에 배치해서는 안 됩니다.
- 불완전한 이동: 기존 Immich 데이터 트리의 일부만 수동으로 복사하면 데이터베이스와 미디어 저장소의 동기화가 깨질 수 있습니다.
- 버전 불일치: Immich의 볼륨 레이아웃은 변경되어 왔으므로, 이전 패키지용으로 작성된 지침이 Immich v2, v3 또는 이후 ZimaOS App Store 정의와 일치하지 않을 수 있습니다.
더 안전한 Immich 저장소 마이그레이션 체크리스트
- 볼륨 매핑을 변경하기 전에 Immich 데이터베이스와 대체할 수 없는 미디어를 백업하세요.
- 사용 중인 Immich 버전과 ZimaOS App Store 패키지를 확인하세요.
- 모든 앱 데이터를 옮길지, 대용량 미디어 라이브러리만 옮길지 결정하세요.
- 일반적인 ZimaOS 앱 데이터를 옮기는 경우 개별 컨테이너 경로를 수정하기 전에 설정 > 데이터 마이그레이션을 시도해 보세요.
- 사용자 지정 Immich 레이아웃을 사용하는 경우, 변경하기 전에 기존의 모든 호스트 경로와 컨테이너 대상 경로를 기록하세요.
- 정확한 Immich 버전의 문서에서 다른 경로를 명시적으로 요구하지 않는 한, 컨테이너 내부 대상 경로는 변경하지 마세요.
- 컨테이너를 다시 만들기 전에 대상 파일 시스템이 마운트되어 있고 쓰기 가능한지 확인하세요.
- PostgreSQL 데이터 디렉터리를 지원되지 않는 네트워크 공유에 두지 마세요.
- 마이그레이션 후 소량의 테스트 파일을 업로드하고, 나머지 라이브러리를 옮기기 전에 원본 파일, 썸네일, 동영상 재생, 메타데이터 및 새 모바일 업로드가 정상인지 확인하세요.
- 새 저장소에서 데이터베이스와 미디어 파일을 모두 확인할 때까지 기존 복사본을 유지하세요.
커뮤니티 답변에서 원래 가이드에 추가된 내용
가장 유용한 답변들은 원래 튜토리얼에 대한 해석을 세 가지 측면에서 바꾸었습니다. 첫째, 수동 매핑이 가능할 수 있지만 정확한 앱 버전, 저장소 권한, 재시작 상태에 민감하다는 점을 보여 주었습니다. 둘째, 사용자들은 모든 Immich 구성 요소를 동일한 어레이로 옮기기보다 SSD와 RAID를 분리한 구성을 원했습니다. 셋째, IceWhale 팀원은 기본 제공 마이그레이션 기능을 권장하며 수동 복사로 인해 오류가 발생할 수 있다고 경고했습니다.
따라서 2025년의 원래 게시물은 이후의 모든 Immich 또는 ZimaOS 릴리스에 적용되는 고정된 사양이 아니라, 당시 작동했던 커뮤니티 예시로 이해하는 것이 가장 적절합니다. 현재 ZimaOS 인터페이스에 스크린샷에 표시된 것과 동일한 Custom Install 필드가 더 이상 나타나지 않는다면, 이전 필드를 재현하려 하지 말고 현재 마이그레이션 UI를 따르면서 설치된 앱의 Compose 구성을 확인하세요.
ZimaOS Immich 스토리지 FAQ
ZimaOS 시스템 드라이브 대신 RAID 드라이브에 Immich를 설치할 수 있나요?
그렇습니다. 다만 ZimaOS 애플리케이션 데이터를 이동하는 것과 사용자 지정 Immich 미디어 레이아웃을 설계하는 것은 구분해야 합니다. 현재 ZimaOS 버전에서는 Docker 애플리케이션 데이터를 다른 위치로 옮기려는 경우 먼저 내장된 Data Migration 기능을 사용하세요. 수동 볼륨 매핑은 의도적으로 스토리지를 분리하는 설계에 한해 사용하는 것이 좋습니다.
Custom Install에서 오른쪽 Immich 볼륨 경로를 변경해야 하나요?
정확한 Immich 배포 방식에 대한 문서에서 그렇게 하도록 안내하지 않는 한, 권장하지 않습니다. 원래 커뮤니티 가이드는 컨테이너 측 대상 경로를 유지하면서 호스트 측 위치를 변경했습니다. 내부 대상 경로를 다시 지정하면 서비스가 예상되는 데이터베이스, 캐시 또는 미디어 디렉터리를 찾지 못할 수 있습니다.
Immich는 SSD에 유지하고 사진만 RAID에 저장할 수 있나요?
원칙적으로는 가능합니다. 현재 Immich는 호스트 업로드 위치 선택과 External Libraries 마운트를 모두 지원합니다. 정확한 ZimaOS 매핑은 설치된 Immich 패키지와 버전에 따라 다르므로 경로를 변경하기 전에 현재 Compose 정의를 확인하세요.
스토리지 위치를 변경하면 PostgreSQL이 비정상 상태가 되는 이유는 무엇인가요?
가능한 원인으로는 잘못된 마운트 대상, 권한 누락, 불완전한 데이터베이스 파일 또는 지원되지 않는 스토리지가 있습니다. 전체 데이터베이스 디렉터리가 올바르게 이동되었는지, 대상 위치가 로컬이고 쓰기 가능한지, 컨테이너 대상 경로가 설치된 Compose 구성과 여전히 일치하는지 확인하세요.
Immich AppData 폴더를 다른 디스크에 그냥 복사해도 되나요?
이는 현재 ZimaOS에서 권장하는 경로가 아닙니다. IceWhale 팀원은 해당 스레드에서 수동 복사로 인해 오류가 발생할 수 있다고 명확히 경고했으며, 대부분의 앱 이동에는 마이그레이션 기능을 사용할 것을 권장했습니다.
2025년 4월 스크린샷 가이드는 아직 최신인가요?
ZimaOS 볼륨 매핑에 대한 역사적 설명으로는 여전히 유용하지만, 그 이후 ZimaOS의 마이그레이션 기능과 Immich의 Compose 레이아웃이 모두 변경되었습니다. 스크린샷은 초기 설정을 보여 주는 참고 자료로만 사용하고, 변경 사항을 적용하기 전에 현재 설치 환경에서 표시되는 필드와 경로를 확인하세요.
