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

エヴァ・ウォン

IceWhale author

エヴァ・ウォン は テクニカルライター であり ZimaSpaceの常駐ティンカーでもあります。 生涯のオタクであり、 ホームラボとオープンソースソフトウェアに情熱を持っています。彼女は複雑な技術的概念をわかりやすく、 実践的なガイドに翻訳することを専門としています。エヴァはセルフホスティングは楽しくあるべきで、怖がるものではないと信じています。彼女のチュートリアルを通じて、コミュニティが ハードウェアのセットアップを解明する手助けをしています。初めてのNAS構築からDockerコンテナの習得まで。

A Pre-Upgrade Checklist for Jellyfin Containers and Dependencies - Zima Store Online

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

サポートされるアップグレード経路とプラグインのリスクを確認する

現在のバージョンから対象バージョンまでの各メジャーバージョン境界について、リリースノートを確認します。必要な中間バージョン、データベース移行、設定変更、プラグイン互換性、FFmpegの要件、起動時に長時間かかる処理がないかを確認してください。

Jellyfinのアップグレードドキュメントでは、バックアップの重要性が繰り返し強調され、スキーマ変更によって単純なダウングレードが不可能になる理由が説明されています。アップグレードとダウングレードの境界メジャーリリースノートにはバージョン固有の前提条件が追加される場合があるため、コンテナイメージが存在するという理由だけで安全なアップグレードだと判断しないでください。

不可欠なプラグインがある場合は、サーバーをアップグレードする前に互換バージョンが利用できることを確認します。任意のプラグインで、起動を妨げた実績がある場合は、現在のバージョンを記録し、新しいサーバーのログでそのプラグインが障害の原因だと特定された場合に限り、無効化できるよう準備してください。

状態の境界を変更せずにアップグレードする

Jellyfinを正常に停止し、目的のイメージを取得して、検証済みの同じ永続パスと実行時依存関係を使用したまま、Jellyfinサービスだけを再作成します。アップグレードにストレージ移行、UID/GIDの再設計、リバースプロキシの書き換え、GPUの再設定を同時に組み込まないでください。それらがメンテナンスの本来の目的である場合を除きます。

初回起動時のログを監視します。大規模なライブラリでは移行に時間がかかるのは正常な場合がありますが、直ちに表示される「permission denied」、空のデータベース、パスの欠落、互換性のないスキーマといったメッセージは、別の問題を示しています。UIがすぐに利用可能にならないというだけで、移行を何度も再起動しないでください。

コンテナが新規サーバーとして開く場合は、何も設定せずに停止してください。この症状は通常、新しいサービスが誤った永続状態を参照していることを意味します。まずマウントマッピングを修正してください。空の新規インスタンスを設定すると新しいファイルが作成され、復旧経路が分かりにくくなる可能性があります。

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

元のサーバーの識別情報、ユーザー、ライブラリ、メタデータ、重要な設定を確認します。Direct Playの項目を1つ、代表的なトランスコードを1つ再生し、環境にとって重要なスケジュールタスクを実行または監視してください。移行、データベース、権限、FFmpegに関するエラーが繰り返し発生していないか、ログを確認します。

最初のセッションが正常に終了した後、コンテナを一度再起動します。新しいバージョンは、クリーンな再作成または再起動後に同じデータとデバイスを再び開けることを確認して、初めて完全に検証されたといえます。これにより、一時的なマウントやランタイム状態に誤って依存していることを検出できます。

サーバーが通常の負荷期間を完了するまで、アップグレード前のバックアップ、以前のイメージ参照、保存した定義を保持してください。データベース移行後にロールバックが必要になった場合は、すでに移行された状態を古いイメージに指定するのではなく、Jellyfinが文書化している復元の境界に従ってください。