Jellyfin 컨테이너 및 종속 항목 사전 업그레이드 체크리스트

Jellyfin 컨테이너를 업그레이드하기 전에 배포 환경의 양쪽을 모두 보존하세요. 영구 Jellyfin 상태와 해당 상태에 접근하는 방법을 알고 있는 정확한 컨테이너 정의가 그것입니다. 새 이미지를 가져오는 일은 쉽지만, 마이그레이션된 데이터베이스나 변경된 마운트, 잊어버린 장치 매핑을 복구하는 일은 쉽지 않습니다.

체크리스트는 의존성 순서대로 사용하세요. 먼저 데이터를 복구할 수 있는지 확인하고, 현재 이미지와 런타임 설정을 기록한 다음, 업그레이드 경로를 검토하고, 그 후에야 이미지를 교체하세요. 이후 롤백 사본을 삭제하기 전에 동일한 라이브러리, 사용자, 재생 모드, 예약 작업 및 재시작 동작을 테스트하세요.

마지막으로 정상 작동한 이미지와 컨테이너 정의 기록

현재 Jellyfin 이미지 태그와 가능하다면 다이제스트도 저장하세요. 포트, 네트워크, 마운트, 환경 값, 재시작 정책, 사용자 매핑, 추가 그룹, GPU 장치 및 리버스 프록시 연결 관계가 포함된 Compose 파일이나 앱 정의를 내보내거나 복사하세요.

Jellyfin 공식 컨테이너 문서에서는 latest와 같은 이동 태그와 명시적인 메이저, 마이너 및 패치 태그를 구분합니다. Jellyfin 이미지 태그 동작 “어제는 latest가 작동했어”라고 기억하는 것보다 정확히 작동한 버전을 알고 있을 때 롤백이 더 쉽습니다.

새 버전이 전체 검증 기간을 통과할 때까지 이전 이미지를 정리하거나 저장한 정의를 삭제하지 마세요. 영구 데이터에 영향을 주기 전에 업그레이드가 실패하면, 보존된 이미지와 정의가 가장 개입이 적은 복구 경로를 제공합니다.

복구 가능한 Jellyfin 상태 백업 생성

이미지를 변경하기 전에 Jellyfin 데이터 및 구성 디렉터리를 보호하세요. 백업은 실행 중인 애플리케이션 경로 외부에 있어야 하며 독립적으로 읽을 수 있어야 합니다. 동일한 데이터 세트에 두 번째 복사본이나 스냅샷을 만드는 것은 어떤 장애를 보호하는지 이해하고 있을 때만 유용합니다.

Jellyfin의 백업 문서에서는 마이그레이션이 적용된 후에는 일반적인 다운그레이드 방법이 없기 때문에 업그레이드 후 데이터를 복원해야 할 수 있다고 경고합니다. 또한 기본 제공 백업과 수동 파일 복사에 필요한 정상 종료 조건도 설명합니다. Jellyfin 백업 및 복원 안내

컨테이너 워크플로에서는 ZimaSpace의 업데이트 전 롤백 지점 워크플로가 같은 원칙을 다룹니다. 영구 경로를 식별할 수 없거나 백업 내용을 확인할 수 없다면 여기서 중단하세요.

마운트, UID/GID 및 하드웨어 종속성 캡처

모든 바인드 마운트와 명명된 볼륨을 나열하고 각각 읽기 전용인지 쓰기 가능한지 기록하세요. 런타임 UID/GID, 그룹 구성원 및 Jellyfin 소유 데이터 디렉터리의 소유권을 기록하세요. 하드웨어 가속이 활성화되어 있다면 GPU 또는 렌더링 장치 매핑도 캡처하세요.

Jellyfin 컨테이너 가이드에서는 미디어, 구성 및 캐시를 별도로 마운트하며 컨테이너가 지정된 UID/GID로 실행될 수 있음을 보여 줍니다. 영구 경로 및 사용자 매핑 이러한 값은 장식이 아니라 종속성입니다. 컨테이너를 다시 만들면 정상적으로 시작되면서도 빈 구성 디렉터리를 보거나 장치에 대한 권한을 잃을 수 있습니다.

