Files
ssw-mpc-flow/CLAUDE.md
T
admin ee8c6c5e64 feat(engine): 执行底座改用 ssw-mpc 版本二进制包 + 运行时能力降级
上游已按版本发布 mpc 单二进制到 Gitea Release,本项目不再从源码构建,
改为下载版本包并做双重校验:
- scripts/install-mpc.sh:按 uname 选产物、比对 Release 的 SHA256SUMS、
  装完再跑 mpc selfcheck 让二进制自报摘要对账;落 <项目根>/.mpc/bin/<tag>/mpc
- mpc-client.ts:二进制解析顺序改为 MPC_BIN → 版本包(取语义化版本最高)
  → 仓库 release/debug 构建 → PATH;新增 binSource 字段与中文标签
- engine-registry / mpc-engine / mpc-operator-map:新增 probeCliSubcommands()
  逐个探测子命令,缺哪个就把对应算子 native → partial 并写明原因
  (applyRuntimeCapability),Engine/Info 的 cliProbe 字段如实给出探测结果

★ 版本包不含 secure feature ⇒ mpc sql/sql-plan/sql-join/pg 不存在
  (实测 exit=2 + 「未知命令: sql」),相关算子按实降级为 partial。

门禁复跑全绿:check-module 219/0 + 21/0 + 21/0、perm-smoke 32/0、
sswflow-smoke 46/0,后端/前端 tsc 0 错。实测 mpc selfcheck 通过
(sha256 394fc5fd… 与 manifest 一致)。
2026-11-10 17:02:19 +08:00

15 KiB
Raw Blame History

CLAUDE.md

本文件是 ssw-mpc-flow 的项目级上下文。改动前先读这里,别凭印象猜。 详细口径见 README.md;踩坑与实测事实见 .workbuddy/memory/。

项目是什么

ssw-mpc-flow(尚数网 · 隐私计算流程编排):把多方安全计算的业务流程编排做成可配置、可视化、 可执行的平台。DAG 画布编排 → 执行引擎跑 → 产物与指标留痕。

  • 框架:JNPF Lite 契约(NestJS + TypeORM + PGlite 嵌入式 Postgres + React 18 / Vite)
  • 执行底座:../ssw-mpc(Rust CLI,mpc-* crate),不修改其源码
  • 来源:从 ../ssw-mvp 抽取 sswflow(隐私计算编排)域,原 Vue 技术栈换成 React
  • 与 ssw-mvp 的关系:只搬「编排」域;设备注册 / 区块链不在 sswflow 域, 本项目改为直接对接 ssw-mpc 的真实接口(见下「两个真源模块」)

三个业务模块是兄弟而非子域,各有 appCode + 模块目录 + 表前缀:

