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

エヴァ・ウォン

IceWhale author

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

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

Home Assistantはリバースプロキシの背後で動作させられますが、書き換えたサブパスから確実に提供する構成は、一般的にサポートされているデプロイ境界ではありません。

example.com/homeassistant のページはHTMLを返しても、その後のリクエストがルート相対のアセット、認証ルート、WebSocket、統合機能のコールバックを対象にすることがあります。最初の画面だけでなく、新しいブラウザーでの確認、サインイン、ライブダッシュボードの表示、ネストされたルートの再読み込み、コールバック1件の完了までテストしてください。いずれかの層でプレフィックスが失われる場合は、書き換えを追加するのではなく、Home Assistantを専用ホスト名に移してください。

リバースプロキシのサポートとサブパスのサポートを分けて考える

リバースプロキシはTLSを終端し、ホスト名のルート宛てのリクエストをHome Assistantに転送できます。サブパスには別の要件があります。生成されるすべてのURL、アセット、API呼び出し、WebSocket、リダイレクト、コールバックが、アプリケーションが理解できるプレフィックスを一貫して維持しなければなりません。プロキシ層で成功しても、アプリケーションとのその契約が成立したことにはなりません。

Home Assistantコミュニティでの検証では、URLプレフィックス配下へのデプロイをアプリケーションがサポートしていないという明確な結論に達しています。Home Assistantをサブパスに配置する方法への確定回答では、プロキシの選択にかかわらずサブドメインを推奨しています。

リバースプロキシのサポートに対するPASSとは、正しい転送によって専用ホスト名のルートでHome Assistantが動作することです。提案したサブパスに対するFAILとは、1つ以上のアプリケーションルートでプレフィックスが失われることです。この2つの判定を混同して、リバースプロキシ自体に互換性がないという主張にしないでください。

最初の低リスクテストとしてフロントエンドアセットを確認する

Home Assistantを変更する前に、プライベートブラウザープロファイルで提案したサブパスを開き、ネットワークリクエストを確認してください。ベースドキュメントは読み込めても、JavaScript、アイコン、マニフェスト、翻訳ファイルがホスト名のルートからパスを要求するなら、その時点で構成は最初の可逆的な判定に失敗しています。

記録されたパス書き換えの試行では、メインページは返されたものの、フロントエンドのリソースがHome Assistantのプレフィックスなしでスラッシュ始まりのURLを要求しました。このルート相対アセットの失敗は、プロキシ上のファイル不足ではなく、アプリケーションのパス不一致です。

PASSとは、意図したルート配下ですべてのフロントエンドリソースが正常に返ることです。FAILとは、404応答またはルートパスへのリクエストが現れることです。そこで止めて専用ホスト名をテストしてください。将来のフロントエンドビルドで、書き換えが対応していない新しいパスが追加される可能性があるため、レスポンス本文の置換は脆弱です。

WebSocket、認証、ネストされたルートをテストする

静的なダッシュボードのシェルだけでは、完全なセッションとはいえません。クリーンなプロファイルからサインインし、数分間エンティティの更新を監視し、ネストされたダッシュボードURLを更新し、サインアウトしてから再度サインインしてください。その後、HTTPアップグレード、トークン、リダイレクト、ルートの再読み込みが同じ公開オリジンとパスを維持しているか確認します。

Home Assistantはライブのフロントエンド通信にWebSocketを大きく依存しているため、プロキシはアップグレードのパスとヘッダーを維持しなければなりません。ある運用者によるリバースプロキシでのWebSocket処理に関する報告は、HTMLの読み込みだけでは十分な互換性テストにならない理由を示しています。

PASSとは、認証、ライブ更新、ナビゲーション、直接の再読み込みがすべて、パス変換エラーなしで動作することです。ソケットまたはリダイレクトだけにFAILが発生する場合でも、サブパス構成は不合格です。プロキシのディレクティブを1つ修正しても、コールバックや将来のルートがプレフィックスを認識するようになる保証はありません。

Featured

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

ZimaCube2

安定した境界として専用ホスト名を選ぶ

ha.example.comのような専用ホスト名のルートでHome Assistantを公開し、そのホスト名をリバースプロキシ経由で内部サービスにルーティングします。これにより、アプリケーションにパスプレフィックスを理解させることなく、1つの公開オリジンを維持できます。プライベートVPNやトンネルでも、公開せずに同じクリーンなルート境界を提供できます。

ネットワーク変更後に既存のリモートパスが壊れた場合は、DNS、公開アドレス、NAT、トンネル、プロキシのルーティングを個別に確認してください。ZimaSpaceのルーター変更後のリモートアクセスに関する診断では、この関連する経路チェックを説明しています。

クリーンなブラウザーでアセットを読み込み、WebSocketを確立し、認証し、ネストされたルートを更新し、プロキシ再起動後にHome Assistantへ到達できれば、代替構成は合格です。DNSまたはプロキシの変更をロールバックできる期間だけ古いルートを利用し、曖昧な公開URLを2つ恒久的に運用しないでください。

完全なセッションが再起動後も維持されるまで終了しない

プロキシとHome Assistantを一度再起動してから、LANと想定するリモートネットワークの両方で完全なテストを繰り返してください。証明書名、転送されたクライアントアドレス、信頼済みプロキシの境界、ログイン、ライブ状態、ログアウト、統合機能のコールバック1件を確認します。これは元のワークロードであり、縮小した静的ページのチェックではありません。

すべての手順に合格したルートホスト名構成についてのみ成功と判定してください。カスタムのレスポンス書き換え後にしか動作しないサブパスは、アップデートによってアセットやコールバックの動作が変わる可能性があるため、運用上の未解決リスクとして残ります。正常動作が確認されたホスト名、アップストリームアドレス、ロールバック構成を文書化してください。

ルートホスト名構成でも失敗する場合は、プロキシの信頼設定、WebSocket転送、DNS、証明書、ルーティングが原因である可能性が高く、ベースパスのサポートが原因ではないため、エスカレーションしてください。希望するURL形式を維持するためだけに、保護されていないポートでHome Assistantを直接公開しないでください。