현재 상태라고 생각하는 템플릿뿐 아니라 실제 실행 중인 컨테이너의 유효 설정과 저장한 정의를 비교하세요. 런타임에 수동으로 변경한 사항이 Compose 또는 NAS 앱 정의에 누락되어 있다면, 업그레이드 전에 그 차이를 수정하여 이전 배포 환경을 재현할 수 있도록 하세요.

Featured

ZimaCube 2 개인용 클라우드 홈 NAS

ZimaCube2

$799.00 - $2,499.00

Buy Now

지원되는 업그레이드 경로 및 플러그인 위험 확인

현재 버전과 대상 버전 사이에 있는 모든 메이저 버전 경계의 릴리스 노트를 읽으세요. 필요한 중간 버전, 데이터베이스 마이그레이션, 변경된 구성, 플러그인 호환성, FFmpeg 요구 사항 또는 오래 걸리는 시작 작업이 있는지 확인하세요.

Jellyfin의 업그레이드 문서는 백업의 중요성을 반복해서 강조하며, 스키마 변경으로 인해 단순한 다운그레이드가 불가능해질 수 있는 이유를 설명합니다. 업그레이드 및 다운그레이드 경계 메이저 릴리스 노트에는 버전별 사전 조건이 추가될 수 있으므로, 컨테이너 이미지가 존재한다는 이유만으로 안전한 업그레이드라고 판단하지 마세요.

플러그인이 필수라면 서버를 업그레이드하기 전에 호환되는 버전을 사용할 수 있는지 확인하세요. 플러그인이 선택 사항이고 시작을 방해한 이력이 있다면 현재 버전을 기록하고, 새 서버 로그에서 해당 플러그인이 장애 원인으로 확인될 경우에만 그 플러그인을 비활성화할 준비를 하세요.

상태 경계를 변경하지 않고 업그레이드 수행

Jellyfin을 정상적으로 중지하고, 대상 이미지를 가져온 다음, 검증된 동일한 영구 경로와 런타임 종속성을 사용하여 Jellyfin 서비스만 다시 만드세요. 업그레이드의 실제 목적이 아니라면 스토리지 마이그레이션, UID/GID 재설계, 리버스 프록시 재작성 및 GPU 재구성을 업그레이드와 함께 진행하지 마세요.

첫 시작 로그를 지켜보세요. 대규모 라이브러리에서는 마이그레이션에 시간이 걸리는 것이 정상일 수 있지만, 즉시 나타나는 “권한 거부”, 빈 데이터베이스, 경로 누락 또는 호환되지 않는 스키마 메시지는 다른 원인을 가리킵니다. UI가 바로 표시되지 않는다는 이유만으로 마이그레이션을 반복해서 재시작하지 마세요.

컨테이너가 새 서버로 열리면 아무것도 구성하지 말고 중지하세요. 이 증상은 대개 새 서비스가 잘못된 영구 상태를 가리키고 있다는 뜻입니다. 먼저 마운트 매핑을 수정하세요. 새로운 빈 인스턴스를 구성하면 복구 경로를 가리는 새 파일이 생성될 수 있습니다.

롤백 자산을 제거하기 전에 새 버전 검증

기존 서버의 식별 정보, 사용자, 라이브러리, 메타데이터 및 중요한 설정을 확인하세요. Direct Play 항목 하나와 대표적인 트랜스코딩 항목 하나를 재생한 다음, 설정에 중요한 예약 작업을 실행하거나 관찰하세요. 반복되는 마이그레이션, 데이터베이스, 권한 및 FFmpeg 오류가 로그에 있는지 확인하세요.

첫 번째 성공적인 세션 후 컨테이너를 한 번 재시작하세요. 새 버전이 동일한 데이터와 장치를 정상적인 재생성 또는 재시작 후 다시 사용할 수 있어야 완전히 검증된 것입니다. 이를 통해 일시적인 마운트나 런타임 상태에 실수로 의존하고 있는지 확인할 수 있습니다.

서버가 정상적인 워크로드 기간을 통과할 때까지 업그레이드 전 백업, 이전 이미지 참조 및 저장한 정의를 보관하세요. 데이터베이스 마이그레이션 후 롤백이 필요하다면, 이전 이미지를 이미 마이그레이션된 상태에 연결하지 말고 Jellyfin이 문서화한 복원 경계를 따르세요.