Jellyfinは起動しますが、バックグラウンドワーカーはオフラインのままです

Jellyfin は、Web サーバーとは別にオンラインにしておく必要がある、単一の汎用バックグラウンドワーカーサービスを提供しているわけではありません。UI は読み込めるのに「ワーカー」がオフラインと表示される場合は、その症状を、ライブラリスキャン、メタデータ更新、チャプター画像タスク、プラグインジョブ、または別のスケジュールタスクなど、停止している具体的なバックグラウンド処理に置き換えて考えてください。

この区別が重要なのは、正常な HTTP エンドポイントから分かるのは、メインサーバープロセスが起動したということだけだからです。次に行うべきことは、実行されるはずのジョブを1つ特定し、最後の結果と対応するログ行を確認してから、最初に失敗した依存関係（データベース、書き込み可能なアプリデータ、メディアストレージ、プラグイン、またはタスク固有のリソース）をたどることです。すでにUIを提供できているサーバーを再構築する必要はありません。

進行していないバックグラウンドタスクを正確に特定する

ダッシュボードを開き、動作を確認できるスケジュールタスクを1つ選びます。最終実行時刻、次回実行時刻、現在の状態、手動で開始したときに変化があるかを記録してください。アイドル状態のスケジュールタスクをすべて、1つの「ワーカーオフライン」という症状としてまとめないでください。

Jellyfin のソースツリーには、サーバー内の専用の ScheduledTasks 実装が記載されており、バックグラウンドメンテナンスが汎用的な第2のデーモンではなく、個別のスケジュール処理として扱われていることが確認できます。Jellyfin ScheduledTasks の実装

1つのタスクだけが失敗し、ほかのタスクが完了する場合は、タスク固有の調査を続けてください。すべてのタスクが開始を拒否する場合は、個別のライブラリ設定を変更する前に、データベースの状態、データディレクトリの権限、起動時のマイグレーションなど、共有依存関係を確認します。

連鎖して発生した最後のエラーではなく、最初の関連エラーを読む

タスクを実行した時刻の前後にある Jellyfin のログを確認します。まずタスク名を検索し、データベースロックを取得できなかった、パスを開けなかった、アプリケーションデータを書き込めなかった、FFmpeg を起動できなかった、またはプラグインの依存関係を読み込めなかった理由を説明する、最初の警告またはエラーまでさかのぼってください。

Jellyfin のトラブルシューティングガイドでは、サーバーや再生の問題を診断する最初の手段としてログを確認することを推奨しており、デバッグログを有効にすると非常に大量の出力が生成される場合があると説明しています。Jellyfin のログに関するガイダンス

通常のログでは原因の分岐が分からない場合に限りデバッグログを有効にし、1回のタスク実行を再現したら、ログレベルを通常に戻してください。複数の無関係なスケジュールジョブがノイズを生成している間、デバッグログを有効にし続けるよりも、制御された再現のほうが有用です。

データディレクトリへの書き込みとデータベースの進行を確認する

移動または再マッピングされたデータパスに、後続のバックグラウンド処理が書き込めない場合でも、Web UI は表示されることがあります。タスク設定を修正する前に、実行時の UID/GID、データディレクトリの所有者、空き容量、コンテナのマウントが書き込み可能かどうかを確認してください。

Jellyfin のトラブルシューティングドキュメントには、スキャン失敗時のデータベースロックに関するガイダンスが含まれています。また、コンテナのドキュメントでは、設定とキャッシュの永続化がマウントされたパスに依存することが説明されています。Jellyfin の永続コンテナパス

ログにデータベースロックのエラーが表示される場合は、データベースを削除するのではなく、該当する並列処理を減らすか、文書化されたデータベースロックのトラブルシューティング手順に従ってください。権限エラーまたは読み取り専用エラーが表示される場合は、そのデータパスを修正して、同じタスクを再実行します。

-15% OFF

ZimaBoard 2 - あなたの大きなアイデアのためのミニホームサーバー

Single board computer zimaboard2

$339.00 - $519.00

Buy Now

ライブラリ処理を実行する前にメディアストレージの存在を確認する

メディアパスのいずれかが存在しない、マウントされていない、または断続的に遅い場合、スキャンやメンテナンスタスクは正常に動作しません。ジョブを手動で再実行する前に、ホストと Jellyfin の実行環境の両方から、同じライブラリパスが存在し、読み取り可能であることを確認してください。

Jellyfin は、メディアストレージが利用できない場合、スケジュールされたメンテナンスによって項目が削除される可能性があると警告しています。スケジュールメンテナンスに関するストレージ上の注意 そのため、NAS や外付けディスクが正しくマウントされていない場合に「とりあえずスキャンを再実行する」のは、最初の対応として適切ではありません。

マウントを復元するとタスクが完了する場合、根本原因はワーカーではありません。マウント順序またはストレージの信頼性を修正し、ホストの再起動後にも、Jellyfin の通常のメンテナンス時間より前にパスが利用可能になることを確認してください。

プラグインとタスク固有の依存関係を切り分ける

プラグインが所有するジョブや特定機能のジョブだけが失敗する場合は、Jellyfin のグローバル設定を変更するのではなく、そのコンポーネントを調査してください。プラグインの更新、サーバーのアップグレード、パスの変更、依存関係の変更後に失敗が始まったかどうかを比較します。

疑わしいオプションコンポーネントだけを無効化またはロールバックし、メインサーバー、データベース、無関係なタスクはそのまま維持してください。ZimaSpace の単一サービスの復旧手法も、正常な依存関係を維持しながら失敗したサービスを切り分けるという同じ原則に基づいています。

ジョブが Jellyfin のコア機能の一部で、ログがバージョン固有の回帰を示している場合は、エスカレーションする前にログと正確なサーバーバージョンを保存してください。プラグインの失敗を、永続データ全体を再作成する理由にしないでください。

再起動は検証のためだけに行う

確認済みの依存関係を1つ修正したら、失敗していたタスクを手動で開始し、期待される完了状態に到達することを確認します。その後、Jellyfin を1回再起動し、タスクを再実行するか次回のスケジュールまで待って、通常のサービス起動後も修正が維持されることを確認してください。

失敗した依存関係を明らかにしないまま、再起動によって一時的に症状が消えるだけでは、持続的な修復とはいえません。問題が再発した場合は、権限、データベース、プラグインへの変更を同時に追加するのではなく、新しい最初のエラーと元のエラーを比較してください。

再起動後に対象タスクが完了し、期待される出力が表示され、ほかのスケジュール処理も正常な状態を維持できたら対応を終了します。ストレージと権限を確認済みで、同じコアタスクが依然として失敗する場合は、タスク名、バージョン、最初のエラー、データパスの状態、再現手順を添えてエスカレーションしてください。