セルフホスト型アプリがローカルでは開くのに、APIへ接続できない場合に確認すべきこと

エヴァ・ウォン

IceWhale author

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

What Should You Check When a Self-Hosted App Opens Locally but Its API Cannot Be Reached?

ページがローカルで開くからといって、APIパスが機能するとは限りません。ブラウザーのインターフェースとバックエンドへのリクエストでは、ホスト、ポート、プロトコル、認証情報が異なる場合があります。

ホームサーバーでは、HTMLや静的アセットがリバースプロキシ、ブラウザーキャッシュ、またはローカルのWebコンテナから読み込まれる一方、API呼び出しが別のサービス、サブパス、WebSocketエンドポイント、または外部設定のベースURLへ送られることがあります。まずブラウザーで失敗したリクエストを1件キャプチャし、関連するネットワーク境界から再現してみてください。そのうえで、表示されたページをスタック全体に到達できる証拠とみなすのではなく、ルーティング、TLS、認証、ブラウザーのポリシー、アプリケーション設定を切り分けます。

ページとAPIが同じネットワーク経路を使っているか確認する

ブラウザーの開発者ツールを開き、失敗する操作を再読み込みします。リクエストURL、メソッド、ステータス、レスポンス本文、リモートアドレス、イニシエーター、そして通常のHTTPリクエスト、WebSocket、サーバー送信イベント、バックグラウンドフェッチのいずれで失敗しているかを記録してください。

セルフホストのBaserowでは、使えるインターフェースが表示されているにもかかわらず、ブラウザーのイベントチャネルが別のプロキシ経路を通ったため、再接続を繰り返すケースがありました。目に見える症状は、Webサーバー全体の停止ではなく、イベント接続の失敗でした。

成功したドキュメントリクエストと失敗したAPIリクエストを、スキーム、ホスト名、ポート、パスプレフィックス、クエリ文字列まで1文字ずつ比較します。異なる場合は、最初に変わった層を調査してください。同一であれば、ヘッダー、Cookie、レスポンス処理、バックエンドのルーティングを確認します。

関係する各境界から正確なリクエストを再現する

失敗したリクエストをコマンドとしてコピーし、クライアント、リバースプロキシのホスト、アプリケーションネットワークに接続した一時コンテナから再現します。メソッド、認証ヘッダー、コンテンツタイプ、本文、想定ホスト名を保持してください。

APIはTCPおよびHTTPレイヤーでは到達可能でも、トークンやヘッダーがないため実際のリクエストを拒否することがあります。FreshRSSのAPIに関する議論では、外部からの失敗原因が一般的なコンテナ到達性ではなく、認証コンテキストの不足に絞り込まれました。

最初に失敗した境界を読み取ります。DNSエラーは名前解決、接続拒否はリスナー、ポート、またはネットワーク、TLSエラーは身元確認または信頼性、401や403は認証またはポリシー、404はルーティングまたはサブパスの書き換えを示すことが多くあります。直接呼び出しは成功するのにブラウザーからの呼び出しが失敗する場合は、プロキシまたはブラウザーのルールに焦点を移します。

APIのベースURL、ポート、サブパスを確認する

アプリケーションの公開URL、API URL、WebSocket URL、ベースパス、フロントエンドのビルド時変数を確認します。ローカルで提供されるインターフェースに、古いドメイン、プライベートIP、誤ったポート、またはサーバー上でしか存在しないルートパスを指す絶対APIアドレスが含まれている場合があります。

サブパスでデプロイする場合、スラッシュの扱いと書き換えルールの影響を特に受けやすくなります。Frigateのリバースプロキシ事例では、メインインターフェースには到達できたにもかかわらず、リソースの失敗原因がサブパスの書き換え動作にあることが判明しました。

正しいルートを特定する目的に限り、設定済みのプレフィックスありとなしの両方でAPIエンドポイントをテストします。その後、アプリケーションとプロキシが1つの正規パスで一致するよう修正してください。一部のメソッドだけが機能し、アップロード、コールバック、ストリーミングエンドポイントが意図したバックエンドを迂回し続けるような、重複した書き換え例外は残さないでください。

Featured

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

ZimaCube2

リバースプロキシのヘッダー、TLS、ストリーミング対応を確認する

通常のページ、API、WebSocket、ストリーミングリクエストで、プロキシの経路を比較します。アップストリームのサービス名、内部ポート、HTTPバージョン、接続のアップグレード動作、読み取りタイムアウト、バッファリング設定、転送されるホストおよびプロトコルのヘッダーを確認してください。

Open WebUIでは、直接アクセスとはバッファリングやストリーミングの動作が異なるため、プロキシ経由のAPI出力が停止しているように見える一方、インターフェース自体は正常に動作するという報告があります。診断の焦点は静的ページではなく、プロキシ経由のストリーミング経路です。

信頼できるプロキシ用に限定して設定したヘッダーを通じて、元のホスト名とスキームをバックエンドへ送信します。WebSocketのアップグレードは必要なルートでのみ有効にし、ストリーミングエンドポイントでは不適切なバッファリングを無効にします。また、プロキシが誤って公開ホストのポートではなく、アプリケーションの内部リスナーを使用していることを確認してください。

ブラウザーのポリシーとサーバーの到達性を切り分ける

直接コマンドでは成功するのにブラウザーで失敗する場合は、ブラウザーのコンソールでCORS、混在コンテンツ、証明書、Cookie、プリフライトのエラーを確認します。サーバーが正しく応答していても、ブラウザーがリクエストの送信やレスポンスの公開を拒否することがあります。

リバースプロキシ経由のOpen WebUIに関する議論では、WebSocketとAPIの失敗がオリジンおよび転送プロトコルの処理に関連付けられています。これは、プロキシを通じてオリジンとプロトコルの識別情報を一貫させる必要性を示しています。

HTTPSページからHTTP APIが呼び出されていないこと、APIが必要なオリジンだけを許可していること、プリフライトリクエストが同じルートに到達すること、セッションCookieに正しいドメイン、パス、Secure、SameSite属性が設定されていることを確認します。ブラウザーの保護機能を全体的に無効化するのではなく、サーバーの公開上の識別情報とポリシーを修正してください。

必要なすべてのネットワークからAPIの完全なワークフローを検証する

最初に失敗したリクエストが機能するようになったら、LANとサポート対象のすべてのリモート経路から、ログイン、一覧または検索、作成または更新、アップロード、ダウンロード、バックグラウンドイベント、トークン更新を1回ずつテストします。GETが1回成功しただけでは、認証が必要な書き込みや長時間接続が修復されたとは限りません。

アドレス経由の直接API呼び出しは機能するのに、公開ホスト名経由では失敗する場合は、ZimaSpaceのIP到達性とドメインルーティングの切り分けに進みます。

ブラウザーとブラウザー以外のクライアントが意図した正規エンドポイントを使用し、プロキシが正しいバックエンドに到達し、リダイレクト後も認証が維持され、ブラウザーのポリシーがレスポンスを受け入れ、ストリーミングまたはWebSocketセッションが安定して初めて問題は解決したと判断できます。今後のアップグレードに備え、キャプチャした失敗リクエストを回帰テストとして保存してください。