真机: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 口径。
19 KiB
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 + 国密链) |
五条铁律(优先级高于一切)
-
三处一字不差:controller 的
MODULE_KEY==seed.service.ts的menus[].urlAddress==App.tsx的<Route path>。改任一处必须同步另两处,否则菜单不显示 / 路由 404 / 权限静默放行 —— 这三种症状都不报错,极难定位。 -
改列改实体后必须重跑
node scripts/gen-schema.js。src/backend/db/schema.sql由实体 自动生成,手改 SQL 会与 TypeORM 漂移。 -
f_id VARCHAR(50)是硬上限。主键由真源稳定键派生(前缀 + hex), 必须 ≤ 50 字符:tee-+46hex=50、rcpt-+45hex=50。 超了报value too long for type character varying(50)。 -
两个兄弟模块是真接口对接,不许灌假数据。真源不可达 ⇒ 0 条 +
source=mock+ 原因, 绝不用假数据顶。造一份演示数据只会让人误以为系统能跑。 -
算子目录以
catalog/catalog.json为唯一事实源(19 个算子)。端口与必填参数以它为准, 不要在别处硬编码算子元信息。
快速验证
环境前置:真机联调 / 真链访问的凭据走 xop(
xop -h), 源码在内网 Git192.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), 不含securefeature ⇒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」 |
三条设计纪律:
- 会话超参走环境变量(
MPC_SESSION_EPOCHS/MPC_SESSION_LR),不从节点参数取 —— 节点参数会导致各方不一致(编排器只跑本方进程)。 - 下发前先探测对端:用 bind 探测(不是 connect!connect 会占掉对端的 accept 名额, 让 ssw-mpc 把探测连接当成真对端,随后卡死在密态通道等待)。
- 探测不可达 ⇒ 降级:
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 契约的可运行子集。迁回时:
- 关闭
synchronize,直接复用src/backend/db/schema.sql显式建表。 base_module插入菜单(已内置在sys/seed.service.ts的menus数组)。ActionResult→ JNPF 原生ResultExceptionHand形状已在common/action-result.filter.ts对齐。f_delete_mark软删语义、JNPFActionResult统一返回体均已按原生风格写。
相关文档
README.md—— 完整口径(目录结构、算子目录、API 契约、两个真源模块详解)docs/e2e/sswflow/README.md—— 端到端演示脚本说明.workbuddy/memory/MEMORY.md—— 项目长期记忆(硬契约 / 关键入口 / 验证命令).workbuddy/memory/2026-11-10.md—— 当日工作日志(踩坑与实测记录)