Jellyfin을 단일 컨테이너에서 복원력 있는 서비스 스택으로 마이그레이션하는 방법

먼저 Jellyfin의 현재 동작을 선언하고, 영속 상태를 보호한 다음, 되돌릴 수 있고 테스트된 단계로 서비스를 추가하여 마이그레이션하세요.

이 절차는 문서화되지 않은 명령어나 올인원 구성에서 벗어난, 정상적으로 작동하는 Docker 컨테이너를 대상으로 합니다. 목표는 컨테이너 수를 최대화하는 것이 아니라, 명시적인 마운트, 네트워크, 장치, 상태 신호, 백업 범위, 롤백을 갖춘 재현 가능한 Jellyfin 서비스를 구축하는 것입니다. 미디어 저장소는 애플리케이션 상태와 분리하고, 승인 테스트가 통과할 때까지 기존 인스턴스를 유지하며, 가정에서 운영할 수 있는 의존성만 추가하세요.

복원력이 무엇을 감당해야 하는지 정의하기

새 스택이 처리해야 할 장애를 선택하세요. Jellyfin 프로세스 충돌, 잘못된 이미지 업데이트, 구성 저장소 손실, 프록시 사용 불가, 호스트 재시작, 완전한 호스트 손실 등이 있습니다. 각각에는 서로 다른 제어 방법이 필요합니다. 재시작 정책은 프로세스 종료 후 복구하는 데 도움이 되지만, 삭제된 볼륨을 복원하거나 연결할 수 없는 미디어 마운트를 고쳐 주지는 않습니다.

구성, 시청 상태, 서비스 가용성에 대한 측정 가능한 복구 목표를 설정하세요. 허용할 수 있는 중단 시간과 데이터 손실량, 알림을 받을 사람, 재구축할 수 있는 부분을 결정하세요. 이렇게 범위를 정하면 식별된 위험을 줄이지 못하는 데이터베이스, 프록시, 대시보드, 자동화 기능이 소규모 홈 마이그레이션에 불필요하게 쌓이는 것을 막을 수 있습니다.

실행 중인 컨테이너 목록 작성

정확한 이미지 참조, 명령어, 환경 변수, 공개 포트, 네트워크, 재시작 정책, 사용자 및 그룹 ID, 장치 매핑, DNS 설정, 레이블, 구성 마운트, 캐시 마운트, 미디어 마운트, 시크릿을 기록하세요. 모든 호스트 경로의 소유권과 권한도 캡처해야 합니다. 컨테이너 UI의 스크린샷은 완전한 배포 기록이 아닙니다.

동작을 변경하지 않고 이 목록을 Compose 정의로 옮기세요. 이 Docker run에서 Compose로 마이그레이션하는 가이드의 플래그별 방식은 첫 번째 이정표를 기능 확장이 아닌 재현성으로 다루기 때문에 유용합니다. 초기 전환에서는 현재 실행 중인 이미지의 다이제스트 또는 버전을 고정하세요.

영속 상태, 캐시, 미디어 분리

Jellyfin 구성과 데이터베이스 상태를 이름이 명확한 영속 경로에 매핑하세요. 삭제 가능한 캐시와 트랜스코딩 조각은 별도의 경로에 두어 중요한 백업 데이터로 오인되지 않게 하세요. 소유한 미디어는 독립적으로 마운트하고, 작업 흐름에서 허용한다면 읽기 전용으로 마운트하세요. 복원력 있는 애플리케이션 계층이 대규모 미디어 라이브러리의 보호 경계를 흐리게 해서는 안 됩니다.

백업 방식이 애플리케이션 일관성을 보장하지 않는 한, 처음으로 일관된 상태를 복사하기 전에 Jellyfin을 중지하거나 일시 정지하세요. 권한, 체크섬 또는 파일 수, 백업 시간, 복원 위치를 기록하세요. 컨테이너 이미지에 사용자 데이터가 포함되어 있다고 가정하지 마세요. 배포 정의, 시크릿, 영속 상태, 미디어 참조는 서로 다른 복구 입력입니다.

Featured

ZimaCube 2 개인용 클라우드 홈 NAS

ZimaCube2

$799.00 - $2,499.00

Buy Now

네트워크를 변경하기 전에 복원 검증

임시 복원 대상을 만들고, 보호된 애플리케이션 상태를 그곳에 복사한 다음, 미디어를 읽기 전용으로 마운트한 상태에서 대체 포트로 고정된 Jellyfin 서비스를 시작하세요. 사용자, 라이브러리, 시청 기록, 메타데이터, 플러그인, 대표적인 재생을 확인하세요. 임시 인스턴스를 삭제하고, 어느 단계라도 기억에 의존했다면 작성된 절차만으로 다시 수행하세요.

실용적인 Compose 백업은 배포 파일, 환경 입력값, 볼륨, 애플리케이션과 일관된 데이터베이스 내보내기를 보존해야 합니다. 이 Compose 백업 및 업그레이드 가이드는 이미지 하나만 복사하거나 실행 중인 데이터베이스 파일만 복사하는 것이 완전한 복구 경로가 아닌 이유를 설명합니다.

