SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场comfyui-gateway

comfyui-gateway

智能体与模型

查看项目

更新于 10-16 02:41

技能介绍

用途

ComfyUI Gateway 是一个 REST API 网关，用于把 ComfyUI 服务器包装成通用、安全且可扩展的服务。它面向需要通过 HTTP 接口调用 ComfyUI 生成能力的场景，例如从 curl、n8n、Claude、Lovable、Supabase 等客户端提交生成任务。

主要能力

  • 工作流管理：以 ComfyUI JSON 作为模板，支持 {{placeholder}} 占位符，运行时结合任务输入与参数渲染；每个工作流可附带 inputSchema（Zod）用于校验客户端入参。提供工作流的增删改查接口。
  • 任务队列：POST /jobs 立即返回 jobId，支持优先级；队列可基于 Redis（BullMQ），也可在未配置 Redis 时使用内存队列。
  • 任务生命周期：queued → running → succeeded / failed / canceled，可查询状态、进度与输出，可获取脱敏后的执行日志，可请求取消。
  • 缓存：缓存键为 workflowId + 排序后的 inputs + 排序后的 params + checkpoint 的 SHA-256；命中时返回已有输出的“虚拟”任务，无需 GPU 计算。缓存与任务数据一同存入数据库，TTL 可配置。
  • 通知：支持 callbackUrl 时发送带 HMAC-SHA256 签名的 Webhook（X-Signature 头），并可通过允许域名白名单限制回调目标。
  • 鉴权与限流：通过 API_KEYS 配置 key:role，支持 admin（工作流与任务完整 CRUD）与 user（创建任务、读取自己的任务）角色；可选 JWT（设置 JWT_SECRET 后接受 Authorization: Bearer）；按 key 与 IP 限流，窗口与上限可配置。
  • 存储与交付：存储后端支持本地磁盘或 S3 兼容对象存储；输出可通过 GET /outputs/:jobId 列出文件与元数据，通过 GET /outputs/:jobId/:file 下载或流式获取；资料描述中提到图片交付支持 URL 与 base64。
  • ComfyUI 集成：通过 ComfyUI 原生 HTTP API 交互，使用 POST /prompt 提交渲染后的工作流，GET /history/{id} 轮询完成状态，GET /view?filename=... 下载生成的图片，GET /object_info 发现可用节点/模型，WS /ws?clientId=... 获取实时进度（可选）。客户端会尝试 WebSocket 优先、回退轮询，兼容两种 /history 响应格式，并识别 OOM 错误并给出建议。
  • 错误分类：包括 COMFYUI_UNREACHABLE、COMFYUI_OOM、COMFYUI_TIMEOUT、COMFYUI_NODE_ERROR、VALIDATION_ERROR、WORKFLOW_NOT_FOUND、RATE_LIMITED、AUTH_FAILED、CACHE_HIT，并给出是否可重试的说明。
  • 可观测性：Pino JSON 结构化日志，每个请求带 correlationId；指标涵盖排队/运行/成功/失败任务数、平均处理时长、缓存命中率；管理操作（工作流 CRUD、密钥管理）写入审计日志。

使用方式

安装与初始化：

cd comfyui-gateway
npm install
cp .env.example .env
npx tsx src/cli/index.ts init
npx tsx src/cli/index.ts add-workflow ./workflows/sdxl_realism_v1.json \
  --id sdxl_realism_v1 --schema ./workflows/sdxl_realism_v1.schema.json
npm run dev
# 或分开启动
npm run start:api
npm run start:worker

CLI 参考：

npx tsx src/cli/index.ts init                    # Create dirs, .env.example
npx tsx src/cli/index.ts add-workflow <file>      # Register workflow template
  --id <id> --name <name> --schema <schema.json>
npx tsx src/cli/index.ts list-workflows           # Show registered workflows
npx tsx src/cli/index.ts run                      # Start API server
npx tsx src/cli/index.ts worker                   # Start job worker
npx tsx src/cli/index.ts health                   # Check ComfyUI connectivity

配置全部通过 .env，主要变量包括 PORT（默认 3000）、HOST（0.0.0.0）、COMFYUI_URL（http://127.0.0.1:8188）、COMFYUI_TIMEOUT_MS（300000）、API_KEYS、JWT_SECRET、REDIS_URL、DATABASE_URL（./data/gateway.db，亦支持 Postgres URL）、STORAGE_PROVIDER（local 或 s3）、STORAGE_LOCAL_PATH（./data/outputs）、S3_ENDPOINT、S3_BUCKET、S3_ACCESS_KEY、S3_SECRET_KEY、S3_REGION（us-east-1）、WEBHOOK_SECRET、WEBHOOK_ALLOWED_DOMAINS（）、MAX_CONCURRENCY（1）、MAX_IMAGE_SIZE（2048）、MAX_BATCH_SIZE（4）、CACHE_ENABLED（true）、CACHE_TTL_SECONDS（86400）、RATE_LIMIT_MAX（100）、RATE_LIMIT_WINDOW_MS（60000）、LOG_LEVEL（info）、PRIVACY_MODE（false）、CORS_ORIGINS（）、NODE_ENV（development）。

主要接口：GET /health、GET /capabilities、/workflows 的 CRUD、/jobs 的创建/查询/日志/取消/列表（支持 status、workflowId、after、before、limit 过滤）、/outputs 的列表与下载。任务处理流程为：客户端提交 → 校验、查缓存与幂等 → 命中缓存立即返回，否则入队并返回 jobId 与 pollUrl → Worker 渲染模板并提交 ComfyUI → 轮询或 WebSocket 获取进度 → 完成后下载、存储并更新数据库 → 如有 callbackUrl 则发送签名 Webhook → 客户端轮询或接收回调。

适用场景

需要以 HTTP 方式集中调用 ComfyUI 生成能力的场景，例如批量图片生成（写实图、带透明通道的 2D 游戏素材、方形应用图标）、需要任务队列与 Webhook 异步通知的自动化流程、需要鉴权、限流、缓存与审计的多用户或多客户端接入。项目自带三个模板：sdxl_realism_v1（SDXL base，1024x1024、30 steps、cfg 7.0）、sprite_transparent_bg（SD 1.5 或 SDXL，512x512、25 steps、cfg 7.5）、icon_512（SDXL base，512x512、20 steps、cfg 6.0，可选 2x 放大）。

限制

资料中提到的已知问题包括：ComfyUI 不可达（防火墙、端口错误、Docker 网络）、OOM（需降低分辨率/批量/步数）、生成缓慢（GPU 利用率、队列深度、模型加载）、Webhook 失败（DNS、SSL、超时、域名白名单）、Redis 连接问题（回退内存）、存储权限错误（本地路径、S3 凭据）。资料未提供计费、价格与性能承诺等信息。