Jellyfinコンテナと依存関係のアップグレード前チェックリスト

Jellyfinコンテナをアップグレードする前に、デプロイ環境の両方を保護してください。永続化されたJellyfinの状態と、そこへの接続方法を把握している正確なコンテナ定義です。新しいイメージは簡単に取得できますが、移行済みのデータベース、変更されたマウント、忘れていたデバイスの割り当てを復旧するのは簡単ではありません。

依存関係の順にチェックリストを実行してください。まずデータを復旧できることを確認し、次に現在のイメージと実行時設定を記録し、その後にリリースの手順を確認してから、イメージを置き換えます。置き換え後は、ロールバック用コピーを削除する前に、同じライブラリ、ユーザー、再生モード、スケジュールタスク、再起動時の動作をテストしてください。

最後に動作したイメージとコンテナ定義を記録する

現在のJellyfinイメージタグを記録し、可能であればダイジェストも保存してください。ポート、ネットワーク、マウント、環境変数、再起動ポリシー、ユーザーマッピング、補助グループ、GPUデバイス、リバースプロキシとの関係が含まれるComposeファイルまたはアプリ定義をエクスポートするか、コピーしてください。

Jellyfinの公式コンテナドキュメントでは、latestのように移動するタグと、明示的なメジャー、マイナー、パッチの各タグを区別しています。Jellyfinのイメージタグの動作 「昨日はlatestで動いていた」と覚えているだけでなく、正確な動作バージョンが分かっていれば、ロールバックが容易になります。

新しいバージョンが検証期間を完全に通過するまで、古いイメージを削除したり、保存した定義を消去したりしないでください。永続データに触れる前にアップグレードが失敗した場合、イメージと定義を保持しておけば、変更を最小限に抑えて復旧できます。

復元可能なJellyfinの状態バックアップを作成する

イメージを変更する前に、Jellyfinのデータディレクトリと設定ディレクトリを保護してください。バックアップは稼働中のアプリケーションのパス外に置き、独立して読み取れる必要があります。同じデータセット上の2つ目のコピーやスナップショットが役立つのは、それがどのような障害からデータを守るのかを理解している場合に限ります。

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の再設定を行わないでください。

最初の起動ログを確認してください。ライブラリが大きい場合、移行に時間がかかるのは正常です。一方、すぐに表示される「permission denied」、データベースが空であること、パスが見つからないこと、スキーマに互換性がないことを示すメッセージは、別の原因を示しています。UIがすぐに利用できないからといって、移行中に何度も再起動しないでください。

コンテナを起動したときに初期状態のサーバーが表示されたら、設定を始める前に停止してください。この症状は通常、新しいサービスが誤った永続状態を参照していることを示します。まずマウントの割り当てを修正してください。新しい空のインスタンスを設定すると、復旧手順が分かりにくくなる新規ファイルが作成されるおそれがあります。

ロールバック用データを削除する前に、新バージョンを検証する

元のサーバーID、ユーザー、ライブラリ、メタデータ、重要な設定が保たれていることを確認してください。Direct Playの項目を1つ、代表的なトランスコードを1つ再生し、セットアップに重要なスケジュールタスクを実行するか、動作を確認してください。ログを確認し、移行、データベース、権限、FFmpegに関するエラーが繰り返し発生していないかを調べてください。

最初のセッションが正常に終了したら、コンテナを一度再起動してください。新しいバージョンは、クリーンな再作成または再起動後に、同じデータとデバイスを再び利用できることを確認するまで、十分に検証されたとはいえません。これにより、一時的なマウントや実行時の状態に誤って依存していないかを確認できます。

アップグレード前のバックアップ、以前のイメージの参照情報、保存した定義は、サーバーが通常の負荷で稼働する時間帯を問題なく終えるまで保持してください。データベースの移行後にロールバックが必要になった場合は、移行済みの状態に古いイメージを向けるのではなく、Jellyfinのドキュメントに記載された復元の境界に従ってください。