从 ssw-mvp 抽取隐私计算编排域,框架换 JNPF Lite 契约 (NestJS + TypeORM + PGlite 嵌入式 Postgres + React 18/Vite), 执行底座对接 ../ssw-mpc Rust CLI。 三个兄弟模块: - sswflow(编排,12 表):DAG 画布(React Flow @xyflow/react)、 19 算子目录、可插拔执行引擎(mpc / simulation)、运行监控 - sswdevice(设备注册,1 表):真源 = ssw-mpc 控制面 GET /nodes, TeeNode 字段逐一对应,含 TTL 90s 在线清单的下线语义 - sswchain(链上存证,1 表):真源 = ssw-mpc outbox 二进制 canonical_bytes + FISCO 国密链自有 RPC,Receipt 四验证位分开报 配套 scripts/ 六个门禁脚本(期望数字写死)+ docs/e2e 端到端演示 + CLAUDE.md 项目级上下文。
ssw-mpc-flow · 隐私计算编排
从 ssw-mvp 抽出隐私计算编排(sswflow)域,重构为独立项目:
框架换成 JNPF Lite + NestJS/React,执行底座换成 ssw-mpc(Rust)。
原始 ssw-mvp 是 Spring Boot + Vue + 自研 NAX 执行层;本项目保留其业务语义与数据契约,
替换掉框架胶水层和执行引擎。
快速开始
./run.sh install # 安装前后端依赖
./run.sh build # 生成 db/schema.sql + 构建前后端
./run.sh dev # 起后端(30000) + 前端(5173)
打开 http://127.0.0.1:5173 ,默认账号 admin / 123456。
数据库用嵌入式 PGlite(WASM Postgres,零服务进程 / 零 docker),引擎即真 PostgreSQL,
所以 f_ 列 / varchar(50) / Postgres 方言契约完全保留。设 PGLLITE_DIR=./.pglite 可持久化。
灌演示数据(幂等,可重复跑):
node scripts/seed-demo.js # 隐私计算编排:参与方 / 项目 / 数据集 / DAG 流程 / 调度
node scripts/seed-infra.js # 设备注册 + 链上存证:**拉真实数据**(控制面 + 真链),不灌假数据
node scripts/seed-infra.js --list # 只看当前库里有什么
node scripts/seed-infra.js --tx 0x<hash> # 额外查一笔 FISCO 链上出块回执
与原项目的关系
| 层 | ssw-mvp(本项目来源) | ssw-mpc-flow(本项目) |
|---|---|---|
| 后端框架 | Spring Boot + MyBatis-Plus | NestJS + TypeORM |
| 前端框架 | Vue 2 + Element UI | React 18 + Vite |
| 权限底座 | JNPF 底座 + TDS/TDC 胶水 | JNPF Lite 契约自建(轻量、可平移) |
| 执行引擎 | NAX / RemoteNax / TeeComputeEngine | ssw-mpc Rust CLI |
| 画布组件 | VueFlow(@vue-flow/core) |
React Flow(@xyflow/react)——xyflow 同门,API 一一对应 |
被裁掉的东西
- TDS / TDC 胶水:跨方 HTTP 转发、SSE 推送、审批待办链。前端改为轮询运行事件(等价物)。
- NAX 执行层:整体替换为
ssw-mpc。NAX 的ComputeEngineSPI 抽象保留为ComputeEngine接口, 换底座不用动业务代码。
被保留的东西
-
DAG 数据契约(前后端完全一致):
steps: [{ stepId, operatorKey, label, x, y, params: {} }] edges: [{ edgeId, sourceStepId, sourcePort, targetStepId, targetPort }] -
运行状态机:
run与step的 PENDING → RUNNING → SUCCESS/FAILED/STOPPED/SKIPPED。 -
6 种运行范围:
FULL / SINGLE / SELECTED / UPSTREAM / DOWNSTREAM / RESUME。 -
端口级连线语义:上游产物按端口装配成本节点输入,不是整图广播。
-
JNPF 数据契约:
f_前缀列、f_id VARCHAR(50)UUID 主键、f_delete_mark软删、ActionResult返回体。
关于画布组件:VueFlow → React Flow
原实现用的是 VueFlow(@vue-flow/core + @vue-flow/background + @vue-flow/minimap),
不是 LogicFlow(全仓 0 引用)。
VueFlow 与 React Flow(@xyflow/react) 是 xyflow 家族的两个前端实现,
核心概念(节点/边/Handle/视口/自定义节点)完全同构,API 几乎一一对应,
所以迁移是平移而不是重写:
| VueFlow(原实现) | React Flow(本项目) |
|---|---|
<VueFlow v-model:nodes v-model:edges> |
<ReactFlow nodes edges onNodesChange onEdgesChange> |
useVueFlow() |
useReactFlow()(需包 <ReactFlowProvider>) |
nodeTypes |
nodeTypes |
defaultEdgeOptions |
defaultEdgeOptions |
addEdge(params, edges) |
addEdge(params, edges)(导入时注意与本地同名函数区分) |
<Handle type="target" :position="Position.Left" /> |
<Handle type="target" position={Position.Left} id="left" /> |
fitView() / zoomIn() / zoomOut() |
fitView() / zoomIn() / zoomOut()(useReactFlow()) |
<Background :gap="16" /> |
<Background variant={BackgroundVariant.Dots} gap={16} /> |
<MiniMap /> |
<MiniMap /> |
<Panel position="top-right"> |
<Panel position="top-right"> |
@connect="onConnect" |
onConnect={onConnect} |
isValidConnection / connection-radius |
isValidConnection / connectionRadius |
两处值得记录的差异:
- 受控模式:VueFlow 用
v-model直接双向绑定;React Flow 走applyNodeChanges/applyEdgeChanges把 change 事件回灌进 React state,本项目在Flow.tsx中显式实现了onNodesChange/onEdgesChange。 - 端口 id 即端口 key:React Flow 的
sourceHandle/targetHandle直接存算子端口 key (prep.intersect的left/right、model.predict的model/in), 与后端edge.sourcePort/edge.targetPort逐字对应,无需再做映射表。
端口锚点比原实现更完整:原 SswNode.vue 只有固定的 in/out 两个 Handle,
所以 prep.intersect 的 left/right、model.predict 的 in/model
在 UI 上无法区分(后端校验会报「输入端口未连线」)。本项目的 SswNode.tsx
按算子 catalog.json 的 ports 动态渲染 N 个 Handle,多端口算子的每个端口都能独立拖线。
目录结构
src/backend/ NestJS + TypeORM
src/sswflow/ 业务域(12 张表 + 14 个控制器)
engine/ 执行引擎层
flow-graph.ts DAG 解析 / 校验 / 拓扑排序 / 上下游闭包
compute-engine.ts ComputeEngine SPI(可插拔执行引擎)
engine-registry.ts 引擎选路(mpc / simulation)
mpc-engine.ts ssw-mpc 执行引擎
simulation-engine.ts 本地模拟引擎(无 Rust 依赖时兜底)
mpc-operator-map.ts 19 算子 → ssw-mpc 能力映射 + plan 编译
mpc-client.ts Rust CLI 调用 / 探测 / orch plan 执行
catalog/ 算子协议目录(catalog.json 为唯一事实来源)
src/sswdevice/ 设备注册模块(1 张表 + 1 控制器)—— 对接控制面节点注册表
src/sswchain/ 链上存证模块(1 张表 + 1 控制器)—— 对接 outbox + FISCO 回执
db/schema.sql 18 张表(由 scripts/gen-schema.js 从实体自动生成)
src/frontend/ React 18 + Vite
src/views/Flow.tsx DAG 画布编辑器(算子面板 + 画布 + 属性面板)
src/views/FlowRun.tsx 运行监控(步骤 / 事件 / 产物)
src/views/Device.tsx 设备注册(TEE 节点)—— 数据源:control-plane
src/views/ChainBlock.tsx 链上存证(Receipt)—— 数据源:chain outbox + FISCO
scripts/
gen-schema.js 实体 → schema.sql 生成器(防漂移)
check-module.sh 模块规范检查
perm-smoke.sh 登录 / 菜单权限冒烟
seed-demo.js 隐私计算编排演示数据
seed-infra.js 设备注册 + 链上存证:**触发真源同步**
业务模块一览
| 模块 | appCode | 路径 | 表 | 说明 |
|---|---|---|---|---|
| 隐私计算编排 | sswflow |
/sswflow/* |
12 | DAG 画布、算子目录、可插拔执行引擎、运行监控 |
| 设备注册 | sswdevice |
/sswdevice/Device |
1 | TEE 节点注册表,真源 = ssw-mpc 控制面 GET /nodes(在线清单,含下线标记) |
| 链上存证 | sswchain |
/sswchain/ChainBlock |
1 | Receipt / FISCO 回执,真源 = ssw-mpc outbox + 国密链 |
三个模块共用同一套 JNPF-Lite 契约:f_ 前缀列、f_id VARCHAR(50) UUID 主键、
f_delete_mark 软删、ActionResult 返回体、模式 B 守卫(登录 + 菜单权限),
路径统一为 /api/ssw/{appCode}/{Entity}/{List|Save|Delete}。
设备注册:对接 ssw-mpc 控制面
这不是手工登记的设备表,而是 TEE 节点经 mpc hostd 向 mpc control-plane
自报后的注册表投影。前端「从控制面同步」调 POST /api/ssw/sswdevice/Device/Sync,
后端打 GET {MPC_CONTROL_PLANE_URL}/nodes 并 upsert。
TeeNode 真实字段(23 列,逐一对应)
| 列 | 来源字段 | 实测取值 |
|---|---|---|
f_key |
key |
site@host(如 [email protected]) |
f_site / f_host |
site / host |
alice / 192.168.1.7 |
f_platform |
platform.kind |
sev-snp(AMD)/ hygon-csv(海光) |
f_tcb |
platform.tcb |
整数:AMD SNP=5,海光 CSV2=3 |
f_capacity |
capacity |
并发槽位 |
f_last_seen |
last_seen |
Unix 秒(bigint) |
f_device_present / f_qemu_present / f_firmware_present / f_image_present |
同名 | 能力位,漏填即被 admit 拒绝 |
f_kbs_reachable |
kbs_reachable |
KBS 是否可达 |
f_kbc |
kbc |
cc_kbc / offline_fs_kbc::null(不是 online/offline) |
f_measurement |
measurement[32] |
镜像度量 hex |
f_kbs_endpoint |
descriptor 的 kbs_endpoint |
★ node_to_json 没有这个字段,只能从 descriptor 解析 |
f_descriptor |
descriptor |
原始描述符全文(key=value 逐行) |
f_online |
— | 本表自己算的:1=此刻在真源清单里 / 0=已掉线 / null=从未同步过 |
f_source / f_source_reason |
— | control-plane / 失败原因 |
★ 下线语义:/nodes 是「当前在线清单」,不是注册档案
控制面 ControlPlane::prune_stale() 会自动剔除超过 node_ttl_secs
(默认 90 秒)未心跳的节点(crates/mpc-tee/src/control_plane.rs)。
所以 GET /nodes 返回的是此刻活跃的节点,不是「注册过的历史档案」。
这带来一个必须处理的问题:真源里消失的节点,在库里会留下旧行, 前端会让人误以为该设备还在线。同步逻辑因此区分三态:
f_online |
含义 |
|---|---|
1 |
本次同步出现在真源清单里 ⇒ 此刻在线 |
0 |
真源里已经没有它(掉线 / TTL 过期)⇒ 同步时自动标出,不软删、不物理删 |
null |
从未同步过(人工登记)⇒ 前端显示「未登记」 |
同步结果会额外返回 offline 计数(本次被标成离线的节点数),前端摘要显示「下线 N 个」。
★ fail-closed 的延伸:只有真源读取成功(source !== 'mock')时才做下线。
控制面不可达时拿到的 0 条节点不代表所有设备都掉线 —— 此时标离线就是误报,
所以 offline 恒为 0,f_online 保持原值。
★ 人工登记不能篡改真源权威字段:save() 会剥掉 online / source / sourceReason,
人工只能填描述性字段(站点、主机、平台、度量、描述符等),
能力位与在线状态一律来自真源。
控制面鉴权口径(crates/mpc-hostd/src/auth.rs)
- 配了共享密钥 ⇒ 必须带
Authorization: Bearer <明文密钥原文>(≥32 字节、纯 ASCII、不许含空白)。服务端只存 SHA-256 摘要,常量时间比对。 - 没配密钥(回环信任模式)⇒ 不带凭据放行,带了任何凭据一律拒。
- ★ 已知坑:下发曾用
hex_encode(secret),节点校验明文 ⇒ 全 401。token 必须是原文。 - ★ 对外统一一句「缺少或无效的凭据」,不区分 missing / malformed / mismatch。
fail-closed
真源读不到 ⇒ 返回 0 条 + source=mock + 原因,绝不用假数据顶。
注册表为空时 GET /nodes 返回空数组(不是 404)。
链上存证:对接 outbox + FISCO 国密链
这不是通用区块浏览器:mpc chain 没有区块浏览命令,链上对象只有
Receipt / Member / PolicyBundleRecord 三类。所以这里做的是
链上对象 / Receipt / 回执浏览器。
Receipt 二进制布局(crates/mpc-chain/src/objects.rs)
outbox 的 payload 是 canonical_bytes 的 hex,本项目实现了逆解:
"mpc/tee/chain/object/v1" 固定 25 字节,无长度前缀
push_field("receipt") 4 字节大端长度前缀 + "receipt"
"v1" 固定 2 字节
push_field(order_id) 变长
push_field(decision_id) 变长
result_hash[32] / input_hash[32] / user_data[64]
attest: 4 个 u8(user_data_ok / meas_ok / tcb_ok / chip_sig)
push_field(link) 变长(p2p / relay / unknown)
link_binding[32]
(signatures 故意不写 —— 签名是产物不是被签内容)
★ 「验证通过」必须拆成四句
user_data_ok / meas_ok / tcb_ok / chip_sig 分开报,不许合并成一个 ok=1。
chip_sig = 否 的含义是「绑定成立但没做芯片验签」,不是「没绑定」。
★ FISCO 成功判据三件套
status == 0 ← TransactionStatus::None = 成功(与 web3 的 0x1 相反)
transactionHash 非空 ← FISCO 自有字段名,不是 txHash
blockNumber > 0 ← 进交易池但没出块时是 0,那只是「已受理未上链」
★ FISCO 自有 RPC 端点(不是 web3 那套)
| 用途 | 方法 | 参数 |
|---|---|---|
| 查回执 | getTransactionReceipt |
4 参 [groupID, nodeName, txHash, requireProof] |
| 只读调用 | call |
4 参 [groupID, nodeName, to, data](第 5 参是签名不是 "latest") |
| 提交交易 | sendTransaction |
4 参 [groupID, nodeName, data(hex), requireProof] |
| 链高度 | getBlockNumber |
★ 只接受 0 参(params:[]) |
真链对 eth_getTransactionReceipt / eth_call 一律回 -32601。
HTTP 200 ≠ 成功 —— 错误在 body 的 error 对象里;result: null = 还没出块。
★ 实测发现的边界
recordHardRule的orderId长度必须 ≤ 16 字节:17 字节起status=16revert、 output 为空。根因是 FISCO solidity 编译器对bytes.concat的长度限制。chain contract deploy --bin参数被忽略:实际读的是--abi文件, 且要求 combined.json({"contracts":{...}})或{abi,bin}形状,裸.bin文件不认。- 合约调用需
EVM_ABI_CODEC(0x1)attribute(写调用 attribute = 0)。 - selector 是二元数组
[keccak_u32, sm3_u32],国密链调用用SM3(signature)[0..4]:recordHardRule=4461f95a、isRecorded=a3414302、hardRuleSummary=73a3d38c。
★ outbox 语义
- 行格式:
v1|key|state|attempts|payload_hex|last_error_hex(6 段缺一即坏行 → 整表拒绝)。 state:P(Pending) /C(Confirmed)。★ Confirmed 只代表已广播,不代表已出块确认。- 幂等键 =
kind:order_id:decision_id;同键重复提交不新增、不覆盖。
端点
| 端点 | 说明 |
|---|---|
Device/{List,Save,Delete} |
设备 CRUD |
Device/Sync |
从控制面同步节点注册表 |
ChainBlock/{List,Save,Delete} |
存证 CRUD |
ChainBlock/Sync |
从真链同步(body 可带 txHash 查链上出块回执) |
环境变量(这两个模块)
| 变量 | 默认 | 说明 |
|---|---|---|
MPC_CONTROL_PLANE_URL |
http://127.0.0.1:3020 |
控制面地址 |
MPC_HOSTD_SHARED_SECRET |
— | 共享密钥原文(非 hex) |
MPC_FISCO_CHAIN_CONFIG |
../ssw-mpc/tools/fisco-realnode/example.chain.json |
链配置(rpc_endpoint / group_id) |
MPC_FISCO_OUTBOX |
<stateRoot>/chain-outbox.txt |
outbox 路径 |
MPC_FISCO_NODE |
node0 |
FISCO nodeName |
算子目录(19 个)
catalog.json 是画布节点类型 / 端口 / 参数的唯一事实来源,7 个分类:
| 分类 | 数量 | 算子 |
|---|---|---|
source 数据接入 |
1 | source.dataset |
prep 数据预处理 |
5 | prep.intersect prep.sample prep.split prep.fillna prep.binning |
stat 统计分析 |
4 | stat.profile stat.correlation stat.iv stat.scql |
model 联合建模 |
6 | model.lr.train model.gbdt.train model.mlp.train model.fedavg.train model.predict model.evaluate |
sink 结果输出 |
1 | sink.export(唯一 terminal) |
tee 机密计算 |
1 | tee.privacy_aggregate |
zkp 零知识证明 |
1 | zkp.prove |
ssw-mpc 能力映射(诚实标注,不粉饰)
| 状态 | 数量 | 含义 |
|---|---|---|
native |
4 | 有对应 Rust CLI 子命令,可真实下发 |
partial |
6 | ssw-mpc 能力部分对齐,回退模拟并写 WARN |
local |
7 | 编排层职责(明文数据准备 / 统计 / 评估 / 导出),无需下发 Rust |
unsupported |
1 | model.gbdt.train,ssw-mpc 无对应实现 |
native 的 4 个:prep.intersect(PSI) stat.scql(SQL) model.lr.train(LR) model.fedavg.train(FedAvg)。
执行底座:ssw-mpc 适配层
不修改 ssw-mpc 的 Rust 源码。 原因:
mpc-ir的 21 个Op是内部 IR,无 JSON / serde 序列化,不能由 NestJS 直接提交。mpc hostd只管理 TEE sandbox,不是 DAG 提交接口。mpc-demo的 HTTP 仅用于单算子参考,不是生产执行协议。
因此适配层把画布编译为 固定 CLI argv:
mpc psi --site alice --sites alice,bob --ids 1,2,3
mpc lr --data-x 1,2,3,4 --data-y 0,1,1,0 --n 4 --d 2 --epochs 10 --lr 0.1
mpc fl --clients 2 --features 4 --per-client 50 --rounds 3
mpc sql --sql "SELECT count(*) FROM t"
整图依赖编译为 mpc orch run --plan 的文本计划:
job A
deps -
expect 35
data alice=1,2,3 bob=4,5,6
orch run 同步执行,stdout 输出稳定 NDJSON、stderr 输出进度、exit code 表示整体成败;
JSONL / orch status 用于崩溃恢复和审计。
环境变量
| 变量 | 默认 | 说明 |
|---|---|---|
MPC_DRIVER |
simulation |
mpc 时启用 ssw-mpc 引擎并置于选路首位 |
MPC_REAL_EXEC |
0 |
1 时真实起 Rust 进程;否则只生成命令写进运行事件(可审计),产物标记 simulated |
MPC_ORCH_EXEC |
0 |
1 时真实执行 mpc orch run |
MPC_SITES |
alice,bob |
各方站点名 |
MPC_BIN |
mpc |
Rust CLI 路径 |
MPC_WORK_DIR |
../ssw-mpc |
ssw-mpc 仓库路径(用于探测二进制) |
MPC_DEMO_URL |
— | demo HTTP 算子服务地址 |
⚠️
mpc psi/lr等会话类子命令需要各方mpc agent进程在场,单进程调用会等到超时。 生产部署请配合 ssw-mpc 的 deploy/ 起多方,或用 demo HTTP 算子服务。
API 契约
路径形如 /api/ssw/sswflow/{Entity}/{List|Save|Delete},返回统一 ActionResult:
{ "code": 200, "msg": "success", "data": { } }
前端 request.ts 统一解包 data,并处理 600/601/602 → 清 token 跳登录。
sswflow 域主要端点:
| 端点 | 说明 |
|---|---|
Flow/{List,Save,Delete} |
流程 CRUD |
Flow/Canvas |
保存画布(steps/edges 以 JSON 字符串落 f_steps/f_edges) |
Flow/Validate |
DAG 校验(返回 issues + 拓扑序) |
Flow/Copy |
复制流程 |
Flow/CompilePlan |
编译为 ssw-mpc 作业计划(不执行) |
Operator/Catalog |
算子目录 + 每个算子的 ssw-mpc 能力状态 |
Engine/Info |
引擎自检:当前驱动、Rust 二进制探测、19 算子能力分布 |
FlowRun/{Start,Stop,Events,Steps,Artifacts} |
运行生命周期与可观测性 |
菜单权限守卫按 base_module.f_url_address 匹配,与前端路由 path 一一对应。
迁回 JNPF 的路径
- 关闭 TypeORM
synchronize,改用db/schema.sql显式建表(已生成,Postgres 方言,13 张表)。 base_module表插入 14 条 sswflow 菜单(见sys/seed.service.ts的menus数组,已内置)。- 实体类可平移到 JNPF 的
SuperEntity子类,列名与 JNPF 原生f_契约一致,无需改名。 ActionResult与前端request.ts是 1:1 对应 JNPFResultExceptionHand/defHttp拦截器。
环境要求
- Node.js ≥ 18
- 无需 Docker、无需独立 PostgreSQL(PGlite 内嵌)
- 可选:
ssw-mpcRust 二进制(仅MPC_DRIVER=mpc+MPC_REAL_EXEC=1时需要)