86 lines
5.5 KiB
Markdown
86 lines
5.5 KiB
Markdown
# CLAUDE.md
|
||
|
||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||
|
||
## 项目概述
|
||
|
||
comfyui-cluster-bridge 是 ComfyUI 实例集群通信中间层，将多个 ComfyUI 实例组成集群，通过统一的任务队列对外提供生图服务。项目分为四个独立子服务。
|
||
|
||
## 启动命令
|
||
|
||
```bash
|
||
# 首次运行需要安装依赖（四个子项目各自安装）
|
||
cd backend && npm install
|
||
cd frontend && npm install
|
||
cd message-dispatcher && npm install
|
||
cd 任务队列后端 && npm install
|
||
|
||
# 桥接器后端 (port 3000)
|
||
cd backend && npm run dev
|
||
|
||
# 前端管理界面 (port 5173)
|
||
cd frontend && npm run dev
|
||
|
||
# 消息分发器 (port 4000)
|
||
cd message-dispatcher && npm run dev
|
||
|
||
# 任务队列后端 (port 8087)
|
||
cd 任务队列后端 && node index.js
|
||
# 或者仅启动 callback 服务 (port 8089)
|
||
cd 任务队列后端 && node app.js
|
||
```
|
||
|
||
## 架构概览
|
||
|
||
整个系统数据流为：**外部调用方 → 任务队列后端 → message-dispatcher → backend(桥接器) → ComfyUI 实例**
|
||
|
||
### 四层服务职责
|
||
|
||
**任务队列后端** (`任务队列后端/`) — 系统的对外入口层
|
||
- `index.js` 启动 HTTP 服务器(8087) + WebSocket 服务器，同时创建 7 个 worker_threads 处理任务全生命周期
|
||
- 7 个 Worker 线程：`assessment`（任务评估/分发）、`wait`（等待/生成任务）、`polling`（轮询外部平台）、`result`（结果获取）、`callback_result`（回调结果）、`callback_timeout`（回调超时）、`error`（错误处理）
|
||
- 通过 WebSocket 接收 message-dispatcher 发来的任务请求(type=generate)，转交 worker 处理后返回结果
|
||
- 使用 Redis 做消息持久化，支持断线消息重发（`redis/messagePersistence.js`）
|
||
- `app.js` 是仅 callback 服务的独立入口(8089)，`index.js` 是完整任务队列入口
|
||
- `outside/outPlatforms/` 包含对接外部平台的适配器（JimuAI、runninghub、coze 等）
|
||
- 配置文件在 `config/` 目录下：`code.json`（错误码映射）、`model.json`（模型配置）、`Platform.json`（平台配置）等
|
||
|
||
**message-dispatcher** (`message-dispatcher/`) — 中心调度层
|
||
- 核心组件：`bridge-manager`（桥接器注册管理 + 实例锁机制）、`task-scheduler`（任务调度 + 队列管理 + 超时检测 + 任务恢复）、`websocket-server`（接收桥接器 WS 连接）、`md-websocket-client`（连接到任务队列后端）
|
||
- BridgeManager 管理所有已注册桥接器的实例池，使用轮询选择空闲实例，实例锁 30s 短超时/2h 长超时机制
|
||
- TaskScheduler 维护 5 种任务状态：pending → processing → completed/failed/recovering，自动调度排队任务
|
||
- 对外提供 REST API（`api/index.js`）和 JWT 认证（`auth/`），前端管理界面通过此 API 获取状态
|
||
|
||
**backend(桥接器)** (`backend/`) — 与 ComfyUI 实例通信的桥接层
|
||
- `cluster-manager`：管理所有 ComfyUI 实例的状态（定时健康检查、负载均衡轮询）
|
||
- `websocket-client`：与各 ComfyUI 实例建立 WebSocket 连接（按 instanceId 复用连接）
|
||
- `task-forwarder`：接收任务 → 转发到 ComfyUI → 监听执行状态（execution_start/progress/executed/error/success）→ 获取结果并上传文件。同时监听 `disconnected` 事件，**ComfyUI 实例断连时按顺序处理：先推实例离线状态给 message-dispatcher，再回调所有受影响任务的失败结果（错误信息"超出显存"），防止在回调期间 message-dispatcher 继续分配任务到已死实例**。
|
||
- `task-queue-client`：作为 WebSocket 客户端连接到 message-dispatcher，报告实例状态、接收任务
|
||
- `workflow-converter`：将外部工作流格式转换为 ComfyUI 格式
|
||
- `file-uploader`：将 ComfyUI 生成的图片等文件上传到外部文件服务器
|
||
- 配置文件 `config/servers.json` 定义 ComfyUI 实例列表，支持热加载
|
||
|
||
**frontend** (`frontend/`) — Vue 3 管理界面
|
||
- 技术栈：Vue 3 + Vite + Pinia + Element Plus + ECharts + Vue Router
|
||
- 4 个页面：实例管理、任务管理、配置管理、系统监控
|
||
- 连接到 message-dispatcher 的 REST API
|
||
|
||
### 关键通信协议
|
||
|
||
- **bridge ↔ message-dispatcher**：WebSocket 长连接，消息类型包括 REGISTER、HEARTBEAT、TASK_ASSIGN、TASK_ACK、TASK_END、INSTANCE_CHECK
|
||
- **message-dispatcher ↔ 任务队列后端**：WebSocket 长连接，message-dispatcher 推送 CAPACITY_UPDATE（算力状态）、JWT_UPDATE，接收来自后端的任务执行结果
|
||
- **bridge ↔ ComfyUI**：HTTP POST `/prompt` 提交任务，WebSocket 监听 `ws://host:port/ws?clientId=xxx` 获取执行事件
|
||
- 实例锁通过 message-dispatcher 的 BridgeManager 统一管理，防止同一实例被分配多个任务
|
||
|
||
### 任务完整生命周期
|
||
|
||
1. 外部系统通过任务队列后端 API 提交任务
|
||
2. 任务队列后端 worker 处理后，通过 assessment worker 判断需要调用 ComfyUI
|
||
3. message-dispatcher 的 md-websocket-client 接收到任务，TaskScheduler 入队
|
||
4. BridgeManager 选一个空闲实例并加锁 → WebSocket 发送 TASK_ASSIGN 到对应 bridge
|
||
5. bridge 的 task-queue-client 收到 TASK_ASSIGN → 转发给 task-forwarder
|
||
6. task-forwarder 调用 workflow-converter 转换工作流 → HTTP POST /prompt 到 ComfyUI
|
||
7. ComfyUI WebSocket 推送 execution_start → progress → executing → executed → execution_success
|
||
8. task-forwarder 收到 execution_success → 调 /history API 获取 outputs → 上传文件 → 发送 TASK_END 回 message-dispatcher
|
||
9. message-dispatcher 转发结果给任务队列后端 → 释放实例锁 → 调度下一个排队任务
|