模块 appCode 路径 表 定位
隐私计算编排 sswflow /sswflow/* 12 DAG 画布、算子目录、执行引擎、运行监控
设备注册 sswdevice /sswdevice/Device 1 TEE 节点注册表(真源 = ssw-mpc 控制面)
链上存证 sswchain /sswchain/ChainBlock 1 Receipt / FISCO 回执(真源 = outbox + 国密链)

五条铁律(优先级高于一切)

  1. 三处一字不差:controller 的 MODULE_KEY == seed.service.ts 的 menus[].urlAddress == App.tsx 的 <Route path>。改任一处必须同步另两处,否则菜单不显示 / 路由 404 / 权限静默放行 —— 这三种症状都不报错,极难定位。

  2. 改列改实体后必须重跑 node scripts/gen-schema.js。src/backend/db/schema.sql 由实体 自动生成,手改 SQL 会与 TypeORM 漂移。

  3. f_id VARCHAR(50) 是硬上限。主键由真源稳定键派生(前缀 + hex), 必须 ≤ 50 字符:tee-+46hex=50、rcpt-+45hex=50。 超了报 value too long for type character varying(50)。

  4. 两个兄弟模块是真接口对接,不许灌假数据。真源不可达 ⇒ 0 条 + source=mock + 原因, 绝不用假数据顶。造一份演示数据只会让人误以为系统能跑。

  5. 算子目录以 catalog/catalog.json 为唯一事实源(19 个算子)。端口与必填参数以它为准, 不要在别处硬编码算子元信息。

快速验证

环境前置:真机联调 / 真链访问的凭据走 xop(xop -h), 源码在内网 Git 192.168.1.18:13300/x/xop。 别把明文密码写进脚本或命令行 —— 用环境变量 + sshpass -e / GIT_ASKPASS。

# 后端编译(★ 不要用 nest start / nest build:它们要清 dist,会被安全删除钩子拦)
cd src/backend && npx tsc -p tsconfig.json          # 增量发射到 dist,不批量删目录

# 起后端(实际监听 30000,不是 3000)
cd src/backend && node dist/main.js

# 前端类型检查
cd src/frontend && npx tsc --noEmit -p tsconfig.json

改完必跑的回归(期望数字写死,掉了就是回归):

node scripts/gen-schema.js                                   # 列有变更时;期望 18 张表
bash scripts/check-module.sh sswflow Artifact Dataset DatasetAuth Datasource Flow \
  FlowRun FlowSchedule FlowStepRun Party Project ProjectParty RunEvent   # 期望 219/0
bash scripts/check-module.sh sswdevice Device                 # 期望 21/0
bash scripts/check-module.sh sswchain ChainBlock              # 期望 21/0
bash scripts/perm-smoke.sh                                    # 权限闭环;期望 32/0
bash scripts/sswflow-smoke.sh                                 # 业务链路;期望 46/0
node scripts/check-canvas-ports.js                            # 画布端口落库校验

★ check-module.sh --all 会把多词实体名拆错(datasetauth → Datasetauth), 必须显式列实体名。

拉真实数据(不是灌演示数据):

node scripts/seed-infra.js                                  # 设备 + 存证:从真源同步(幂等)
node scripts/seed-infra.js --list                           # 只看库里有什么
node scripts/seed-infra.js --tx 0x<hash>                   # 额外查一笔 FISCO 链上出块回执
node scripts/seed-demo.js                                   # 编排域演示数据(参与方/项目/DAG)

端到端演示(参考 ssw-mvp 的 e2e 脚本做的自包含版):

bash docs/e2e/sswflow/run.sh          # 无头:API 直通执行引擎,出控制台 + JSON + HTML 报告
bash docs/e2e/sswflow/run.sh --ui     # 额外用浏览器打开 Flow 画布真实点「▶ 运行」并截图

登录契约:POST /api/oauth/Login(不是 /api/sys/Account/Login), x-www-form-urlencoded 的 account + AES-ECB-PKCS7 密文密码(encryptPassword('123456'))

  • grant_type=password,token 在 data.token。

关键入口

用途 路径
画布编辑器 src/frontend/src/views/Flow.tsx(React Flow @xyflow/react 受控模式)
画布节点 src/frontend/src/components/SswNode.tsx(按算子 ports 动态渲染 Handle)
画布转换层 src/frontend/src/utils/flowTransform.ts(端口 key 直通,无映射表)
执行引擎层 src/backend/src/sswflow/engine/
算子能力映射 src/backend/src/sswflow/engine/mpc-operator-map.ts(静态基线 + applyRuntimeCapability 实测降级)
二进制客户端 src/backend/src/sswflow/engine/mpc-client.ts(版本包解析 + 子命令探测)
版本包安装脚本 scripts/install-mpc.sh(Gitea Release 下载 + sha256 校验 + selfcheck 自证)
真源适配层 src/backend/src/sswflow/engine/ssw-mpc-adapter.ts(控制面 / outbox / FISCO 回执)
运行调度中枢 src/backend/src/sswflow/flowrun.service.ts
菜单种子 src/backend/src/sys/seed.service.ts(menus[] 字面量,perm-smoke 动态解析它)
schema 生成器 scripts/gen-schema.js(递归扫 src/backend/src/**/*.entity.ts)
设备注册 src/backend/src/sswdevice/ · src/frontend/src/views/Device.tsx
链上存证 src/backend/src/sswchain/ · src/frontend/src/views/ChainBlock.tsx
通用 CRUD 页 src/frontend/src/components/CrudPage.tsx(apiBase prop 区分 appCode)

架构要点

前后端契约

  • DAG 结构:steps[{stepId,operatorKey,label,x,y,params}] / edges[{edgeId,sourceStepId,sourcePort,targetStepId,targetPort}]
  • JNPF 数据契约:f_ 前缀列、f_id VARCHAR(50) UUID 主键、f_delete_mark 软删、 ActionResult 统一返回、API 路径 /api/ssw/{appCode}/{Entity}/{List|Save|Delete}
  • 前端菜单全动态:Dashboard.tsx 从 currentUser().menuList 渲染 ⇒ 加菜单不用改导航代码,只要三处一致就会自动出现

画布组件:VueFlow → React Flow

