上游已按版本发布 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 一致)。
456 lines
22 KiB
Markdown
456 lines
22 KiB
Markdown
# ssw-mpc-flow · 隐私计算编排
|
||
|
||
从 `ssw-mvp` 抽出隐私计算编排(sswflow)域,重构为独立项目:
|
||
**框架换成 JNPF Lite + NestJS/React,执行底座换成 `ssw-mpc`(Rust)**。
|
||
|
||
原始 `ssw-mvp` 是 Spring Boot + Vue + 自研 NAX 执行层;本项目保留其业务语义与数据契约,
|
||
替换掉框架胶水层和执行引擎。
|
||
|
||
---
|
||
|
||
## 快速开始
|
||
|
||
```bash
|
||
./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:
|
||
|
||
```bash
|
||
./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` 并写明原因(界面与运行事件里都如实标注,不会把跑不了的算子说成原生支持)。
|
||
|
||
灌演示数据(幂等,可重复跑):
|
||
|
||
```bash
|
||
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 数据契约**(前后端完全一致):
|
||
|
||
```ts
|
||
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`(如 `alice@192.168.1.7`) |
|
||
| `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`** 的文本计划:
|
||
|
||
```text
|
||
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`:
|
||
|
||
```json
|
||
{ "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`(实测到的子命令可用性)。
|
||
> 界面顶部也会显示「执行底座 + 二进制来源 + 版本号」。
|