# kais-aigc-platform 架构分析 — 2026-10-17

分析对象:/home/kai/workspace/kais-aigc-platform(readlink 复验 = /data/workspace 同一工作树),git HEAD 1dfa8baf(10-16 23:23:20,Merge wt/flux3-route);origin/main 领先 2 commits 未推(feat + merge)。本日头条 = flux3 生图引擎路由族合入主干并部署上线,首夜即有真实流量(2× POST /generate,含 1 笔全生命周期成功实录)。

## 1. 一句话定位

Toonflow 衍生的 AI 短剧/漫剧一站式生成平台(npm 名 kais-core-backend v6.0.0):以「无限画布」为创作面,以本地 GPU 引擎群(ComfyUI×3 探针臂 + llama.cpp×2 + diffusers sidecar×N)为生产后端,单 Node 进程 :10588 统一进出门户/API/产物静态面。

1017 时点:flux3 生图路由族 C1-C4 合入(b67e2380+1dfa8baf,机械验收全绿:tsc RC=0 / 26 tests / GT 整树全等对拍 / 邻域 qwen21 48/48);服务 10-16 23:24:40 随新 bundle 重启,自此窗口零重启、零 5xx。

## 2. 技术栈与规模

后端:Node.js v24 + Express 5 + Socket.IO,TypeScript(esbuild bundle → data/serve/app.js),knex + better-sqlite3 单库 48 表。

前端:React 19 + Vite 静态岛 ×3(portal / infinite-canvas / flowgraph-v3 schema 包),Express 静态直挂 + vite alias 单源纪律。

规模口径:src+packages(排 node_modules/dist/build)TS/TSX 609 文件 157,309 行(较 1016 的 605/156,379 +4 文件 +930 行,增量即 flux3 路由族)。

注册表座次(04:05 live):engineOrder 16 席不变(ace,breeze_tts,default,flux2,indextts2,kais_ear,ltx,minimax_h3,music3,postprocess,qwen_eye,qwen_tts,rtx_vsr,sa3,trellis2,yue2);flux3 与 qwen21 同形态——不占 legacy engineOrder,走 UGQ enqueue/dispatch 新路由族注册(vramRequirements 表同样未列,UGQ enqueue 落 default 8192MiB 档,实测 enqueue 行 required 8192MiB mode=exclusive)。

代码锚点:gpuVramManager.ts ~3,900 行 / GpuScheduler.ts ~1,500 行 / yue2 路由 index.ts 989 行 / canvasApi.ts 1,596 行(+1 行 M 未提交)。

数据面(sqlite 直读 04:02):canvas_nodes 14,176(持平)/ canvas_links 28,095(持平)/ o_assets 8,198 / o_project 74 / kv_pipelineRun、kv_syncEvent 仍 0/0 行(第 4 日)。

数据库陷阱延续:仓库根 db2.sqlite 0 字节空壳,真库 data/db2.sqlite 394MB(+WAL 8.8MB);o_assets 列实名驼峰,蛇形直查报错;canvas_nodes 双主键 (id, project)。

## 3. 仓库顶层拓扑

kais-aigc-platform/
├── src/                    # 后端单体(app.ts 入口;routes/lib/services/socket/skills)
├── packages/               # 前端三包:portal(门户)/ infinite-canvas(画布)/ flowgraph-v3(图 schema SSOT)
├── index.js                # 1.7MB 误入库的第三方 CLI 产物,非服务入口(与启动链无关)
├── data/                   # 运行时:db2.sqlite(394MB)/ serve/app.js(23MB bundle)/ web/*(三 SPA 静态岛)/ oss/ / jobs.jsonl
├── workflows/              # 实验工件区(自带独立 .git;服务端不加载)
├── docker-compose.*.yml    # v9 大一统主 stack + real(gold-team 唯一构建路径)+ secondary(GPU2 双臂)+ override
├── scripts/                # 构建/部署/GPU 运维/verify 阶段门/e2e/canvas 运维百余脚本
├── schema/                 # pipeline-field-map.yaml + generate_mappings.py(三消费者代码生成)
├── config/                 # h3-lora-registry.json(H3 LoRA 唯一真源 r13)
├── models/                 # film-storyboard.safetensors(172MB LoRA);大模型在 /data/models(471G 共享库)
├── kohya-lora-training/    # LoRA 训练 dataset + sd-scripts + venv
├── textguard/              # 中文错字修复 sidecar(:5120,systemd 单元文档性提交)
└── docs|specs|milestones/  # 交付文档/规格/里程碑

