NextGPU 是一套分布式 AI 算力调度与 ComfyUI 工作流执行平台。它将用户侧的 ComfyUI 工作流请求，通过云端编排调度到全球分布的 GPU 算力节点上执行，并按任务消耗积分计费；同时提供工作流市场、会员订阅、多通道支付等门户能力。
本文档面向首次接触本项目的开发者、运维与产品人员，帮助快速理解 NextGPU 是什么、能做什么、以及整体技术架构与设计思路。更细粒度的业务流程与数据库说明见文末「延伸阅读」。
| 维度 | 说明 |
|---|---|
| 形态 | 去中心化算力网络 + SaaS 门户 |
| 核心引擎 | ComfyUI 工作流（Stable Diffusion 等 AIGC 管线） |
| 商业模式 | 积分（点数）按任务扣费；VIP 等级限制配额；微信/支付宝/Stripe 等充值订阅 |
| 算力供给 | 第三方 GPU 机器安装 Node 客户端，接入后自动拉镜像、跑基准测试、进入调度池 |
| 用户入口 | Web 门户（Backend API）+ 直连 AiHub 的任务 WebSocket |
一句话概括：用户在市场选工作流并提交任务 → AiHub 拆分子任务、选节点、经 WebSocket 下发 → Node 在本机 Docker/ComfyUI 中推理 → 结果上传 OSS 并回写数据库 → 用户经 WS 收进度与结果。
- 工作流市场：浏览模型/分类/标签，查看工作流详情与运行时参数模板
- 任务提交与追踪：创建 Session，发布 ComfyUI 任务，WebSocket 实时推送队列位置、开始、完成、失败等事件
- 账户体系：注册（邀请码）、用户名密码登录、Keycloak SSO
- 积分与会员：按工作流定价扣点；等级控制工作流数、图片数、存储上限
- 支付充值：微信支付、支付宝、Stripe（Webhook 回调）
- 硬件准入：GPU 白名单、最低内存/CPU 核心数校验
- 自动化部署：AiHub 下发 Docker/Compose 模板，Node 拉镜像、启动 ComfyUI
- 性能基准（Benchmark）：ComfyUI 就绪后自动跑测量任务，标定该节点 GPU 族的推理耗时，通过后方可接 AI 任务
- 心跳与对账：周期 NodePing，AiHub 与 Node 双向同步 Docker 状态
- 多槽位并发：单节点单 Docker，按 GPU 显存/族配置多个任务槽（Slot）
- 节点与 GPU 运维视图：节点列表、在线统计、GPU 档位与白名单
- 管理员 GPU 配置：维护
t_gpu_family、t_available_gpu、t_gpu_family_gpu（Backend/admin/gpuConfig） - 工作流上架审核：用户
submitWorkflow提交，运营在库表侧处理 - 监控与日志：节点监控配置下发；Node/AiHub 日志可上传阿里云 OSS
NextGPU 由 三个可独立部署的 Go 服务 与 一个算力客户端 构成，共用同一 MySQL 数据库 nextGPU：
┌─────────────────────────────────────────────────────────────────────────────┐
│ 用户 / 浏览器 / App │
└───────────────────────────────┬─────────────────────────────────────────────┘
│ HTTP 8080（门户）
│ HTTP 9080 + WS 9082（任务，可选直连 AiHub）
▼
┌──────────────────┐ 共享 MySQL ┌──────────────────┐
│ Backend │◄────────────────►│ AiHub │
│ 门户 · 市场 │ nextGPU 库 │ 运行时 · 调度 │
│ 支付 · 只读查询 │ │ 节点编排 · 计费 │
└──────────────────┘ └────────┬─────────┘
│ HTTP 9080（注册/校验）
│ WS 9081（节点通道）
▼
┌──────────────────┐
│ Node │
│ GPU 算力客户端 │
│ Docker + ComfyUI │
└──────────────────┘
| 项 | 说明 |
|---|---|
| 职责 | 用户注册登录、工作流市场只读 API、任务/节点统计查询、支付下单与回调、文件上传、管理员 GPU 配置 |
| 默认端口 | HTTP 8080，路由前缀 /backend |
| 数据访问 | 以读为主；写用户、订阅、投稿等；不负责任务调度与节点 WS |
| 代码路径 | nextGPU/Backend/ |
典型接口分组：用户账户、工作流市场、支付回调、登录后可用的 userInfo/userTasks、公开节点/GPU 查询、管理员 /admin/gpuConfig。
| 项 | 说明 |
|---|---|
| 职责 | 算力节点生命周期、Docker 分发、性能测量、用户 Session、任务拆分与调度、子任务下发、结果回写、积分扣退 |
| 端口 | HTTP 9080（/node、/session、/docker、/files）；节点 WS 9081；用户 WS 9082 |
| 数据访问 | 几乎全部 21 张表的读写 |
| 代码路径 | nextGPU/AiHub/ |
AiHub 是系统的大脑：内存中维护 Nodes（算力节点）、Users/UserSessions（用户会话与任务队列），通过 WebSocket 与 Node、用户客户端长连接通信。
| 项 | 说明 |
|---|---|
| 职责 | 采集硬件信息、HTTP 注册、维持到 AiHub 的 WebSocket、管理本机唯一 Docker/ComfyUI 实例、执行 AI/测量子任务、上传 OSS |
| 部署位置 | GPU 服务器（Linux / Windows+WSL） |
| 数据访问 | 不直连数据库，仅通过 AiHub 协议交互 |
| 代码路径 | nextGPU/Node/ |
设计约束：1 节点 = 1 Docker = 1 ComfyUI，并发由 GPU 槽位数控制（MaxDockerPerNode = 1）。
| 路径 | 说明 |
|---|---|
nextGPU/common/ |
跨服务工具（崩溃转储、路径检测等） |
nextGPU/include/ |
公共库：日志、支付插件、LLM 封装、OSS、监控、Web3 等（各服务按需引用） |
nextGPU/go.mod |
统一 Go module：github.com/nextGPU |
| 层次 | 选型 |
|---|---|
| 语言 | Go 1.25 |
| HTTP 框架 | Gin |
| 实时通信 | Gorilla WebSocket |
| 数据库 | MySQL（database/sql + go-sql-driver/mysql / sqlx） |
| 配置 | YAML（config.yaml，约 30 秒热重载） |
| 容器 | Docker / Docker Compose（Node 侧 docker API + WSL 适配） |
| AI 运行时 | ComfyUI（HTTP /prompt、/history + WebSocket 进度） |
| 对象存储 | 阿里云 OSS（任务产物、日志） |
| 支付 | 微信支付 APIv3、支付宝、Stripe |
| 身份 | 自研用户名密码 + Keycloak OpenID（Backend SSO） |
| 其他 | NTP 校时、Prometheus 监控钩子、多种 LLM/链上支付扩展（include/，按需集成） |
- Backend 面向产品运营与用户门户，接口稳定、以 REST 为主，避免承载高并发 WS 与调度逻辑。
- AiHub 面向运行时，承担状态机、队列、长连接，是延迟敏感路径的核心。
- 两者共享 MySQL，保证市场配置、用户积分、任务记录在门户与运行时一致，但写任务、写子任务、调度仅发生在 AiHub。
算力节点由第三方自行部署 Node，平台不持有机器，但通过 AiHub 统一：
- 准入（GPU 白名单 + 硬件门槛）
- 镜像与工作流模板分发
- 性能标定（只有通过 Benchmark 的节点进入调度池）
- 任务路由与失败重试
这是典型的 「众包 GPU + 中心调度器」 模型，类似渲染农场，但工作负载是 ComfyUI 图。
| 概念 | 说明 |
|---|---|
| 主任务（Job） | 用户一次提交，对应 t_jobs |
| 子任务（SubJob） | 工作流按 batch/节点拆分，对应 t_sub_jobs |
| Slot | 节点上 ComfyUI 的一个并发执行位；空闲 Slot 来自 GPU 族配置的池大小 |
| Session | 用户 WS 会话，用于推送该用户所有任务的进度事件 |
调度器（AiHub/process/nodes.go → TaskDispense）从全局等待队列取子任务，匹配空闲 Slot，经 WS 下发 TaskPublish，Node 侧 ComfyUI 插件执行并回传。
降低运维复杂度：每个 Node 进程只维护一个 NodeDocker、一条 ComfyUI WebSocket。多 GPU 并发通过逻辑槽位而非多容器实现。协议层仍使用 dockers[] 数组，便于未来扩展，但当前 MaxDockerPerNode = 1 在代码与 DB 逻辑上双重约束。
Node 与 AiHub 之间通过固定 messageID 的二进制/JSON 协议通信（如 DispenseStart=11、TaskPublish=1、MeasurePublish=21、NodePing=99）。节点状态、Docker 状态、任务状态均为显式枚举，便于对账与重试。
Docker 状态对账（docker_sync.go）：Node 心跳携带本机真实 dockers[]，AiHub 与内存/DB 比对，非法或漂移时清绑定并重新 Docker2Node。
调度与计费依赖 GPU 族（Family） 概念：
t_gpu_family：档位（槽位数、显存、权重）t_gpu_family_gpu：具体型号 → 族映射t_workflow_completion_times：族 + 工作流 + 分辨率下的历史耗时基准
新节点通过测量任务写入基准；用户发布任务时用 CalcEstimates 估算扣费与排队时间。
各服务启动后加载 config.yaml，后台 goroutine 定期检测文件变更并重载。业务对象（DB 连接、Web 路由、Process 单例）采用 Singleton 模式，main 仅负责初始化后阻塞保活。
validate → enroll → 连接 WS 9081 → Docker 分发(DispenseStart) → 拉镜像/compose up
→ ComfyUI 就绪 → 性能测量(MeasurePublish) → 通过 → 进入调度池(MeasurementComplete)
详见：nextGPU/AiHub/README.md §1–§2，nextGPU/Node/README.md。
POST /session/publish → 鉴权扣积分 → NewTask 写 DB → 拆分子任务入队
→ TaskDispense 匹配 Slot → WS TaskPublish → Node/ComfyUI 执行
→ 结果上传 OSS → 回写 t_sub_jobs → WS 推送用户 SessionSync
详见：nextGPU/AiHub/README.md §3–§7。
Backend /register|/login → 浏览 /models → （充值 /wxPayment 等）
→ 前端或 SDK 直连 AiHub /session/publish + WS /user/{session}
→ Backend /getTask 或 /userTasks 查询历史
Backend 与 AiHub 共用 21 张 MySQL 表，按六条业务线组织：
| 业务线 | 核心表 |
|---|---|
| 用户账户 | t_users、t_levels、t_invitation |
| 计费订阅 | t_subscription、t_users（积分） |
| 算力节点 | t_nodes、t_node_online_time、t_monitor_configuration |
| Docker 与工作流 | t_workspaces、t_node_workspaces、t_workflows、t_workflow_base |
| 任务调度 | t_jobs、t_sub_jobs、t_user_job |
| GPU 调度与基准 | t_available_gpu、t_gpu_family、t_gpu_family_gpu、t_workflow_completion_times |
完整 ER 与字段说明见 db/README.md 及同目录分册文档。
命名提示：表字段仍大量使用
f_workspace_id，Go 代码与协议 JSON 已统一称为dockerID。
AI Hub/ ← 本 README 所在目录
├── README.md ← 项目总览（本文）
├── db/ ← 数据库表关系文档（21 表）
└── nextGPU/ ← Go monorepo
├── go.mod
├── common/ ← 跨服务公共工具
├── include/ ← 日志、支付、LLM、监控等可选库
├── Backend/ ← 门户服务
│ ├── main.go
│ ├── config.yaml
│ ├── configure/
│ ├── db/
│ ├── net/web/business/ ← HTTP handlers
│ ├── middleware/
│ └── payment/ ← 支付证书与密钥（部署时配置）
├── AiHub/ ← 调度运行时
│ ├── main.go
│ ├── config.yaml
│ ├── README.md ← AiHub 业务流程详解
│ ├── process/ ← 节点/用户/任务核心逻辑
│ ├── net/web/ ← HTTP API
│ ├── net/websocket/ ← 节点与用户 WS
│ └── db/
└── Node/ ← 算力客户端
├── main.go
├── config.yaml
├── README.md ← Node 协议与 Docker 生命周期
├── process/ ← 注册、WS、Docker、ComfyUI 插件
└── header/protocol.go ← 与 AiHub 对齐的消息定义
| 组件 | 建议部署 | 依赖 |
|---|---|---|
| MySQL | 云端 RDS 或自建 | 库名 nextGPU，utf8 |
| Backend | 公网或内网，HTTPS 终结 | MySQL、支付商户配置、OSS（上传封面） |
| AiHub | 与 Node 网络可达，低延迟 | MySQL、OSS（任务产物+日志）、9080–9082 端口 |
| Node | 各 GPU 机器 | Docker/WSL、能访问 AiHub HTTP/WS、出站 OSS |
| ComfyUI | Node 拉起的容器内 | 由 t_workspaces 模板定义镜像与 compose |
最小本地开发：AiHub + MySQL + 单 Node（本机 GPU），Backend 可选（仅测门户时需要）。
构建示例（在 nextGPU/ 下）：
go build -o bin/backend ./Backend
go build -o bin/aihub ./AiHub
go build -o bin/node ./Node各服务启动前将对应目录下的 config.yaml 改为实际 MySQL、域名与 OSS 配置；切勿将生产密钥提交版本库。
| 服务 | HTTP | WebSocket | 说明 |
|---|---|---|---|
| Backend | 8080 /backend |
— | 门户 API |
| AiHub | 9080 | 9081 节点 /node/{uuid} |
节点注册、Docker、文件 |
| AiHub | — | 9082 用户 /user/{session} |
任务进度推送 |
| Node → ComfyUI | 8188（本地） | 8188 /ws |
容器内或本地 ComfyUI |
具体端口以各服务 config.yaml 为准。
| 场景 | 机制 |
|---|---|
| Backend 用户 API | Query/Header userName + password，或 middleware.UserAuth |
| Backend 管理员 | admin.userNames 账号密码，或 Header X-Admin-Token |
| Backend SSO | Keycloak Bearer Token → ssoLogin / ssoUserinfo |
| AiHub 任务发布 | 用户密码或 Session 归属校验；任务归属 t_user_job |
| Node WS | 路径携带 systemUUID，须已在 AiHub 内存 Nodes 中 enroll |
| 支付回调 | 各渠道签名校验（微信/支付宝/Stripe Webhook） |
| 文档 | 内容 |
|---|---|
| nextGPU/AiHub/README.md | 节点上线、测量、用户 Session、任务调度、消息 ID、注意事项 |
| nextGPU/Node/README.md | Node 目录结构、注册流程、WS 分发、Docker 状态机、ComfyUI 插件 |
| db/README.md | 21 张表职责、ER 图、跨业务链路 |
| db/01-用户账户.md ~ 06-GPU调度与性能基准.md | 分域表结构详解 |
- Go module：
github.com/nextGPU - 服务版本号：各
main.go中Version常量（当前多为1.0.0） - Node 客户端版本：与 AiHub
clientVersion配置及t_client_version表联动，支持增量更新清单
| topic | 说明 |
|---|---|
| 单 Docker 约束 | 简化 Node 运维；多卡机器通过 Slot 池利用显存，而非多容器 |
| 共享数据库 | 降低一致性成本；需注意 Backend 勿写入调度临界表 |
| 历史命名 | workspace / dockerID、f_account / f_user_name 等存在代码与表字段不完全一致，以文档与 AiHub 运行时为准 |
| Backend 任务写路径 | 已移除无用 TaskDB 初始化；任务生命周期以 AiHub 为唯一写入方 |
| 扩展方向 | include/ 中 LLM、Web3、多支付渠道等可按产品需要接入，与核心调度路径解耦 |
文档基于 nextGPU 代码库与 db/ 反推文档整理，随代码演进请同步更新各子 README。