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 mpc        # 安装 ssw-mpc **版本二进制包**(上游 Release 产物,自动校验 sha256)
./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 可持久化。

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

上游 ssw-mpc 已按版本发布 mpc 单二进制(Gitea Release),本项目直接用版本包,不在本机编 Rust:

./run.sh mpc                       # 装 latest(当前平台)
./run.sh mpc --tag v0.2.0          # 装指定版本
./run.sh mpc --list                # 看远端版本 + 本地已装
./run.sh mpc --uninstall           # 移除本地已装

落盘在 <项目根>/.mpc/bin/<tag>/mpc(已 gitignore)。安装时会:

  1. 下载 Release 里的 SHA256SUMS + 对应平台产物;
  2. 校验 sha256,不符直接拒绝安装;
  3. 装完跑一次 mpc selfcheck,让二进制自报摘要与 Release 对账。

后端按 MPC_BIN → 本地已装版本包 → 仓库构建产物 → PATH 的顺序找二进制, GET /api/ssw/sswflow/Engine/Info 会如实展示二进制来源与版本号。

⚠️ 版本包与源码构建的能力面不同:版本包是 --features vendored 构建(静态 OpenSSL), 不含 secure feature ⇒ mpc sql / sql-plan / sql-join / pg 这几个子命令不存在。 本项目因此在运行时实测二进制支持哪些子命令,缺哪个就把对应算子从 native 降级为 partial 并写明原因(界面与运行事件里都如实标注,不会把跑不了的算子说成原生支持)。

灌演示数据(幂等,可重复跑):

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 的 ComputeEngine SPI 抽象保留为 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=16 revert、 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 可执行文件路径(不设则按「版本包 → 仓库构建 → PATH」自动找)
MPC_BIN_DIR .mpc/bin 已安装版本包的目录(scripts/install-mpc.sh 的落盘位置)
MPC_WORK_DIR ../ssw-mpc ssw-mpc 仓库路径(用于找 chain.json / 合约 ABI 等素材,不用于找二进制)
MPC_DEMO_URL — demo HTTP 算子服务地址

⚠️ mpc psi / lr 等会话类子命令需要各方 mpc agent 进程在场,单进程调用会等到超时。 生产部署请配合 ssw-mpc 的 deploy/ 起多方,或用 demo HTTP 算子服务。

★ 二进制解析顺序:MPC_BIN → 已安装版本包(.mpc/bin/<tag>/mpc,取版本号最高的) → 仓库 target/release/mpc → 仓库 target/debug/mpc → PATH。


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 的路径

  1. 关闭 TypeORM synchronize,改用 db/schema.sql 显式建表(已生成,Postgres 方言,13 张表)。
  2. base_module 表插入 14 条 sswflow 菜单(见 sys/seed.service.ts 的 menus 数组,已内置)。
  3. 实体类可平移到 JNPF 的 SuperEntity 子类,列名与 JNPF 原生 f_ 契约一致,无需改名。
  4. ActionResult 与前端 request.ts 是 1:1 对应 JNPF ResultExceptionHand / defHttp 拦截器。

环境要求

  • Node.js ≥ 18
  • 无需 Docker、无需独立 PostgreSQL(PGlite 内嵌)
  • 可选:ssw-mpc 版本二进制包(仅 MPC_DRIVER=mpc + MPC_REAL_EXEC=1 时需要) —— 用 ./run.sh mpc 装,不需要本机 Rust 工具链。

附带的 API 端点说明

端点 说明
GET /api/ssw/sswflow/Engine/Info 引擎自检:驱动、二进制来源与版本号、实测子命令可用性、19 算子能力分布

Engine/Info 的 mpc 字段会如实给出:binSource(版本包 / 仓库构建 / PATH)、 binSourceLabel(中文说明)、releaseTag(版本包 tag)、cliProbe(实测到的子命令可用性)。 界面顶部也会显示「执行底座 + 二进制来源 + 版本号」。

S
Description
隐私计算流程编排平台(NestJS + PGlite + React Flow),对接 ssw-mpc 真源
Readme
432 KiB
0 Stars 1 Watchers 0 Forks
Languages
TypeScript 86.1%
Shell 9.5%
JavaScript 4.1%
CSS 0.2%