Jellyfinはリバースプロキシのサブパス配下で動作しますか？

エヴァ・ウォン

IceWhale author

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

Can Jellyfin Work Behind a Reverse Proxy on a Subpath? - Zima Store Online

はい。Jellyfin は https://example.com/jellyfin のようなサブパスの背後でリバースプロキシ経由で動作できますが、Jellyfin とプロキシで同じベースパスを指定する必要があります。

サブパスの問題は、ログインページは表示されるのに、JavaScript、画像、WebSocket、リダイレクト、ネイティブクライアントが機能しないという、部分的にしか動作しないサイトとして現れることがよくあります。問題を切り分けるには、まず Base URL、次にプロキシルート、最後に転送ヘッダーとクライアントアドレスという順で段階的にテストし、パスの不一致なのか、TLS やプロキシの識別情報の問題なのかを確認してください。

Jellyfin の Base URL を公開サブパスに合わせる

Jellyfin の Base URL には、使用する公開プレフィックスを正確に設定します。たとえば /jellyfin です。プロキシが名前付きロケーションブロックを使用しているからといって、別の内部プレフィックスを追加しないでください。ブラウザーに表示されるパスと Jellyfin の Base URL は、同じアプリケーションルートを示す必要があります。

Jellyfin の Apache リバースプロキシドキュメントには、サブパスの例が明示されており、クライアントをその完全なアドレスに接続する前に Base URL を /jellyfin に設定するよう案内されています。公式のサブパス例

Base URL を変更したら Jellyfin を再起動し、新しいプライベートブラウザーウィンドウで公開サブパスを開きます。最初のリダイレクトですぐに /jellyfin が消えたり、二重になったりする場合は、WebSocket や認証の設定に触れる前に Base URL を修正してください。

リバースプロキシで同じプレフィックスをルーティングする

公開プレフィックスで始まるリクエストが、余分なパス変換を加えずに Jellyfin へ転送されるよう、リバースプロキシを設定します。最もシンプルな構成は、1 つの公開プレフィックス、対応する 1 つの Jellyfin Base URL、1 つのアップストリームサービスです。

Caddy の Jellyfin ガイドでも同じパターンが示されています。Jellyfin のベースパスを設定し、末尾にスラッシュが付いた形式へプレフィックスのみの URL をリダイレクトし、そのプレフィックス以下のリクエストを Jellyfin バックエンドへプロキシします。ベースパスとプロキシルートの一致

Jellyfin のログにリクエストが記録される前に、ブラウザーがプロキシから 404 を受け取る場合は、プロキシ層のルートが間違っています。Jellyfin がリクエストを受け取っているのに、プレフィックスなしのリンクを生成する場合は、アプリケーション層の Base URL が間違っています。この 2 つの症状を区別してください。

ログインページだけでなく静的アセットと WebSocket も確認する

HTML のレスポンスが成功しただけでは、サブパスの設定が正常とはいえません。開発者ツールまたはプロキシログを開き、JavaScript、CSS、画像、API、WebSocket のリクエストがすべて同じ公開プレフィックス以下に収まっていることを確認します。

Jellyfin のリバースプロキシ例に WebSocket の処理が含まれているのは、インタラクティブなクライアントが通常の HTTP リクエストに加えてソケット接続を維持するためです。そのため、ページリクエストだけを処理するプロキシルールは、再生状態、セッション更新、ライブ UI の動作が壊れるまで正しく見えることがあります。リバースプロキシの要件

合格条件はシンプルです。プレフィックス付きアセットで 404/502 が繰り返し発生せず、WebSocket のアップグレードが成功し、ナビゲーションがサイトのルートへ移動しないことです。1 種類のリクエストだけが失敗する場合は、Jellyfin のライブラリや認証設定を変更せず、そのプロキシルールを修正してください。

Featured

ZimaCube 2 パーソナルクラウドホームNAS

ZimaCube2

プロキシ経由でクライアントの識別情報を維持する

パスが機能したら、転送されるクライアント情報を確認します。Jellyfin はプロキシの信頼設定を使って、転送されたアドレスやプロトコルを受け入れるかどうかを判断します。これは、ローカルとリモートの判定や外部アクセスのルールに影響します。

Jellyfin のネットワークガイドでは、信頼されていないプロキシからの転送ヘッダーは破棄されると警告し、「既知のプロキシ」にプロキシアドレスを設定するよう推奨しています。既知のプロキシ設定サイトは動作しているのに、すべてのリクエストがプロキシから発信されたように見える場合は、別途クライアント IP の検証を行うと有効です。

すべてのプライベートサブネットや転送ヘッダーを信頼することで、識別情報の問題を解決しようとしないでください。実際のプロキシホップ、または管理下にあるプロキシネットワークだけを追加し、Jellyfin のログで LAN からのリクエストとリモートからのリクエストを 1 件ずつ比較して、想定どおりに分類されていることを確認します。

ブラウザーとネイティブクライアントのアドレスを個別にテストする

Jellyfin クライアントがサーバー URL を要求したら、サブパスを含む完全なサーバーアドレスを入力します。https://example.com として保存されたクライアントは、Jellyfin が /jellyfin 以下にあることを推測できません。

まず LAN からブラウザーとネイティブクライアントを 1 つずつテストし、その後、公開ホスト名経由でも繰り返します。ホスト名では動作するのに、ローカル IP への直接アクセスでは動作しない場合、プロキシルートや証明書がホスト名に依存しているため、想定された動作である可能性があります。ホスト名と IP のテストを行えば、プロキシを弱体化せずにこのケースを切り分けられます。

実際にサポートするクライアントで、プレフィックス付き URL がログイン、ナビゲーション、WebSocket の使用、再生を通して維持されることを確認できたら完了です。ブラウザーや他のクライアントは通るのに 1 つのクライアントだけが失敗する場合は、動作しているプロキシ設定を書き換えるのではなく、クライアントアドレスまたはクライアント互換性の問題として扱ってください。