静的ファイルとディレクトリのレスポンス

Host マッピングでは、リバースプロキシを経由せず、fn-knock ゲートウェイが動作するファイルシステム上のファイルまたはディレクトリから直接リクエストに応答できます。ダウンロードファイル、静的ドキュメント、小規模なサイト、読み取り専用のファイル一覧を公開する用途に適しており、別途 Web Server を動かす必要はありません。

静的レスポンスも完全な Host ルートです。ログインを必須にする、高度な認証、ゲートウェイの可視性、WAF、利用可能時間、リクエストログ、ゲートウェイのスロットリングは、ファイルを読み取る前に適用されます。サーバー側の書き換えやシングルページアプリケーション（SPA）のフォールバックは提供しません。不明なパスをすべて index.html へ返す必要がある場合は、その機能を備えたアップストリーム Web Server を引き続き使用してください。

レスポンス種別を選択

サービス用 Host を追加または編集するときに、レスポンス種別 から選択します。

レスポンス種別	リクエストの動作	主な用途
リバースプロキシ	リクエストを HTTP、HTTPS、または WebSocket の Target へ転送	動的な Web アプリケーションと API
単一ファイル	現在の Host のルートパス / でのみ指定ファイルを返す	ダウンロード入口、説明ファイル、固定リソース
ディレクトリ	URL パスを指定ディレクトリ内のファイルやサブディレクトリへ対応付ける	静的サイト、ドキュメント、ファイル閲覧

リバースプロキシから静的レスポンスへ切り替えるときは確認が表示され、プロキシ専用の Target、パス別応答、アップストリーム Basic 認証、Host の維持、Target パスモードが消去されます。Host の認証、可視性、WAF、利用可能時間、タイトル、アイコン、グループは保持されます。編集画面を閉じる前にリバースプロキシへ戻せば、今回まだ保存していないプロキシの下書きを復元できます。

静的マッピングはファイルの内容からタイトルやアイコンを自動取得しません。ポータル、マッピング一覧、ブックマークに分かりやすい名前を表示する場合は、表示タイトル を手入力し、カスタムアイコンをアップロードしてください。

設定手順

1. サブドメインモード または トンネル → サブドメインマッピング を使用し、サービス用 Host が fn-knock ゲートウェイへ到達するようにします。
2. サブドメインマッピング でサービス用 Host を追加または編集し、単一ファイル または ディレクトリ を選びます。
3. サーバーパス の横にある 参照 をクリックします。ゲートウェイサーバーを階層ごとに参照するか、アドレスバーへ絶対パスを入力して Enter キーで移動できます。
4. ディレクトリレスポンスでは対象ディレクトリへ移動して 現在のフォルダーを使用 をクリックします。単一ファイルのレスポンスでは通常ファイルを選択してから 選択したファイルを使用 をクリックします。
5. ディレクトリレスポンスでは、必要に応じてデフォルトドキュメント、ディレクトリ一覧、README の表示を調整します。
6. ログインを必須にする、ゲートウェイの可視性、WAF、利用可能時間、タイトル、アイコンを設定して保存します。
7. 実際のアクセス経路からルートパス、存在するファイル、存在しないパスをリクエストし、リクエスト分析でルート種別とステータスコードを確認します。

サーバーパスを参照する

パスブラウザーに表示されるのは、管理画面を開いている端末ではなく、fn-knock ゲートウェイプロセスから見えるファイルシステムです。すでにパスが入力されていれば、その場所から開始します。空の場合、POSIX プラットフォームでは / から始まり、Windows では利用可能なローカルドライブが最初に表示されます。ファイルシステムのルートは移動にだけ使用でき、静的ディレクトリとして選択できません。Docker ではコンテナへマウント済みの内容だけを参照でき、パスブラウザーがホスト側のパスを読み取ったり、マウントを作成・変更したりすることはありません。

