系统架构(当前形态)
+++活文档 · A 类真相源 | 更新 2026-11-08 | 总入口 docs/INDEX.md
+本文只回答三个问题:系统现在长什么样、组件摆在哪、信任边界在哪。
++ +
++ + + +想看什么 +去哪 +别来本文 ++ +计算分层「为什么这样分」 +ARCHITECTURE.md +— ++ +决策取证「为什么这么定」 +INTEGRATION_ANALYSIS.md(历史快照) +— ++ +当前能力清单与硬证据 +INDEX.md §1、README.md 现状 +— ++ + +上游逐字节事实(TARS / ZA / 回执) +FISCO_UPSTREAM_TRUTH.md +— +本文拆解自
+INTEGRATION_ANALYSIS.md的 §1(双层控制面)/ §4(链上形态)/ §5(会话主键), +只收架构结论与当前事实,不复制它的论证过程、阶段状态与判据逻辑。 +判定口径只有一份实现(代码 / 判据脚本),本文一律给指针。
状态图例(全文通用,别把蓝图当现状):
+| 标记 | +含义 | +
|---|---|
| [实证] | +真机 / 真链上跑通,有判据与硬证据 | +
| [桩验] | +代码已实现,但只在桩 / 环回 / 假服务上验过 | +
| [设计] | +决策已定稿,尚未具象为独立服务或完整链路 | +
| [禁用] | +明确不做,或已被决策删除 | +
+
0. 一页速览
+一句话:一套 Rust 单二进制的多方安全计算引擎,宿主侧直起 TEE guest 做隔离计算, +链上层用国密签名把订单 / 回执 / 硬规则写进 FISCO 国密链,站点与链的管理面落在 k8s, +而 TEE 执行面必须留在真机。
+┌───────────────────────── 管理面 / 站点面(wuguirong k8s)─────────────────────────┐
+│ mpc-demo 算子集市 :30082 fisco-verify 守卫 ConfigMap 台账/工具 │
+│ (Rust 单二进制 + 内嵌前端) (链活性 + 高度 + 指纹) (不含私钥、不复制判据) │
+└───────────────────────────┬──────────────────────────────────────────────────────┘
+ │ JSON-RPC(自有 4 参端点)/ ConfigMap
+┌───────────────────────────▼──────────────────────────────────────────────────────┐
+│ 链面 FISCO BCOS 3.17.1 国密链(Deployment + NFS PVC,NodePort 30100/30101) │
+│ sm_crypto=true · group0/chain0 · MpcHardRule.sol(硬规则,不开 WASM) │
+│ mpc-chain:objects / rpc / outbox / admission / fisco_tx / sm2 / opa / policy │
+└───────────────────────────┬──────────────────────────────────────────────────────┘
+ │ 站点端编排 / 会话登记([设计] 尚未具象为独立服务)
+┌───────────────────────────▼── TEE 真机(编排层之外)─────────────────────────────┐
+│ 宿主机控制面 mpc-hostd :3010/:3011 e2b 兼容 API + /attestation │
+│ TeeRuntime:qemu spawn / 状态表 / reaper / 孤儿校验(pid + 启动时间) │
+│ 证明采集 → KBS 验签 → 放密钥 → tap(宿主) + socket(跨 guest) │
+│ │ vsock / tap(不进网络栈) │
+│ guest:musl `mpc` + 策略引擎 → 只做计算与出证明,不持链凭据、不发 HTTP │
+│ 192.168.1.102 海光 CSV ✧ 192.168.1.7 AMD SNP(本身是 guest 虚机) │
+└─────────────────────────────────────────────────────────────────────────────────┘
+
+三条硬边界(越界即失去多机构前提,不许借「方便」冲掉):
+-
+
- 站点端不碰 qemu,宿主机端不碰私钥。 调度落点与芯片报告只在宿主机;成员策略与签发私钥只在站点端。 +
- TEE 直调度,绝不走 Kata / 编排层。
/dev/sev、/dev/csv-guest设备直通决定了 hostd 必须留在真机,k8s 里只有台账。
+ - 判定口径只有一份实现。 生成端自检 == 审计端判定;四布尔不许合并成一个
ok,文档不许复述判据逻辑当第二真相源。
+
+
1. 组件清单(按「面」分组,路径真实存在)
+1.1 计算面(单二进制内)
+| 层 | +crate | +职责 | +依赖约束 | +
|---|---|---|---|
| 算子核 | +mpc-core |
+u64 环算术 / 分享 / PRG / 比较本地步骤 | +[实证] 零 crates.io 依赖、no_std、零分配 |
+
| 编译期 | +mpc-ir |
+算子图、轮数规划、强制 Lift | +不碰密码学 | +
| 协议编排 | +mpc-vault / mpc-proto |
+Beaver / 截断 / open / 帧协议 | +自研 TCP 帧 | +
| 应用 | +mpc-sql / mpc-ml / mpc-psi / mpc-fl / mpc-he / mpc-zkp |
+各场景算子 | +协议都走图 | +
| 编排 | +mpc-node / mpc-orch / mpc-runtime |
+一方一进程、成员与放置 | +Ray 可选,不是必需 | +
| 入口 | +mpc-cli(mpc) |
+node/psi/lr/.../tee/hostd/link/chain |
+见 1.4 profile 切分 | +
++这一层的分层理由与「为什么不是每方一个 Ray Actor」见 ARCHITECTURE.md,本文不重复。
+
1.2 TEE 执行面(真机)
+| 组件 | +落点 | +职责 | +状态 | +
|---|---|---|---|
mpc-tee |
+crates/mpc-tee/ |
+HAL:seal/attest/sign/device_key;verify.rs / collect.rs / kbs.rs / session.rs / site_admit.rs |
+[实证] 零 crates.io 依赖,两个平台真机跑通 | +
mpc-hostd |
+crates/mpc-hostd/ |
+e2b 兼容 API + /attestation;runtime.rs 起 qemu + reaper;api.rs 四布尔 AttestationVerdict |
+[实证] 真机运行 | +
| KBS | +真机上各起一个 | +芯片验签放行后才给密钥(key_source=kbs) |
+[实证] 同一次运行合流 | +
| qemu guest | +musl mpc |
+计算 + 出证明 | +[实证] 跨物理机双 guest 密文会话,两侧 35.000000 |
+
1.3 链面
+| 组件 | +落点 | +职责 | +状态 | +
|---|---|---|---|
mpc-chain |
+crates/mpc-chain/ |
+对象规范编码 / JSON-RPC / 幂等 outbox / 准入 / 国密签名 / OPA / 治理形状 | +[实证] 真链发交易 | +
fisco_tx.rs |
+同上 | +TARS 编码(非 RLP)、e = SM3(ZA‖dataHash) 签名、r‖s‖pub 128B |
+[实证] 逐字节核对 | +
MpcHardRule.sol |
+contracts/ + build/contracts/combined.json |
+硬规则上链(成员白名单 / TCB 门槛 / 算法准入) | +[实证] 部署 / 调用 / 读回 22/22 | +
| FISCO 节点 | +k8s Deployment + nfs-wuguirong PVC |
+共识 / 执行 / 账本,sm_crypto=true |
+[实证] 连同现有账本迁入,删 Pod 重建高度不变 | +
mpc link |
+crates/mpc-cli/src/link.rs |
+会话级入网、三档 relay 策略、credential 绑定 | +[桩验] 进程化已实现;credential 由管理节点签发([设计] 签发侧未独立成服务) | +
1.4 站点 / 管理面(k8s)
+| 组件 | +落点 | +职责 | +状态 | +
|---|---|---|---|
mpc-demo |
+demo/ → k8s NodePort 30082 |
+算子集市站点,Rust 单二进制 + include_str! 内嵌前端,零外部依赖 |
+[实证] 已在 k8s,/tmp 挂 NFS PVC |
+
fisco-verify |
+deploy/k8s/fisco/40-admin.yaml |
+常驻守卫:链活性 + 高度 ≥ 30 + block30 哈希指纹 | +[实证] 三条负向样例逐条破坏过,非恒绿 | +
| ConfigMap | +mpc-admin-tools / mpc-hostd-registry |
+工具与台账(从仓库原文件生成,不复制判据逻辑) | +[实证] 台账类 | +
| 站点端控制面 | +— | +会话编排 / 成员策略签发 / 链交互 / 跨宿主调度 / 审计对账 | +[设计] 决策定稿的角色,不是已实现的 mpc site 命令;CLI 无此子命令,部分职责由 mpc-hostd client 侧、判据脚本与站点承担 |
+
++⚠️ 别照着
+INTEGRATION_ANALYSIS.md的示意敲mpc site/--order/--pubkey: +那是设计蓝图。当前可用的命令以mpc --help与crates/mpc-cli/src/main.rs注册为准。
1.5 单二进制、两种 profile(编译期硬切分)
+| profile | +构建 | +含 | +不含 | +
|---|---|---|---|
| 宿主控制面(默认) | +cargo build --bin mpc |
+mpc-hostd + mpc-chain(control-plane) |
+— | +
| musl guest | +--no-default-features |
+计算 + TEE 证明 | +hostd / chain / OpenSSL |
+
main.rs 的 compile_error! 在 target_env=musl 且带 control-plane 时硬拒绝;
+mpc-cli/Cargo.toml 按 target 把 openssl-sys 排除出 musl 依赖图,保证守卫真的可达,
+而不是先撞上含混的 pkg-config 报错。主门禁第 4 条三层探针钉死这条边界。
+
2. 双层控制面与信任边界
+切两层不是审美选择,是判据归属决定的:芯片报告只能由宿主机读(/dev/sev),
+「谁是联盟成员、这轮算什么」只有站点端知道,两边各持一半判据;单层控制面必然
+要么把宿主机凭据发给每一方,要么假装能远程调度,两者都破坏隔离。
站点端控制面([设计] 角色) 只持:成员表 / 策略签发 SM2 私钥 / 会话编排
+ │ e2b 兼容 API(HTTPS + 双向认证):控制面 3010 / 数据面 3011
+ ▼
+宿主机控制面 mpc-hostd([实证]) 只持:芯片报告 / 度量 pin / TCB / qemu 生命周期
+ │ vsock / tap(不进网络栈)
+ ▼
+guest([实证]) 只做计算与出证明,不持链凭据、不发 HTTP
+
+准入拆两段:站点管成员与策略,宿主管度量与芯片;链的硬规则在站点段,芯片判定在宿主段。
+四布尔不许合并(crates/mpc-hostd/src/api.rs 的 AttestationVerdict):
+user_data_ok / meas_ok / tcb_ok / chip_sig 分开报,响应里不允许出现 ok 合并字段;
+布尔字段缺失一律当 false——「没拿到」和「不成立」在安全语义上必须同向,
+否则解析失败会伪装成通过。chip_sig=0 的含义是「绑定关系成立但没做芯片验签」,
+不能让运维看到一个 ok=1 就以为安全。
+
3. 会话是唯一主键
+三个子系统不共享数据库,靠 session_id + session_pubkey 对齐:
Session(session_id + session_pubkey)
+ │ │ │
+ ┌────────────┘ │ └────────────┐
+ ▼ ▼ ▼
+ TEE 绑定 EasyTier 入网 飞梭链登记
+ user_data[0..32] 短期 credential(管理节点签发) ComputeOrder.会话公钥
+ user_data[32..64] allow_relay 单独授权 Receipt.decision_id
+ (绑定会话公钥与度量) 会话结束 revoke Receipt.user_data(64B)
+ └──────────► 会话准入(站点)· 运行时准入(宿主)◄────────┘
+
+-
+
user_data已绑定会话公钥(crates/mpc-tee/src/session.rs),链上登记的会话公钥与报告天然可对齐,不需要新协议。
+- credential 由管理节点签发,不是从
session_id派生;框架只承载 / 绑定 / 回收,CredentialProvider未配置即拒。
+ Receipt.user_data存原始 64 字节,不存链上重算值(国密链无 sha256 预编译)。
+- 别把 EasyTier 塞进 TCB:组网是传输设施,不是可信计算基。 +
+
4. 端到端数据流(真机实证链路)
+这一条是同一次运行跑通的,不是分两次拼出来的结论(判据见
+deploy/tee/real-machine/tee-pair-attest-e2e.sh、docs/REAL_MACHINE_FINDINGS.md 第 10 节):
attest-collect → attest-post(KBS 芯片验签放行) → key_source=kbs
+ → 跨物理机密文会话 → 两侧还原 35.000000
+ 判据 TEE_ATTEST_GATE_OK 判据 TEE_PAIR_OK
+
+链侧对应的是另一条独立实证链路(tools/selftest-fisco-contract.py,主门禁第 22 条):
dataHash → TARS 编码已签名交易 → sendTransaction(4 参)→ receipt(status==0)
+ → 部署 MpcHardRule.sol → recordHardRule → call 读回 → 负向矩阵
+
+两条链路目前没有合流:TEE 证明未上链、未绑定链上状态位; +链上撤销状态位读取后端未接入(声明 chain 即 fail-closed 拒)。这是当前最重要的架构缺口, +不是「已经打通的端到端」。
+组网事实(踩过坑,别重犯):跨 guest 走 qemu socket(二层),访问宿主 KBS 走 tap
+(三层须同网段);网卡按 MAC 认、不按枚举顺序;两侧数据面 MAC 必须不同;
+两侧各起一个 KBS、不共用;SESSION_WAIT_BUDGET_SECS=180 两侧对称。
+
5. 部署拓扑与端点(当前物理落点)
+| 组件 | +落在哪 | +是不是虚拟机 | +端点 | +
|---|---|---|---|
| FISCO 国密链 | +wuguirong k8s,Pod + NFS PVC | +❌ 容器 | +集群内 fisco-chain.wuguirong.svc.cluster.local:20200;外 192.168.1.26|27|29:30100(RPC) / 30101(P2P) |
+
mpc-demo 站点 |
+wuguirong k8s,Pod + NFS PVC | +❌ 容器 | +192.168.1.26|27|29:30082 |
+
fisco-verify 守卫 |
+wuguirong k8s | +❌ 容器 | +常驻,无对外端口 | +
mpc-hostd / guest / KBS |
+192.168.1.102 海光 CSV、192.168.1.7 AMD SNP |
+.7 本身是 SNP guest 虚机,.102 裸机 / hypervisor |
+本机 127.0.0.1:3010 |
+
本机 fisco-gm |
+macOS Docker 容器(已 stop 未删,可回滚) | +❌ 容器 | +旧 :20200,不要再启动 |
+
++⚠️ 本机
+fisco-gm与 k8s 链是同账本两份拷贝,同时对外服务会分叉。 +迁移与回滚 SOP 见 deploy/k8s/fisco/README.md。
链配置真相源:tools/fisco-realnode/example.chain.json(客户端)
-
+
deploy/k8s/fisco/README.md(集群)。旧的127.0.0.1:20200只能作为历史叙述出现。
+
持久化边界
+-
+
- PVC 承载的是落盘数据:FISCO 账本 / 配置 / 国密证书(5Gi RWO),站点的
/tmp工作文件(2Gi RWO)。
+ replicas=1+strategy: Recreate:单节点 PBFT 不许双写,RWO 不许新旧 Pod 抢挂载。
+- 幂等解包
[ -f /data/config.ini ] || tar xf:Pod 重建不覆盖账本(防「假持久化」)。
+ - 内存任务表按 Pod 隔离,PVC 救不了:站点
replicas固定 1,扩副本会分裂任务。
+ - 账本 /
conf/node.pem私钥只经 PVC 注入,不进镜像 / ConfigMap / git。
+
+
6. 平台形态矩阵(不是同一套形态)
+| + | 海光 CSV / AMD SNP | +ARM OP-TEE | +
|---|---|---|
| 宿主侧动作 | +Command::spawn(qemu) 拉起 VM |
+attach 到已有 /dev/tee0 |
+
| 信任根 | +芯片密钥 + 度量 | +设备密钥 + TA 签名 | +
| 生命周期 | +进程级,起 → 跑 → 退 → reaper | +会话级,CA 开关会话,TA 常驻 | +
| 回收 | +kill qemu | +只关会话;杀进程会切断别人正在用的 TA | +
| 多方组网 | +需要 | +不需要 | +
| 链上存证 | +需要 | +可选(只存结果 hash 与设备身份) | +
| 控制面 | +两层 | +退化为一层(设备本地 CA 即控制面) | +
PlatformKind 四个值里只有 CSV / SNP 能「直接启动」(PlatformProfile::builtin() 对
+Optee / Tdx 返回 None,有断言钉死)。OP-TEE 是同一套 mpc-tee 抽象下的另一个部署形态,
+不是另一套基础设施,走独立编译与验证通道;QEMU 实跑仍待 SDK。
为什么不在 OP-TEE 上假装是 VM:TeeRuntime 靠 pid + 启动时间 校验孤儿进程;
+TA 是所有 CA 共享的,没有「这个 TA 属于哪个租户」的进程语义,硬套会让 reaper 变成事故源。
+
7. 判定、门禁与治理分域
+| 事项 | +唯一实现 | +纪律 | +
|---|---|---|
| 主门禁 | +tools/ci.sh,22 条 |
+缺环境显式 *_SKIPPED;闸门不扫自己 = 盲区,lint 含 tools/ |
+
| 真链验收 | +tools/selftest-fisco-contract.py(第 22 条) |
+部署→写→读→负向矩阵,--self-test 零依赖 22/22 |
+
| 生成端 / 审计端判定 | +同一份 security_audit::semantic_review() |
+仅 High/Critical 阻断,不得为通过设豁免 | +
| SM2 口径 | +docs/FISCO_UPSTREAM_TRUTH.md §3.1 |
+e = SM3(ZA‖dataHash),distid 唯一值 1234567812345678 |
+
| 真机双 guest 判据 | +deploy/tee/real-machine/ 判据脚本 |
+每条负向判据用构造样例逐条破坏过,恒真 / 恒假一律不算 | +
治理分域故意不同、不开 WASM:
+-
+
TEE_CHAIN_HARD_RULE→ 硬规则进 Solidity 合约,链上共识执行(成员白名单 / TCB 门槛 / 算力上限 / 算法准入)。
+TEE_OPA_BUNDLE→ 业务合规策略走 OPA(真opa buildbundle + SM3 hash pin + SM2 真签 + 真opa eval)。
+undefined不当 deny:要求恰好 1 个 bool,{}/ errors / 多结果 / 非 bool / 非零退出一律拒;策略没加载 ≠ 策略拒绝。
+- 两者字段互相禁止;[禁用] Rego→WASM 上链已删除,
WITH_WASM保持 OFF。
+
fail-open / fail-closed 不许混:存证走 outbox 等补链(fail-open);成员准入缓存过期即拒、 +撤销链读后端未接入即拒(fail-closed)。两侧混起来会让「没数据」伪装成「已放行」。
++
8. 诚实边界(仍然不宣称,不许借更新冲掉)
+-
+
- 软件 OpenSSL 签名器私钥可导出 ⇒ 密评不可过;真链能上链 ≠ 生产可用,生产必须换硬件模组签名器(
SignerPolicy::ProductionModule必拒软件签名器)。
+ - 真实
bcos-rpc的 TLCP 通道未通:第 18 条服务端是环回 echo,不是真节点,BCOS_RPC_NOT_VERIFIED仍成立;当前实证用client_tlcp=false。
+ hostd执行面仍在 TEE 真机:需要 qemu guest +/dev/sev/ CSV ioctl,wuguirong 节点无 TEE 设备,且项目铁律禁止编排层;进 k8s 的只是台账 ConfigMap。
+- TEE 证明未上链、未绑定链上状态位;链上撤销状态位读取后端未接入(声明 chain 即 fail-closed 拒);OPA 不在 guest 内;decision 未签名未上链;OPA bundle 的 guest 分发未做。 +
- OP-TEE QEMU 实跑未做(缺 SDK);
CryptoPrecompiled.sm2Verify真机对拍未做;tools/fisco-realnode-probe.py的 4 处IMPL_GAPS未销账。
+ - 本租户 SA 无
create secret权限;链客户端私钥MPC_FISCO_KEY保持仓库外,不进镜像 / ConfigMap / git。
+ - 站点端控制面是 [设计] 决策角色,不是已实现的独立服务;别把 §2 的职责矩阵当成已部署清单。 +
逐条对照与旧结论见 INDEX.md §4 / §5。
++
9. 阅读路线与文档分工
+想快速知道「现在能干什么」 → README.md 现状 → INDEX.md §1
+想搞懂「系统怎么摆、边界在哪」 → 本文
+想搞懂「计算层为什么这样分」 → ARCHITECTURE.md
+想看「当时为什么这么决策」 → INTEGRATION_ANALYSIS.md(先看文首状态提示)
+想核对「链上逐字节事实」 → FISCO_UPSTREAM_TRUTH.md
+想真跑一遍 → tools/ci.sh(22 条)/ deploy/k8s/fisco/README.md
+ / deploy/tee/real-machine/README.md
+
+更新纪律:本文是 A 类活文档,事实变了就改;但不得复制判据逻辑、不得写死门禁条数
+(只认 tools/ci.sh)、不得把 [设计] 悄悄改成 [实证]。新增架构结论先改本文,
+历史文档的正文按 INDEX.md §6 只加锚点、不改写。
可分享版本:docs/ARCHITECTURE_SYSTEM.html 由 tools/render-share-html.py
+从本文生成,是派生产物,勿手改;改架构请改本 md 后重新生成。