パスベースのリバースプロキシ（互換モード）
パスマッピング は、トンネル → パスモード でのみメインルートとして使用されます。1 つの外部 Host にあるパスプレフィックスを別々の HTTP アップストリームへ転送します。たとえば、/alist を AList へ転送できます。
新規デプロイではサブドメインルーティングを優先してください。Host ルーティングでは各アプリをルートパスで動作させられるため、通常はパスの書き換えより安定します。パスモードは、既存の URL を維持する場合や、複数のサブドメインをすぐに用意できない構成に適しています。
ルーティングモデル
https://example.com/alist -> http://127.0.0.1:5244
https://example.com/jellyfin -> http://127.0.0.1:8096ゲートウェイは、最も長いパスプレフィックスから照合します。/app と /app-admin が同時に存在する場合、/app-admin/users へのリクエストは /app-admin に一致します。
パスプレフィックスはブラウザの URL に含まれます。アプリが /、コールバック URL、Service Worker のスコープ、WebSocket アドレスをハードコードしていると、書き換えを有効にしても正常に動作しない場合があります。その場合はルールを追加し続けるのではなく、Host ルーティングへ移行してください。
マッピングの追加
パスマッピング を開き、サービスを検出 で候補ルールを生成するか、手動で入力します。
| フィールド | 役割 |
|---|---|
トリガーパス | / で始まる外部パスのプレフィックス |
転送先 | http、https、ws、wss のアップストリーム URL |
認証を必須にする | 未認証の場合、最初に fn-knock のログインフローへ進めます |
リクエストのプレフィックスを削除 | /alist/users を /users としてアップストリームへ送信します |
HTML の内容を書き換える | 一部のページリソース参照に外部パスのプレフィックスを追加します |
ルートモードを使用 | 一致したマッピングを記録した後、ブラウザを / へ移動させ、ルートパスでの動作が必要なアプリに対応します |
転送先には、fn-knock の実行環境からアクセスできるアドレスを指定する必要があります。通常はループバックアドレスまたは LAN 内のアドレスを使用します。Docker 内の 127.0.0.1 はコンテナ自身を指すため、ホスト上のサービスにはコンテナから到達できるアドレスを使用してください。
サービス検出で提示される認証、書き換え、プレフィックス削除の設定は推奨値にすぎません。保存前に、対象アプリがベースパスへ対応しているかに応じて調整してください。
スキャン画面では、「デバイスの推奨に従う」または低、中、高、最大の強度を選択できます。検出範囲と結果はどのレベルでも同じで、同時実行数、所要時間、デバイス負荷だけが変わります。リソースの限られたデバイスでは、自動または低強度を優先してください。
スキャン対象に指定できるのは、ローカル IPv4 CIDR だけです。候補の設定が自動的に公開されることはありません。転送先の検出元、ポート範囲、同時実行数の制限、トラブルシューティングの詳しい手順については、サービス検出と一括登録を参照してください。
アクセスポリシー
認証を必須にする を無効にすると、そのパスは公開されます。有効にすると、インターネットからの利用者は fn-knock へログインしてからアップストリームへアクセスします。パスマッピングには、独立した厳格な許可リストポリシーはありません。IP 許可リスト で送信元にアクセスを許可できますが、「認証を必須にする」パスをその送信元だけに限定するものではありません。リクエストがパスへ到達する前に送信元を制限するには、ゲートウェイの公開範囲または外部ネットワーク層のルールを使用してください。
ゲートウェイが送信元をループバック、プライベートネットワーク、リンクローカルのいずれかと認識すると、認証結果は local_exempt となり、通常のログイン検査を省略します。このため、LAN からパスを直接開けても、インターネット側の認証が有効になっているとは限りません。FRP などのプロキシを経由する場合は、実際のグローバルクライアント IP が維持されていることをリクエストログで確認してください。
Host マッピングの Basic 認証を自動入力 は、転送先サービスへアップストリーム用の認証情報を挿入する機能で、fn-knock へのログインではありません。パスマッピングで、ブラウザの Basic 認証をゲートウェイ認証の代わりに使用しないでください。
デフォルトルート
デフォルトルートはルートパス / を処理します。サービス検出では通常、fnOS がデフォルトサービスとして設定されます。ルートパスを別のアプリへ明示的に転送する必要がある場合にだけ変更してください。
複数のマッピングまたはデフォルトルートを変更した後は、ルートを同期 をクリックして、現在の設定をゲートウェイへ明示的に再送信できます。通常、個別のルールを保存した時点ですでに同期が実行されます。
Host ルーティングへ移行する場合
次のいずれかに該当する場合は、移行を優先してください。
- 静的リソース、WebSocket、ログインのコールバックがルートパスへ戻ってしまう。
- アプリが設定可能なベースパスに対応していない。
- 複数のアプリでプレフィックス、Cookie、Service Worker が相互に干渉する。
- サービスごとに
ログインを必須にする、公開スケジュール、アップストリームの Basic 認証情報の挿入を設定する必要がある。
トンネル → サブドメインマッピング へ切り替えると、既存のパスルールは保持されますが、入口は非表示になります。Host の経路が安定したことを確認してから、古いルールを削除してください。
トラブルシューティング
- 現在のモードが
トンネル → パスモードであることを確認します。 - fn-knock の実行環境から転送先 URL へ直接アクセスします。
- 最も長いプレフィックスが、想定したルールに一致しているかを確認します。
- アップストリームが受信した URI に応じて、
リクエストのプレフィックスを削除を有効にするか判断します。 - ページリソースの読み込みに失敗する場合は、
HTML の内容を書き換えるを確認します。それでも失敗する場合は、Host ルーティングへの移行を検討してください。 - リクエストログで、クライアント IP、一致したパス、ステータスコード、アップストリームの転送先を確認します。
ネットワークの入口についてはNAT 越えとトンネル、操作手順についてはNAT 越え：サブドメインルーティングとグローバル IP なしでトンネル経由のサブドメインを公開を参照してください。