アドレスバーには絶対パスを入力でき、その横にはルート、1 つ上の階層、パンくずリスト、再読み込みの操作があります。一覧は常にディレクトリを通常ファイルより先に表示し、1 ページあたり最大 100 項目で、前後のページへ移動できます。単一ファイルモードで選べるのは通常ファイルだけで、ディレクトリモードでは現在のフォルダーを使用します。安全上の上限内で走査できないほど項目が多い場合はディレクトリ全体がエラーになり、選択を誤らせる可能性のある途中までの一覧は返しません。

パスブラウザーでは、. で始まる隠し名、__ で始まる内部予約名、特殊ファイル、安全に開けない項目、保護対象パスとその配下が省略されます。保護対象パスの上位ディレクトリは別の場所へ移動するために参照できますが、静的ルートには選択できません。シンボリックリンクが表示されるのは、解決後も現在参照中のディレクトリ内に留まり、隠し場所や保護対象の場所へ入らない場合だけです。

現在のフォルダーを使用 または 選択したファイルを使用 をクリックすると、その正確なパスが存在し、読み取り可能で、種類も一致しているかが改めて確認されます。確認に成功しても、現在編集中のマッピングの下書きへパスが書き戻されるだけで、反映するにはマッピングを保存する必要があります。これはその時点での確認であり、ファイルやマウントポイントを固定するものではありません。新しい静的マッピングを保存するとき、またはサーバーパスやレスポンス種別を変更するときもパスが確認されますが、ディレクトリオプションだけを変更した場合は再確認されません。選択時と保存時の両方で確認に成功しても、その後にパスが削除、置換されたり、読み取り権限を失ったりする可能性があります。ゲートウェイはリクエストごとに対象を開き直して検証します。

単一ファイルのレスポンス

単一ファイルのマッピングは、Host のルートパスにだけ応答します。

download.example.com/        -> /srv/downloads/manual.pdf
download.example.com/other   -> 404

ゲートウェイはサーバー上のファイル名の拡張子に基づいて Content-Type を設定し、GET、HEAD、Range リクエスト、一般的な条件付きキャッシュリクエストに対応します。ファイルの内容が変わると、ETag と更新日時もファイルの状態に合わせて変わります。URL にサーバー上のファイル名を含める必要はなく、クエリパラメーターによって選択されるファイルが変わることもありません。

ディレクトリのレスポンス

ディレクトリマッピングは、リクエストパスを設定したルートディレクトリの配下へ順に対応付けます。

docs.example.com/                 -> /srv/docs/
docs.example.com/assets/app.css   -> /srv/docs/assets/app.css
docs.example.com/manual/          -> /srv/docs/manual/

リクエストがディレクトリに一致しているのに URL の末尾に / がない場合、ゲートウェイはクエリパラメーターを保ったまま、末尾にスラッシュが付いた正規 URL へ恒久的にリダイレクトします。通常ファイルの URL の末尾に誤って / が付いている場合は、クエリパラメーターを保ったまま、末尾のスラッシュを取り除いた正規 URL へ恒久的にリダイレクトします。ディレクトリに入ると、設定順にデフォルトドキュメントを探します。初期順序は index.html、index.htm で、最大 16 件まで設定できます。名前はパス区切り文字を含まない、表示可能な単一のファイル名に限られます。一覧を空にするとデフォルトドキュメントの検索は無効になります。

デフォルトドキュメントが見つからない場合は、次のように動作します。

• ディレクトリ一覧 が無効：404 を返します。
• ディレクトリ一覧 が有効：現在のディレクトリのファイル一覧を生成します。
• README.md を表示 はディレクトリ一覧が有効な場合だけ利用でき、現在のディレクトリにある README.md を安全にレンダリングして一覧の下に表示します。