工作树 4 M + 2 ?? 第 25 日:real.yml(gold-team J3-B/C 新增:容器内显存真值锚 GOLD_TEAM_GPU_UUID + KAP 提交闸 GOLD_TEAM_KAP_GATE,随 src ro 直挂即时生效)/ canvasApi.ts / server.mjs / phase-config-model.mjs + jobs.jsonl / docs/batch-logs/。

生产 bundle:23,137,930B mtime 10-16 23:24(flux3 部署重打,终结 10-14 起的连续不动);systemd ExecStartPre build --check 门在位。

## 4. 后端架构(路由 / 服务 / 实时层)

启动链:src/app.ts → esbuild → data/serve/app.js → systemd(node data/serve/app.js,WorkingDirectory=/home/kai/workspace 同一树,EnvironmentFile .env PORT=10588)。gen8 现役(10-16 23:24:40 起),NRestarts=0,Memory 326.9M / peak 684.9M。

三层调度同心圆(代码级确认):

GpuScheduler(服务级,L1):13 个服务 profile 注册(comfyui-primary/auxiliary、cosyvoice、chatterbox、lora-trainer、qwen-llm、kais-ear、qwen-vllm、wemm-embedding、embeddinggemma-2、hybrid-asr、ming-image、yue2-music),docker 拉停 + ensureVram 驱逐 + idle 释放 + personaArbiter 双人格。

gpuVramManager(锁级+作业级,L2):per-GPU FIFO 锁(withGpuQueue / gpuQueueTimedCore)+ UGQ 统一队列(全局 pending,FIFO + skip-head 防队头阻塞 + 30min 饥饿升级 + pack 打包账本 + balance 取空者裁决 + rescan-evict 重扫驱逐复检)+ acquireEngineOccupancy 服务级占用(qwen-eye/ear 跨请求持锁 + 健康看门狗)。

gpuQueueCrossProc(跨进程):Redis strict(SET NX PX + 心跳 + Lua 释放),REDIS_URL=redis://127.0.0.1:6390。

engine 路由族全表(router 179 条挂载,dispatchEngine 收编 12 引擎):

minimax_h3(/api/production/minimax-h3/{generate,i2va,ref2va,t2va,replace-audio};VRAM 18432;GPU2 白名单双臂)

flux2(/api/production/flux/{flux2Generate,sceneGenerate,kontext-generate};12288;双臂)

flux3(/api/production/flux3/{generate,status};新增,buildFlux3Workflow 9 节点,GT 对拍 :8196;双臂 onRedirect) ★

qwen21(/api/production/qwen21;Qwen-Image-2.1 生图+edit;双臂)★ 上线后流量复活

qwen-edit / trellis2(3D)/ postprocess(CodeFormer/UltraSharp/SeedVR2/RTX VSR)/ stableaudio(sa3)/ ace(音乐)/ yue2(音乐三提交路由,UGQ 钉死单卡)

