새 홈 서버를 위한 안전한 Immich 마이그레이션 체크리스트

Eva Wong 는 테크니컬 라이터 이자 상주 메이커 로 ZimaSpace에서 활동합니다. 평생 기술을 사랑해 온 그녀는 홈랩과 오픈 소스 소프트웨어에 열정을 품고 있으며, 복잡한 기술 개념을 누구나 이해하기 쉬운 실습 가이드로 풀어내는 데 전문성을 갖추고 있습니다. Eva는 셀프 호스팅이 어렵고 부담스러운 일이 아니라 즐거워야 한다고 믿습니다. 그녀는 튜토리얼을 통해 커뮤니티가 하드웨어 설정의 어려움을 풀어내고, 첫 NAS를 조립하는 것부터 Docker 컨테이너를 능숙하게 다루는 것까지 도전하도록 돕습니다.

안전한 Immich 마이그레이션은 무엇을 보존해야 하는지 확인하는 것부터 시작합니다. 즉, 사진 파일, 데이터베이스, 그리고 새 호스트에서 두 요소를 다시 연결하는 배포 설정입니다.

홈 서버에서는 각 요소를 서로 다른 시점에 옮기거나 잘못된 경로로 새 환경을 시작할 때 마이그레이션 위험이 발생하는 경우가 많습니다. 이전 서버를 롤백용 복사본으로 유지하고, 피할 수 있는 쓰기 작업은 중지하고, 현재 버전과 저장소 매핑을 기록한 다음, 검증이 완료된 데이터 세트 하나를 새 시스템으로 옮기세요. 아래 체크리스트를 따르면 새 인스턴스에서 로그인하고 원본 라이브러리를 찾고 작업을 처리하며 빈 상태로 되돌아가지 않고 재부팅할 수 있을 때까지 작업을 되돌릴 수 있습니다.

원본을 동결하고 정상 작동 상태를 기록하기

새 서버가 아니라 현재 정상 작동 중인 서버에서 시작하세요. Immich 버전, Compose 또는 앱 스토어 정의, 데이터베이스 및 저장 경로를 제어하는 환경 변수, 사진 라이브러리 위치, 데이터베이스 위치, 외부 라이브러리 마운트를 기록하세요. 현재 서버 URL과 검증에 사용할 사용자 계정도 적어 두세요.

이 목록을 작성하는 목적은 마이그레이션이 자신도 모르게 업그레이드, 경로 재설계, 네트워크 변경을 동시에 진행하는 상황을 방지하는 것입니다. 복원이 성공적으로 끝날 때까지 애플리케이션 버전과 논리적 저장소 구조를 최대한 그대로 유지하세요. 버전 변경은 새 환경이 정상적으로 작동하는 것을 확인한 뒤 처리할 수 있습니다.

복사하기 전에 가정에서 감당할 수 있다면 새 업로드를 중지하거나 일시 중지하세요. 그게 현실적으로 어렵다면 전환 시간을 정하고 마지막으로 짧게 동기화할 계획을 세우세요. 이 단계의 완료 조건은 원본 파일의 위치, 데이터베이스 상태의 위치, 동일한 연결 관계를 재현하는 구성 정보를 확인할 수 있는 문서화된 원본 경로 맵입니다.

데이터베이스, 에셋, 구성 정보를 하나의 마이그레이션 세트로 수집하기

데이터베이스와 미디어 파일을 서로 독립적인 백업 두 개가 아니라 하나의 복구 세트로 취급하세요. 현재 Immich 데이터베이스 백업에는 메타데이터와 파일 참조가 들어 있지만 사진이나 동영상 자체는 포함되지 않으므로, 데이터베이스 백업은 해당 UPLOAD_LOCATION의 내용 및 별도로 관리하는 외부 라이브러리 데이터와 함께 옮겨야 합니다.

사용 가능한 마이그레이션 세트에는 자산, PostgreSQL 상태, 그리고 이를 다시 연결하는 구성이 필요합니다. 완전한 Immich 백업 세트에는 업로드된 자산, 지원되는 데이터베이스 백업, 배포 구성이 포함되며, 복원 테스트를 통해 세트가 작동하는지 확인합니다. 대상 환경을 하나의 복구 시점에 맞출 수 있도록 이 항목들을 함께 보관하세요.

대상 서버를 건드리기 전에 마이그레이션 자료를 확인하세요. 데이터베이스 덤프가 비어 있지 않은지 확인하고, 복사한 라이브러리에서 원본 파일 여러 개를 표본 검사하며, Compose 파일과 환경 파일이 같은 마이그레이션 폴더나 문서 세트에 있는지 확인하세요. 구성 요소 중 하나라도 확인할 수 없다면 여기서 중단하고 새로 복사하세요. 새 서버에서 임시방편으로 보완하지 마세요.

