- reconciler:可注入时钟 + 唯一判定 pending_timed_out(saturating_sub 防回拨);超时真调 destroy、释放容量、/report 留带原因失败、本轮不重建(下轮按期望态重试) - 修真 bug:PendingSession.created_at 曾写 now_secs(),与判定时钟分叉 ⇒ 超时永不触发,单测直接抓到 - ControlPlaneConfig / CLI:--pending-timeout SECS(0=显式禁用),默认值只有 DEFAULT_PENDING_TIMEOUT_SECS 一份常量;help 数字由守卫测试对拍 - 新增 8 个构造用例 + 跨文件判据自测 16 条 / 破坏实验 15 条,并入主门禁第 25 条(分母仍 25) - 文档:ARCH §1.6/§8、FINDINGS §12、README/INDEX/CLAUDE/真机 README/env 样例/MEMORY 同步;HTML 重新生成并校验 - 诚实边界:未做真机验证、真机 musl 产物未更新、超时后下一轮重试不是永久隔离
233 lines
22 KiB
Markdown
233 lines
22 KiB
Markdown
# 文档索引与当前状态(总入口)
|
||
|
||
> **本文是 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`;负向逐条破坏过 |
|
||
| ★ 集群端点公布门禁 | [实证] 双节点自报 → 非回环暴露(共享密钥 + `--allow-remote`)→ 真 KBS 芯片验签 → 9p 手牌回传证明包 → hostd 独立判定 → `proven_endpoints()` → `GET /sessions`;判据 `CLUSTER_ENDPOINT_GATE_OK` 20/0,负向零外泄 + 带原因、收尾端点收回 | `deploy/tee/real-machine/cluster-endpoint-gate-e2e.sh`、`REAL_MACHINE_FINDINGS.md` 第 11 节;主门禁第 25 条含端点判据自测 25 项 + 破坏实验 14 项 |
|
||
| ★ pending 超时回收 | [离线实证] 证明迟迟不落 ⇒ 真回收实例、释放容量、`/report` 留带原因失败;默认 900 秒可配(`0` = 禁用),判定只有一份且防时钟回拨。**未做真机验证** | `crates/mpc-tee/src/reconciler.rs`、`REAL_MACHINE_FINDINGS.md` 第 12 节;`cargo test` 8 个构造用例 + 主门禁第 25 条跨文件判据 16 项 / 破坏实验 15 项 |
|
||
| 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 条;零依赖 `--self-test` 每次必跑,真链批缺环境显式 `FISCO_REALNODE_SKIPPED`) |
|
||
| 主门禁 | [实证] **25 条**(`tools/ci.sh` 的 `step "N/25"` 是唯一计数) | `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` |
|
||
| ★ SA 扩展模式 | [实证] **板端 SA 服务端 ↔ OrbStack 外挂 VM 端到端跑通**,判据 26/26;seal/unseal/attest/sign + 会话物料全部可用;**VM 侧拿不到 `K_root`**(site 名骗不出、协议无导出端点、VM 侧无根密钥文件) | `docs/SA_EXTENDED_MODE.md`、`deploy/arm/zynq7015/sa-pair-e2e.sh` |
|
||
| ★ 零种子守卫 | [实证] CLI 入口(连网前)+ `Vault::new` 双层拒绝全零主种子;判据 18 条;破坏实验证明非恒绿 | `tools/selftest-seed-guard.py`(主门禁第 24 条) |
|
||
| ★ 集群自报判据链 | [实证] **离线自测 11 项 + 破坏实验 13 项全绿**,每条判据都被构造样例逐条破坏过;不依赖真机 / xop 保险库。**真机只读链路已复验** `remote()` 返回值纯度(xop WARN 与 ssh 客户端 Warning 都不进返回值、临时文件无残留),但脚本**完整 e2e 尚未复跑** | `tools/selftest-cluster-selfreport.py`(主门禁第 25 条) |
|
||
|
||
---
|
||
|
||
## 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 推算表当实测 |
|
||
| ★ 看 SA 扩展模式(安全锚点供能力、算力挂 VM) | `docs/SA_EXTENDED_MODE.md`(形态 / 信任模型 / 协议 / 诚实边界 / PCIe 演进路径) | 把 `platform=none` 当成硬件隔离已成立;以为主种子是秘密 |
|
||
| 复现 SA 真机端到端 | `deploy/arm/zynq7015/sa-pair-e2e.sh`(`--prepare-with-fwd` 后跑判据) | 逐条手敲 orbctl;忘了跨网段要 socat 转发 |
|
||
|
||
**端点速查**:集群内 `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` | **系统架构当前形态**:组件清单 / 双层控制面 / 会话主键 / 端到端数据流 / 部署拓扑 / 平台矩阵(**含 SA 扩展模式 §1.7,第四种形态**)/ 诚实边界;拆解自 `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` | 主门禁(25 条)唯一实现 |
|
||
| `tools/selftest-fisco-contract.py` | 真链验收唯一权威脚本(★ **独立于主门禁**:它要连真链,故不在 `ci.sh` 里) |
|
||
| `tools/selftest-sa.py` / `tools/selftest-seed-guard.py` | SA 契约(52 条)/ 零种子守卫(18 条)—— 主门禁第 23 / 24 条 |
|
||
| `tools/selftest-pending-timeout.py` / `-break.py` | pending 超时回收**跨文件接线**判据(16 条)/ 破坏实验(15 条)—— 主门禁第 25 条;逻辑本身由第 1 条 `cargo test` 真跑 |
|
||
|
||
### 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/SA_EXTENDED_MODE.md`(**SA 扩展模式:板端供能力、算力挂 VM;2026-11-09 真机端到端跑通**)、
|
||
`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 条」 | **25 条** | `tools/ci.sh` |
|
||
| 「`selftest-fisco-contract.py` 不在主门禁里」 | ★ **已回到主门禁第 22 条**(`27cbdc7` 误删过,现已恢复) | `tools/ci.sh`、`tools/fisco-realnode/README.md` |
|
||
| 「`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/25 ..."` 是唯一计数;文档写死的
|
||
数字必须同步,改完用 python 扫全仓 `*.md` 复核(macOS 的 grep 对中文匹配不稳)。
|
||
★ 另:**判据脚本在仓库里 ≠ 判据在门禁里** —— 提交 `27cbdc7` 曾删掉
|
||
`tools/ci.sh` 里 5 个 step(第 18–22 条),脚本都还在,只是不再被调用 ⇒
|
||
门禁**静默削弱**(文件在、判据在、门禁不跑)。改完 `ci.sh` 必须核对:
|
||
① `tools/ci.sh` 里的 step 条数与文档条数一致(★ 数 step 时注意**注释里
|
||
出现 step 字面样例会被一起数进去** ⇒ 计数永远多 1,2026-11-09 实测踩过);
|
||
② 逐条确认被调用的脚本**真的存在**;
|
||
③ 头部注释编号与 step 号一一对应。
|
||
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` 跑全量 25 条。确认没有把活文档改坏。
|
||
9. **★ 帮助文本 / 文档里的参数必须与实现对齐**:2026-11-09 实测踩过两次 ——
|
||
改 `mpc tee` 帮助文本时漏掉了 `attest-upload` 的 `--upload-path-file`
|
||
(实现里**必填**),以及 SA 客户端的 `--plaintext-hex` / `--blob-hex` /
|
||
`--user-data-hex` / `--message-hex` / `--session-id` 全都没写进帮助。
|
||
这类漂移**静默**:代码照样编译、门禁照样全绿,只有用户照着帮助敲命令才失败。
|
||
已加守卫测试 `tee_usage_flags_are_all_implemented`(正向:帮助里每个 flag
|
||
必须有对应解析调用)+ `sa_required_flags_appear_in_usage`(反向:实现里
|
||
必填的参数必须在帮助里),两条都做过破坏实验(自指型假绿也修掉了)。
|
||
10. **架构结论只改 `docs/ARCHITECTURE_SYSTEM.md`**:新增 / 变更组件、边界、端点先改它,
|
||
再跑 `python3 tools/render-share-html.py`(重新生成 `.html`)与 `--check`(校验同步)。
|
||
HTML 是**派生产物不许手改**;历史决策文档正文不因架构变更而改写。
|
||
文档里写「部署了什么」必须区分 [实证] / [桩验] / [设计] / [禁用],不许把蓝图写成现状。
|
||
11. **真机参数只认 `deploy/tee/real-machine/real-machines.env.example`**:换机器 / 换网段
|
||
改这一份,不要逐个脚本 export;重跑前先 `preflight-real-machine.sh`(`--self-test`
|
||
用构造样例钉死参数判据非恒绿)。`/tmp` 的 60+ 个探索脚本是过程产物,结论已
|
||
沉淀进验签器与 `REAL_MACHINE_FINDINGS.md`,**不许整批入库或重跑确认**。
|
||
12. **两台真机 `/opt` 物料只认 `nodes/host-materials.sha256` 基线**:远端 `/tmp` 是运行时
|
||
目录(每次 e2e 重铺,丢了不用管),`/opt` 的 qemu / 固件 / 内核 / 海光官方验签器 /
|
||
GmSSL / CSV 证书链才是不可再生的。重启后先 `--verify`(缺文件 / 被替换 / 被升级
|
||
一律 FAIL 并打印 diff),换机或物料升级后 `--collect` 重采并提交。
|
||
**清单本身由 git 保护**,不许在仓库外偷改;也不许把 69MB/78MB 二进制搬进仓库。
|
||
新增判据必须能用构造样例推翻(`--self-test` 6 条 + 端到端篡改 hash 判红)。
|
||
13. **TA 签名密钥分级只有一份实现**:`build/ta-key-tier.sh` 是唯一真相源,
|
||
`build_optee.sh` 与 `build_optee_zynq7k.sh` 都 source 它;
|
||
`tools/selftest-ta-key-tier.py` 反向守卫「入口里不许有第二份拷贝」。
|
||
改密钥规则必须改共享文件并重跑该自检,别在某个入口里私改一份。
|