未收编 dispatchEngine 的面:qwen-eye /api/production/llm/*(:8125 llama.cpp,allocate/release + 服务级占用)、kais-ear /ear/*(:8126 同构)、TTS 族(qwenTts/breezeTts/indextts2,走 withGpuQueue)、music3/m3(:5112 独立 server 满卡)、ming(:5140 双 3090 共驻租约)、hybridAsr(:8012)。

实时层:socket.io 三命名空间(productionAgent/scriptAgent/pipelineProgress)+ /ws/projects 画布事件(subscribe+since 补发,cap 500 发 canvas:reset)。

鉴权现状:/api/v1/* 以 v6-internal、/api/* 以 v6-web 放行,实际免登录;管理面端点另有 KAP_ADMIN_TOKEN Bearer 守卫。

## 5. 数据模型与画布体系

单库 48 表骨架不变;kv_pipelineRun / kv_syncEvent 仍 0/0 行(第 4 日)——hermes 管线资产入库持续不经 kv 台账。

本窗画布动静平缓:v2/load-v2 11 + v2/save-v2 9(23:24 重启后)+ projects POST ×4;无新 scope 立项,存量项目零增长(canvas_nodes 14,176 持平)。

画布双存储:canvasEventStore(事件溯源,快照存 o_agentWorkData + 增量)+ canvasRelationalStore(save-v2 全量替换,canvas_nodes/links UPSERT + DiffDeleteGuard)。

jobs 面:jobs.jsonl append-only(last-write-wins 快照追加),启动时非终态→orphaned;ENGINE_REGISTRY 现仅 minimax_h3 注册(facade 第 19 日),转发回自环 :10588 引擎路由。

## 6. GPU 调度与引擎生态

三层架构不变:GpuScheduler(L1 13 profile)+ gpuVramManager(L2 UGQ/evict/pack/priority/balance)+ Redis strict 跨进程门。

flux3 首夜实录(本日最有信息量链):POST /flux3/generate 首笔 400(4.3ms,参数错误);第二笔全生命周期绿:enqueue(required 8192MiB, exclusive, eligible=[1,2])→ dispatch GPU1(waited 0.1s)→ vram ok(free 13,345MiB)→ 200 / 14,104ms → release(held 14.0s)。GET /flux3/status ×1(177ms)同窗在场。

UGQ balance 裁决 1 笔:qwen21 candidates GPU1(free 13,345,holds=0)/ GPU2(free 22,755,holds=0)→ GPU2 取空者;另 3 笔 qwen21 直接落 GPU1。

rescan-evict 再显身手:qwen21 GPU1 free 1,581 < need 8,192 → POST /free → evicted 11,616MiB(free 1,581→13,197)→ recheck passed → dispatch,UGQ 自愈能力持续在役。

pinnedEngines live:music3 / rtx_vsr / yue2;UGQ pool=[1,2];pack(max 12,288 / reserve 2,048)、priority、sweep 60s、starve 30min、leaseReclaim(600s)全开;legacyDirectDispatches=0。

secondary(GPU2 双臂):enabled=true 但 avail=false(04:05 探活),engines=[sa3,ace,minimax_h3]——夜间 idle 面。

GPU 进程快照(04:02):GPU0 3060Ti 4,131/8,192(auxiliary + eg2 1,630 + chrome);GPU1 3090 10,930/24,576(comfyui-primary 残留 + flux3-probe);GPU2 3090 1,370/24,576(近空)。

常驻面 live:eg2 :8152 model_loaded:true(embeddinggemma-2, cuda:0);qwen21 health ready(comfyui-primary,unet/clip/vae 全 true,missing 空);wemm :8151 按需态。

容器 15 件(较 1016 的 13 件 +2):comfyui-flux3-probe(yanwk/comfyui-boot:cu130-megapak-pt211,8196→8188,GPU 钉死 3090 UUID,Up 8h——flux3 对拍 GT 实例转常驻)★;jimeng-free-api(ghcr.io/iptag/jimeng-api:latest,5100→8003,Up 7h——即梦云端生图白盒代理)★。

## 7. 前端体系(packages 三包)

三包锚点不变:portal(React19+Vite6,base=/portal/,2 路由手写 switch:PortalHome + /deliver/:ep)/ infinite-canvas(React19 + @xyflow/react 12 + zustand5 + socket.io-client,LOD 三级 LodProvider 单点 viewport 订阅)/ flowgraph-v3 3.1.0(纯数据层:JSON Schema SSOT + zod + 迁移 + 脏传播 + 变体 + 布局,vitest 101/101)。

依赖方向严格单向:portal → infinite-canvas → flowgraph-v3;跨包复用全走 vite alias + tsconfig paths 直指对方 TS 源(零复制零 npm 构建)。

同步协议四通道:socket 增量广播(主通道,scope 守卫 + savedBy 自回声守卫)/ REST 全量(load-v2)/ 30s health-poll 兜底(eventCount 增长→全量重载)/ canvas:event 事件源增量(feature-flag)。

零重建第 20 日(data/web 三岛 mtime 09-28 起);本窗画布写入全走既有协议(save-v2 ×9);canvasApi.ts 1,596 行的 M 改动仍未提交(e2e 面同)。

KapNavbar vanilla custom element「单源三宿主」:portal React 宿主 / 画布 topbar / 静态站 esbuild IIFE,deploy-portal.sh 先 build-kap-nav.mjs + sed hash 改写。

## 8. 生成数据流与外部管线集成

外部依赖锚点:ComfyUI 三实例(:8188 primary / :8189 auxiliary / :8190 secondary)+ 探针双臂(:8195 yue2 / :8196 flux3 GT)、gold-team :8002、review-platform :8090(review-nginx 汇总 minio/postgres/redis)、ming :5140、music3/m3 :5112、llm :8125 / ear :8126、eg2 :8152 / wemm :8151、hybrid-asr :8012、textguard :5120、breeze-tts :5130、RTX VSR :10589/:10590、jimeng :8003、Blender BVH :8095-8098、H3 viewer nginx :8082。

/oss 双源架构:express.static(data/oss)主源 + /mnt/agents/output fallback(OUTPUT_DIR);缩略图 sharp/ffmpeg → /oss/_thumbs。

flux3 产物链:POST /generate(同步直返 JSON {images,seed,elapsed_ms})→ /tmp/comfyui-flux3-output → /view 拉图;当前 FLUX3_COMFYUI_URL 指 :8196 GT 容器,割接后回 :8188/:8190 双臂(compose env 一行切换)。

引擎流量座次(23:24 起 ~4.6h):gpu-usage 2,042(~8s)+ gpu-queue 377(~43s)遥测双腿健在;qwen21 6 笔(2 generate + 4 edit)/ flux3 2 笔(1×400 + 1×200 全生命周期成功)★ / canvas load-v2 11 + save-v2 9 / H3·yue2·ming·sa3·TTS·hybrid-asr 0。

窗口异常面:零 5xx、零 502/503/504、零 error 日志(grep 复验 0)。

kgr 外部渲染:本窗无租约动作(对照 1015 两轮 acquire-batch/release);jobs.jsonl 2 ?? 面未入 o_assets 谱系形态不变。

## 9. 部署与运行时拓扑(1017 实测)

boot 第 6 日(up 5d18h23m,10-11 09:38 起,零整机重启);load 0.74 平;内存 125G 档。

kais-aigc-platform.service 于 10-16 23:24:40 重启(flux3 上线窗口,人工触发;ExecStartPre build --check 通过,NRestarts=0)——发布纪律「无在飞 GPU 作业时重启」执行到位。

容器 15 件健康面:comfyui-primary Up 28h(healthy)/ secondary Up 4d(healthy)/ auxiliary Up 5d(healthy)/ yue2-probe Up 3d / flux3-probe Up 8h ★ / gold-team Up 5d(healthy)/ redis+audit-db+review 全家 5d(healthy)/ jimeng 7h(healthy)。

端口常驻面:10588 / 8188-8190 / 8195 / 8196 ★ / 8002 / 8090 / 8095-8098 / 8003 ★ / 5120 / 5130 / 5140 / 5152 / 8152 / 8125 / 8126 / 8012 / 6390 / 5433 / 8082 / 8642 / 10589 / 10590。

drop-in ugq-rescan-evict.conf(KAP_UGQ_RESCAN_EVICT=1)在役;comfy-idle-unload.timer ~5min 节奏持续在役(本窗 evict-try 由 UGQ 派发前 headroom 不足触发 1 笔成功)。

systemd 单元族:kais-aigc.target(拉 redis/syncthing/docker)、kais-eg2-embed(+watchdog timer)、kais-nvidia-xid-watchdog、kais-rtx-vsr×2、kais-syncthing。

## 10. 近期架构演进(flux3 上线日:五条新增)

增量一 = flux3 生图引擎路由族合入 + 部署(§4/§6):C1-C4 全绿验收(tsc RC=0 / 26 tests / GT 整树全等对拍 / 邻域 qwen21 48/48),buildFlux3Workflow 9 节点以 GT JSON 为节点面真源,双臂 onRedirect 备援;首夜真实流量即跑通全生命周期(§6 实录)。

增量二 = flux3-probe 探针容器转常驻(§6/§9):yanwk/comfyui-boot:cu130-megapak-pt211(ComfyUI 0.41.2 档),8196→8188,UUID 钉 3090;当前 FLUX3_COMFYUI_URL 指 GT,割接路径已预留。

增量三 = jimeng-free-api 容器入列(§9):ghcr.io/iptag/jimeng-api :8003,即梦云端生图白盒代理——云端生图旁路落地(dreamina CLI 的容器化对偶)。

增量四 = gold-team J3-B/C compose 增量(§3 工作树 M):GOLD_TEAM_GPU_UUID 容器内显存真值锚 + GOLD_TEAM_KAP_GATE 提交闸(默认开,KAP_GPU_QUEUE_URL 指回 :10588 gpu-queue),src ro 直挂即时生效——gold-team 侧 GPU 提交对齐 KAP 统一队列的关键一步。

增量五 = UGQ 注册形态分化确认(§2/§6):flux3/qwen21 为「UGQ 路由族」形态(不占 legacy engineOrder/vramRequirements,enqueue 落 default 档),与 16 席 legacy 表并存——新引擎接入模式事实上转向 UGQ 注册。

顺延条目:origin 2 commits 未推(9→2,git-api-push 工具在位;昨推 7)/ kv 0 行第 4 日 / jobs facade 第 19 日 / rtx_vsr UUID 化未修 / canvasApi.ts M 未提交第 26 日。

本窗对账动作:journal 2,525 行全分类 / live 三端点(gpu-queue 双层键 / eg2 health / qwen21 health)/ sqlite 直读 / GPU 三卡快照 / flux3-probe+jimeng 容器 inspect。

## 11. 架构风险与债务清单

新记三条:①flux3 依赖 :8196 GT 探针容器转产线——cu130-megapak 镜像(ComfyUI 0.41.2)与 primary(0.37)/secondary(0.36)三版本并存,割接前 FLUX3_COMFYUI_URL 单点指 GT,该容器 restart 策略/版本漂移未纳管;②jimeng-free-api 为第三方镜像(ghcr.io/iptag/jimeng-api),云端即梦配额/稳定性无 SLA,旁路依赖需标注 degraded 语义;③gold-team J3-B/C 走 src ro 直挂即时生效——镜像与挂载源漂移窗口扩大(ETS-03 禁本地 build 红线仍在,重 build 后须回收挂载行)。

顺延六条:origin 2 commits 未推(已收敛)/ kv_pipelineRun、kv_syncEvent 0 行第 4 日 / GpuScheduler GPU0 3060Ti 8G 地板卡不入池(桌面卡)/ jobs facade 单引擎第 19 日 / canvasApi.ts + e2e 面 M 未提交第 26 日 / 仓库根 db2.sqlite 空壳陷阱延续。

观察位:qwen21 双卡复活后 GPU1 白天负载回升(free 13,195 常态),H3 18,432MiB 大作业若同窗进入将再度触发 rescan-evict 换模——flux3 14s 级生图与 H3 小时长视频共用 GPU1 的优先级交织尚未经压力验证。