Files
ssw-mpc/docs/INDEX.md
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

207 lines
17 KiB
Markdown
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.
# 文档索引与当前状态(总入口)
> **本文是 ssw-mpc 文档体系的总索引与当前状态快照(2026-11-08)。**
> 存在的理由:同一件事散在多份文档里,其中不少写的是**当时**的阶段结论
> (「主门禁 18 条」「不宣称能上链」「合约部署未做」),不标注就会被当成现状。
>
> 两条纪律:**① 判定口径只有一份实现**(代码 / 判据脚本),文档只写事实与指针,
> 不复制判据逻辑;**② 历史阶段文档不改写历史**,只加「当时状态 → 当前状态」的锚点。
---
## 0. 三类文档,别混着读
| 类别 | 含义 | 更新纪律 | 代表 |
|---|---|---|---|
| **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 节 |
> 判断口径:文档里出现「本轮 / 本期 / 阶段状态 / 主门禁共 N 条 / 未落地 /
> 不宣称」而没有日期锚点的,一律先按 C 类处理,再去 A 类核对。
---
## 1. 当前状态总览(2026-11-08)
| 领域 | 状态 | 权威入口 / 硬证据 |
|---|---|---|
| 算子与协议基线 | [实证] 零依赖 `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` |
| ARM 边缘板(Zynq-7015) | [实证] `mpc` 二进制上板:selftest 5/5、两进程会话 `35.000000`、sha256 与本机一致;selftest 单次 **≈4 ms**、峰值 RSS 3.5 MB | `docs/ZYNQ.md` §4 |
| ★ Zynq 真板 OP-TEE | [设计] 产物已能交叉编译;**板端未部署**——当前内核 `CONFIG_TEE is not set`、`BOOT.BIN` 无 EL3 承载 ⇒ 须换启动链 | `docs/ZYNQ.md` §4.3、`build/build_optee_zynq7k.sh` |
---
## 2. 权威入口:一件事只认一个地方
| 想干什么 | 去哪 | 别去哪 |
|---|---|---|
| 看当前能力 / 项目门面 | `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` | 任何文档里写的数字 |
| 查链端点 / 链配置 | `tools/fisco-realnode/example.chain.json` + `deploy/k8s/fisco/README.md` | `127.0.0.1:20200`(旧本机容器,已停) |
| 复现真机证明门控 | `deploy/tee/real-machine/README.md`(开头「重跑前先看」) | `docs/REAL_MACHINE_FINDINGS.md` 第 7/9 节的「当时边界」 |
| 重跑真机双机 e2e:配置 / 预检 / 症状速查 | `deploy/tee/real-machine/real-machines.env.example` + `preflight-real-machine.sh` + 该 README 速查表 | 逐个脚本 export 参数;去 `/tmp` 翻 60+ 个探索脚本 |
| 核对两台真机 `/opt` 物料是否被换 / 丢失 | `deploy/tee/real-machine/host-materials.sh --verify` + `nodes/host-materials.sha256` | 只看预检「qemu/固件/内核存在」(不比 sha256);把 69MB qemu 拷进仓库 |
| 部署 / 回滚链节点 | `deploy/k8s/fisco/`(含 `migrate-ledger.sh`、`README.md`) | 手动 `docker start fisco-gm`(会与 k8s 链分叉) |
| 看真链实证期的审计轨迹 | `tools/fisco-realnode/README.md` | `/tmp`(会被清) |
| 查两台真机硬事实 / 踩坑 | `docs/REAL_MACHINE_FINDINGS.md`(第 10 节最新) | 记忆或口头结论 |
| 查决策依据(为什么这么设计) | `docs/INTEGRATION_ANALYSIS.md` 决策台账 + `ARCHITECTURE.md` | 把它当进度表 |
| 上 ARM 边缘板 / 真板 OP-TEE | `docs/ZYNQ.md`(板端实证 + 启动链缺口)+ `build/build_optee_zynq7k.sh` | 以为「装个 OP-TEE 包就行」;拿 §1 推算表当实测 |
**端点速查**:集群内 `fisco-chain.wuguirong.svc.cluster.local:20200`;
集群外 `192.168.1.26|27|29:30100`(RPC)/ `30101`(P2P);
站点 `192.168.1.26|27|29:30082`。
---
## 3. 文档清单(按定位分组)
### A 活状态 / 真相源
| 文档 | 定位 |
|---|---|
| `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 条)唯一实现 |
| `tools/selftest-fisco-contract.py` | 真链验收唯一权威脚本(第 22 条) |
### B 专题设计(结论稳定,不含进度)
`docs/ARCHITECTURE.md`(分层 / Ray / TEE 定位)、`docs/IR.md`(轮数规划)、
`docs/N_PARTY.md`(n 方能力矩阵)、`docs/COMPARE_SECRETFLOW.md`(与隐语对照)、
`docs/OPT_PLAN.md`、`docs/ZYNQ.md`(**ARM 边缘板:2026-11-09 已上板实测 + 真板 OP-TEE 启动链缺口**)、`docs/PG.md`,
`docs/TEE_DIRECT_LAUNCH.md`(AMD/海光直接调度,已加 11-08 状态核对)、
`docs/TEE_OCI_PATH.md`、`docs/OPTEE_VERIF_PLAN.md`(**QEMU 实跑已做:selftest + 第 5 条跨设备 + 第 4 条跨重启**),
`docs/RAY_CORE.md` / `RAY_CORE_101.md` / `RAY_ARMV7.md`。
### C 历史阶段快照(先看文首状态提示)
| 文档 | 当时状态 | 现在读法 |
|---|---|---|
| `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 形态」边界继续成立 |
### D 部署与复现
`deploy/k8s/fisco/README.md`(链迁移 SOP / 账本 / 回滚 / 边界)、
`deploy/arm/zynq7015/README.md`(**ARM 边缘板**:板端速查 / `board-selftest.sh` 判据 /
板端三条硬坑 / 真板 OP-TEE 缺口 / 上板产物 sha256)、
`deploy/tee/real-machine/README.md`(真机 e2e;**开头有重跑三步、参数真相源与症状速查表**)、
`deploy/tee/real-machine/real-machines.env.example`(**双机参数唯一集中入口**,脱敏、可 source)、
`deploy/tee/real-machine/preflight-real-machine.sh`(重跑前环境预检,`--self-test` 负向矩阵;
含本机重建条件检查)、
`deploy/tee/real-machine/host-materials.sh` + `nodes/host-materials.sha256`
(**两台真机 `/opt` 不可再生物料的入仓基线**:采集 / 核对 / 判据自测;
`--verify` 比 sha256,`--self-test` 用 6 个构造样例证明非恒绿)、
`deploy/tee/real-machine/nodes/*.node.example` + `fixtures/`(真机路径与真实报告 / 证书链样本)、
`deploy/tee/README.md`、
`deploy/tee/oci/README.md`、`deploy/ray/README.md`、
`demo/README.md`、`demo/k8s/README.md`(站点 + PVC)、
`tools/fisco-realnode/README.md`(复现工具与审计轨迹)、
`examples/12_k8s_two_party/README.md`。
### 非文档(不参与索引)
`.workbuddy/memory/*.md` 是**工作日志**(追加式,只记有跨会话价值的事实);
`.tmp-fisco/` 是临时解包目录;`refs/nax/` 是独立只读参考仓库。
---
## 4. 容易读错的旧结论(对照表)
| 旧文档写过的 | 当前事实 | 权威入口 |
|---|---|---|
| 「主门禁共 18 条 / 20 条」 | **22 条** | `tools/ci.sh` |
| 「`flush` 只发规范字节,不是已签名交易」 | `flush --mode signed-tx` 发**完整已签名 FISCO 交易**(TARS + 128B 签名),且走 `Outbox::flush_with` 状态机 | `crates/mpc-cli/src/chain.rs`、`fisco_tx.rs` |
| 「不宣称能上链」「合约部署未做」 | 真链部署 / 调用 / 读回已实证,22/22 全绿 | `selftest-fisco-contract.py` |
| 「签名 = 32B `dataHash` 上直接 SM2,不再二次 SM3」 | `e = SM3(ZA‖dataHash)`,ZA 用 distid 与曲线参数算;`a=p-3` 末字节 `fc` 不许手抄 | `FISCO_UPSTREAM_TRUTH.md` §3.1 |
| 「3.x 是 `eth_` 兼容端点」 | `eth_call` / `eth_getTransactionReceipt` 实测 method-not-found;用自有 `call` / `getTransactionReceipt`(4 参) | 同上、`catalog.rs` 守卫测试 |
| 链在 `127.0.0.1:20200` / 本机 `fisco-gm` | 已迁 k8s `30100`,账本 PVC;本机容器只 stop 未删、**别同时对外服务** | `deploy/k8s/fisco/README.md` |
| 「CSV 的 KBS 链路仍待落地」「证明与会话尚未合流」 | 第 10 节已合流跑通(`key_source=kbs`) | `REAL_MACHINE_FINDINGS.md` 第 10 节 |
| 「站点在 cube 沙箱 / 虚拟机里」 | 站点一直在 k8s(30082);链原是**本机 macOS Docker 容器**,不是虚机 | 本文 §1、`demo/k8s/README.md` |
---
## 5. 诚实边界(仍然不宣称,不许借更新冲掉)
- 软件 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 未签名未上链。
- OP-TEE **QEMU 实跑已做**(2026-11-09,见 `docs/OPTEE_VERIF_PLAN.md`):
全流程 selftest、第 5 条跨设备解封被拒、第 4 条跨重启 unseal 成功三条**都真跑通了**。
但那是 **QEMU 模拟**:`dna` 是编译期 sha256 种子、HUK 是模拟值 ⇒
**不能**当成真板的设备绑定证据,**不能**替代真板一次性验收。
`CryptoPrecompiled.sm2Verify` 真机对拍未做;
`tools/fisco-realnode-probe.py` 的 4 处 `IMPL_GAPS` 未销账。
- ★ **Zynq-7015 真板 OP-TEE 未部署**:产物能交叉编译(`build/build_optee_zynq7k.sh`),
但板子当前内核 `CONFIG_TEE is not set`、`BOOT.BIN` 里**没有 EL3 承载**
(U-Boot 2018.01 直接 `bootz` 进内核)⇒ 必须换启动链;
板子上跑着 `board-agent` / `easytier-core`(m4gw) 等在役服务,
且**没有第二台板子**可试 ⇒ 部署前必须先做带哈希基线的完整备份 + 回滚路径。
本轮**未改动板子任何文件**。
- 本租户 SA 无 `create secret` 权限;链客户端私钥 `MPC_FISCO_KEY` 保持仓库外,
不进镜像 / ConfigMap / git。
---
## 6. 更新纪律(下次改文档照这个走)
1. **门禁条数只认 `tools/ci.sh`**:脚本里 `step "N/22 ..."` 是唯一计数;文档写死的
数字必须同步,改完 `grep -rnE "18 条|20 条|十八条" --include=*.md .` 复核。
2. **链端点只认两处**:`tools/fisco-realnode/example.chain.json`(客户端)与
`deploy/k8s/fisco/README.md`(集群);旧 `127.0.0.1:20200` 只能作为历史叙述出现。
3. **上游事实只认 `FISCO_UPSTREAM_TRUTH.md`**:任何「签名口径 / 编码 / 回执字段」
的新结论先在这份文档核对,再改代码与判据;`catalog.rs` 每条 API 签名必须真存在。
4. **判定只有一份实现**:生成端自检 == 审计端判定;文档不得复述判据逻辑当作第二真相源。
5. **历史文档只加锚点**:写「(YYYY-MM-DD 当时)」+ 文首「当时 → 当前」对照表,
**不要把历史改写成就没发生过**,也不要为了好看删掉当时的诚实边界。
6. **每条负向判据都要用构造样例破坏过**,否则恒绿;文档里「已验证」必须有对应脚本与判据名。
7. **新增文档必须回本文登记**(§3 分组),并在 `CLAUDE.md` 文档章节留指针;
部署类脚本 / 证据不得只留在 `/tmp`。
8. 改完做校验:**纯文档改动**至少跑 `python3 tools/selftest-fisco-contract.py --self-test`
+ `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 是**派生产物不许手改**;历史决策文档正文不因架构变更而改写。
文档里写「部署了什么」必须区分 [实证] / [桩验] / [设计] / [禁用],不许把蓝图写成现状。
10. **真机参数只认 `deploy/tee/real-machine/real-machines.env.example`**:换机器 / 换网段
改这一份,不要逐个脚本 export;重跑前先 `preflight-real-machine.sh`(`--self-test`
用构造样例钉死参数判据非恒绿)。`/tmp` 的 60+ 个探索脚本是过程产物,结论已
沉淀进验签器与 `REAL_MACHINE_FINDINGS.md`,**不许整批入库或重跑确认**。
11. **两台真机 `/opt` 物料只认 `nodes/host-materials.sha256` 基线**:远端 `/tmp` 是运行时
目录(每次 e2e 重铺,丢了不用管),`/opt` 的 qemu / 固件 / 内核 / 海光官方验签器 /
GmSSL / CSV 证书链才是不可再生的。重启后先 `--verify`(缺文件 / 被替换 / 被升级
一律 FAIL 并打印 diff),换机或物料升级后 `--collect` 重采并提交。
**清单本身由 git 保护**,不许在仓库外偷改;也不许把 69MB/78MB 二进制搬进仓库。
新增判据必须能用构造样例推翻(`--self-test` 6 条 + 端到端篡改 hash 判红)。
12. **TA 签名密钥分级只有一份实现**:`build/ta-key-tier.sh` 是唯一真相源,
`build_optee.sh` 与 `build_optee_zynq7k.sh` 都 source 它;
`tools/selftest-ta-key-tier.py` 反向守卫「入口里不许有第二份拷贝」。
改密钥规则必须改共享文件并重跑该自检,别在某个入口里私改一份。