선언적 Jellyfin 서비스로 전환

유지보수 시간을 정하고, 기존 컨테이너를 중지하고, 최종 일관 상태 백업을 만든 뒤, 기존 인스턴스가 자동으로 다시 시작되지 않게 하세요. 동일한 영속 경로와 장치 액세스로 동등한 Compose 서비스를 시작하세요. 로컬 상태와 재생 확인이 성공한 후에만 공개 경로를 그대로 유지하세요.

컨테이너 상태, 로그, 라이브러리 표시 여부, 하드웨어 장치 액세스, 직접 재생, 대표적인 트랜스코딩 한 건, 자막 처리, 재시작을 검증하세요. 서비스가 장치나 마운트를 볼 수 없다면 여러 계층을 압박 속에서 수정하지 말고 중지한 후 기존 컨테이너를 복원하세요. 롤백은 이전에 고정한 이미지와 전환 전 상태, 원래 실행 매개변수를 사용하는 것입니다.

인접 서비스를 한 번에 하나씩 경계 안에 추가

원격 인그레스에 별도로 관리되는 경로가 필요할 때만 리버스 프록시를 도입하세요. 명확한 상태 신호가 있고 누군가 대응할 때만 모니터링을 추가하세요. 재시작 반복, 저장소 손실, 백업 실패를 반드시 알아야 할 때 알림 채널을 추가하세요. 각 서비스에는 담당자, 영속 상태 결정, 네트워크 범위, 업데이트 방식, 장애 영향이 필요합니다.

이러한 경계가 필요한 아키텍처상의 이유는 ZimaSpace의 Jellyfin 배포에서 서비스 스택을 사용하는 이유 설명에서 별도로 다룹니다. 마이그레이션 중에는 이 모델을 보수적으로 적용하세요. 함께 복구되어야 하는 구성 요소는 묶고, 선택적 대시보드나 자동화 기능 때문에 재생이 의존성을 갖게 만들지 마세요.

상태, 업데이트, 백업을 관찰 가능하게 만들기

상태를 단순히 프로세스가 실행 중인지가 아니라 사용자 경로에서 정의하세요. Jellyfin이 로컬에서 응답하는지, 미디어 마운트가 존재하는지, 활성화된 경우 공개 경로가 의도한 서비스에 도달하는지, 알려진 파일 하나를 읽을 수 있는지 확인하세요. 실패한 검사는 운영자가 이미 사용하는 알림 채널로 보내고, 애플리케이션 장애와 저장소 또는 네트워크 손실을 구분할 수 있을 만큼 충분한 맥락을 제공하세요.

Compose 정의는 버전 관리하고, 시크릿은 저장소에서 제외하며, 배포 전에 이미지 변경 사항을 검토하세요. 수동 복원이 성공한 후에만 백업을 자동화하세요. 이 Jellyfin 상태 확인 및 모니터링 가이드의 작업 흐름은 선언, 검사, 알림, 백업이 어떻게 연결되는지 보여 줍니다. 저장된 상태를 변경할 수 있는 업데이트에는 승인 및 롤백 지점을 유지하세요.

기존 경로를 폐기하기 전에 장애 훈련 실시

호스트를 재시작하고, Jellyfin을 예기치 않게 중지하고, 프록시를 사용할 수 없게 만들고, 테스트 미디어 경로를 분리한 뒤, 깨끗한 임시 위치에 애플리케이션 상태를 복원하세요. 각 훈련에서 예상한 알림, 복구 순서, 사용자에게 보이는 동작을 확인하세요. 유일한 미디어 사본을 대상으로 파괴적인 저장소 손실을 시뮬레이션하지 마세요.

복구 시간과 수동 명령을 기록하세요. 빠르게 재시작되지만 빈 라이브러리로 돌아오는 컨테이너는 서비스 테스트에 실패한 것입니다. 백업이 존재하지만 목표 시간 안에 복원할 수 없다면 복구 테스트에 실패한 것입니다. 더 많은 서비스를 추가하기 전에 이러한 경계를 수정하세요.

안정적인 운영 계약으로 마이그레이션 마무리

새 Jellyfin 서비스가 일상적인 가정 사용, 계획된 업데이트, 호스트 재부팅, 정상적인 복원 리허설을 견딘 후에만 원래 컨테이너를 폐기하세요. 선택한 보존 정책에 따라 이전 매개변수, 전환 전 최종 백업, 현재 Compose 정의, 시크릿 복구 방법, 마운트 맵, 롤백 절차를 보관하세요.

스택이 재현 가능하고, 모니터링되며, 복구 가능하고, 운영자가 이해할 수 있을 때 확장을 멈추세요. 측정된 용량, 신뢰, 장애 도메인 요구 사항이 있을 때만 다른 노드나 의존성을 추가하세요. 복원력은 다이어그램 속 컨테이너 수가 아니라, 알려진 상태와 연습된 복구에서 나옵니다.