平台架构

平台架构

> 硬件验证边界（截至 2026-10-20）：本文中的“10 种品牌/检测器”指代码检测与适配范围，不代表 10 种硬件都完成了真机端到端验证。现有项目记录显示 NVIDIA 多机型已有真机端到端证据；国产加速卡检测逻辑已做软件及厂商命令输出对照，真机端到端验证仍待对应硬件。

HeteroFlow v2 是面向异构 GPU 算力池的裸金属调度平台，整体形态是一台控制面 + N 个 Agent 节点 + 一个 PostgreSQL：控制面是一个 Go 单体二进制（端口 3333），聚合 API、调度、网关、告警等全部服务；每台 GPU 节点运行一个轻量 Agent 守护进程，以纯出站轮询方式与控制面通信；持久化只依赖 PostgreSQL 一件事。刻意不上 Kubernetes——裸金属形态让调度器直接面对 GPU 硬件事实（型号、显存、拓扑、分片能力），不需要经过 Device Plugin 与 K8S 调度语义的翻译层，单集群内完成检测、调度、分片、推理网关与用量核算闭环。

总体分层架构

┌──────────────────────────────────────────────────────────────────────┐
│  前端 SPA（React 19 + TypeScript + Vite，28 个路由，静态托管 5173）      │
│  仪表盘 · 任务/训练/推理 · 节点 · 分片 · 告警 · 多租户 · 插件 · 日志      │
└──────────────────────────────┬───────────────────────────────────────┘
                               │ REST /api/v1（JWT · 租户 API Key）