原 ssw-mvp 用 VueFlow(@vue-flow/core),本项目用同门 React Flow(@xyflow/react)。 二者 API 一一对应(受控用 applyNodeChanges、Handle id = 端口 key、 useReactFlow/fitView、Background/MiniMap/Panel 全有)。

端口 key 透传:React Flow 的 sourceHandle/targetHandle == 后端 edge.sourcePort/edge.targetPort == catalog.json 的端口 key,没有映射表。

两个真源模块

设备注册 —— 真源 = ssw-mpc 控制面 GET {MPC_CONTROL_PLANE_URL}/nodes。

  • TeeNode 真实字段:site/host/platform{kind,tcb}/device_present/qemu_present/ firmware_present/image_present/measurement[32]/kbc/kbs_reachable/kbs_endpoint/qemu_bin…
  • platform = sev-snp / hygon-csv;kbc = cc_kbc / offline_fs_kbc::null (不是 online/offline);key = site@host;tcb 是整数
  • ★ kbs_endpoint 只能从 descriptor 解析(node_to_json 没有该字段)
  • ★ 控制面鉴权:配了共享密钥 ⇒ 必须带 Authorization: Bearer <明文密钥原文> (≥32 字节、纯 ASCII、不许含空白)。用了 hex 编码会全 401
  • ★ /nodes 是「当前在线清单」,不是注册档案:控制面 prune_stale() 会剔除超 node_ttl_secs(默认 90s)未心跳的节点 ⇒ 真源里消失的节点要标 f_online=0(不软删), 且只有真源读取成功时才标(不可达时 offline 恒 0,否则是误报)
  • f_online 三态:1=在线 / 0=掉线 / null=从未同步(人工登记)

链上存证 —— 真源 = ssw-mpc outbox(二进制 canonical_bytes)+ FISCO 国密链自有 RPC。

  • Receipt 布局:域分隔固定 25B 无长度前缀 → push_field("receipt") → "v1" → 字段
  • ★ 「验证通过」必须拆成四句:user_data_ok / meas_ok / tcb_ok / chip_sig 分开报, 不许合并成 ok=1(chip_sig=0 意为「绑定成立但没做芯片验签」)
  • ★ FISCO 成功三件套:status == 0(与 web3 的 0x1 相反)+ transactionHash 非空
    • blockNumber > 0
  • ★ FISCO 自有端点(不是 web3 那套):getTransactionReceipt / call / sendTransaction 都是 4 参 [groupID, nodeName, …];getBlockNumber 只接受 0 参。HTTP 200 ≠ 成功
  • outbox 行式:v1|key|state|attempts|payload_hex|last_error_hex, 6 段缺一即坏行 ⇒ 整表拒绝,绝不静默跳过;Confirmed 只代表已广播,不代表已出块

环境坑

  • 起后端用 node dist/main.js(nest start/nest build 会被安全删除钩子拦)。 编译用 npx tsc -p tsconfig.json —— 增量覆盖,不批量删目录。
  • PGlite 0.5.8 持久化模式起不来(卡 waitReady),纯 memory:// 正常 ⇒ 每次重启后端数据清空。这是既有环境限制,不是代码问题。
  • 后端启动后 5~8s 内登录会失败(PGlite 初始化竞态) ⇒ 要等日志出现「Nest application successfully started」再打 API。
  • ./run.sh dev 的 nohup 进程在工具 shell 里会被回收 → 用工具原生后台任务起进程。
  • 浏览器自动化:aix 软链当前是断的(指向的 agentx 二进制不存在), 用 agent-browser(/Users/xs/.npm-global/bin/agent-browser)。 React 重渲染后 @ref 失效 → 改用 eval + element.click()。
  • 端口扫描必须加 --noproxy '*' / NO_PROXY=*:本机 HTTP 代理会把 nc -z 的 「succeeded」报成假阳性(AMD 真机就踩过)。
  • macOS grep 无 -P;grep 对部分 ssw-mpc 源文件返回空 → 改用 python3 读。
  • npm bin -g 已移除 → 用 npm root -g。
  • Gitea 资产下载:API 端点 /releases/{id}/assets/{aid} 返回的是 JSON 元数据, 真字节在 browser_download_url = /ssw/ssw-mpc/releases/download/{tag}/{name} (API 给的 localhost:13300 要换成 127.0.0.1 才连得上)。 读接口允许匿名 ⇒ 下载不带凭据也行。

执行底座:ssw-mpc 版本二进制包(不本地编 Rust)

上游已按版本发布 mpc 单二进制(Gitea Release),本项目直接用版本包:

