Files
ssw-mpc/docs/ARCHITECTURE_SYSTEM.html
T
admin c51190b20c docs: 拆解决策文档形成系统架构文档,附可分享 HTML
- 新增 docs/ARCHITECTURE_SYSTEM.md(活真相源):组件清单、双层控制面、
  会话主键、端到端数据流、部署拓扑、平台矩阵、判定治理、诚实边界。
  用 [实证]/[桩验]/[设计]/[禁用] 区分实证与蓝图 —— `mpc site` 等
  决策角色不再被写成已部署服务,避免照着文档敲不存在的命令。
- 新增 tools/render-share-html.py 与 docs/ARCHITECTURE_SYSTEM.html:
  自包含单文件分享页,md 是唯一真相源、HTML 是派生产物勿手改;
  --check 校验两者同步,生成幂等无 diff 噪音。
- INTEGRATION_ANALYSIS.md 文首加「架构结论已抽出」指针,正文决策取证链
  保持不变;INDEX.md(§0/§2/§3/§6)、CLAUDE.md、README.md 登记新文档
  与第 9 条更新纪律。与原 ARCHITECTURE.md(计算分层)明确分工。
- 校验:HTML 与 md 同步、ci.sh 语法、判据自测 22/22、diff 空白、
  23 个引用路径与密钥扫描全过;纯文档改动未跑全量门禁。
2026-11-08 19:29:18 +08:00

674 lines
32 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="lv2" href="#sec-9">2. 双层控制面与信任边界</a>
<a class="lv2" href="#sec-10">3. 会话是唯一主键</a>
<a class="lv2" href="#sec-11">4. 端到端数据流(真机实证链路)</a>
<a class="lv2" href="#sec-12">5. 部署拓扑与端点(当前物理落点)</a>
<a class="lv3" href="#sec-13">持久化边界</a>
<a class="lv2" href="#sec-14">6. 平台形态矩阵(不是同一套形态)</a>
<a class="lv2" href="#sec-15">7. 判定、门禁与治理分域</a>
<a class="lv2" href="#sec-16">8. 诚实边界(仍然不宣称,不许借更新冲掉)</a>
<a class="lv2" href="#sec-17">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-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></td>
<td>[实证] 零 crates.io 依赖,两个平台真机跑通</td>
</tr>
<tr>
<td><code>mpc-hostd</code></td>
<td><code>crates/mpc-hostd/</code></td>
<td>e2b 兼容 API + <code>/attestation</code>;<code>runtime.rs</code> 起 qemu + reaper;<code>api.rs</code> 四布尔 <code>AttestationVerdict</code></td>
<td>[实证] 真机运行</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>
<hr />
<h2 id="sec-9">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-10">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-11">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-12">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-13">持久化边界</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-14">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-15">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-16">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>(缺 SDK);<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>
</ul>
<p>逐条对照与旧结论见 <a href="INDEX.md">INDEX.md</a> §4 / §5。</p>
<hr />
<h2 id="sec-17">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>