diff --git a/CLAUDE.md b/CLAUDE.md index 3748baf..ecef3ed 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -459,6 +459,13 @@ AMD SNP(alice)+ 海光 CSV(bob)两侧**各自**完成 - `README.md` — 项目门面;「现状(2026-10-30 算子基线 + 2026-11-08 增量)」是当前能力总表 - `docs/INDEX.md` — **文档索引 + 当前状态快照**(本文所指) +- `docs/ARCHITECTURE_SYSTEM.md` — **系统架构当前形态**:组件清单 / 双层控制面 / + 会话主键 / 端到端数据流 / 部署拓扑 / 平台矩阵 / 诚实边界;拆解自 + `INTEGRATION_ANALYSIS.md`,用 [实证][桩验][设计][禁用] 区分实证与蓝图。 + `docs/ARCHITECTURE.md` 只讲计算分层「为什么」,别混着读 +- `docs/ARCHITECTURE_SYSTEM.html` — 上者的**可分享单文件 HTML**,由 + `tools/render-share-html.py` 生成;**派生产物勿手改**,改 md 后跑 + `python3 tools/render-share-html.py --check` 校验同步 - `docs/FISCO_UPSTREAM_TRUTH.md` — **国密链上游事实唯一真相源**:TARS 编码、 `e = SM3(ZA‖dataHash)` 签名口径、`sendTransaction` 4 参、`status==0`、selector 二元数组 - `docs/REAL_MACHINE_FINDINGS.md` — 两台真机硬事实;第 10 节是**证明门控合流** diff --git a/README.md b/README.md index 89cacae..fcd53c0 100644 --- a/README.md +++ b/README.md @@ -520,6 +520,8 @@ refs/nax/ 参考实现(独立仓库,仅作基线) tools/ golden 生成 + numpy 基准 + 主门禁 ci.sh(22 条)+ 各判据脚本 tools/fisco-realnode/ 真链复现工具与审计轨迹(SDK 发送器 / JNI 交叉验证 / TARS 辅助) docs/ 架构、专题设计与真相源;**总入口 `INDEX.md`**; + `ARCHITECTURE_SYSTEM.md` 是系统架构当前形态(另有同名 .html 分享版); + `ARCHITECTURE.md` 只讲计算分层; `FISCO_UPSTREAM_TRUTH.md` 是国密链上游逐条核对的唯一真相源; `REAL_MACHINE_FINDINGS.md` 是两台真机硬事实; `INTEGRATION_ANALYSIS.md` 是 2026-11-07 决策定稿(历史快照) diff --git a/docs/ARCHITECTURE_SYSTEM.html b/docs/ARCHITECTURE_SYSTEM.html new file mode 100644 index 0000000..fcbd6f9 --- /dev/null +++ b/docs/ARCHITECTURE_SYSTEM.html @@ -0,0 +1,673 @@ + + + + + +系统架构(当前形态) · ssw-mpc + + + +
+ +
+ +
+

系统架构(当前形态)

+
+

活文档 · 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 虚机)           │
+└─────────────────────────────────────────────────────────────────────────────────┘
+
+

三条硬边界(越界即失去多机构前提,不许借「方便」冲掉):

+
    +
  1. 站点端不碰 qemu,宿主机端不碰私钥。 调度落点与芯片报告只在宿主机;成员策略与签发私钥只在站点端。
  2. +
  3. TEE 直调度,绝不走 Kata / 编排层。 /dev/sev、/dev/csv-guest 设备直通决定了 hostd 必须留在真机,k8s 里只有台账。
  4. +
  5. 判定口径只有一份实现。 生成端自检 == 审计端判定;四布尔不许合并成一个 ok,文档不许复述判据逻辑当第二真相源。
  6. +
+
+

1. 组件清单(按「面」分组,路径真实存在)

+