┌──────────────────────────────▼───────────────────────────────────────┐
│  API 层（Go，106 条路由注册；CORS / 审计 / 限流 / 租户上下文中间件）       │
│  业务域 26 组：任务/节点/租户/模型/分片/告警/网关/集群配置…                │
│  + OpenAI 兼容推理口 /v1/* + Agent 分发与指令通道 + GPU 健康独立注册       │
├──────────────────────────────────────────────────────────────────────┤
│  控制面服务群（单体二进制内，多实例部署 + advisory lock 选主）             │
│  ┌──────────┐ ┌───────────┐ ┌──────────┐ ┌───────────┐ ┌──────────┐ │
│  │ 调度器    │ │ AutoScaler │ │健康检查   │ │ 告警监控   │ │ 推理网关  │ │
│  │ 事件循环5s│ │ 30s        │ │ 5s       │ │ 30s       │ │ 探测10s  │ │
│  └──────────┘ └───────────┘ └──────────┘ └───────────┘ └──────────┘ │
│  ┌───────────┐ ┌───────────┐ ┌───────────┐ ┌────────────────────┐   │
│  │ 调度窗口   │ │ 孤儿分片GC │ │ 指标采集   │ │ GPU 故障预测 worker │   │
│  │ 60s       │ │ 60s       │ │ 30s      │ │                    │   │
│  └───────────┘ └───────────┘ └───────────┘ └────────────────────┘   │
└──────────────────────────────┬───────────────────────────────────────┘
                               │
┌──────────────────────────────▼───────────────────────────────────────┐
│  PostgreSQL（38 张表；advisory lock 键空间：选主/配额/分片补偿/租户守卫） │
└──────────────────────────────┬───────────────────────────────────────┘
                               │ 纯出站轮询：心跳 5s · 任务拉取 5s · 指令轮询 5s
┌──────────────────────────────▼───────────────────────────────────────┐
│  Agent 群（每 GPU 节点一个，独立 Go 模块，X-API-Key 节点作用域）          │
│  硬件检测(10 检测器) · 执行器(Docker) · MPS/MIG · 拓扑 · 模型缓存        │
│  推理引擎探测 · 模型扫描 · 掉卡探测(cardprobe) · 对账(60s)              │
└──────────────────────────────┬───────────────────────────────────────┘
                               ▼
              GPU 节点（10 品牌硬件 + Docker，混插多厂商可同报）

分层要点：Agent 是纯出站轮询进程、不监听任何端口——节点无需暴露入站端口、无需预注册，首次心跳即隐式建节点记录，天然适配 NAT 后的 GPU 节点；控制面对节点的全部"指令"（分片创建/销毁、文件/镜像请求）都落库为指令表，由 Agent 轮询认领，整个系统没有一条反向长连接。

组件交互的四条纪律贯穿全系统：① API 只经 Store 访问数据——handler 不写裸 SQL，租户过滤在存储层统一施加；② 调度器单事件循环单写者——所有对任务状态的迁移要么出自调度循环、要么走 CAS 原子翻转，多实例下交接窗口的正确性靠动作级 CAS 兜底；③ 对 Agent 永远下发意图而非命令——服务端落库的是"要什么"（分片指令、停止意图），Agent 幂等轮询执行并回报结果，双方都能安全重试；④ 破坏性操作失败语义显式化——MIG 分区销毁等操作按"已下发/已确认/已超时"三态记账，崩溃窗口由补偿扫描（advisory lock 9603）收敛。

后端架构

后端 Go 代码分四个物理边界：共享核心 core/pkg/、服务端专属包 pkg/、内置插件 plugins/、节点程序 agent/（独立 go.mod，不 import 主模块，保证 Agent 二进制可单独分发到任意架构节点）。

五阶段调度流水线位于 core/pkg/scheduler/scheduler_core.go 的插件周期（PreScore → Filter → Score → PostScore，见《GPU 统一调度》篇），Bind 阶段在调度核心内完成资源复核、端口分配与 CAS 认领（pending→scheduled 原子 UPDATE，从根上防多实例/多轮次双绑）。

GPU 抽象是异构能力的地基：服务端 core/pkg/gpu/ 以 Provider 接口 + 注册表收敛 8 家厂商差异（NVIDIA/海光/昇腾/寒武纪/壁仞/摩尔线程/昆仑/AMD），调度器只面对统一的类型枚举与显存/算力语义；Agent 侧 detection/ 以 Detector 接口对同一批厂商做统一探测（多路径：设备节点 / sysfs / 厂商管理工具）。两层各自独立演进——服务端加一种卡不必改 Agent，反之亦然；海光 DCU 另有 cgroup 级执行通道（hygoncgroup）。插件化则让调度策略可插拔：8 个内置调度插件（binpack/spread/gpu_filter/resource_filter/preempt/rdma/nvlink/topology）实现 Plugin / FilterPlugin / ScorePlugin 扩展点，开关与权重经 /api/v1/plugins 热调；通知插件服务于告警渠道。TaskGroup 组调度（推理副本编排与 DDP/DeepSpeed/FSDP 训练组）复用同一条流水线：按并行策略拆分子任务、拓扑感知选节点组、注入 WORLD_SIZE/RANK/MASTER_ADDR 环境变量后逐个走标准绑定路径。

控制面服务群逐组件

每个组件的运行方式与节拍（数字均为代码常量，非配置值）：

> AlertMonitor 是唯一不受选主门控的巡检组件：告警可见性在每个实例上都保持新鲜；代价是"必须单写者"的迁移写路径靠任务行级 CAS 保证不重复迁移。

Agent 架构

Agent 是独立编译的静态链接二进制（heteroflow-agent，go 1.21 模块），一键部署脚本分发，systemd 托管。所有请求仅携带 X-API-Key（与控制面共享的 agent_secret，服务端对其施加节点作用域查询约束：取任务必须带 node_id+status、禁止创建任务）。核心组件：

Agent 与控制面的每类交互（任务 / 分片 / 文件 / 镜像指令）都是"指令表 + 轮询 + CAS 认领"同一骨架，进程重启后靠 60s 对账自动收敛与服务端的认知差，任意网络条件下幂等可恢复。

前端架构

单页应用（SPA），实况技术栈 React 19 + TypeScript + Vite + Tailwind CSS，图表 ECharts / Recharts，路由 react-router-dom。无全局状态库，按 React 惯用法分层：auth/AuthProvider（Context 管登录态与租户角色，localStorage 缓存）、hooks/（useApiData / useNodes / useTasks 等数据钩子）、api/（按域拆分的请求模块，原生 fetch 封装：超时 / 指数退避重试 / 四类错误分级）、pages/（28 路由页面）与 components/（按域组织的通用组件）。28 个路由全列：

生产形态是 Vite 构建产物由静态服务器托管，API 请求经反代到控制面 3333 端口。

关键数据流

① 任务全链路（普通 Docker 任务）

创建   POST /api/v1/tasks → 租户/配额检查（配额临界区 advisory lock）
       → 任务 pending 入队（容量 1000 单队列，优先级 0-100 降序 + FIFO）
调度   事件循环 5s tick → 内置过滤链（离线→租户→VRAM→反亲和→模型→分片租户）
       → 插件周期 PreScore → Filter → Score（并行加权）→ PostScore
绑定   BindTask：负载阈值复核 + 端口分配 + DB CAS pending→scheduled（防双绑）
       （分片任务在此完成 GPU 分片分配与 QoS 推导）
执行   Agent 每 5s 拉取 scheduled → CAS 认领 running（409 让步）
       → 模型缓存 Ensure → docker run → 探针/看门狗/优雅停止监测
回报   容器退出 → CAS 上报终态 + exit_code（失败有限重试，未送达保留容器
       由 60s 对账补报）→ GPU-秒用量结算
兜底   节点失联 45s → AlertMonitor 迁任务回 pending 温和重试；
       停滞回收 60s；节点故障统一处置政策裁决 container_lost 等场景

② 推理调用链（OpenAI 兼容网关）

客户端 → POST /v1/chat/completions（Bearer 端点 API Key + key 级限流）
       → 模型名解析 + 模型路由策略 → 定位推理端点（endpoint）
       → 选后端：会话粘性五级 key 级联①X-Session-Id 头 →②prompt_cache_key
         →③user →④hash(system+user[0]+assistant[0]) →⑤hash(system+user[0])
         未命中/关闭粘性 → 负载均衡（round_robin / random / least_connections）
       → 代理到该后端对应的推理容器（vLLM/SGLang/llama.cpp/TRT-LLM/MindIE）
       → 用量回写：token 计量、GPU-秒结算、连接计数（供 least_connections）

网关不做跨实例内存共享——多实例部署时 PostgreSQL 是唯一共享权威源（后端存活、连接计数落库），不引入 Redis/MQ。

③ 心跳链路（Agent → 控制面）

采集   CollectAllStats 逐卡（温度/利用率/显存/compute_capability）
       + /proc CPU/内存两次采样 + docker inspect 实测 live_task_ids
       + task_health 探针 + 引擎/模型/构建指纹 + gpu_capabilities 分片能力位
上报   POST /api/v1/nodes/{id}/heartbeat（X-API-Key；未知节点隐式注册）
处理   更新 nodes/gpus 与 last_report_at → HealthChecker 5s 状态机
       （online/suspect/offline）→ AlertMonitor 30s 巡检与自动消解
消费   调度器下一轮把 GPU 余量/能力位（MIG→gold、MPS→silver、无→bronze）
       /拓扑标签/引擎分布纳入过滤与打分；计量侧按活跃任务结算 GPU-秒

多实例与高可用

控制面支持多实例部署，单集群控制面 HA（不做跨集群管理——多集群 API 是占位实现，不参与调度），机制全部构建在 PostgreSQL advisory lock 上：

已知边界（如实声明）：网络分区型"真双主"未做过实测，降级感知最长 2 秒窗口内可能短暂双主，对策是降级 ERROR + 停任务；不应宣传为"完全杜绝双主"。

存储架构

双后端：PostgreSQL（生产唯一持久化后端） 与 Memory（单测/单机），同一套 Storage 聚合接口（27 个领域 Store 访问器，其中 16 个有独立小接口约束）。38 张表按域分组：

并发控制四件套：乐观锁版本号（防更新覆盖）、状态机 CAS（任务认领/终态翻转原子化）、advisory lock（跨实例临界区）、事务 + Context 传播纪律。schema 由 CreateTables 统一管理，存量库靠 scripts/sql/ 幂等迁移脚本（编号至 039，028/029 为预留号未用）补齐，另有 db-drift-check 自查工具。

技术栈清单

部署拓扑

单机一体：server 二进制 + PostgreSQL + 前端静态服务同机，适合小规模与开发环境。

控制面 + 多 Agent（标准形态）

              ┌────────────── 控制面（可多实例）──────────────┐
              │  server × N + PostgreSQL（选主 advisory lock）│
              └───────┬───────────────┬───────────────┬──────┘
                      │ 心跳/拉任务     │               │
              ┌───────▼──────┐ ┌───────▼──────┐ ┌──────▼───────┐
              │ Agent+GPU 节点│ │ Agent+GPU 节点│ │ Agent(CPU)    │
              │ NVIDIA / 国产 │ │ 混插多厂商    │ │ virtual 兜底  │
              └──────────────┘ └──────────────┘ └──────────────┘

节点只需能出站访问控制面 3333 端口——NAT 后的节点、跨网段节点均以纯出站轮询接入，公网/内网双 IP 与 heteroflow.network_zone 网络域标签解决内网撞址与连通性判定。多实例 HA：N 个 server 实例共指一个 PostgreSQL，抢主接管如上节。

部署就两条命令：服务端 ./manage-services.sh start all（server 二进制 + PostgreSQL + 前端静态服务）；GPU 节点 curl -fsSL http://SERVER:5173/deploy-agent-all-in-one.sh | bash 一键完成 GPU 类型检测、厂商管理工具 wrapper 安装、Agent 二进制下载、配置生成与 systemd 托管。Agent 版本随平台同步演进，控制面提供 /static/agent 分发与快速更新脚本。

安全架构摘要

认证授权四类凭据两条路径：JWT（Web 登录，token_version 支持即时吊销）、租户 API Key（sk-tenant- 前缀，成员级独立 key 与限额）、X-API-Key（Agent 共享密钥 + 服务端节点作用域约束）、端点 API Key（推理网关，可轮换/撤销）。租户隔离下沉到 SQL 层——所有业务表带 tenant_id，查询统一走租户过滤；三层权限（admin / member / viewer）决定资源可见性与写权限；跨租户共卡/复用仅限管理员配置的共享租户组内，组外完全隔离。生产模式 fail-fast：启动姿态检查（外部可达 + 默认凭据等危险组合）会拒绝启动或 ERROR 留痕。详细模型见《多租户》与认证授权篇。

<!-- 状态标注说明：本文所有组件周期数字（调度 5s/积压 60s/推理恢复 10s/唤醒 15s/抢占看门狗 30s/AutoScaler 30s/健康检查 5s/告警 30s/网关探测 10s/网关清理 5min/调度窗口 60s/分片 GC 60s/指标采集 30s/选主保活 2s/Agent 心跳 5s/对账 60s）均为代码常量核实值；路由 106 条 = server.go 102 条 HandleFunc + GPU 健康独立注册 4 条；表 38 张为 schema.go 实数（含 users 平台管理员表与 energy_accumulators 能耗累计表）。多集群管理为占位实现不参与调度，本文仅描述"单集群控制面多实例 HA"。NVLink 拓扑采集代码就绪但机内 NVLink 联调未做（历史节点均 PCIe 形态）；国产卡检测已适配、端到端验证以 NVIDIA 节点为准。 -->