comfyui-gateway

ComfyUI ゲートウェイ

概要

既存の ComfyUI サーバーを取り巻く REST ゲートウェイを設計またはレビューします。このスキルにはドキュメントのみが含まれています。ゲートウェイアプリケーション、パッケージマニフェスト、Dockerfile、CLI、データベースマイグレーション、実行可能なワークフローテンプレートは同梱されていません。インストールや起動コマンドを提案する前に、実際の実装とそのバージョンを確認してください。以下に示すゲートウェイのルートは、ComfyUI のネイティブエンドポイントではありません。

使用する場面

ComfyUI のジョブ送信、認証済みの結果配信、ワーカーキュー、Webhook 統合を設計する場合に使用します。ComfyUI を直接呼び出す場合は、ネイティブ API を参照してください。

アーキテクチャと契約

ゲートウェイでは、リクエストを検証し、レビュー済みのワークフローテンプレートにマッピングし、ComfyUI に作業を送信し、ジョブ状態を永続化して、認可された出力を配信できます。Fastify、BullMQ、Redis、SQLite/Postgres、S3 は利用可能なコンポーネントの例であり、インストール済みの機能ではありません。

提案するゲートウェイ操作	必須の動作
POST /jobs	呼び出し元を認証し、入力の範囲を検証し、ワークフローを認可して、ジョブ ID を返す
GET /jobs/:id	このプリンシパルがアクセスできるジョブのみを返す
POST /jobs/:id/cancel	キャンセルを認可し、キャンセル要求とキャンセル確認を区別する
GET /outputs/:id/:file	所有権とパスの包含関係を確認し、呼び出し元のファイルパスを決して信頼しない
Workflow CRUD	管理者権限を必須とし、変更を監査する
Health/capabilities	秘密情報を含めず、最小限の運用情報を公開する

たとえば queued、running、succeeded、failed、canceled のように、状態を表す用語を統一して定義してください。状態遷移はアトミックに永続化してください。クライアントのタイムアウトによってサーバー側の処理がキャンセルされることはありません。再起動後の復旧、冪等性キーの適用範囲と有効期限、リトライの動作を定義してください。Redis だけでは耐久性や厳密に 1 回の実行は保証されません。

ComfyUI のネイティブルートには、POST /prompt、GET /history/{prompt_id}、GET /view、GET /object_info、WS /ws があります。固定したサーバーバージョンのリクエスト／レスポンス形式を検証してください。ComfyUI から API 形式のワークフローを完全な形でエクスポートしてください。存在しないノードを参照する 2 ノードの断片は実行できません。テンプレートをレンダリングする際は数値入力の型を保持し、不明なノードやパラメーターを拒否してください。

セキュリティと運用上の境界

• 開発用リスナーはループバックにバインドしてください。リモート環境へのデプロイには、TLS、認証、プリンシパルごとの認可、ネットワーク制御が必要です。CORS はアクセス制御ではありません。必須の認証情報が不足している場合は、起動を失敗させてください。
• API／JWT／ストレージのシークレットはシークレットストアに保管してください。環境ファイルの内容を表示したり、管理者キーをブラウザクライアントに埋め込んだり、アクセスを修正するために場当たり的な管理者 JWT を発行したりしないでください。
• コールバックのオリジンと解決された IP を制限し、適切にプライベートネットワーク／メタデータネットワークをブロックして、リダイレクトのたびに再検証するか、リダイレクトを無効にしてください。ホスト名の許可リストだけでは、SSRF や DNS リバインディングを防げません。
• Webhook の正確なバイト列に署名し、副作用を起こす前に検証してください。リプレイ対策と永続的な重複排除を追加し、永続的な受け入れが完了してからのみ応答してください。
• 出力はデフォルトで非公開にしてください。ファイルシステムのパス、テナント別キャッシュキー、署名付き URL の有効期間を制限してください。キャッシュの識別情報にはワークフロー／モデル／バージョン／シードを含めてください。ランダムシードのジョブで、別の生成結果やテナントデータを誤って再利用しないでください。
• ジョブ数、寸法、バッチ、実行時間、ポーリング、ダウンロード量、コストに上限を設定してください。通常、ステップ数が増えると所要時間も長くなります。ステップ数を減らせば OOM が解決すると約束する前に、実際にメモリ不足を引き起こしているノードを特定してください。モデル、ハードウェア、カスタムノードも影響します。
• モデル／カスタムノードのライセンスとコードを有効化前に確認してください。計画されているインストール、デプロイ、データ送信、破壊的な操作を提示し、承認を得てください。

例

ユーザー：「ローカルの ComfyUI をジョブ API の背後に配置してください。」

応答：「まず、レビュー済みのサーバー／ゲートウェイのコミット、ワークフロー全体、許可された呼び出し元、出力の保持期間を確認します。ジョブ状態と認証の契約を提案し、その後、隔離されたデプロイ環境で、無効な入力、ユーザーをまたいだジョブへのアクセス、コールバックの SSRF、リプレイ、再起動後の復旧、キャンセルをテストしてから公開します。」

Webhook の検証については統合ガイダンスを、範囲を限定した診断についてはトラブルシューティングを参照してください。

制限事項

これは設計リファレンスであり、デプロイ可能なゲートウェイでも、本番環境のセキュリティ認証でもありません。このツリーでは、ランタイム／API 互換性、スループット、自動フォールバック、プライバシーモード、同梱モデル、デプロイに関する保証は確立されていません。これらの機能を主張する前に、実際の実装に対するテストを必須としてください。

ソース

• ComfyUI サーバールート
• Node の定数時間比較