init

2026-06-30 15:02:20 +08:00
commit 3948b5a48a
306 changed files with 77275 additions and 0 deletions
@@ -0,0 +1,389 @@
+```markdown
+文件 欧先生提供@全力以赴提供
+
+# ComfyUI OpenAI API Proxy
+
+基于 Rust 构建的高性能反向代理，将标准 OpenAI 图像/视频生成 API 调用无缝转换为 ComfyUI 后端请求。支持多后端健康检查、智能负载均衡、WebSocket 双通道、指数退避完全抖动、令牌桶限流、幂等键缓存、请求级响应缓存以及 OpenTelemetry 可观测性，为生成服务提供生产级可靠性。
+
+## 概述
+
+`comfyui-openai-api` 是 OpenAI API 兼容客户端与 ComfyUI 工作流引擎之间的桥梁，核心职责：
+
+- **接收** 标准 OpenAI 格式的图像/视频生成请求
+- **转换** 请求参数为 ComfyUI 工作流注入格式
+- **路由** 根据配置策略将请求分发至健康的 ComfyUI 后端
+- **管理** 异步任务生命周期，支持状态持久化与查询
+- **交付** 符合 OpenAI API 规范的响应（Base64 编码图像/视频）
+
+在 **LocalMiniDrama**（本地 AI 短剧全流程创作工具）等项目生态中，本代理承载着底层生成引擎的统一 API 基座角色，为从剧本到成片的完整链路提供稳定、可扩展的推理调度能力。
+
+## 核心特性
+
+### API 兼容性
+- **OpenAI 图像生成** —— `POST /v1/images/generations`，同步返回 Base64 图像
+- **视频生成扩展** —— `POST /v1/videos/generations`，异步返回 `task_id`，通过 `GET /v1/tasks/{task_id}` 查询结果
+- **任务生命周期管理** —— 查询、列出、删除任务（`GET /v1/tasks`、`GET /v1/tasks/{task_id}`、`DELETE /v1/tasks/{task_id}`）
+- **模型列表** —— `GET /v1/models` 返回所有可用工作流（模型）
+- **后端状态查询** —— `GET /v1/backends` 查看各后端健康状态
+- **健康检查** —— `GET /v1/health` 存活探针
+- **视频子系统状态** —— `GET /v1/videos/health`
+- **Prometheus 指标** —— `GET /v1/metrics`
+- **API 帮助文档** —— `GET /v1/help`
+
+### 多后端管理
+- 支持配置多个 ComfyUI 后端节点，按名称 (`?backend=xxx`) 显式指定或自动选择
+- **定期健康检查**：通过请求每个后端的 `/system_stats`，连续失败达阈值自动摘除，恢复后自动加入
+- **负载均衡策略**：轮询（Round Robin）、最少连接数（Least Connections）、随机（Random），可在配置文件中切换
+
+### 前置条件
+- Rust 1.70+
+- ComfyUI 后端（需启用 `--api` 模式）
+
+
+### 运行
+
+./target/release/comfyui-openai-api
+
+
+
+## API 端点详解
+
+所有端点均以 `/v1` 为前缀。以下是完整列表：
+
+| 端点 | 方法 | 说明 |
+|------|------|------|
+| `/v1/models` | GET | 列出所有可用模型（工作流文件名） |
+| `/v1/health` | GET | 简单存活检查 |
+| `/v1/backends` | GET | 查看所有后端健康状态 |
+| `/v1/images/generations` | POST | 图像生成，同步返回 |
+| `/v1/videos/generations` | POST | 视频生成，异步返回 `task_id` |
+| `/v1/tasks` | GET | 列出所有任务状态 |
+| `/v1/tasks/{task_id}` | GET / DELETE | 查询或删除单个任务 |
+| `/v1/videos/health` | GET | 视频生成子系统状态 |
+| `/v1/metrics` | GET | Prometheus 指标导出 |
+| `/v1/help` | GET | API 帮助文档（JSON） |
+
+### 1. 图像生成 `POST /v1/images/generations`
+
+**请求示例**
+```bash
+curl -X POST 'http://localhost:8080/v1/images/generations?backend=backend-a' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "model": "sdxl-workflow",
+    "prompt": "a cat wearing a hat, masterpiece",
+    "negative_prompt": "low quality, blurry",
+    "size": "1024x1024",
+    "n": 1,
+    "seed": 42,
+    "reference_images": [
+      {"name": "ref1", "data": "data:image/png;base64,iVBOR..."}
+    ]
+  }'
+```
+
+**请求参数（Body）**
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `model` | string | 是 | 工作流文件名（不含 `.json`） |
+| `prompt` | string | 否 | 正向提示词 |
+| `negative_prompt` | string | 否 | 负向提示词 |
+| `size` | string | 否 | 尺寸，如 `"1024x1024"`（可被配置文件覆盖） |
+| `seed` | integer | 否 | 随机种子 |
+| `n` | integer | 否 | 生成数量（批次大小） |
+| `reference_images` | array | 否 | 参考图数组 `[{name, data}]` |
+| `image` | array | 否 | Base64 图片字符串数组（等效于 `reference_images`） |
+
+**查询参数**
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `backend` | string | 否 | 指定后端名称，未指定时自动使用负载均衡策略 |
+
+**响应格式**
+```json
+{
+  "created": 1704067200,
+  "data": [
+    {
+      "b64_json": "iVBORw0KGgoAAAANSUhEUg..."
+    }
+  ]
+}
+```
+
+### 2. 视频生成 `POST /v1/videos/generations`
+
+**请求示例**
+```bash
+curl -X POST 'http://localhost:8080/v1/videos/generations?backend=backend-b' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "model": "video-workflow",
+    "content": [
+      {"type": "text", "text": "a dog running in the park"},
+      {"type": "image_url", "image_url": {"url": "https://example.com/ref.png"}, "role": "reference_image"}
+    ],
+    "duration": 5,
+    "resolution": "720p"
+  }'
+```
+
+**请求参数（Body）**
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `model` | string | 是 | 视频工作流文件名 |
+| `content` | array | 是 | 内容数组，每项可为 `{"type":"text", "text":"..."}` 或 `{"type":"image_url", "image_url":{"url":"..."}, "role":"reference_image"}` |
+| `duration` | integer | 否 | 时长（秒），默认 5 |
+| `resolution` | string | 否 | `"720p"` 或 `"1080p"` |
+| `ratio` | string | 否 | 宽高比，如 `"16:9"` |
+| `local_prompts` | string | 否 | 多镜头提示词，格式 `[起始-结束]\n描述` |
+| `global_prompt` | string | 否 | 全局提示词 |
+| `guide_strengths` | array | 否 | 引导强度数组 |
+
+**响应格式**
+```json
+{
+  "task_id": "vid-1715432100123-789"
+}
+```
+
+### 3. 任务查询 `GET /v1/tasks/{task_id}`
+
+```bash
+curl http://localhost:8080/v1/tasks/vid-1715432100123-789
+```
+
+响应示例（处理中）：
+```json
+{
+  "status": "processing"
+}
+```
+
+响应示例（已完成）：
+```json
+{
+  "status": "completed",
+  "video_url": "http://backend-b:8000/view?filename=video.mp4&subfolder=&type=output",
+  "b64_json": "..."
+}
+```
+
+响应示例（失败）：
+```json
+{
+  "status": "failed",
+  "error": "ComfyUI node error: ..."
+}
+```
+
+### 4. 列出所有任务 `GET /v1/tasks`
+
+```bash
+curl http://localhost:8080/v1/tasks
+```
+
+返回：
+```json
+{
+  "tasks": [
+    {
+      "task_id": "vid-1715432100123-789",
+      "status": "completed"
+    },
+    {
+      "task_id": "img-1715432100456-123",
+      "status": "processing"
+    }
+  ]
+}
+```
+
+### 5. 删除任务 `DELETE /v1/tasks/{task_id}`
+
+```bash
+curl -X DELETE http://localhost:8080/v1/tasks/img-1715432100456-123
+```
+成功时返回 HTTP `204 No Content`。
+
+### 6. 其他端点
+
+- **列出模型** `GET /v1/models`
+```bash
+curl http://localhost:8080/v1/models
+```
+响应：
+```json
+{
+  "object": "list",
+  "data": [
+    { "id": "sdxl-workflow", "object": "model", "owned_by": "comfyui-openai-api" },
+    { "id": "video-workflow", "object": "model", "owned_by": "comfyui-openai-api" }
+  ]
+}
+```
+
+- **后端健康状态** `GET /v1/backends`
+```json
+{
+  "backends": [
+    { "name": "backend-a", "healthy": true },
+    { "name": "backend-b", "healthy": false }
+  ]
+}
+```
+
+- **存活探针** `GET /v1/health`：返回 `OK`
+
+- **Prometheus 指标** `GET /v1/metrics`：返回标准 Prometheus 文本格式指标。
+
+
+### 完整配置项详解
+
+```yaml
+# 日志级别：trace, debug, info, warn, error
+log_level: "info"
+
+# 代理服务绑定地址和端口
+server:
+  host: "0.0.0.0"
+  port: 8080
+
+# 多后端列表，至少需要一个后端
+comfyui_backends:
+  - name: "backend-a"        # 唯一名称，用于通过 ?backend= 选择
+    host: "127.0.0.1"        # ComfyUI 地址
+    port: 8000               # ComfyUI 端口
+    default: true            # 是否默认后端（用于 WebSocket 连接）
+  - name: "backend-b"
+    host: "192.168.1.100"
+    port: 8188
+    default: false
+
+# 代理内部设置
+comfyui_backend:
+  client_id: "comfyui-api"         # WebSocket 客户端 ID
+  workflows_folder: "./workflows"  # 工作流 JSON 存放目录
+  use_ws: true                     # 是否启用 WebSocket 连接默认后端
+  input_dir: "./cache"             # 图片缓存目录，保存上传的参考图
+
+# 路由与运行时配置
+routing:
+  timeout_seconds: 3600            # ComfyUI 任务总超时（秒）
+  max_payload_size_mb: 500         # 请求体最大大小（MB）
+  Image_Width: 1280                # 图像默认宽度（可被请求中的 size 覆盖）
+  Image_Height: 704                # 图像默认高度
+  video_Width: 1024                # 视频默认宽度
+  video_Height: 576                # 视频默认高度
+  fps: 24                          # 默认帧率
+  free_model_before_video: true    # 生成视频前是否调用 ComfyUI /free 释放显存
+
+  # 负载均衡策略，可选值：RoundRobin, LeastConnections, Random
+  lb_strategy: "RoundRobin"
+
+  # 令牌桶限流（可选，注释或删除则限流不生效）
+  rate_limit:
+    max_tokens: 60       # 桶容量
+    refill_rate: 1.0     # 每秒补充令牌数
+
+  # 请求级响应缓存（可选，注释或删除则缓存不生效）
+  response_cache:
+    ttl_secs: 600        # 缓存有效期（秒）
+    max_entries: 500     # LRU 最大条目数
+
+  # 是否启用幂等键检查（Idempotency-Key 头）
+  enable_idempotency: true
+
+  # 优雅关闭最长等待时间（秒），超时后强制退出
+  graceful_shutdown_timeout_secs: 30
+
+  # 健康检查间隔（秒）与连续失败阈值
+  health_check_interval_secs: 15
+  health_check_fail_threshold: 3
+```
+
+## 架构与请求流程
+
+### 架构概览
+
+```
+┌──────────────────────────────────────┐
+│         OpenAI 兼容客户端            │
+│   (Python, JS, curl, LocalMiniDrama) │
+└────────────────┬─────────────────────┘
+                 │ HTTP POST /v1/images/generations
+                 ▼
+┌──────────────────────────────────────┐
+│        comfyui-openai-api            │
+│  ┌──────────┐ ┌────────────────┐     │
+│  │ 限流器   │ │ 幂等键检查     │     │
+│  └──────────┘ └────────────────┘     │
+│  ┌──────────┐ ┌────────────────┐     │
+│  │ 工作流   │ │ 后端池 & LB    │     │
+│  │ 注入器   │ │ + 健康检查     │     │
+│  └──────────┘ └────────────────┘     │
+│  ┌──────────────────────────────┐    │
+│  │ WebSocket / HTTP 轮询        │    │
+│  │ (全抖动退避)                 │    │
+│  └──────────────────────────────┘    │
+└────────────────┬─────────────────────┘
+                 │
+                 ▼
+┌──────────────────────────────────────┐
+│  ComfyUI 后端 A (健康)               │
+│  ComfyUI 后端 B (健康)               │
+│  ComfyUI 后端 C (不健康，已摘除)     │
+└──────────────────────────────────────┘
+```
+
+## 与 LocalMiniDrama 的生态协同
+
+- **统一生成接口**：`LocalMiniDrama` 通过标准 OpenAI API 调用本代理，无需关心底层 ComfyUI 工作流细节。
+- **批量分镜生成**：逐镜生成流程可借助多后端负载均衡实现并行加速。
+- **角色一致性**：通过 `X-Consistent-Role` 头与种子追踪器联动，保持同一角色多分镜外貌一致。
+- **视频模型支持**：内置豆包 Seedance、通义万相、Vidu 等工作流注入兼容，覆盖短剧制作的多模型需求。
+
+## 故障排查
+
+| 现象 | 可能原因 | 排查方法 |
+|------|---------|---------|
+| 502 Bad Gateway | ComfyUI 后端不可达 | 检查 `comfyui_backends` 配置中 host/port 是否正确，确认 ComfyUI 已启动 `--api` |
+| 404 Workflow not found | `model` 参数对应的工作流文件不存在 | 确认 `workflows_folder` 目录下存在 `{model}.json` 文件 |
+| 400 Invalid request | 请求体格式错误或 Base64 解码失败 | 检查 JSON 格式，验证 Base64 编码有效性 |
+| 504 Timeout | 生成时间超过 `timeout_seconds` | 增大超时值或检查 ComfyUI 日志中的节点错误信息 |
+| 429 Too Many Requests | 触发令牌桶限流 | 调整 `rate_limit` 配置或降低请求频率 |
+| 后端被摘除 | 健康检查连续失败 | 检查 ComfyUI `/system_stats` 是否正常返回，网络连通性 |
+
+## 版本历史
+
+### v0.3.0
+- 🏗️ 模块化架构重构，拆分 handlers/backend/transport/middleware/cache/workflows
+- 🔄 多后端健康检查与负载均衡（RoundRobin / LeastConnections / Random）
+- 🔒 令牌桶限流中间件
+- 🆔 幂等键支持
+- 💾 请求级 LRU 响应缓存
+- 📡 OpenTelemetry 分布式追踪
+- 🧹 优雅关闭与任务排水
+- 🌱 角色种子稳定性追踪器
+- 📋 新增 `/v1/models`、`/v1/backends`、`/v1/tasks` 列表与删除等端点
+
+### v0.2.0
+- 视频生成支持
+- 多后端手动路由
+- 任务持久化（tasks.json）
+- PromptRelayEncode / LTXVAddGuideMulti 节点注入
+
+### v0.1.0
+- 初始版本，OpenAI 图像生成兼容
+
+## 贡献指南
+
+欢迎通过 Issue 和 Pull Request 参与贡献。请遵循以下准则：
+
+- 为新增的公共函数和模块添加文档注释
+- 面向用户的功能改动需同步更新配置示例和 API 文档（即本 README 与 /v1/help 端点）
+- 针对多种工作流配置进行测试
+- 遵循现有代码风格和模块组织方式