1.1 计算面(单二进制内)

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
层crate职责依赖约束
算子核mpc-coreu64 环算术 / 分享 / PRG / 比较本地步骤[实证] 零 crates.io 依赖、no_std、零分配
编译期mpc-ir算子图、轮数规划、强制 Lift不碰密码学
协议编排mpc-vault / mpc-protoBeaver / 截断 / 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-teecrates/mpc-tee/HAL:seal/attest/sign/device_key;verify.rs / collect.rs / kbs.rs / session.rs / site_admit.rs[实证] 零 crates.io 依赖,两个平台真机跑通
mpc-hostdcrates/mpc-hostd/e2b 兼容 API + /attestation;runtime.rs 起 qemu + reaper;api.rs 四布尔 AttestationVerdict[实证] 真机运行
KBS真机上各起一个芯片验签放行后才给密钥(key_source=kbs)[实证] 同一次运行合流
qemu guestmusl mpc计算 + 出证明[实证] 跨物理机双 guest 密文会话,两侧 35.000000
+

1.3 链面

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
组件落点职责状态
mpc-chaincrates/mpc-chain/对象规范编码 / JSON-RPC / 幂等 outbox / 准入 / 国密签名 / OPA / 治理形状[实证] 真链发交易
fisco_tx.rs同上TARS 编码(非 RLP)、e = SM3(ZA‖dataHash) 签名、r‖s‖pub 128B[实证] 逐字节核对
MpcHardRule.solcontracts/ + build/contracts/combined.json硬规则上链(成员白名单 / TCB 门槛 / 算法准入)[实证] 部署 / 调用 / 读回 22/22
FISCO 节点k8s Deployment + nfs-wuguirong PVC共识 / 执行 / 账本,sm_crypto=true[实证] 连同现有账本迁入,删 Pod 重建高度不变
mpc linkcrates/mpc-cli/src/link.rs会话级入网、三档 relay 策略、credential 绑定[桩验] 进程化已实现;credential 由管理节点签发([设计] 签发侧未独立成服务)
+

1.4 站点 / 管理面(k8s)

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
组件落点职责状态
mpc-demodemo/ → k8s NodePort 30082算子集市站点,Rust 单二进制 + include_str! 内嵌前端,零外部依赖[实证] 已在 k8s,/tmp 挂 NFS PVC
fisco-verifydeploy/k8s/fisco/40-admin.yaml常驻守卫:链活性 + 高度 ≥ 30 + block30 哈希指纹[实证] 三条负向样例逐条破坏过,非恒绿
ConfigMapmpc-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 mpcmpc-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 / KBS192.168.1.102 海光 CSV、192.168.1.7 AMD SNP.7 本身是 SNP guest 虚机,.102 裸机 / hypervisor本机 127.0.0.1:3010
本机 fisco-gmmacOS 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 SNPARM OP-TEE
宿主侧动作Command::spawn(qemu) 拉起 VMattach 到已有 /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.1e = SM3(ZA‖dataHash),distid 唯一值 1234567812345678
真机双 guest 判据deploy/tee/real-machine/ 判据脚本每条负向判据用构造样例逐条破坏过,恒真 / 恒假一律不算
+

治理分域故意不同、不开 WASM:

