Files
ssw-mpc/docs/INDEX.md
T
admin 660e5712c3 feat(tee): 真机双机实跑复验,固化 /opt 物料基线与本机重建条件
用户要求「跑一遍,确保本地资源能用,别两台机器重启就找不到了」。
按固化的三步重跑(env 样例 → 预检 → e2e)在两台真机上实跑:

- 正向 e2e 全绿:从源码重编 musl mpc → 重新导出 alpine rootfs → 重新打
  initrd → 分发 → 双 KBS → 双 guest,TEE_PAIR_OK + TEE_ATTEST_GATE_OK
  + TEE_PAIR_ATTEST_OK,两侧还原 35.000000(2m05s)。
- 负向矩阵全绿:篡改度量 pin ⇒ 403 拒证明、guest fail-closed 拿不到密钥;
  恢复 pin ⇒ 又拿到(TEE_ATTEST_NEGATIVE_OK,exit=0)。
  ★ 修掉旧版单独跑报「缺少 MPC_TEE_MANIFEST」:负向脚本现在自动从
    ${MPC_TEE_WORK}/image 用同一份 oci-image.py verify 重算并断言 64 hex,
    不手抄;两个构造样例验证非法值 / 无产物都 exit=2。

持久化保障(回答「重启就找不到」):
- 实测两台真机 / 是 ext4 / xfs 持久根盘、无独立 /tmp tmpfs;远端三个
  /tmp 运行时目录本来全为空,e2e 每次重铺 ⇒ 丢了不影响重跑。
- 新增 host-materials.sh + nodes/host-materials.sha256(入仓基线 18 条:
  AMD 3 / 海光 15,sha256 + size):--verify 逐台比对,缺文件/被替换/
  被升级一律 FAIL 并打印 diff;--self-test 6 个构造样例证明非恒绿;
  另用「篡改清单一条 hash」端到端破坏验证(精确判红 exit=1)。
  ★ 清单只记路径/大小/哈希,不搬 69MB qemu / 78MB initrd 进仓库;
  清单本身由 git 保护。换机/升级后 --collect 重采。
- 预检新增「本机重建条件」检查:alpine:3.18 镜像、musl target、
  oci-image.py、guest/init.sh、fixtures、物料基线;缺一项即 FAIL。
  完整预检 29/0(含远端),离线 25/0 SKIP=1,自测 7/0,
  lint-shell-vars 34 脚本无隐患。

文档:真机 README 增「机器重启 / 换机后怎么办」分工表与症状速查一条;
INDEX §2/§3/§6 登记新资产与第 11 条纪律;CLAUDE.md 部署段加指针;
env 样例 H 段写明 manifest 两处都不许手抄。
校验:ci.sh 语法、判据零依赖自测 22/0、diff --check、密钥扫描全过。
门禁条数仍为 22(未改 ci.sh)。
2026-11-08 20:01:22 +08:00

15 KiB
Raw Blame History

文档索引与当前状态(总入口)

本文是 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

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 把它当进度表

端点速查:集群内 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、docs/PG.md、 docs/TEE_DIRECT_LAUNCH.md(AMD/海光直接调度,已加 11-08 状态核对)、 docs/TEE_OCI_PATH.md、docs/OPTEE_VERIF_PLAN.md(QEMU 实跑仍待 SDK)、 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/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 实跑未做(缺 SDK);CryptoPrecompiled.sm2Verify 真机对拍未做; tools/fisco-realnode-probe.py 的 4 处 IMPL_GAPS 未销账。
  • 本租户 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 判红)。