Files
admin 5501a8a2f2 feat(device): zynq 注册为节点,设备页标注 TEE 支持与否
真机:zynq(192.168.1.233) 以 platform=none 注册进 ssw-mpc 控制面,
与 AMD(sev-snp)/海光(hygon-csv) 并列,ssw-mpc-flow 同步到 3 台。

- 修复事件流游标:afterSeq 默认 -1(exclusive 游标,sortCode 从 0 编号,
  原默认 0 会永久丢掉第一条事件,Overview 只返 5/6 条)。service/controller/前端 api 三处同步改。
- 设备页新增派生列「TEE 支持」:none ⇒ 标注「不支持 TEE」;
  平台列显示中文名 + PlatformKind 规范名。
- 适配层/实体的 platform 改为原样透传 PlatformKind(sev-snp/hygon-csv/optee/tdx/none),
  不做白名单,真源加新平台不被挡在适配层。
- 文档:真机验证报告补 §1B(zynq 注册全链路)与 §0.3(上游 issue #3 修复背景);
  CLAUDE.md 纠正 platform 口径。
2026-11-11 15:55:44 +08:00

19 KiB
Raw Permalink 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 = PlatformKind 的规范名(crates/mpc-tee/src/lib.rs): sev-snp / hygon-csv / optee / tdx / none。 ★ none = 无 TEE 的普通计算节点(如 zynq 边缘板)—— 界面必须标注「不支持 TEE」。 历史别名(snp/csv/amd/hygon)只在各自输入层放宽,不进协议口径。
  • 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 字段如实给出探测结果。

★ 能力不满足时:去 ssw-mpc 提 issue,不要在本项目里 hack

本项目只消费 ssw-mpc 的二进制,不改它的 Rust 源码。遇到下列任一情况:

  • 需要的子命令/feature 不存在(如版本包缺 sql / secure 系列)
  • 算子语义、入参契约、协议行为与本项目需求不符
  • 二进制本身有 bug(崩溃、结果错、退出码异常)
  • 需要新增端口、参数、输出格式或性能改进

正确做法:去上游仓库提 issue,由 ssw-mpc 维护方修复并重新打版本包; 本项目只负责升版本 + 重装(校验 SHA256SUMS + mpc selfcheck),不自己编译、不自己打包。

项 值
提 issue http://192.168.1.18:13300/ssw/ssw-mpc/issues/new
仓库 http://192.168.1.18:13300/ssw/ssw-mpc

issue 必须写清:二进制版本(mpc --version 或 mpc selfcheck 自报摘要)、 完整可复现命令、实际输出 vs 期望输出、影响哪个算子(catalog/catalog.json 的 operatorKey)。

禁止:在本项目里私改 Rust 源码顶替、用 simulation 掩盖真实失败、 把 partial 硬写成 native。降级必须显式(native → partial + 写明原因), 让 Engine/Info 说实话;该修的东西一律走上游 issue。

两方会话算子:参数契约(实测踩过的坑,别再改错)

prep.intersect → mpc psi;model.lr.train → mpc lr-vertical (不是 mpc lr —— 那是横向/本地 LR,与纵向联邦语义不符)。

参数 约束(源码依据) 踩过的坑
--site / --sites 必填;--site 必须在 --sites 里;--sites ≥ 2 方 漏 --site ⇒ exit=1「缺少 --site」
--col-blocks site:offset:len,条数必须与 --sites 一一对应且铺满 0..d_total 只给本方一条 ⇒「有 1 条,--sites 有 2 个」
--label-owner 必填,语义是参与方名(不是标签列名) 传列名 ⇒「不在 --sites 里」
--data-y 只有 label_owner 本方能给 其他方给了 ⇒「标签会被重复计数」
--data-x 长度 == 样本数 × 本方列数 长度不符 ⇒ 直接拒收
--seed 64 位十六进制,全体一致 不给 ⇒ 各方随机 ⇒ PSI 交集必空
--epochs / --lr 各方必须一致 不一致 ⇒「open_batch 值长度不一致: 本方 18,第 0 方 3」
--listen / --connect 二选一;密态通道自动用 端口 +1 都不给 ⇒「必须给 --listen 或 --connect」

三条设计纪律:

  1. 会话超参走环境变量(MPC_SESSION_EPOCHS / MPC_SESSION_LR),不从节点参数取 —— 节点参数会导致各方不一致(编排器只跑本方进程)。
  2. 下发前先探测对端:用 bind 探测(不是 connect!connect 会占掉对端的 accept 名额, 让 ssw-mpc 把探测连接当成真对端,随后卡死在密态通道等待)。
  3. 探测不可达 ⇒ 降级:ssw-mpc 的 connect_within 会重试到 180s 预算耗尽 (mpc-node/src/lib.rs:238),失败只报「Connection refused」,极具误导性(同文件 :232-234)。

已知未实现

  • FlowSchedule 周期调度:只有表和 CRUD,调度器未实现(到点不自动起 run)。
  • 两方会话算子需对端在场:prep.intersect(mpc psi)与 model.lr.train (mpc lr-vertical)是会话型算子,必须有对端进程同时在场。 单进程部署 ⇒ 下发前先探测对端端口(bind 探测,无副作用), 不可达就降级回退模拟并写明原因,绝不挂满 180s 等待预算。 配齐 MPC_SEED + MPC_SESSION_* + 对端进程后,已实测跑通真密态纵向 LR (双方权重完全一致)。
  • 版本包不含 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 的落盘位置)
MPC_SITES alice,bob 全体站点(字典序即 party 编号,ssw-mpc 铁律)
MPC_SEED — 两方会话的共享主种子(64 位十六进制);各方必须一致
MPC_SESSION_LISTEN / MPC_SESSION_CONNECT — 会话地址 host:port;本方 listen 或 connect(二选一)
MPC_SESSION_EPOCHS / MPC_SESSION_LR 20 / 0.1 会话训练超参;各方必须一致
MPC_AGENT_PRESENT — 1 = 声明各方 mpc agent 在场(跳过端口探测)

迁回 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 —— 当日工作日志(踩坑与实测记录)