Jellyfinとその依存関係のヘルスチェックを設定する方法
有用なJellyfinのヘルスチェックでは、サービスが起動を完了し、データベースに接続できることを確認します。コンテナプロセスがまだ存在していることだけを確認するものではありません。アプリケーションのチェックにはJellyfinの/healthエンドポイントを使用し、オーケストレーターがサービスを異常と判断できるようになる前に、起動時のマイグレーションに十分な時間を与えます。
ホームサーバーでは、Jellyfinがマウント済みメディア、リバースプロキシ、DNS、ストレージ、または準備完了のタイミングが異なる別のサービスに依存している場合に、ヘルスチェックが特に役立ちます。チェックは層に分けて構築してください。まずJellyfinアプリケーションのヘルス、次に依存関係の準備状態、その次にアラート、最後に自動再起動という順序です。この順序により、ウォッチドッグが正当なマイグレーションや起動処理を実行中のサーバーを繰り返し強制終了するのを防げます。
まずJellyfinのアプリケーション・ヘルスエンドポイントから始める
ヘルスチェッカーが使用するのと同じネットワーク名前空間から、http://SERVER:8096/healthをテストします。ノートパソコンのブラウザーからリクエストが成功しても、実際のチェックが異なるDNS名や経路を持つコンテナ内で実行される場合は、あまり参考になりません。
Jellyfinには、HTTP接続とデータベース接続を確認する組み込みのヘルスエンドポイントが用意されています。同じドキュメントでは、サーバーの起動中はこのエンドポイントが起動完了を示すレディネスシグナルのようには動作しないことにも注意を促しています。そのため、起動時間を設計に含める必要があります。
起動直後、Jellyfinが利用可能になった後、そして意図的に停止している間の3つの状態を記録します。再起動ロジックや通知システムに接続する前に、チェックがこれらの状態を確実に区別できるようにしてください。
マイグレーションに起動時の猶予期間を与える
コンテナの起動直後から失敗回数を数え始めるヘルスポリシーは、アップグレード中に再起動ループを引き起こす可能性があります。通常のデータベースマイグレーションとプラグインの読み込みに十分な長さの起動時猶予期間を設定し、その期間が終わってから通常の間隔と再試行回数のカウントを開始します。
Docker Composeでは、サービスのヘルスチェックにstart_period、start_interval、interval、timeout、retriesを指定できます。長いスリープをテストコマンドに埋め込むのではなく、これらのヘルスチェックのタイミング制御を使って、起動時の許容範囲を表現してください。
猶予期間を設定したら、Jellyfinを2回再起動します。1回は通常の起動時、もう1回はより時間のかかるアップデートまたはバックアップの復元後です。適切なポリシーであれば、Jellyfinの初期化中はstarting状態を維持し、不要なコンテナ再起動なしにhealthy状態になります。
依存関係はJellyfinとは別にチェックする
1つのJellyfinプローブを、メディアマウント、DNS、リバースプロキシ、インターネット上のメタデータプロバイダー、すべてのクライアントまで検査する巨大なスクリプトにしないでください。各依存関係には個別のシグナルを用意し、障害が発生したときにどの層が壊れているのか分かるようにします。
マウント済みライブラリの場合、リスクの低い依存関係チェックとして、想定したマウントポイントが存在し、既知の読み取り専用のセンチネルパスが含まれていることを確認できます。リバースプロキシの場合は、公開TLSエンドポイントとは別にプロキシから上流への到達性をチェックし、証明書の問題をJellyfinのデータベース障害と誤認しないようにします。
このような層別の検証は、ハードウェアトランスコードの動作確認にも似ています。重要な証拠は、設定画面に有効と表示されているかではなく、想定したサブシステムが実際に稼働しているかどうかです。
自動再起動の前にアラートを出す
異常な結果は、まず証拠として扱います。ディスク競合中の単発のプローブ失敗や短時間のネットワーク中断だけで、必ずしもJellyfinを再起動する必要はありません。特に、障害の原因がJellyfinプロセスの外部にある場合はなおさらです。
実用的なホームサーバーポリシーでは、連続した失敗を条件に管理者へ通知し、ホストと必要なストレージが利用可能であるにもかかわらずアプリケーションのヘルスチェックが失敗し続ける場合にのみ再起動します。ストレージの依存関係が失われている場合、Jellyfinを再起動すると、不完全なライブラリパスに対して起動処理が実行され、状況が悪化する可能性があります。
アラートメッセージは具体的にします。エンドポイントの結果、依存関係の結果、最後に成功した時刻、再起動を試みたかどうかを含めてください。これにより、ヘルスチェックが単なる二値の赤・緑表示ではなく、運用に役立つツールになります。
実際の障害条件でチェックを検証する
完成したポリシーは、Jellyfinを正常に停止し、アプリケーションポートを一時的にブロックし、さらに本番環境ではないテスト経路で依存関係を利用不能にして検証します。それぞれのイベントが想定どおりの状態を生成し、関係のない破壊的な処理を引き起こさないことを確認してください。
次に、すべての依存関係を復旧させ、手動で編集しなくてもJellyfinがhealthy状態に戻ることを確認します。復旧もヘルスチェック設計の一部です。障害を検出できても、サービス復旧後に正常状態へ戻らないプローブは信頼できません。
繰り返しテストで、チェックがstarting、healthy、unhealthy、dependency-failedの各状態を区別できるようになったら、調整を終えます。これらの状態が依然として曖昧な場合は、プローブが安全に再起動を実行できるほど具体的になるまで、自動化をアラートのみのモードにしておきます。
おすすめ商品
サポートとヒント
もっと読む
Jellyfinでは共有アカウントを1つ使うべきか、それとも家庭内で別々のアカウントを使うべきか？
必要な本人確認、アクセス、ペアレンタルコントロール、復旧の境界に応じて、Jellyfinの家庭用アカウントを選択してください。
作業完了後もJellyfinのメモリ使用量が高いままなのはなぜですか？
Jellyfinプロセスの増加とLinuxキャッシュを切り分け、メモリ使用量が増え続けるか、実際にメモリ圧迫が発生した場合にのみ調査してください。
Jellyfinのストレージ構成が復旧リスクになりつつある兆候
Jellyfinのストレージの役割を監査し、稼働中の状態をバックアップや再構築可能なデータから分離したうえで、復元によってその構成を検証する。
