CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

项目概述

comfyui-cluster-bridge 是 ComfyUI 实例集群通信中间层，将多个 ComfyUI 实例组成集群，通过统一的任务队列对外提供生图服务。项目分为四个独立子服务。

启动命令

# 首次运行需要安装依赖（四个子项目各自安装）
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 统一管理，防止同一实例被分配多个任务

任务完整生命周期

外部系统通过任务队列后端 API 提交任务
任务队列后端 worker 处理后，通过 assessment worker 判断需要调用 ComfyUI
message-dispatcher 的 md-websocket-client 接收到任务，TaskScheduler 入队
BridgeManager 选一个空闲实例并加锁 → WebSocket 发送 TASK_ASSIGN 到对应 bridge
bridge 的 task-queue-client 收到 TASK_ASSIGN → 转发给 task-forwarder
task-forwarder 调用 workflow-converter 转换工作流 → HTTP POST /prompt 到 ComfyUI
ComfyUI WebSocket 推送 execution_start → progress → executing → executed → execution_success
task-forwarder 收到 execution_success → 调 /history API 获取 outputs → 上传文件 → 发送 TASK_END 回 message-dispatcher
message-dispatcher 转发结果给任务队列后端 → 释放实例锁 → 调度下一个排队任务

5.5 KiB Raw Permalink Blame History Unescape Escape