事项 口径
安装 bash scripts/install-mpc.sh(./run.sh mpc 同效)→ 落 <项目根>/.mpc/bin/<tag>/mpc
校验 下载后必须比对 Release 的 SHA256SUMS;装完再跑 mpc selfcheck 让二进制自报摘要对账
二进制解析顺序 MPC_BIN → 已装版本包(.mpc/bin/<tag>/mpc,取语义化版本最高)→ 仓库 target/release/mpc → target/debug/mpc → PATH
MPC_WORK_DIR 的用途 只用来找素材(chain.json / 合约 ABI / outbox),不再用来找二进制

★★ 版本包与源码构建的能力面不同(这条最容易踩):

  • 上游版本包是 --features vendored 构建(静态 OpenSSL + 默认 control-plane), 不含 secure feature ⇒ mpc sql / sql-plan / sql-join / pg 不存在 (实测:exit=2 + stderr「未知命令: sql」)。
  • 从源码树 cargo build 出来的默认构建含 secure ⇒ 有 sql。
  • ⇒ 同一张静态能力映射表对两种二进制答案不同 ⇒ 必须实测: probeCliSubcommands() 挨个试,缺哪个就把对应算子 native → partial 并写明原因 (applyRuntimeCapability())。Engine/Info 的 cliProbe 字段如实给出探测结果。

已知未实现

  • FlowSchedule 周期调度:只有表和 CRUD,调度器未实现(到点不自动起 run)。
  • ssw-mpc 真实执行未跑通:需 MPC_DRIVER=mpc + MPC_REAL_EXEC=1 + 各方 mpc agent; 默认走 simulation 引擎(确定性占位指标,界面会显式标注,不粉饰)。
  • 版本包不含 secure:stat.scql 等依赖 mpc sql 的算子在版本包下不可原生执行 (已按实测降级为 partial);要原生跑得等上游出带 secure 的发布包。
  • 设备注册无 mTLS 握手:走 ssw-mpc 既有机制(TEE 节点经 hostd 向控制面自报), 本项目只做注册表的读取与呈现,不自建注册协议。
  • 链上存证不是通用区块浏览器:ssw-mpc mpc chain 没有区块浏览命令, 链上对象只有 Receipt / Member / PolicyBundleRecord 三类。
  • AMD 真机 192.168.1.7 的 SSH 未打通:22 端口 TCP 可连但握手被 reset (ssh -vvv 定位:服务端在发 banner 前 RST ⇒ 服务端侧行为,客户端无解)。 该机 hostd 已停(3010/3020 refused),所以控制面当前只有海光一个节点。

环境变量

变量 默认 用途
PORT 30000 后端监听端口
PGLLITE_DIR memory:// PGlite 数据目录(持久化模式当前不可用)
PG_SYNC — false 关掉 TypeORM 自动建表
MPC_CONTROL_PLANE_URL — ssw-mpc 控制面地址(设备注册真源)
MPC_HOSTD_SHARED_SECRET — 控制面共享密钥(Bearer 原文,不是 hex)
MPC_FISCO_CHAIN_CONFIG — FISCO chain.json 路径
MPC_FISCO_OUTBOX — chain outbox 路径
MPC_FISCO_NODE node0 FISCO 节点名
MPC_DRIVER / MPC_REAL_EXEC — mpc + 1 切真实引擎
MPC_BIN 自动探测 mpc 可执行文件路径(不设则按「版本包 → 仓库构建 → PATH」自动找)
MPC_BIN_DIR .mpc/bin 已安装版本包的目录(scripts/install-mpc.sh 的落盘位置)

迁回 JNPF

本项目是 JNPF Lite 契约的可运行子集。迁回时:

  1. 关闭 synchronize,直接复用 src/backend/db/schema.sql 显式建表。
  2. base_module 插入菜单(已内置在 sys/seed.service.ts 的 menus 数组)。
  3. ActionResult → JNPF 原生 ResultExceptionHand 形状已在 common/action-result.filter.ts 对齐。
  4. f_delete_mark 软删语义、JNPF ActionResult 统一返回体均已按原生风格写。

相关文档

  • README.md —— 完整口径(目录结构、算子目录、API 契约、两个真源模块详解)
  • docs/e2e/sswflow/README.md —— 端到端演示脚本说明
  • .workbuddy/memory/MEMORY.md —— 项目长期记忆(硬契约 / 关键入口 / 验证命令)
  • .workbuddy/memory/2026-11-10.md —— 当日工作日志(踩坑与实测记录)