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

Eva Wong は テクニカルライター であり、 生粋の技術好き としてZimaSpaceで活動しています。ホームラボやオープンソースソフトウェア をこよなく愛する生粋のギークで、複雑な技術概念をわかりやすく、実践的なガイド にまとめることを得意としています。Evaは、セルフホスティングは難しいものではなく、楽しむものだと考えています。チュートリアルを通じて、初めてのNAS構築からDockerコンテナの使いこなしまで、コミュニティがハードウェアのセットアップをわかりやすく理解できるよう 支援しています。、初めてのNAS構築からDockerコンテナの習得まで。

ローカルでページを開けても、APIへの経路が機能するとは限りません。ブラウザーの画面とバックエンドへのリクエストでは、ホスト、ポート、プロトコル、認証情報が異なる場合があります。

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

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

ブラウザーの開発者ツールを開き、問題の操作を再読み込みします。リクエストURL、メソッド、ステータス、レスポンス本文、リモートアドレス、開始元を記録し、失敗が通常のHTTPリクエスト、WebSocket、サーバー送信イベント、バックグラウンドフェッチのどれに当たるかを確認します。

セルフホスト型Baserowの事例では、画面は使用できるものの、ブラウザーのイベント接続が別のプロキシ経路をたどっていたため、再接続の通知が繰り返し表示されました。目に見える症状は、Webサーバー全体の停止ではなくイベント接続の失敗でした。

成功したドキュメントリクエストと失敗したAPIリクエストを、スキーム、ホスト名、ポート、パスのプレフィックス、クエリ文字列の各文字単位で比較します。違いがあれば、最初に変化した層を調べます。同一であれば、ヘッダー、Cookie、レスポンス処理、バックエンドのルーティングを確認します。

各関連ネットワーク境界から同一のリクエストを再実行する

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

APIはTCPおよびHTTPの各層で到達可能でも、トークンやヘッダーがないために実際のリクエストを拒否することがあります。FreshRSSのAPIに関する議論では、外部からの接続障害の原因は、コンテナ全般の到達性ではなく認証コンテキストの欠如に絞り込まれました。

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

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

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

サブパスでのデプロイでは、スラッシュの扱いと書き換えルールが特に重要です。Frigateのリバースプロキシ事例では、メインインターフェースにアクセスできるにもかかわらず、サブパスの書き換え動作がリソース読み込みの失敗原因だと判明しました。

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

リバースプロキシのヘッダー、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セッションが安定している場合にのみ、問題は解決したといえます。将来のアップグレードに備え、失敗したリクエストを記録して回帰テストとして保存してください。

サポートとヒント

続きを読む

Get More Builds Like This

Stay in the Loop

Get updates from Zima - new products, exclusive deals, and real builds from the community.

Stay in the Loop preferences

We respect your inbox. Unsubscribe anytime.