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

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

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

복원력의 적용 범위 정의

새 스택이 대응해야 할 장애를 선택하세요. Jellyfin 프로세스 충돌, 잘못된 이미지 업데이트, 구성 스토리지 손실, 프록시 접속 불가, 호스트 재시작 또는 호스트 전체 손실 등이 있습니다. 각 장애에는 서로 다른 제어 수단이 필요합니다. 재시작 정책은 프로세스 종료 후 복구에 도움이 되지만, 삭제된 볼륨을 복원하거나 접근할 수 없는 미디어 마운트를 복구하지는 않습니다.

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

실행 중인 컨테이너 목록화

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

동작을 바꾸지 않으면서 해당 목록을 Compose 정의로 옮기세요. 이 Docker run-to-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 정의, 비밀 정보 복구 방법, 마운트 맵, 롤백 단계를 보관하세요.

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