Files
ssw-mpc/docs/ARCHITECTURE_SYSTEM.html
T
admin 01b8bb44aa docs: 更新 OP-TEE 实跑状态,纠正文档里 storage 默认路径的错误认知
- docs/INDEX.md / ARCHITECTURE_SYSTEM.md / README.md:
  「OP-TEE QEMU 实跑未做(缺 SDK)」改为已做,但明确标注是 QEMU 模拟
  (dna = 编译期 sha256 种子、HUK = 模拟值),不能当真板设备绑定证据。
- docs/OPTEE_VERIF_PLAN.md:补第 4 条实跑证据表与破坏实验表;
  新增坑 ⑦⑧⑨(storage 默认路径 / 落点检查时机 / QEMU 不退出);
  状态表判据用例 15 → 19;步骤 3 状态改为完成。
- 更正 §3 里「storage 默认在 /data/tee,所以不用改 tee-supplicant 启动参数」
  这句错误认知 —— 实测默认是 /var/lib/tee,必须显式 -f /data/tee。
- ARCHITECTURE_SYSTEM.html 由 tools/render-share-html.py 重新生成,--check 同步通过。
- CLAUDE.md 补集群调度面与 OP-TEE 实跑结论。
2026-11-09 13:20:35 +08:00

780 lines
39 KiB
HTML
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
<!doctype html>
<html lang="zh-CN">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>系统架构(当前形态) · ssw-mpc</title>
<style>
: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}
}
</style>
</head>
<body>
<div class="layout">
<nav class="toc" aria-label="目录">
<div class="brand">ssw-mpc · 系统架构</div>
<div class="sub">当前形态 · 2026-11-08</div>
<a class="lv2" href="#sec-2">0. 一页速览</a>
<a class="lv2" href="#sec-3">1. 组件清单(按「面」分组,路径真实存在)</a>
<a class="lv3" href="#sec-4">1.1 计算面(单二进制内)</a>
<a class="lv3" href="#sec-5">1.2 TEE 执行面(真机)</a>
<a class="lv3" href="#sec-6">1.3 链面</a>
<a class="lv3" href="#sec-7">1.4 站点 / 管理面(k8s)</a>
<a class="lv3" href="#sec-8">1.5 单二进制、两种 profile(编译期硬切分)</a>
<a class="lv3" href="#sec-9">1.6 集群调度面(CubeMaster 等价物)与单机面分离</a>
<a class="lv2" href="#sec-10">2. 双层控制面与信任边界</a>
<a class="lv2" href="#sec-11">3. 会话是唯一主键</a>
<a class="lv2" href="#sec-12">4. 端到端数据流(真机实证链路)</a>
<a class="lv2" href="#sec-13">5. 部署拓扑与端点(当前物理落点)</a>
<a class="lv3" href="#sec-14">持久化边界</a>
<a class="lv2" href="#sec-15">6. 平台形态矩阵(不是同一套形态)</a>
<a class="lv2" href="#sec-16">7. 判定、门禁与治理分域</a>
<a class="lv2" href="#sec-17">8. 诚实边界(仍然不宣称,不许借更新冲掉)</a>
<a class="lv2" href="#sec-18">9. 阅读路线与文档分工</a>
</nav>
<main>
<div class="banner">
<strong>派生产物,勿手改。</strong>
真相源是 <code>docs/ARCHITECTURE_SYSTEM.md</code>;
由 <code>tools/render-share-html.py</code> 生成,改架构请改 md 后重新生成。
文内链接指向仓库内其他 <code>.md</code>:单独分享本页时这些链接不可用,
但正文、表格与拓扑图完全自包含,可离线阅读。
</div>
<article>
<h1 id="sec-1">系统架构(当前形态)</h1>
<blockquote>
<p><strong>活文档 · A 类真相源</strong> | 更新 2026-11-08 | 总入口 <a href="INDEX.md">docs/INDEX.md</a></p>
<p>本文只回答三个问题:<strong>系统现在长什么样、组件摆在哪、信任边界在哪</strong>。</p>
<table>
<thead>
<tr>
<th>想看什么</th>
<th>去哪</th>
<th>别来本文</th>
</tr>
</thead>
<tbody>
<tr>
<td>计算分层「为什么这样分」</td>
<td><a href="ARCHITECTURE.md">ARCHITECTURE.md</a></td>
<td>—</td>
</tr>
<tr>
<td>决策取证「为什么这么定」</td>
<td><a href="INTEGRATION_ANALYSIS.md">INTEGRATION_ANALYSIS.md</a>(历史快照)</td>
<td>—</td>
</tr>
<tr>
<td>当前能力清单与硬证据</td>
<td><a href="INDEX.md">INDEX.md</a> §1、<a href="../README.md">README.md</a> 现状</td>
<td>—</td>
</tr>
<tr>
<td>上游逐字节事实(TARS / ZA / 回执)</td>
<td><a href="FISCO_UPSTREAM_TRUTH.md">FISCO_UPSTREAM_TRUTH.md</a></td>
<td>—</td>
</tr>
</tbody>
</table>
<p>本文拆解自 <code>INTEGRATION_ANALYSIS.md</code> 的 §1(双层控制面)/ §4(链上形态)/ §5(会话主键),
<strong>只收架构结论与当前事实</strong>,不复制它的论证过程、阶段状态与判据逻辑。
判定口径只有一份实现(代码 / 判据脚本),本文一律给指针。</p>
</blockquote>
<p><strong>状态图例</strong>(全文通用,别把蓝图当现状):</p>
<table>
<thead>
<tr>
<th>标记</th>
<th>含义</th>
</tr>
</thead>
<tbody>
<tr>
<td>[实证]</td>
<td>真机 / 真链上跑通,有判据与硬证据</td>
</tr>
<tr>
<td>[桩验]</td>
<td>代码已实现,但只在桩 / 环回 / 假服务上验过</td>
</tr>
<tr>
<td>[设计]</td>
<td>决策已定稿,尚未具象为独立服务或完整链路</td>
</tr>
<tr>
<td>[禁用]</td>
<td>明确不做,或已被决策删除</td>
</tr>
</tbody>
</table>
<hr />
<h2 id="sec-2">0. 一页速览</h2>
<p><strong>一句话</strong>:一套 Rust 单二进制的多方安全计算引擎,宿主侧直起 TEE guest 做隔离计算,
链上层用国密签名把订单 / 回执 / 硬规则写进 FISCO 国密链,站点与链的管理面落在 k8s,
而 <strong>TEE 执行面必须留在真机</strong>。</p>
<pre><code class="language-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 control-plane :3020 [桩验] 收自报 / 选址 / 对账 / 公布端点 │
│ 宿主机控制面 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 虚机) │
└─────────────────────────────────────────────────────────────────────────────────┘
</code></pre>
<p><strong>三条硬边界</strong>(越界即失去多机构前提,不许借「方便」冲掉):</p>
<ol>
<li><strong>站点端不碰 qemu,宿主机端不碰私钥。</strong> 调度落点与芯片报告只在宿主机;成员策略与签发私钥只在站点端。</li>
<li><strong>TEE 直调度,绝不走 Kata / 编排层。</strong> <code>/dev/sev</code>、<code>/dev/csv-guest</code> 设备直通决定了 hostd 必须留在真机,k8s 里只有台账。</li>
<li><strong>判定口径只有一份实现。</strong> 生成端自检 == 审计端判定;四布尔不许合并成一个 <code>ok</code>,文档不许复述判据逻辑当第二真相源。</li>
</ol>
<hr />
<h2 id="sec-3">1. 组件清单(按「面」分组,路径真实存在)</h2>
<h3 id="sec-4">1.1 计算面(单二进制内)</h3>
<table>
<thead>
<tr>
<th>层</th>
<th>crate</th>
<th>职责</th>
<th>依赖约束</th>
</tr>
</thead>
<tbody>
<tr>
<td>算子核</td>
<td><code>mpc-core</code></td>
<td>u64 环算术 / 分享 / PRG / 比较本地步骤</td>
<td>[实证] 零 crates.io 依赖、<code>no_std</code>、零分配</td>
</tr>
<tr>
<td>编译期</td>
<td><code>mpc-ir</code></td>
<td>算子图、轮数规划、强制 Lift</td>
<td>不碰密码学</td>
</tr>
<tr>
<td>协议编排</td>
<td><code>mpc-vault</code> / <code>mpc-proto</code></td>
<td>Beaver / 截断 / open / 帧协议</td>
<td>自研 TCP 帧</td>
</tr>
<tr>
<td>应用</td>
<td><code>mpc-sql</code> / <code>mpc-ml</code> / <code>mpc-psi</code> / <code>mpc-fl</code> / <code>mpc-he</code> / <code>mpc-zkp</code></td>
<td>各场景算子</td>
<td>协议都走图</td>
</tr>
<tr>
<td>编排</td>
<td><code>mpc-node</code> / <code>mpc-orch</code> / <code>mpc-runtime</code></td>
<td>一方一进程、成员与放置</td>
<td>Ray 可选,不是必需</td>
</tr>
<tr>
<td>入口</td>
<td><code>mpc-cli</code>(<code>mpc</code>)</td>
<td><code>node/psi/lr/.../tee/hostd/link/chain</code></td>
<td>见 1.4 profile 切分</td>
</tr>
</tbody>
</table>
<blockquote>
<p>这一层的分层理由与「为什么不是每方一个 Ray Actor」见 <a href="ARCHITECTURE.md">ARCHITECTURE.md</a>,本文不重复。</p>
</blockquote>
<h3 id="sec-5">1.2 TEE 执行面(真机)</h3>
<table>
<thead>
<tr>
<th>组件</th>
<th>落点</th>
<th>职责</th>
<th>状态</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>mpc-tee</code></td>
<td><code>crates/mpc-tee/</code></td>
<td>HAL:<code>seal/attest/sign/device_key</code>;<code>verify.rs</code> / <code>collect.rs</code> / <code>kbs.rs</code> / <code>session.rs</code> / <code>site_admit.rs</code>;<strong>集群调度层</strong>:<code>scheduler.rs</code>(<code>NodeRegistry</code> / <code>TeePool</code>)/ <code>dispatch.rs</code> / <code>reconciler.rs</code> / <code>control_plane.rs</code> / <code>probe.rs</code></td>
<td>[实证] 零 crates.io 依赖,两个平台真机跑通;调度层 [桩验] 见 §1.6</td>
</tr>
<tr>
<td><code>mpc-hostd</code></td>
<td><code>crates/mpc-hostd/</code></td>
<td><strong>单机 e2b 兼容面</strong>:<code>/sandboxes</code> + <code>/attestation</code>;<code>runtime.rs</code> 起 qemu + reaper;<code>api.rs</code> 四布尔 <code>AttestationVerdict</code>。<strong>集群面</strong>:<code>registry_api.rs</code> / <code>control_plane_api.rs</code> / <code>control_plane_server.rs</code> / <code>host_dispatch.rs</code></td>
<td>[实证] 单机面真机运行;集群面 [桩验] 见 §1.6</td>
</tr>
<tr>
<td><code>mpc control-plane</code></td>
<td><code>crates/mpc-cli/src/control_plane.rs</code></td>
<td>集群面命令:<code>serve</code> / <code>nodes</code> / <code>sessions</code> / <code>set-desired</code> / <code>report</code>,默认只听 <code>127.0.0.1:3020</code></td>
<td>[桩验] 真 socket 门禁跑通,非真机集群;见 §1.6</td>
</tr>
<tr>
<td>KBS</td>
<td>真机上各起一个</td>
<td>芯片验签放行后才给密钥(<code>key_source=kbs</code>)</td>
<td>[实证] 同一次运行合流</td>
</tr>
<tr>
<td>qemu guest</td>
<td>musl <code>mpc</code></td>
<td>计算 + 出证明</td>
<td>[实证] 跨物理机双 guest 密文会话,两侧 <code>35.000000</code></td>
</tr>
</tbody>
</table>
<h3 id="sec-6">1.3 链面</h3>
<table>
<thead>
<tr>
<th>组件</th>
<th>落点</th>
<th>职责</th>
<th>状态</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>mpc-chain</code></td>
<td><code>crates/mpc-chain/</code></td>
<td>对象规范编码 / JSON-RPC / 幂等 outbox / 准入 / 国密签名 / OPA / 治理形状</td>
<td>[实证] 真链发交易</td>
</tr>
<tr>
<td><code>fisco_tx.rs</code></td>
<td>同上</td>
<td>TARS 编码(<strong>非 RLP</strong>)、<code>e = SM3(ZA‖dataHash)</code> 签名、<code>r‖s‖pub</code> 128B</td>
<td>[实证] 逐字节核对</td>
</tr>
<tr>
<td><code>MpcHardRule.sol</code></td>
<td><code>contracts/</code> + <code>build/contracts/combined.json</code></td>
<td>硬规则上链(成员白名单 / TCB 门槛 / 算法准入)</td>
<td>[实证] 部署 / 调用 / 读回 22/22</td>
</tr>
<tr>
<td>FISCO 节点</td>
<td>k8s Deployment + <code>nfs-wuguirong</code> PVC</td>
<td>共识 / 执行 / 账本,<code>sm_crypto=true</code></td>
<td>[实证] 连同现有账本迁入,删 Pod 重建高度不变</td>
</tr>
<tr>
<td><code>mpc link</code></td>
<td><code>crates/mpc-cli/src/link.rs</code></td>
<td>会话级入网、三档 relay 策略、credential 绑定</td>
<td>[桩验] 进程化已实现;credential 由管理节点签发([设计] 签发侧未独立成服务)</td>
</tr>
</tbody>
</table>
<h3 id="sec-7">1.4 站点 / 管理面(k8s)</h3>
<table>
<thead>
<tr>
<th>组件</th>
<th>落点</th>
<th>职责</th>
<th>状态</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>mpc-demo</code></td>
<td><code>demo/</code> → k8s NodePort <code>30082</code></td>
<td>算子集市站点,Rust 单二进制 + <code>include_str!</code> 内嵌前端,零外部依赖</td>
<td>[实证] 已在 k8s,<code>/tmp</code> 挂 NFS PVC</td>
</tr>
<tr>
<td><code>fisco-verify</code></td>
<td><code>deploy/k8s/fisco/40-admin.yaml</code></td>
<td>常驻守卫:链活性 + 高度 ≥ 30 + block30 哈希指纹</td>
<td>[实证] 三条负向样例逐条破坏过,非恒绿</td>
</tr>
<tr>
<td>ConfigMap</td>
<td><code>mpc-admin-tools</code> / <code>mpc-hostd-registry</code></td>
<td>工具与台账(<strong>从仓库原文件生成</strong>,不复制判据逻辑)</td>
<td>[实证] 台账类</td>
</tr>
<tr>
<td>站点端控制面</td>
<td>—</td>
<td>会话编排 / 成员策略签发 / 链交互 / 跨宿主调度 / 审计对账</td>
<td>[设计] <strong>决策定稿的角色,不是已实现的 <code>mpc site</code> 命令</strong>;CLI 无此子命令,部分职责由 <code>mpc-hostd</code> client 侧、判据脚本与站点承担</td>
</tr>
</tbody>
</table>
<blockquote>
<p>⚠️ 别照着 <code>INTEGRATION_ANALYSIS.md</code> 的示意敲 <code>mpc site</code> / <code>--order</code> / <code>--pubkey</code>:
那是设计蓝图。当前可用的命令以 <code>mpc --help</code> 与 <code>crates/mpc-cli/src/main.rs</code> 注册为准。</p>
</blockquote>
<h3 id="sec-8">1.5 单二进制、两种 profile(编译期硬切分)</h3>
<table>
<thead>
<tr>
<th>profile</th>
<th>构建</th>
<th>含</th>
<th>不含</th>
</tr>
</thead>
<tbody>
<tr>
<td>宿主控制面(默认)</td>
<td><code>cargo build --bin mpc</code></td>
<td><code>mpc-hostd</code> + <code>mpc-chain</code>(<code>control-plane</code>)</td>
<td>—</td>
</tr>
<tr>
<td>musl guest</td>
<td><code>--no-default-features</code></td>
<td>计算 + TEE 证明</td>
<td><code>hostd</code> / <code>chain</code> / OpenSSL</td>
</tr>
</tbody>
</table>
<p><code>main.rs</code> 的 <code>compile_error!</code> 在 <code>target_env=musl</code> 且带 <code>control-plane</code> 时<strong>硬拒绝</strong>;
<code>mpc-cli/Cargo.toml</code> 按 target 把 <code>openssl-sys</code> 排除出 musl 依赖图,保证守卫真的可达,
而不是先撞上含混的 <code>pkg-config</code> 报错。主门禁第 4 条三层探针钉死这条边界。</p>
<h3 id="sec-9">1.6 集群调度面(CubeMaster 等价物)与单机面分离</h3>
<p><code>mpc control-plane</code> 是 2026-11-09 起新增的<strong>集群面</strong>命令,参考 CubeSandbox 的
CubeMaster / Cubelet / Redis / reconciler 三层映射。落点仍在 <code>mpc-tee</code>(纯逻辑,
零 crates.io 依赖)与 <code>mpc-hostd</code>(HTTP 实现),<strong>不新增编排层、不落 <code>mpc-orch</code></strong>:</p>
<table>
<thead>
<tr>
<th>CubeSandbox</th>
<th>本项目落点</th>
<th>文件</th>
</tr>
</thead>
<tbody>
<tr>
<td>Cubelet(节点自描述 / 心跳)</td>
<td><code>hostd</code> 探针 + 周期自报</td>
<td><code>mpc-tee/src/probe.rs</code>、<code>mpc-hostd/src/registry_api.rs</code></td>
</tr>
<tr>
<td>Redis(共享状态源)</td>
<td><code>NodeRegistry</code> / <code>TeePool</code> 候选池</td>
<td><code>mpc-tee/src/scheduler.rs</code></td>
</tr>
<tr>
<td>CubeMaster(收自报 / 选址 / 公布端点)</td>
<td><code>ControlPlane</code></td>
<td><code>mpc-tee/src/control_plane.rs</code></td>
</tr>
<tr>
<td>reconciler(对账下发)</td>
<td><code>TeeReconciler</code>(create / attest / destroy)</td>
<td><code>mpc-tee/src/reconciler.rs</code></td>
</tr>
</tbody>
</table>
<p><strong>两个命令、两个端口、两套面,故意不合并</strong>:</p>
<table>
<thead>
<tr>
<th></th>
<th><code>mpc hostd</code>(单机 e2b 兼容面)</th>
<th><code>mpc control-plane</code>(集群面)</th>
</tr>
</thead>
<tbody>
<tr>
<td>对应角色</td>
<td>Cubelet</td>
<td>CubeMaster</td>
</tr>
<tr>
<td>默认监听</td>
<td><code>127.0.0.1:3010</code></td>
<td><code>127.0.0.1:3020</code></td>
</tr>
<tr>
<td>主要端点</td>
<td><code>/sandboxes</code>、<code>/attestation</code>、<code>/node</code></td>
<td><code>/registry</code>、<code>/nodes</code>、<code>/sessions</code>、<code>/desired</code>、<code>/report</code></td>
</tr>
<tr>
<td>生命周期</td>
<td>机器级(跟着一台 TEE 真机)</td>
<td>集群级(可独立于任何一台真机)</td>
</tr>
<tr>
<td>失败语义</td>
<td>「这台机器起不了 guest」</td>
<td>「整个集群排不出会话」</td>
</tr>
</tbody>
</table>
<p>分开的理由是<strong>暴露面与失败语义不同</strong>:集群面要跨网段可达(因此非回环监听强制
共享密钥 <strong>且</strong> 显式 <code>--allow-remote</code>,见 <code>mpc-cli/src/control_plane.rs</code>),单机面
只该本机回环;合并会让「能起 guest」那条路随集群面一起暴露。<code>mpc-tee</code> 的
<code>probe</code> / <code>reconciler</code> / <code>control_plane</code> 仍受 <code>std</code> 门控(<code>--no-default-features</code>
不编进 guest),HTTP 服务器与 tokio runtime 只在 <code>mpc-hostd</code>。</p>
<p><strong>闭环</strong>:<code>hostd</code> 周期自报 → <code>POST /registry</code>(复用 <code>TeeNode::parse()</code> 的唯一
fail-closed 口径,解析失败拒收、不写半条记录)→ <code>NodeRegistry</code> → 期望态
(<code>POST /desired</code>,存在 <code>Mutex&lt;Vec&lt;DesiredSession&gt;&gt;</code> 里,<strong>运行期可改</strong>,不是
启动脚本常量)→ 选址(<code>node_satisfies</code> + <code>admit</code>;注册表为空即失败,绝不硬塞
一台)→ 下发 <code>create</code> → 取 <code>attestation</code> → 四布尔 <code>all_ok()</code> 才把端点放进
<code>proven_endpoints()</code>(<code>GET /sessions</code>)。证明一旦漂移,<strong>先</strong>把旧记录从
<code>placed</code> 移除再重新选址 —— 否则「重新选址失败」会把证明已不通过的旧端点
继续对外公布。下发统一走 <code>HostDispatcher</code>(<code>mpc-hostd/src/host_dispatch.rs</code>),
请求体形状只有一份 <code>launch_body</code>。</p>
<p><strong>每会话专属绑定</strong>:<code>DesiredSession.binding: Option&lt;SessionBinding&gt;</code> 优先于
控制面全局绑定。绑定值写进芯片报告 <code>user_data</code>,两个会话共用一份绑定等于
两份报告可互相冒用(重放)。</p>
<p><strong>状态</strong>:[桩验] 真 socket 端到端门禁已跑通完整闭环,且用<strong>假 hostd</strong> 给
「端点不外泄」补了正向对照(证明通过 ⇒ 端点真的出现;证明不齐 ⇒ 端点被收回),
避免否定式判据因 <code>create</code> 恒失败而恒真(空集通过)。但节点是本机假 hostd /
不可达节点,<strong>不等于真机集群调度已跑通</strong> —— 见 §8。</p>
<hr />
<h2 id="sec-10">2. 双层控制面与信任边界</h2>
<p>切两层不是审美选择,是<strong>判据归属</strong>决定的:芯片报告只能由宿主机读(<code>/dev/sev</code>),
「谁是联盟成员、这轮算什么」只有站点端知道,两边各持一半判据;单层控制面必然
要么把宿主机凭据发给每一方,要么假装能远程调度,两者都破坏隔离。</p>
<pre><code class="language-text">站点端控制面([设计] 角色) 只持:成员表 / 策略签发 SM2 私钥 / 会话编排
│ e2b 兼容 API(HTTPS + 双向认证):控制面 3010 / 数据面 3011
▼
宿主机控制面 mpc-hostd([实证]) 只持:芯片报告 / 度量 pin / TCB / qemu 生命周期
│ vsock / tap(不进网络栈)
▼
guest([实证]) 只做计算与出证明,不持链凭据、不发 HTTP
</code></pre>
<p><strong>准入拆两段</strong>:站点管成员与策略,宿主管度量与芯片;链的硬规则在站点段,芯片判定在宿主段。</p>
<p><strong>四布尔不许合并</strong>(<code>crates/mpc-hostd/src/api.rs</code> 的 <code>AttestationVerdict</code>):
<code>user_data_ok</code> / <code>meas_ok</code> / <code>tcb_ok</code> / <code>chip_sig</code> 分开报,响应里<strong>不允许出现 <code>ok</code> 合并字段</strong>;
布尔字段缺失一律当 <code>false</code>——「没拿到」和「不成立」在安全语义上必须同向,
否则解析失败会伪装成通过。<code>chip_sig=0</code> 的含义是「绑定关系成立但没做芯片验签」,
不能让运维看到一个 <code>ok=1</code> 就以为安全。</p>
<hr />
<h2 id="sec-11">3. 会话是唯一主键</h2>
<p>三个子系统不共享数据库,靠 <strong><code>session_id</code> + <code>session_pubkey</code></strong> 对齐:</p>
<pre><code class="language-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)
└──────────► 会话准入(站点)· 运行时准入(宿主)◄────────┘
</code></pre>
<ul>
<li><code>user_data</code> 已绑定会话公钥(<code>crates/mpc-tee/src/session.rs</code>),链上登记的会话公钥与报告天然可对齐,不需要新协议。</li>
<li>credential <strong>由管理节点签发</strong>,不是从 <code>session_id</code> 派生;框架只承载 / 绑定 / 回收,<code>CredentialProvider</code> 未配置即拒。</li>
<li><code>Receipt.user_data</code> 存<strong>原始 64 字节</strong>,不存链上重算值(国密链无 sha256 预编译)。</li>
<li><strong>别把 EasyTier 塞进 TCB</strong>:组网是传输设施,不是可信计算基。</li>
</ul>
<hr />
<h2 id="sec-12">4. 端到端数据流(真机实证链路)</h2>
<p>这一条是<strong>同一次运行</strong>跑通的,不是分两次拼出来的结论(判据见
<code>deploy/tee/real-machine/tee-pair-attest-e2e.sh</code>、<code>docs/REAL_MACHINE_FINDINGS.md</code> 第 10 节):</p>
<pre><code class="language-text">attest-collect → attest-post(KBS 芯片验签放行) → key_source=kbs
→ 跨物理机密文会话 → 两侧还原 35.000000
判据 TEE_ATTEST_GATE_OK 判据 TEE_PAIR_OK
</code></pre>
<p>链侧对应的是另一条独立实证链路(<code>tools/selftest-fisco-contract.py</code>,主门禁第 22 条):</p>
<pre><code class="language-text">dataHash → TARS 编码已签名交易 → sendTransaction(4 参)→ receipt(status==0)
→ 部署 MpcHardRule.sol → recordHardRule → call 读回 → 负向矩阵
</code></pre>
<p><strong>两条链路目前没有合流</strong>:TEE 证明未上链、未绑定链上状态位;
链上撤销状态位读取后端未接入(声明 chain 即 fail-closed 拒)。这是当前最重要的架构缺口,
不是「已经打通的端到端」。</p>
<p>组网事实(踩过坑,别重犯):跨 guest 走 qemu <code>socket</code>(二层),访问宿主 KBS 走 <code>tap</code>
(三层须同网段);网卡按 <strong>MAC</strong> 认、不按枚举顺序;两侧数据面 MAC 必须不同;
两侧各起一个 KBS、不共用;<code>SESSION_WAIT_BUDGET_SECS=180</code> 两侧对称。</p>
<hr />
<h2 id="sec-13">5. 部署拓扑与端点(当前物理落点)</h2>
<table>
<thead>
<tr>
<th>组件</th>
<th>落在哪</th>
<th>是不是虚拟机</th>
<th>端点</th>
</tr>
</thead>
<tbody>
<tr>
<td>FISCO 国密链</td>
<td>wuguirong k8s,Pod + NFS PVC</td>
<td>❌ 容器</td>
<td>集群内 <code>fisco-chain.wuguirong.svc.cluster.local:20200</code>;外 <code>192.168.1.26|27|29:30100</code>(RPC) / <code>30101</code>(P2P)</td>
</tr>
<tr>
<td><code>mpc-demo</code> 站点</td>
<td>wuguirong k8s,Pod + NFS PVC</td>
<td>❌ 容器</td>
<td><code>192.168.1.26|27|29:30082</code></td>
</tr>
<tr>
<td><code>fisco-verify</code> 守卫</td>
<td>wuguirong k8s</td>
<td>❌ 容器</td>
<td>常驻,无对外端口</td>
</tr>
<tr>
<td><code>mpc-hostd</code> / guest / KBS</td>
<td><code>192.168.1.102</code> 海光 CSV、<code>192.168.1.7</code> AMD SNP</td>
<td><code>.7</code> 本身是 SNP guest 虚机,<code>.102</code> 裸机 / hypervisor</td>
<td>本机 <code>127.0.0.1:3010</code></td>
</tr>
<tr>
<td>本机 <code>fisco-gm</code></td>
<td>macOS Docker 容器(<strong>已 stop 未删</strong>,可回滚)</td>
<td>❌ 容器</td>
<td>旧 <code>:20200</code>,<strong>不要再启动</strong></td>
</tr>
</tbody>
</table>
<blockquote>
<p>⚠️ 本机 <code>fisco-gm</code> 与 k8s 链是<strong>同账本两份拷贝</strong>,同时对外服务会分叉。
迁移与回滚 SOP 见 <a href="../deploy/k8s/fisco/README.md">deploy/k8s/fisco/README.md</a>。</p>
</blockquote>
<p><strong>链配置真相源</strong>:<code>tools/fisco-realnode/example.chain.json</code>(客户端)</p>
<ul>
<li><code>deploy/k8s/fisco/README.md</code>(集群)。旧的 <code>127.0.0.1:20200</code> 只能作为历史叙述出现。</li>
</ul>
<h3 id="sec-14">持久化边界</h3>
<ul>
<li>PVC 承载的是<strong>落盘数据</strong>:FISCO 账本 / 配置 / 国密证书(5Gi RWO),站点的 <code>/tmp</code> 工作文件(2Gi RWO)。</li>
<li><code>replicas=1</code> + <code>strategy: Recreate</code>:单节点 PBFT 不许双写,RWO 不许新旧 Pod 抢挂载。</li>
<li>幂等解包 <code>[ -f /data/config.ini ] || tar xf</code>:Pod 重建不覆盖账本(防「假持久化」)。</li>
<li><strong>内存任务表按 Pod 隔离,PVC 救不了</strong>:站点 <code>replicas</code> 固定 1,扩副本会分裂任务。</li>
<li>账本 / <code>conf/node.pem</code> 私钥<strong>只经 PVC 注入</strong>,不进镜像 / ConfigMap / git。</li>
</ul>
<hr />
<h2 id="sec-15">6. 平台形态矩阵(不是同一套形态)</h2>
<table>
<thead>
<tr>
<th></th>
<th>海光 CSV / AMD SNP</th>
<th>ARM OP-TEE</th>
</tr>
</thead>
<tbody>
<tr>
<td>宿主侧动作</td>
<td><code>Command::spawn(qemu)</code> 拉起 VM</td>
<td>attach 到已有 <code>/dev/tee0</code></td>
</tr>
<tr>
<td>信任根</td>
<td>芯片密钥 + 度量</td>
<td>设备密钥 + TA 签名</td>
</tr>
<tr>
<td>生命周期</td>
<td>进程级,起 → 跑 → 退 → reaper</td>
<td><strong>会话级</strong>,CA 开关会话,TA 常驻</td>
</tr>
<tr>
<td>回收</td>
<td>kill qemu</td>
<td>只关会话;<strong>杀进程会切断别人正在用的 TA</strong></td>
</tr>
<tr>
<td>多方组网</td>
<td>需要</td>
<td>不需要</td>
</tr>
<tr>
<td>链上存证</td>
<td>需要</td>
<td>可选(只存结果 hash 与设备身份)</td>
</tr>
<tr>
<td>控制面</td>
<td>两层</td>
<td>退化为一层(设备本地 CA 即控制面)</td>
</tr>
</tbody>
</table>
<p><code>PlatformKind</code> 四个值里只有 CSV / SNP 能「直接启动」(<code>PlatformProfile::builtin()</code> 对
<code>Optee</code> / <code>Tdx</code> 返回 <code>None</code>,有断言钉死)。OP-TEE 是同一套 <code>mpc-tee</code> 抽象下的<strong>另一个部署形态</strong>,
不是另一套基础设施,走独立编译与验证通道;<strong>QEMU 实跑仍待 SDK</strong>。</p>
<p><strong>为什么不在 OP-TEE 上假装是 VM</strong>:<code>TeeRuntime</code> 靠 <code>pid + 启动时间</code> 校验孤儿进程;
TA 是所有 CA 共享的,没有「这个 TA 属于哪个租户」的进程语义,硬套会让 reaper 变成事故源。</p>
<hr />
<h2 id="sec-16">7. 判定、门禁与治理分域</h2>
<table>
<thead>
<tr>
<th>事项</th>
<th>唯一实现</th>
<th>纪律</th>
</tr>
</thead>
<tbody>
<tr>
<td>主门禁</td>
<td><code>tools/ci.sh</code>,<strong>22 条</strong></td>
<td>缺环境显式 <code>*_SKIPPED</code>;闸门不扫自己 = 盲区,lint 含 <code>tools/</code></td>
</tr>
<tr>
<td>真链验收</td>
<td><code>tools/selftest-fisco-contract.py</code>(第 22 条)</td>
<td>部署→写→读→负向矩阵,<code>--self-test</code> 零依赖 22/22</td>
</tr>
<tr>
<td>生成端 / 审计端判定</td>
<td>同一份 <code>security_audit::semantic_review()</code></td>
<td>仅 High/Critical 阻断,不得为通过设豁免</td>
</tr>
<tr>
<td>SM2 口径</td>
<td><code>docs/FISCO_UPSTREAM_TRUTH.md</code> §3.1</td>
<td><code>e = SM3(ZA‖dataHash)</code>,distid 唯一值 <code>1234567812345678</code></td>
</tr>
<tr>
<td>真机双 guest 判据</td>
<td><code>deploy/tee/real-machine/</code> 判据脚本</td>
<td>每条负向判据用构造样例逐条破坏过,恒真 / 恒假一律不算</td>
</tr>
</tbody>
</table>
<p><strong>治理分域故意不同、不开 WASM</strong>:</p>
<ul>
<li><code>TEE_CHAIN_HARD_RULE</code> → <strong>硬规则进 Solidity 合约</strong>,链上共识执行(成员白名单 / TCB 门槛 / 算力上限 / 算法准入)。</li>
<li><code>TEE_OPA_BUNDLE</code> → <strong>业务合规策略走 OPA</strong>(真 <code>opa build</code> bundle + SM3 hash pin + SM2 真签 + 真 <code>opa eval</code>)。</li>
<li><code>undefined</code> 不当 deny:要求恰好 1 个 bool,<code>{}</code> / errors / 多结果 / 非 bool / 非零退出一律拒;<strong>策略没加载 ≠ 策略拒绝</strong>。</li>
<li>两者字段互相禁止;[禁用] Rego→WASM 上链已删除,<code>WITH_WASM</code> 保持 OFF。</li>
</ul>
<p><strong>fail-open / fail-closed 不许混</strong>:存证走 outbox 等补链(fail-open);成员准入缓存过期即拒、
撤销链读后端未接入即拒(fail-closed)。两侧混起来会让「没数据」伪装成「已放行」。</p>
<hr />
<h2 id="sec-17">8. 诚实边界(仍然不宣称,不许借更新冲掉)</h2>
<ul>
<li>软件 OpenSSL 签名器<strong>私钥可导出 ⇒ 密评不可过</strong>;真链能上链 ≠ 生产可用,生产必须换硬件模组签名器(<code>SignerPolicy::ProductionModule</code> 必拒软件签名器)。</li>
<li>真实 <code>bcos-rpc</code> 的 <strong>TLCP 通道未通</strong>:第 18 条服务端是环回 echo,不是真节点,<code>BCOS_RPC_NOT_VERIFIED</code> 仍成立;当前实证用 <code>client_tlcp=false</code>。</li>
<li><strong><code>hostd</code> 执行面仍在 TEE 真机</strong>:需要 qemu guest + <code>/dev/sev</code> / CSV ioctl,wuguirong 节点无 TEE 设备,且项目铁律禁止编排层;进 k8s 的只是台账 ConfigMap。</li>
<li>TEE 证明<strong>未上链</strong>、未绑定链上状态位;链上撤销状态位读取后端<strong>未接入</strong>(声明 chain 即 fail-closed 拒);OPA <strong>不在 guest 内</strong>;decision 未签名未上链;OPA bundle 的 guest 分发未做。</li>
<li>OP-TEE <strong>QEMU 实跑已做</strong>(2026-11-09,<code>docs/OPTEE_VERIF_PLAN.md</code> 有完整证据表):全流程 selftest、第 5 条跨设备解封被拒、第 4 条跨重启 unseal 成功三条<strong>都真跑通了</strong>。但那是 <strong>QEMU 模拟</strong>(<code>dna</code> = 编译期 sha256 种子,HUK = 模拟值)⇒ <strong>不是</strong>真板的设备绑定证据,<strong>不能</strong>替代真板一次性验收;<code>CryptoPrecompiled.sm2Verify</code> 真机对拍未做;<code>tools/fisco-realnode-probe.py</code> 的 4 处 <code>IMPL_GAPS</code> 未销账。</li>
<li>本租户 SA 无 <code>create secret</code> 权限;链客户端私钥 <code>MPC_FISCO_KEY</code> 保持仓库外,不进镜像 / ConfigMap / git。</li>
<li>站点端控制面是 [设计] 决策角色,不是已实现的独立服务;别把 §2 的职责矩阵当成已部署清单。</li>
<li><strong>集群控制面只在假 hostd / 不可达节点上验过框架契约</strong>:<code>mpc control-plane</code>
的「收自报 → 注册表 → 期望态 → 选址 → 下发 → 证明门控 → 公布端点」闭环
在真 socket 门禁里全绿,但节点是本机假 hostd(证明结论可控)或不可达节点;
真机多节点自报、跨网段暴露、真 KBS 验签后的会话端点交付<strong>未做</strong>。
别把 §1.6 当成已部署的集群清单。</li>
</ul>
<p>逐条对照与旧结论见 <a href="INDEX.md">INDEX.md</a> §4 / §5。</p>
<hr />
<h2 id="sec-18">9. 阅读路线与文档分工</h2>
<pre><code class="language-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
</code></pre>
<p><strong>更新纪律</strong>:本文是 A 类活文档,事实变了就改;但不得复制判据逻辑、不得写死门禁条数
(只认 <code>tools/ci.sh</code>)、不得把 [设计] 悄悄改成 [实证]。新增架构结论先改本文,
历史文档的正文按 <a href="INDEX.md">INDEX.md</a> §6 只加锚点、不改写。</p>
<p><strong>可分享版本</strong>:<code>docs/ARCHITECTURE_SYSTEM.html</code> 由 <code>tools/render-share-html.py</code>
从本文生成,是<strong>派生产物,勿手改</strong>;改架构请改本 md 后重新生成。</p>
</article>
<footer>ssw-mpc · 文档总入口 <code>docs/INDEX.md</code> · 本页自包含,可离线查看与分享</footer>
</main>
</div>
</body>
</html>