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	强制执行所有权和路径限制；绝不信任调用方提供的文件路径
工作流 CRUD	要求管理员授权并审计变更
健康状态/功能	公开最少的运行信息，不包含机密

指定一套状态词汇，例如 queued、running、succeeded、failed 和 canceled。以原子方式持久化状态转换。客户端超时不会取消服务器端任务。定义重启恢复、幂等键的作用范围和有效期，以及重试行为；仅使用 Redis 并不能证明数据持久性或恰好一次执行。

ComfyUI 原生路由包括 POST /prompt、GET /history/{prompt_id}、GET /view、GET /object_info 和 WS /ws。请验证固定版本的服务端请求/响应格式。从 ComfyUI 导出完整的 API 格式工作流；引用了缺失节点的双节点片段无法执行。渲染模板时保留数值输入类型，并拒绝未知节点/参数。

安全与运行边界

• 将开发环境的监听器绑定到回环地址。远程部署需要 TLS、身份验证、针对每个主体的授权以及网络控制。CORS 不属于访问控制。缺少必需凭据时，启动必须失败。
• 将 API/JWT/存储机密保存在机密存储中；不要回显环境文件、在浏览器客户端中嵌入管理员密钥，也不要为修复访问问题临时签发管理员 JWT。
• 限制回调来源和解析后的 IP；酌情阻止私有网络/元数据网络，并重新验证每次重定向，或禁用重定向。仅使用主机名允许列表无法防止 SSRF 或 DNS 重绑定。
• 对 Webhook 的原始字节进行签名，并在执行副作用前完成验证。添加重放处理和持久化去重机制；仅在持久化接受请求后确认。
• 默认将输出设为私有。限制文件系统路径、租户缓存键和签名 URL 的有效期。将工作流/模型/版本/种子纳入缓存标识；随机种子的作业不得意外复用其他生成结果或租户数据。
• 限制作业数量、尺寸、批次、运行时间、轮询次数、下载字节数和成本。更多步骤通常会增加耗时；在承诺减少步数可以解决 OOM 前，应先诊断实际导致内存故障的节点。模型、硬件和自定义节点都很重要。
• 激活前审核模型/自定义节点的许可证和代码。将计划中的安装、部署、数据传输和破坏性操作展示给用户审批。

示例

用户：“为本地 ComfyUI 接入任务 API。”

回复：“首先确认经过审查的服务/网关提交版本、完整工作流、允许的调用方和输出保留策略。我会提出任务状态/身份验证契约，然后在隔离的部署环境中测试无效输入、跨用户任务访问、回调 SSRF、重放、重启恢复和取消操作，再将其开放出去。”

请阅读集成指南，了解 Webhook 验证；阅读故障排查指南，了解范围受限的诊断。

限制

这是一份设计参考，不是可部署的网关，也不构成生产环境安全认证。本项目树并未保证运行时/API 兼容性、吞吐量、自动回退、隐私模式、包含模型或部署能力。在断言这些功能存在之前，必须针对实际实现进行测试。

来源

• ComfyUI 服务端路由
• Node 恒定时间比较