+
    +
  • TEE_CHAIN_HARD_RULE → 硬规则进 Solidity 合约,链上共识执行(成员白名单 / TCB 门槛 / 算力上限 / 算法准入)。
  • +
  • TEE_OPA_BUNDLE → 业务合规策略走 OPA(真 opa build bundle + 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 后重新生成。

+ +
+ +
+
+ + diff --git a/docs/ARCHITECTURE_SYSTEM.md b/docs/ARCHITECTURE_SYSTEM.md new file mode 100644 index 0000000..b852f32 --- /dev/null +++ b/docs/ARCHITECTURE_SYSTEM.md @@ -0,0 +1,301 @@ +# 系统架构(当前形态) + +> **活文档 · A 类真相源** | 更新 2026-11-08 | 总入口 [docs/INDEX.md](INDEX.md) +> +> 本文只回答三个问题:**系统现在长什么样、组件摆在哪、信任边界在哪**。 +> +> | 想看什么 | 去哪 | 别来本文 | +> |---|---|---| +> | 计算分层「为什么这样分」 | [ARCHITECTURE.md](ARCHITECTURE.md) | — | +> | 决策取证「为什么这么定」 | [INTEGRATION_ANALYSIS.md](INTEGRATION_ANALYSIS.md)(历史快照) | — | +> | 当前能力清单与硬证据 | [INDEX.md](INDEX.md) §1、[README.md](../README.md) 现状 | — | +> | 上游逐字节事实(TARS / ZA / 回执) | [FISCO_UPSTREAM_TRUTH.md](FISCO_UPSTREAM_TRUTH.md) | — | +> +> 本文拆解自 `INTEGRATION_ANALYSIS.md` 的 §1(双层控制面)/ §4(链上形态)/ §5(会话主键), +> **只收架构结论与当前事实**,不复制它的论证过程、阶段状态与判据逻辑。 +> 判定口径只有一份实现(代码 / 判据脚本),本文一律给指针。 + +**状态图例**(全文通用,别把蓝图当现状): + +| 标记 | 含义 | +|---|---| +| [实证] | 真机 / 真链上跑通,有判据与硬证据 | +| [桩验] | 代码已实现,但只在桩 / 环回 / 假服务上验过 | +| [设计] | 决策已定稿,尚未具象为独立服务或完整链路 | +| [禁用] | 明确不做,或已被决策删除 | + +--- + +## 0. 一页速览 + +**一句话**:一套 Rust 单二进制的多方安全计算引擎,宿主侧直起 TEE guest 做隔离计算, +链上层用国密签名把订单 / 回执 / 硬规则写进 FISCO 国密链,站点与链的管理面落在 k8s, +而 **TEE 执行面必须留在真机**。 + +```text +┌───────────────────────── 管理面 / 站点面(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 虚机) │ +└─────────────────────────────────────────────────────────────────────────────────┘ +``` + +**三条硬边界**(越界即失去多机构前提,不许借「方便」冲掉): + +1. **站点端不碰 qemu,宿主机端不碰私钥。** 调度落点与芯片报告只在宿主机;成员策略与签发私钥只在站点端。 +2. **TEE 直调度,绝不走 Kata / 编排层。** `/dev/sev`、`/dev/csv-guest` 设备直通决定了 hostd 必须留在真机,k8s 里只有台账。 +3. **判定口径只有一份实现。** 生成端自检 == 审计端判定;四布尔不许合并成一个 `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](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`), +「谁是联盟成员、这轮算什么」只有站点端知道,两边各持一半判据;单层控制面必然 +要么把宿主机凭据发给每一方,要么假装能远程调度,两者都破坏隔离。 + +```text +站点端控制面([设计] 角色) 只持:成员表 / 策略签发 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`** 对齐: + +```text + 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 节): + +```text +attest-collect → attest-post(KBS 芯片验签放行) → key_source=kbs + → 跨物理机密文会话 → 两侧还原 35.000000 + 判据 TEE_ATTEST_GATE_OK 判据 TEE_PAIR_OK +``` + +链侧对应的是另一条独立实证链路(`tools/selftest-fisco-contract.py`,主门禁第 22 条): + +```text +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](../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 build` bundle + 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](INDEX.md) §4 / §5。 + +--- + +## 9. 阅读路线与文档分工 + +```text +想快速知道「现在能干什么」 → 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](INDEX.md) §6 只加锚点、不改写。 + +**可分享版本**:`docs/ARCHITECTURE_SYSTEM.html` 由 `tools/render-share-html.py` +从本文生成,是**派生产物,勿手改**;改架构请改本 md 后重新生成。 diff --git a/docs/INDEX.md b/docs/INDEX.md index 5fd4717..3221d81 100644 --- a/docs/INDEX.md +++ b/docs/INDEX.md @@ -13,7 +13,7 @@ | 类别 | 含义 | 更新纪律 | 代表 | |---|---|---|---| -| **A 活状态 / 真相源** | 描述当前事实,随代码同步 | 事实变了就改;同一事实只认一处权威 | `README.md` 现状、`FISCO_UPSTREAM_TRUTH.md`、`tools/ci.sh`、本文 | +| **A 活状态 / 真相源** | 描述当前事实,随代码同步 | 事实变了就改;同一事实只认一处权威 | `README.md` 现状、`ARCHITECTURE_SYSTEM.md`、`FISCO_UPSTREAM_TRUTH.md`、`tools/ci.sh`、本文 | | **B 专题设计** | 结论稳定、不含进度,讲「为什么不是另一种做法」 | 基本不动;若被推翻只在文首标注 | `ARCHITECTURE.md`、`IR.md`、`ZYNQ.md`、`RAY_*.md` | | **C 历史阶段快照** | 记录某一轮的决策、取证与当时边界 | **不改写历史正文**,文首加状态对照表 | `INTEGRATION_ANALYSIS.md`、`GAP_PLAN.md`、`REAL_MACHINE_FINDINGS.md` 第 7/9.4 节 | @@ -26,16 +26,16 @@ | 领域 | 状态 | 权威入口 / 硬证据 | |---|---|---| -| 算子与协议基线 | ✅ 零依赖 `mpc-core`、golden 向量、n 方 / PSI / SQL / IR | `README.md`「算子与协议基线」表(2026-10-30,仍适用) | -| TEE 直接调度 | ✅ 框架直出 qemu argv,**不走编排层 / Kata** | `TEE_DIRECT_LAUNCH.md`、`deploy/tee/README.md` | -| 真 TEE 双 guest 密文会话 | ✅ 海光 CSV + AMD SNP 跨物理机,两侧还原 `35.000000` | `deploy/tee/real-machine/tee-pair-attest-e2e.sh`,判据 `TEE_PAIR_OK` | -| 芯片证明链合流 | ✅ **同一次运行**:`attest-collect → attest-post(KBS 验签放行)→ key_source=kbs → 密文会话` | `REAL_MACHINE_FINDINGS.md` 第 10 节,判据 `TEE_ATTEST_GATE_OK`;负向逐条破坏过 | -| FISCO 国密链真交易 | ✅ TARS 编码(非 RLP)、`sendTransaction` 4 参、`r‖s‖pub` 128B 签名 | `FISCO_UPSTREAM_TRUTH.md`、`crates/mpc-chain/src/fisco_tx.rs` | -| ★ SM2 签名口径 | ✅ **`e = SM3(ZA‖dataHash)`**,distid `1234567812345678`;**不是**签裸 `dataHash` | `FISCO_UPSTREAM_TRUTH.md` §3.1、`tools/sm2_verify.py`;这是 `10008 InvalidSignature` 的真根因 | -| 智能合约真链部署 / 调用 / 读回 | ✅ `MpcHardRule.sol` 部署 → `recordHardRule` → 读回 → 负向矩阵,**22 项判据全绿** | `tools/selftest-fisco-contract.py`(主门禁第 22 条) | -| 主门禁 | ✅ **22 条**(第 21 条真交易编码、第 22 条真链合约) | `tools/ci.sh`;缺环境显式 `*_SKIPPED`,绝不静默通过 | -| FISCO 链节点 + 账本持久化 | ✅ 迁入 wuguirong k8s,`nfs-wuguirong` PVC;历史区块哈希逐个一致,删 Pod 重建后高度不变 | `deploy/k8s/fisco/README.md` | -| MPC 站点 `mpc-demo` | ✅ 已在 k8s(NodePort `30082`),`/tmp` 挂 NFS PVC | `demo/k8s/README.md` | +| 算子与协议基线 | [实证] 零依赖 `mpc-core`、golden 向量、n 方 / PSI / SQL / IR | `README.md`「算子与协议基线」表(2026-10-30,仍适用) | +| TEE 直接调度 | [实证] 框架直出 qemu argv,**不走编排层 / Kata** | `TEE_DIRECT_LAUNCH.md`、`deploy/tee/README.md` | +| 真 TEE 双 guest 密文会话 | [实证] 海光 CSV + AMD SNP 跨物理机,两侧还原 `35.000000` | `deploy/tee/real-machine/tee-pair-attest-e2e.sh`,判据 `TEE_PAIR_OK` | +| 芯片证明链合流 | [实证] **同一次运行**:`attest-collect → attest-post(KBS 验签放行)→ key_source=kbs → 密文会话` | `REAL_MACHINE_FINDINGS.md` 第 10 节,判据 `TEE_ATTEST_GATE_OK`;负向逐条破坏过 | +| FISCO 国密链真交易 | [实证] TARS 编码(非 RLP)、`sendTransaction` 4 参、`r‖s‖pub` 128B 签名 | `FISCO_UPSTREAM_TRUTH.md`、`crates/mpc-chain/src/fisco_tx.rs` | +| ★ SM2 签名口径 | [实证] **`e = SM3(ZA‖dataHash)`**,distid `1234567812345678`;**不是**签裸 `dataHash` | `FISCO_UPSTREAM_TRUTH.md` §3.1、`tools/sm2_verify.py`;这是 `10008 InvalidSignature` 的真根因 | +| 智能合约真链部署 / 调用 / 读回 | [实证] `MpcHardRule.sol` 部署 → `recordHardRule` → 读回 → 负向矩阵,**22 项判据全绿** | `tools/selftest-fisco-contract.py`(主门禁第 22 条) | +| 主门禁 | [实证] **22 条**(第 21 条真交易编码、第 22 条真链合约) | `tools/ci.sh`;缺环境显式 `*_SKIPPED`,绝不静默通过 | +| FISCO 链节点 + 账本持久化 | [实证] 迁入 wuguirong k8s,`nfs-wuguirong` PVC;历史区块哈希逐个一致,删 Pod 重建后高度不变 | `deploy/k8s/fisco/README.md` | +| MPC 站点 `mpc-demo` | [实证] 已在 k8s(NodePort `30082`),`/tmp` 挂 NFS PVC | `demo/k8s/README.md` | --- @@ -44,6 +44,7 @@ | 想干什么 | 去哪 | 别去哪 | |---|---|---| | 看当前能力 / 项目门面 | `README.md`「现状」+ 本文 §1 | `GAP_PLAN.md`(2026-10-30 缺口计划) | +| 看系统架构 / 组件怎么摆 / 信任边界 / 端点 | `docs/ARCHITECTURE_SYSTEM.md`(含 `.html` 分享版) | `INTEGRATION_ANALYSIS.md` 正文(决策取证)、`ARCHITECTURE.md`(只讲计算分层) | | 查 FISCO 上游事实(编码/哈希/签名/回执/端点) | `docs/FISCO_UPSTREAM_TRUTH.md` | 凭 web3 直觉;`INTEGRATION_ANALYSIS.md` 的 11-07 推断 | | 跑真链验收 | `tools/selftest-fisco-contract.py`(`--self-test` 零依赖) | 自己拼交易;`fisco-realnode-probe.py`(历史契约,未销账) | | 查门禁条数 / 跑全量闸门 | `tools/ci.sh` | 任何文档里写的数字 | @@ -69,6 +70,8 @@ | `README.md` | 项目门面:命名沿革、定位、现状(算子基线 + 11-08 增量)、验收命令、目录树 | | `CLAUDE.md` | 给 AI / 开发者的约束:三条铁律、快速验证、crate 分层、关键设计决策、文档章节 | | `docs/INDEX.md` | **本文**:总索引 + 当前状态快照 + 更新纪律 | +| `docs/ARCHITECTURE_SYSTEM.md` | **系统架构当前形态**:组件清单 / 双层控制面 / 会话主键 / 端到端数据流 / 部署拓扑 / 平台矩阵 / 诚实边界;拆解自 `INTEGRATION_ANALYSIS.md`,[实证][桩验][设计][禁用] 区分实证与蓝图 | +| `docs/ARCHITECTURE_SYSTEM.html` + `tools/render-share-html.py` | 上者的**可分享单文件 HTML** 与生成器;HTML 是派生产物勿手改,`--check` 校验与 md 同步 | | `docs/FISCO_UPSTREAM_TRUTH.md` | 国密链上游逐字节核对的唯一真相源(TARS / ZA / `status==0` / selector) | | `docs/REAL_MACHINE_FINDINGS.md` | 两台真机实测硬事实;第 10 节是最新合流结论 | | `tools/ci.sh` | 主门禁(22 条)唯一实现 | @@ -87,7 +90,7 @@ | 文档 | 当时状态 | 现在读法 | |---|---|---| -| `docs/INTEGRATION_ANALYSIS.md` | 2026-11-07 决策定稿,主门禁 18 条 | 决策台账仍生效;文首对照表列出被推进的 7 条结论 | +| `docs/INTEGRATION_ANALYSIS.md` | 2026-11-07 决策定稿,主门禁 18 条 | 决策台账仍生效;文首对照表列出被推进的 7 条结论;**架构骨架已抽到 `ARCHITECTURE_SYSTEM.md`** | | `docs/GAP_PLAN.md` | 2026-10-30 改名前缺口计划 | 已加归档声明,不据它判断「现在还缺什么」 | | `docs/REAL_MACHINE_FINDINGS.md` 第 7 / 9.4 节 | 11-07 当时的不宣称项 | 已加状态锚点,指向第 10 节 | | `docs/TEE_DIRECT_LAUNCH.md` 未交付段 | 11-06 当时 OCI 链路未复跑 | 已加 11-08 核对:仅「OCI 形态」边界继续成立 | @@ -158,3 +161,7 @@ + `bash -n tools/ci.sh` + `git diff --check`(不必跑全量门禁,避免真链判据往链上 写新块 / 部署新合约,那是文档校验不需要的副作用);**涉及代码 / 判据 / 门禁的改动** 才按 `tools/ci.sh` 跑全量 22 条。确认没有把活文档改坏。 +9. **架构结论只改 `docs/ARCHITECTURE_SYSTEM.md`**:新增 / 变更组件、边界、端点先改它, + 再跑 `python3 tools/render-share-html.py`(重新生成 `.html`)与 `--check`(校验同步)。 + HTML 是**派生产物不许手改**;历史决策文档正文不因架构变更而改写。 + 文档里写「部署了什么」必须区分 [实证] 实证 / [桩验] 桩验 / [设计] 设计角色,不许把蓝图写成现状。 diff --git a/docs/INTEGRATION_ANALYSIS.md b/docs/INTEGRATION_ANALYSIS.md index c9472eb..d2a156d 100644 --- a/docs/INTEGRATION_ANALYSIS.md +++ b/docs/INTEGRATION_ANALYSIS.md @@ -29,6 +29,13 @@ echo);硬件模组 provider 未落地;OPA 不在 guest 内;撤销链读后端未接入 (声明 chain 即 fail-closed 拒);decision 未签名未上链;TEE 证明未上链。 +**架构结论已抽出(2026-11-08)**:本文 §1 双层控制面、§4 链上形态、§5 会话主键的 +**架构骨架**已拆到 [ARCHITECTURE_SYSTEM.md](ARCHITECTURE_SYSTEM.md)(活文档), +并结合真链 / 合约 / k8s / 真机实证补齐当前形态与状态标注([实证] / [桩验] / [设计] / [禁用])。 +本文保留决策台账与取证推理链,**不再承担「系统长什么样」的职责**: +查架构去那份,查「当时为什么这么定」来本文。请勿把本文的职责矩阵当成已部署清单 +(例如 `mpc site` 是设计角色,CLI 里没有这个子命令)。 + --- ## 0. 决策台账 diff --git a/tools/render-share-html.py b/tools/render-share-html.py new file mode 100755 index 0000000..c642ae1 --- /dev/null +++ b/tools/render-share-html.py @@ -0,0 +1,218 @@ +#!/usr/bin/env python3 +"""把 docs/ARCHITECTURE_SYSTEM.md 渲染成自包含、可分享的单文件 HTML。 + +设计约束(与项目「判定口径只有一份实现」一致): + * md 是唯一真相源,HTML 是**派生产物,勿手改**; + * 输出不含外部资源(CDN / 字体 / JS),离线双击即可看,也可直接分享; + * 生成结果幂等:不写时间戳,重复生成不产生 diff 噪音; + * `--check` 用于校验 HTML 是否与 md 同步(改了 md 忘记重新生成会被抓到)。 + +用法: + python3 tools/render-share-html.py # 生成 + python3 tools/render-share-html.py --check # 只校验,不写文件 + python3 tools/render-share-html.py --input X --output Y + +依赖:markdown-it-py(本机已装)。缺失时明确报错,绝不静默跳过。 +""" + +from __future__ import annotations + +import argparse +import html +import re +import sys +from pathlib import Path + +REPO = Path(__file__).resolve().parent.parent +DEFAULT_INPUT = REPO / "docs" / "ARCHITECTURE_SYSTEM.md" +DEFAULT_OUTPUT = REPO / "docs" / "ARCHITECTURE_SYSTEM.html" + +try: + from markdown_it import MarkdownIt +except ImportError: + sys.exit( + "缺少 markdown-it-py:请先 `python3 -m pip install markdown-it-py`。\n" + "本脚本不静默降级 —— 半渲染的 HTML 比没有 HTML 更危险。" + ) + + +CSS = r""" +:root{ + --bg:#f7f8fa; --surface:#ffffff; --ink:#1b1f24; --muted:#5b6572; + --line:#e3e7ec; --accent:#2563a8; --accent-soft:#eaf2fb; + --code-bg:#f2f4f7; --quote-bg:#f4f8fd; --warn-bg:#fff7e8; --warn-line:#e0a336; + --mono:ui-monospace,SFMono-Regular,Menlo,Consolas,"Liberation Mono",monospace; + --sans:-apple-system,BlinkMacSystemFont,"PingFang SC","Hiragino Sans GB", + "Microsoft YaHei","Segoe UI",Roboto,sans-serif; +} +@media (prefers-color-scheme:dark){ + :root{ + --bg:#14171c; --surface:#1b2027; --ink:#e6e9ee; --muted:#9aa5b3; + --line:#2c333d; --accent:#79b8ff; --accent-soft:#1c2c3e; + --code-bg:#20262f; --quote-bg:#1a2532; --warn-bg:#33291a; --warn-line:#b8842f; + } +} +*{box-sizing:border-box} +html{scroll-behavior:smooth} +body{margin:0;background:var(--bg);color:var(--ink);font-family:var(--sans); + font-size:15.5px;line-height:1.75;-webkit-font-smoothing:antialiased} +.layout{display:flex;gap:0;max-width:1320px;margin:0 auto;align-items:flex-start} +nav.toc{position:sticky;top:0;flex:0 0 268px;width:268px;height:100vh;overflow-y:auto; + padding:28px 18px 40px 24px;border-right:1px solid var(--line);background:var(--surface)} +nav.toc .brand{font-weight:700;font-size:15px;letter-spacing:.02em;margin-bottom:4px} +nav.toc .sub{font-size:12px;color:var(--muted);margin-bottom:20px} +nav.toc a{display:block;color:var(--muted);text-decoration:none;font-size:13px; + padding:5px 8px;border-radius:5px;border-left:2px solid transparent} +nav.toc a:hover{color:var(--accent);background:var(--accent-soft)} +nav.toc a.lv3{padding-left:22px;font-size:12.5px;opacity:.9} +main{flex:1 1 auto;min-width:0;padding:30px 40px 90px;background:var(--bg)} +.banner{background:var(--warn-bg);border-left:3px solid var(--warn-line); + padding:10px 14px;border-radius:0 6px 6px 0;font-size:13px;color:var(--ink); + margin-bottom:26px} +.banner code{font-family:var(--mono);font-size:12px} +article{background:var(--surface);border:1px solid var(--line);border-radius:10px; + padding:34px 40px 48px;box-shadow:0 1px 3px rgba(0,0,0,.04)} +article h1{font-size:27px;line-height:1.35;margin:0 0 22px;padding-bottom:14px; + border-bottom:2px solid var(--accent)} +article h2{font-size:20px;margin:38px 0 14px;padding-top:10px; + border-top:1px solid var(--line)} +article h3{font-size:16.5px;margin:26px 0 10px;color:var(--accent)} +article h1:first-of-type{border-top:0} +article p{margin:10px 0} +article a{color:var(--accent);text-decoration:none;border-bottom:1px solid var(--accent-soft)} +article a:hover{border-bottom-color:var(--accent)} +article strong{font-weight:650} +article hr{border:0;border-top:1px solid var(--line);margin:30px 0} +article blockquote{margin:16px 0;padding:10px 18px;background:var(--quote-bg); + border-left:3px solid var(--accent);border-radius:0 6px 6px 0; + color:var(--ink)} +article blockquote p{margin:6px 0} +article ul,article ol{padding-left:24px;margin:10px 0} +article li{margin:4px 0} +article code{font-family:var(--mono);font-size:.88em;background:var(--code-bg); + padding:1px 5px;border-radius:4px;word-break:break-word} +article pre{background:var(--code-bg);border:1px solid var(--line);border-radius:7px; + padding:16px 18px;overflow-x:auto;line-height:1.55;margin:16px 0} +article pre code{background:none;padding:0;font-size:12.6px;white-space:pre} +article table{display:block;width:100%;overflow-x:auto;border-collapse:collapse; + margin:16px 0;font-size:13.8px} +article th,article td{border:1px solid var(--line);padding:8px 11px;text-align:left; + vertical-align:top;min-width:80px} +article th{background:var(--accent-soft);font-weight:650;white-space:nowrap} +article tr:nth-child(even) td{background:rgba(127,140,160,.045)} +article blockquote table{font-size:13px} +footer{max-width:760px;margin:26px auto 0;color:var(--muted);font-size:12.5px;text-align:center} +@media (max-width:900px){ + .layout{display:block} + nav.toc{position:static;width:auto;height:auto;border-right:0; + border-bottom:1px solid var(--line);padding:18px 20px} + nav.toc a{display:inline-block;margin:2px 4px 2px 0} + nav.toc a.lv3{display:none} + main{padding:20px 16px 60px} + article{padding:22px 18px 32px} +} +@media print{ + body{background:#fff;color:#000;font-size:11pt} + nav.toc,.banner{display:none} + main{padding:0} + article{border:0;box-shadow:none;padding:0} + article h2{page-break-after:avoid} + article pre,article table,article blockquote{page-break-inside:avoid} + a{color:#000;text-decoration:underline} +} +""" + +HTML_TEMPLATE = """ + + + + +{title} · ssw-mpc + + + +
+ +
+ +
+{body} +
+ +
+
+ + +""" + + +def render(md_text: str) -> tuple[str, str]: + """返回 (标题, 完整 HTML)。""" + md = MarkdownIt("commonmark").enable(["table", "strikethrough"]) + rendered = md.render(md_text) + + title_m = re.search(r"

(.*?)

", rendered, re.S) + title = html.unescape(re.sub(r"<[^>]+>", "", title_m.group(1))).strip() if title_m else "系统架构" + + headings: list[tuple[str, str, str]] = [] + counter = [0] + + def add_ids(m: re.Match[str]) -> str: + counter[0] += 1 + level, inner = m.group(1), m.group(2) + sec_id = f"sec-{counter[0]}" + text = html.unescape(re.sub(r"<[^>]+>", "", inner)).strip() + if level in ("2", "3"): + headings.append((sec_id, level, text)) + return f'{inner}' + + rendered = re.sub(r"(.*?)", add_ids, rendered, flags=re.S) + + toc = "\n ".join( + f'{html.escape(text)}' + for sec_id, level, text in headings + if level in ("2", "3") + ) + return title, HTML_TEMPLATE.format(title=html.escape(title), css=CSS, toc=toc, body=rendered) + + +def main() -> int: + ap = argparse.ArgumentParser(description=__doc__) + ap.add_argument("--input", type=Path, default=DEFAULT_INPUT) + ap.add_argument("--output", type=Path, default=DEFAULT_OUTPUT) + ap.add_argument("--check", action="store_true", help="只校验产物是否与 md 同步,不写文件") + args = ap.parse_args() + + if not args.input.is_file(): + sys.exit(f"输入不存在:{args.input}") + md_text = args.input.read_text(encoding="utf-8") + _, output = render(md_text) + + if args.check: + if not args.output.is_file(): + print(f"FAIL: 产物不存在 {args.output}") + return 1 + if args.output.read_text(encoding="utf-8") != output: + print("FAIL: HTML 与 md 不同步,请运行 python3 tools/render-share-html.py") + return 1 + print(f"OK: HTML 与 md 同步({args.output.relative_to(REPO)})") + return 0 + + args.output.parent.mkdir(parents=True, exist_ok=True) + args.output.write_text(output, encoding="utf-8") + print(f"OK: 已生成 {args.output.relative_to(REPO)}({len(output)} 字节,自包含)") + return 0 + + +if __name__ == "__main__": + sys.exit(main())