ディレクトリ一覧はデフォルトで名前順に並び、通常ファイルよりもディレクトリを常に先に表示します。名前、サイズ、更新日時を基準に昇順と降順を切り替えられ、パンくずナビゲーション、ライト／ダークテーマ、前後のページ移動も備えています。1 ページには最大 100 件を表示します。インデックス画面のラベルは現在英語で、更新日時は北京時間（UTC+8）で固定表示されます。隠し名、特殊ファイル、安全に開けない項目は表示されません。

README には GitHub Flavored Markdown を使用し、1 ファイルの上限は 1 MiB です。生の HTML と安全でない内容は除去され、画像には同一オリジンの相対アドレスだけを使用できます。外部リンクには安全性を高める属性が追加されます。README が表示されるのは、デフォルトドキュメントに一致せず、実際にディレクトリ一覧を表示する場合だけです。

ディレクトリレスポンスでは、拡張子の書き換え、動的圧縮、末尾パスのフォールバック、SPA History Fallback は行われません。また、静的ターゲット用のカスタムレスポンスヘッダーやキャッシュポリシーを設定する項目もありません。リクエストしたファイルが存在しない場合は、そのまま 404 を返します。

認証、WAF、ログ、キャッシュ

静的 Host には、リバースプロキシ Host と同じ受信ポリシーが適用されます。

• ログインを必須にする と高度な認証は、ファイルを読み取る前に確認されます。LAN からのアクセスは引き続き local_exempt になる場合があるため、公開側のポリシーは実際の外部ネットワークから検証してください。
• ゲートウェイの可視性、共通ブラックリスト、スキャンのブロック、リバースプロキシのスロットリング、利用可能時間は引き続き有効です。
• 現在の Host で WAF を有効化 がオンになり、グローバル WAF も有効な場合は、静的コンテンツを読み取る前にリクエストが WAF を通過します。
• リクエストログと WAF ログでは、ルート種別がそれぞれ 静的ファイル または 静的ディレクトリ と記録され、アップストリーム Target は空になります。サーバーのファイルシステムパスがログへ記録されることはありません。

公開された静的ファイルには、再検証が必要な共有キャッシュポリシーが使用されます。認証が必要なレスポンス、または認証結果を伴うレスポンスには private, no-store が使用され、保護された内容が共有キャッシュへ入ることを防ぎます。生成されたディレクトリ一覧、リダイレクト、エラーレスポンスも共有キャッシュには入りません。

ファイルシステムのセキュリティ境界

サーバーパス は絶対パスで、表示可能な通常ファイルまたはディレクトリを指している必要があります。ゲートウェイは、ファイルシステムのルートディレクトリ、隠しターゲット、親ディレクトリへの移動、制御文字、Windows の UNC／デバイス名前空間、fn-knock の設定、データ、ログ、鍵、システムディレクトリと重複するパスを拒否します。保護対象のディレクトリを内包するほど範囲が広い親ディレクトリも拒否されます。

ファイルシステム上の名前は正確な表記のまま扱われます。POSIX プラットフォーム（Linux、macOS など）では、パス要素の先頭または末尾にある空白は自動で削除されないため、/srv/docs と /srv/docs は別の対象です。入力全体が空白だけの場合に限って拒否されます。混同しやすい名前はできるだけ避け、パスをコピーするときは実際の文字を保ってください。Windows では引き続き、空白またはピリオドで終わる名前、予約済みのデバイス名、その他の安全でない名前が拒否されます。

ディレクトリ内で応答対象になるのは、表示可能な通常ファイルとサブディレクトリだけです。ドットファイル、ドットディレクトリ、.well-known は利用できません。シンボリックリンクは、静的ルートの内部にある安全なターゲットへ解決される必要があります。ルート外へ出る場合、隠し場所へ入る場合、検証中に変化した場合はリクエストが失敗します。FIFO、Socket、デバイスファイルなどの特殊な種類がダウンロード内容として開かれることはありません。

