メインサービスは起動するものの依存サービスが失敗した場合に Jellyfin を復旧する方法
Jellyfinのプロセスが起動していることは、サービスの準備が整っている証拠ではありません。メディアのマウントが欠落していても、リバースプロキシがコンテナに接続できなくても、ハードウェアデバイスが利用できなくても、DNSが壊れていても、必要なパスが読み取り専用でも、Webリスナーは存在する可能性があります。
復旧時は、Jellyfinを繰り返し再起動するのではなく、ユーザーに見える症状より前に最初に失敗した依存関係を見つけます。現在の状態を固定し、各依存関係を必須または任意に分類し、Jellyfinの実際の実行境界からテストしたうえで、最も低い失敗レイヤーから上に向かってスタックを復元します。
準備完了と判断する前に、Jellyfinに必要なものを定義する
失敗している操作に必要な依存関係を一覧化します。永続化された設定とデータベースのパス、メディアマウント、キャッシュとトランスコード用ストレージ、ローカルDNS、リバースプロキシまたはトンネル、GPUデバイス、そして実際のワークフローで必要となるプラグインや外部サービスです。任意のメタデータプロバイダーを、アプリケーションデータベースと同じカテゴリに入れないでください。
コンテナの起動順序は、準備完了状態と混同されがちです。実用的なヘルスチェックで制御する依存関係パターンでは、依存先が単に起動しただけでなく、利用可能になるまで待機します。Jellyfinをネイティブで実行する場合でも、同じ区別を適用してください。プロセスの状態とサービスの準備状態は、異なる問いに答えるものです。
各必須依存関係について、簡単な合格条件を作成します。マウントは、想定した既知のファイルが想定したパスに表示されれば合格です。プロキシのパスは、有効なアップストリーム応答を取得できれば合格です。GPUは、実際のトランスコード中にJellyfinが開ければ合格です。永続状態は、初期化を行わずにユーザーとライブラリが読み込まれれば合格です。
再起動ポリシーに隠される前に、最初の失敗を記録する
Jellyfinの起動時刻、ヘルス状態、プロセスの終了履歴、ホストとコンテナのログ、マウント状態、ファイルシステムエラー、DNS解決、プロキシエラーを記録します。再起動ポリシーによってループが発生している場合は、1回のクリーンな起動試行を記録できる程度に、ループを一時的に停止します。
最初に現れる失敗は、その後に最も大きな音で現れるエラーより価値があります。マウントの欠落はライブラリエラーを引き起こす可能性があり、読み取り専用の設定パスはデータベース障害を引き起こす可能性があり、DNS障害は複数のプラグインから同時にエラーを発生させる可能性があります。最上位のサービスを再起動しても、元の境界が修復されないまま、二次的なメッセージが増えるだけのことがあります。
既存の最初に失敗した依存関係を特定する手順では、再起動の繰り返しによって根本原因のイベントが見えにくくなった場合にも、同じ順序付けの原則を適用できます。
Jellyfinの実行コンテキストから各必須依存関係をテストする
ホストのシェルから依存関係を確認するだけでは不十分です。Jellyfinがコンテナで動作している場合は、そのコンテナ内、または同じネットワークと同じID境界に接続した同等の診断コンテナから、マウント、DNS名、ポート、権限、デバイスを確認します。
有用なサービス準備状態のチェックでは、表面的なプロセス確認ではなく、クライアントが実際に必要とする操作をテストします。Jellyfinの場合は、設定パスの読み取り、既知のメディアファイルの一覧表示、想定したリスナーへの接続、ローカルAPIリクエスト1回の完了などが該当します。
依存関係が任意の場合は、サーバー全体を停止させるのではなく、失敗しても適切に機能を縮退できるようにします。必須の場合は、まずそれを復元し、独立して検証します。依存関係に到達できないという理由だけで、権限を広げたりホストネットワークに切り替えたりしないでください。失敗がパス、権限、名前解決、ポート、準備状態のどれに該当するのかを特定します。
Jellyfinが依存関係を利用する方向に沿って復元する
アプリケーションが書き込む前に、ストレージと永続状態を復元します。次にローカルサービスのネットワーク、Jellyfin、リバースプロキシまたはリモートイングレス、最後に任意の外部連携を復元します。正確な順序はスタックによって異なりますが、原則は、依存関係が欠落している際に、コンシューマーを空の代替先や誤った代替先に対して初期化させないことです。ヘルスチェックと再起動動作を組み合わせるComposeパターンは、自動再起動が観測可能な準備状態に従うべきであり、その代わりになるものではない理由を示しています。
ネットワークマウントの準備が遅れている場合は、空のフォールバックディレクトリがスキャンされる前にJellyfinを停止します。復元した設定パスが空に見える場合は、セットアップウィザードが新しい状態を作成する前に停止します。ハードウェアアクセラレーションが利用できない場合は、多数のクライアントによって予期しないソフトウェアトランスコードが発生しないよう、再生テストを管理されたファイルに限定します。
破損した状態を所有しているサービスが1つだけの場合は、単一サービスの復元境界を使うことで、障害が1つ発生したからといってスタック全体を置き換えず、正常な共有依存関係を維持できます。
元のユーザー操作と依存関係の再起動で復旧を証明する
スタックが正常になったら、失敗した操作を正確に再実行します。ログイン、ライブラリの閲覧、ダイレクト再生、強制トランスコード、リモートプロキシ経由のアクセス、スキャンなどです。その後、以前失敗した依存関係を意図的に再起動し、Jellyfinが期待どおりに再試行するのか、機能を縮退するのか、利用不能になるのかを観察します。
必須の依存関係が既知の状態に戻り、Jellyfinが正しい永続パスを認識し、空の代替状態が作成されず、通常のユーザー操作がもう一度の再起動サイクル後も維持された場合にのみ、サービスは復旧したといえます。コンテナのステータスがグリーンであっても、これらの確認がなければ、まだプロセスレベルの結果にすぎません。
依存関係、合格条件、起動順序、復旧動作、停止条件を文書化します。そうすれば次のインシデントは、「Jellyfinは起動しているのに壊れている」という広範な問題ではなく、再現可能な準備状態テストを備えた、担当が明確な1つの依存関係の問題になります。
おすすめ商品
サポートとヒント
もっと読む
Jellyfinでは共有アカウントを1つ使うべきか、それとも家庭内で別々のアカウントを使うべきか？
必要な本人確認、アクセス、ペアレンタルコントロール、復旧の境界に応じて、Jellyfinの家庭用アカウントを選択してください。
作業完了後もJellyfinのメモリ使用量が高いままなのはなぜですか？
Jellyfinプロセスの増加とLinuxキャッシュを切り分け、メモリ使用量が増え続けるか、実際にメモリ圧迫が発生した場合にのみ調査してください。
Jellyfinのストレージ構成が復旧リスクになりつつある兆候
Jellyfinのストレージの役割を監査し、稼働中の状態をバックアップや再構築可能なデータから分離したうえで、復元によってその構成を検証する。
