OpenAPI：管理 API の公開と AI Agent
fn-knock の Rust 管理バックエンドは OpenAPI 3.1 ドキュメントを提供しています。管理エンドポイントの確認、クライアントコードの生成、自動化ツールとの連携に利用できます。このガイドでは、管理バックエンドが 127.0.0.1:7998 で待ち受け、fn-knock 自身のプロトコルマッピングを使って knock.example.com:7999 からドキュメントへアクセスする構成を例にします。
管理 API では、マッピング、証明書、DDNS、WAF、その他のシステム設定を変更できます。通常の公開 Web ページのように直接公開しないでください。プロトコルマッピングの認証を有効にし、固定送信元 IP、VPN、または別のネットワークアクセス制限を併用してください。
ドキュメントのエンドポイント
| アドレス | 内容 |
|---|---|
http://127.0.0.1:7998/docs | Swagger UI の対話型ドキュメント |
http://127.0.0.1:7998/docs/json | OpenAPI 3.1 JSON |
http://knock.example.com:7999/docs | 以下のマッピング設定後に使える外部ドキュメントエンドポイント |
この例では、現在のインスタンスの管理バックエンドがポート 7998 を使用しているものとします。OpenWrt のデフォルトは 17998 です。ポートを変更している場合は、実際のデプロイ設定を使用してください。外部マッピングを作成する前に、fn-knock ホスト上でローカルの /docs を開き、バックエンドポートとドキュメントが利用できることを確認します。
プロトコルマッピングでドキュメントを公開する
プロトコルマッピングは、ドメインではなく TCP／UDP とポートで転送します。knock.example.com は fn-knock の公開入口 IP を参照するだけです。この経路を識別するのは外部 TCP ポート 7999 です。
ブラウザー
-> http://knock.example.com:7999/docs
-> ルーターまたはクラウドファイアウォールで TCP 7999 を許可
-> fn-knock プロトコルマッピング TCP :7999
-> 127.0.0.1:7998
-> Swagger UIシステム設定 → モードを開き、現在のモードがサブドメインモードであることを確認します。システム設定 → 機能でプロトコルマッピングを有効にします。プロトコルマッピングを開き、次のルールを追加します。項目 例 トランスポートプロトコル TCP外部ポート 7999コメント fn-knock OpenAPI転送先 127.0.0.1:7998認証を必須にする 有効 ルーターで「公開 TCP
7999→ fn-knock ホストの TCP7999」を設定します。クラウドサーバーでは、セキュリティグループでも同じポートを許可してください。Docker では、コンテナの起動設定でこのポートを明示的に公開する必要があります。認証を必須にするを有効にした場合は、同じグローバル IP から fn-knock の Web ログインを完了し、ログイン後の IP アクセス許可が無効になっていないことを確認します。固定送信元には IP／CIDR を手動で許可することもできます。http://knock.example.com:7999/docsを開きます。バックエンドポート7998はデフォルトで HTTP を提供します。前段に TLS 終端を別途設定していない限り、この例をそのままhttps://に変更することはできません。
Swagger UI のスクリプト、スタイル、アイコンは fn-knock に同梱され、/docs/assets/ からローカル配信されます。jsDelivr、unpkg、その他の公開 CDN には依存しません。管理バックエンドと /docs/json にアクセスできれば、オフライン環境やフロントエンド CDN を利用できない環境でもドキュメント全体を開けます。不明なアセットパスには 404 が返ります。
OpenAPI 契約ではすべての管理操作に、簡体字中国語のカテゴリ説明、操作概要、動作上の境界、レスポンス説明が用意されています。一部の複雑な操作には、リクエスト例、レスポンス例、Schema フィールドの説明も含まれます。同じ内容が Swagger UI と /docs/json の両方に入るため、コードジェネレーターや AI Agent も読み取れます。パス、メソッド、フィールド名はコード内の元の形式のままです。
契約の説明文は管理画面の言語に連動せず、現在は簡体字中国語で提供されます。書き込み操作の副作用を名前だけから推測せず、呼び出し前に操作説明と Schema の両方を確認してください。
403 が返る、または接続できない場合
403 Forbidden：一部の Docker、Linux、OpenWrt、Windows 環境では、保護された管理エンドポイントを経由する必要があります。内部バックエンドへの直接アクセスは拒否されます。この保護は維持し、内部プロキシヘッダーの偽装や管理画面の迂回は行わないでください。- すぐに切断される：プロトコルマッピングの認証、現在の送信元 IP 許可、認証情報のサービススコープを確認します。
- 接続がタイムアウトする：DNS、ルーターのポート転送、クラウドのセキュリティグループ、Docker のポート公開、ホストファイアウォールの順に確認します。
- ローカルでは開けるが外部から開けない：ルーターの転送先が内部ポート
7998ではなく、fn-knock の外部ポート7999になっていることを確認します。
プラットフォームごとの制限と詳しい調査方法は、TCP／UDP ストリームプロキシを参照してください。
OpenAPI ファイルを取得する
OpenAPI JSON をローカルへ保存し、コードジェネレーター、API クライアント、AI Agent に渡すことができます。
curl --fail \
http://knock.example.com:7999/docs/json \
-o fn-knock-openapi.json現在の契約は実際に登録された管理ルートから生成され、リクエストボディ、レスポンス、パスパラメーター、主要なエラー構造の Schema を提供します。ビルドとテストでは、ドキュメントにある path / method が実在することも検証されます。契約は fn-knock のバージョンとともに変わるため、クライアント生成時には対象インスタンスの /docs/json とバージョン番号を保存し、古い Schema を異なるバージョンへそのまま適用しないでください。型が揃っていても、生成コードはテスト用インスタンスで検証し、まず読み取り専用の GET エンドポイントから始めます。
AI Agent に連携コードを書かせる
URL またはローカルファイルを読み取れる AI Agent は、最初に /docs/json を確認し、実際のタスクに応じて Python、TypeScript、Go、Shell のコードを生成できます。例：
http://knock.example.com:7999/docs/json を読み取り、
TypeScript クライアントを生成してください。
1. 読み取り専用エンドポイントだけを実装し、POST、PATCH、PUT、DELETE は呼び出さない。
2. fn-knock のレスポンスエンベロープと 2xx 以外のエラーを統一して処理する。
3. ベース URL は FN_KNOCK_API_BASE 環境変数から読み取る。
4. 各関数に型、タイムアウト、テストを生成する。
5. Cookie、パスワード、Token をソースコードやログへ書き込まない。設定を変更する場合は、操作範囲、対象リソース、確認手順をプロンプトに含めます。たとえば、Agent が現在の状態を読み取り、変更内容をプレビューし、人が確認した後にだけ書き込みエンドポイントを呼び出すよう指定します。OpenAPI にリクエストボディが記載されていない場合は、ブラウザーの開発者ツールから機密情報を除いたリクエスト例も渡し、実際のフィールドに合わせて型を補完させます。
生成されたコードを使う前に、少なくとも次を確認します。
- ベースアドレスが意図したインスタンスを指している。
- そのデプロイで必要な管理セッションまたは認証情報を送信している。
- リクエストにタイムアウトがあり、失敗レスポンスを処理している。
- 書き込み操作に冪等性、バックアップ、または人による確認がある。
- ログに Cookie、認証情報、証明書の秘密鍵、内部アドレスが含まれない。
セキュリティ境界
VPN、固定グローバル IP、または一時的なポートマッピング経由のアクセスを優先してください。インターネット全体へ長期間公開することは推奨しません。
プロトコルマッピングの
認証を必須にするを有効にします。テスト完了後に不要になった場合は、機能を無効にするかルールを削除してください。/docsはインターフェイスの説明ページであり、危険な書き込み操作を安全にするものではありません。Swagger UI のTry it outは現在のインスタンスへ実際のリクエストを送信します。/docs/jsonも管理エンドポイントの一覧を公開するため、管理プレーンの一部として扱ってください。変更前にバックアップをエクスポートしてください。証明書、WAF、DDNS、マッピング、メンテナンスの書き込みエンドポイントは、非本番環境で検証します。