서로 충돌하는 상태를 만들지 않고 새 호스트 준비하기

먼저 대상 디렉터리와 마운트를 만들고, 새 호스트에서 사용할 정확한 경로에 의도한 디스크나 네트워크 공유가 연결되어 있는지 확인하세요. NAS 마운트가 누락되면 일반 빈 디렉터리가 남을 수 있으며, 컨테이너는 그 대체 경로를 사용해 문제없이 초기화될 수 있습니다.

런타임을 설치하고 배포 정의를 다시 만들되, 이전 상태를 복원하기 전에 빈 Immich 인스턴스에 업로드나 구성이 쌓이지 않도록 하세요. 마이그레이션 계획에 통제된 경로 변경이 명시되어 있지 않다면 인증 정보, 데이터베이스 이름, 스토리지 변수, 외부 라이브러리 마운트 경로를 원본과 일치시키세요.

새 서버에서 호스트 측 경로를 다르게 설정해야 한다면, 컨테이너에서 보이는 경로와 데이터베이스의 요구 사항이 서로 일치하도록 유지하면서 경로를 신중하게 매핑하세요. 적용된 마운트가 복사된 데이터 위치를 가리키고 전체 애플리케이션을 시작하기 전에 모든 경로 변환을 설명할 수 있어야 대상 환경이 준비된 것입니다.

상태를 복원하고 모든 스토리지 경로를 다시 연결하기

백업을 생성한 Immich 버전에 적합한 복구 절차를 사용해 데이터베이스를 복원한 다음, 데이터베이스가 준비된 후에만 나머지 서비스를 시작하세요. 최신 설치에서 다른 복원 절차를 사용하는 경우, 오래된 가이드의 데이터베이스를 파괴하는 명령을 임의로 사용하지 마세요.

전환 과정에서는 정상적으로 사용을 재개하기 전에 데이터베이스와 스토리지의 관계를 유지하세요. 검증된 Immich 마이그레이션 순서도 같은 원칙을 따릅니다. 애플리케이션은 새 라이브러리를 초기화해 처음부터 다시 구축하는 것이 아니라, 복원된 데이터베이스 상태와 지정된 미디어 경로를 사용해 열려야 합니다.

시작한 뒤에는 대규모 백그라운드 작업을 실행하기 전에 스토리지 액세스를 확인하세요. 날짜가 서로 다른 오래된 항목 몇 개를 열고, 썸네일이 로드되는지 확인하세요. 마이그레이션 전부터 있던 앨범과 인물 또는 검색 결과도 확인하고, 외부 라이브러리를 사용한다면 해당 라이브러리를 읽을 수 있는지 확인하세요. 새 사용자 설정 화면이나 비어 있는 타임라인이 나타나면 중단 신호입니다. 새 상태를 기록하기 전에 데이터베이스와 마운트 매핑을 다시 확인하세요.

기존 서버를 폐기하기 전에 기존 작업 부하를 검증하세요

첫 로그인에 성공했다고 해서 마이그레이션이 끝난 것은 아닙니다. 평소 사용하는 클라이언트에서 삭제해도 되는 테스트 사진 하나를 업로드하고, 예상한 호스트 스토리지에 표시되는지 확인한 다음 Immich에서 삭제하고 라이브러리가 정상인지 검증하세요. 이 과정을 통해 기존 데이터를 읽을 수 있는지만 확인하는 것이 아니라 전체 쓰기 경로를 점검할 수 있습니다.

새 홈 서버를 재부팅하고 가정에서 중요한 항목을 다시 확인하세요. 브라우저 로그인, 모바일 백업 연결, 오래된 사진 몇 장, 검색, 대표 동영상, 작업 대기열, 그리고 평소 설정에 포함된 경우 원격 액세스를 확인하세요. 호스트를 재부팅한 뒤에도 같은 상태가 유지되고 Immich가 시작되기 전에 스토리지 마운트가 완료되어야 마이그레이션이 끝난 것입니다.

롤백 기간 동안 기존 서버는 전원을 끈 채 그대로 두고, 즉시 초기화하지 마세요. 새 인스턴스가 예상치 못한 빈 폴더에 쓰기를 시작하거나, 재부팅 후 기존 라이브러리를 재현하지 못하거나, 설명할 수 없는 데이터베이스 오류가 나타나면 새 업로드를 중단하고 마이그레이션 데이터를 비교하는 동안 검증된 기존 소스로 되돌아가세요. 대상 서버가 정상적으로 사용되고 새로운 백업 테스트까지 통과한 후에만 기존 호스트를 폐기하세요.

지원 및 팁

더 읽어보기

Get More Builds Like This

Stay in the Loop

Get updates from Zima - new products, exclusive deals, and real builds from the community.

Stay in the Loop preferences

We respect your inbox. Unsubscribe anytime.