これらの制限だけでは、業務上の内容を公開してよいか判断できません。サイトごとに独立した最小限のディレクトリを用意し、読み取り専用権限を使用してください。バックアップ、環境変数、秘密鍵、データベース、アプリケーション設定を静的ルートへコピーしないでください。ディレクトリ一覧を公開する前に、すべてのサブディレクトリと README 内のリンクや画像を確認してください。

Docker とプラットフォーム別パス

パスは常に fn-knock プロセスから見たものとして解釈されます。

• Docker では、最初にホスト側のコンテンツをコンテナへ読み取り専用でマウントしてから、コンテナ内のパスを入力します。ホスト側のパスをそのまま使用することはできません。
• Linux、macOS、OpenWrt、fnOS FPK / Lite、Synology DSM では、該当パッケージの実行アカウントにディレクトリの走査権限とファイルの読み取り権限が必要です。
• Windows では C:\Sites\docs のようなローカルドライブの絶対パスを使用します。ネットワーク共有パスとデバイス名前空間には対応していません。

Docker Compose の例：

services:
  fn-knock:
    volumes:
      - /srv/public-site:/srv/public-site:ro

マウントを変更したらコンテナを再作成し、管理画面で 参照 をクリックします。パスブラウザーに /srv/public-site が表示されることを確認し、そのディレクトリへ移動して 現在のフォルダーを使用 をクリックしてから、マッピングを保存します。静的コンテンツを読み取る目的で、ホストのルートディレクトリ、/etc、fn-knock のデータボリューム全体をコンテナへマウントしないでください。

静的マッピングは既存ファイルを読み取るだけで、DNS レコードの作成、ファイアウォールポートの開放、コンテナマウントの変更は行いません。外部から到達できるかどうかは、現在のデプロイプラットフォームにおけるゲートウェイ入口、DNS、証明書、ルーター、トンネルによって決まります。

ステータスコードとトラブルシューティング

症状	確認項目
保存時にパスが利用できないと表示される	絶対パス、ファイル／ディレクトリの種類、読み取り権限、保護対象のパス、Docker マウント
パスブラウザーにファイルやディレクトリが表示されない	現在参照しているのがゲートウェイ／コンテナのファイルシステムか、名前が隠し名や予約名でないか、読み取り権限、保護対象パス、シンボリックリンクの解決先を確認
パスブラウザーにディレクトリ内の項目が多すぎると表示される	より小さい専用コンテンツディレクトリを使用し、範囲の広い共有ディレクトリを静的ルートへ直接指定しない
ルートパスが 503 を返す	設定したルートディレクトリまたは単一ファイルが存在しない、読み取れない、安全でなくなっている。レスポンスには短時間後の再試行を促す情報が含まれます
サブパスが 404 を返す	ファイルが存在しない、安全規則により名前が非表示、ディレクトリ一覧が無効、または単一ファイルのマッピングにルート以外のパスが送られた
405 を返す	静的レスポンスが受け付けるのは GET と HEAD だけです
サイトのトップページではなくディレクトリ一覧が表示される	デフォルトドキュメントの名前または優先順位が正しくないか、該当ファイルを読み取れません
ページ更新後にフロントエンドルートが 404 になる	静的ディレクトリには SPA フォールバックがありません。History Fallback に対応するアップストリーム Web Server を使用してください
リクエストログにアップストリームアドレスがない	静的レスポンスはゲートウェイがファイルを直接読み取るため、想定どおりの動作です

トラブルシューティングでは、まず編集画面で 参照 を開き、同じ場所へ移動して 現在のフォルダーを使用 または 選択したファイルを使用 をもう一度実行します。次に fn-knock の実行環境から権限とマウントを確認し、最後にリクエストログの Host、ルート種別、認証結果、WAF アクション、ステータスコードを確認します。パスの安全確認を回避するためにシステムディレクトリまで範囲を広げたり、不要な root 権限を与えたりしないでください。

関連する設定については、サブドメインマッピング、Docker Compose でデプロイ、WAF、セキュリティ境界とベースラインを参照してください。