从 CBOM 到回滚按钮：PQC 迁移的 6 块工程拼图

副标题：工具链是把“接标准”能力长出来的载体

§1 引子：迁移做完了，工具链没跟上

前两篇分别谈了“为什么现在就要动”（标准真空期）和“混合 HTTPS 落地撞了什么墙”（5 个工程问题）。这一篇回到一个更基础的问题：做迁移，到底要先把哪些工具、流水线、平台搭好。

这不是一个新问题，但 2026 年变得尤其尖锐。

按 NGCC 的征集与评审节奏推算，国密 PQC 标准预期在 2027 年底到 2028 年初发布。在这之前的 12~18 个月里，几乎每个工程团队都会撞到同一组症状：

• 升级公告发下去了，但没人能回答“现在还有哪些地方在用 SM2”
• 某个 PR 提交了 crypto.createCipher('des')，过了 code review 才被发现
• 算法升级上线一周，监控拿不出“今天握手里有多少走的是混合 PQ 路径”
• 迁移结束后想做端到端的密钥轮换，发现 KMS 不支持 PQC 算法
• 算法候选被淘汰时，发现它已经写死在 5 个服务的配置里，拔不掉

这些症状的共同根因只有一个：迁移被当作季度项目做完，没有把工具链当作产品投资。

这一篇按“工具链”维度拆开看。从我自己的工程实践里，能稳定复用的有 6 块拼图：算法元数据注册表、CBOM、CI 策略门禁、KAT 自测、可观测性面板、KMS/HSM/TPM 适配。6 块之外还有一个贯穿能力：应急回滚。

每块拼图都不是单一工具，而是“做这件事的最小可执行动作 + 一组可复用的反模式”。

§2 第一块拼图：算法元数据注册表

为什么：第一篇提了“密码敏捷性”。既然标准未定、候选会洗牌，工程上唯一确定能投资的，就是让系统能在不推翻业务代码的前提下平滑切换算法。而敏捷性的最小前提，是每个算法都能被查询：它是什么、它现在在哪个标准号下、它的经典与量子安全强度是多少、它处于什么迁移优先级。

没有这一步，后面 5 块拼图都失去坐标系：CI 门禁不知道该 fail 哪个算法，CBOM 不知道该标哪个字段，可观测性不知道该分几个桶。

怎么做：建一个独立的算法元数据模块（独立 npm 包、独立 git 仓库、独立服务都行，关键是能被多个上下游引用），按统一 schema 描述每个算法：

字段最少 6 个：类型、经典安全强度、量子安全强度、标准号、迁移优先级、状态。replacement 是预留字段，等 NGCC 第一轮候选公布后再填。

踩坑：注册表不要嵌进业务代码库。一是标准在变、字段在变，嵌进去会让业务跟着抖；二是多个仓库需要共享同一份事实源，跨仓 import 的成本比独立包高一个数量级。

fibemate 的做法：算法注册表是 fibemate packages/algorithm-registry/ 模块的内容，本文不复述字段细节，仅作“可复用的元数据 schema”的实例参考。具体结构以你团队的技术栈为准。

教训：把“量子安全强度”显式化，是密码敏捷性的最小可执行动作。不做的代价，是每次算法洗牌都要重新盘点代码，而盘点本身就是迁移里最贵的部分。

§3 第二块拼图：CBOM

为什么：CBOM（Cryptographic Bill of Materials）是密码学界的 SBOM，把散落在代码、证书、依赖、配置里的算法统一成一份清单。盘资产是迁移的第一步（第一篇 §6 的“治理节奏”第一节），没有 CBOM，后面所有动作都建立在猜测上。

怎么做：CBOM 不是一次生成的快照，而是 CI 流水线里的 diff 检查。具体三层：

• 代码层：grep/regex 抓 crypto.createCipher、sm2、RSA、ECDSA 等关键字，标注文件 + 行号
• 依赖层：npm audit / cargo audit / OSV API / Dependabot，标注包名 + 版本 + 已知漏洞
• 证书层：解析服务器实际加载的证书链，标注签名算法 + 公钥算法 + 有效期

产出格式走 CycloneDX 1.5+（已有 crypto 扩展字段）或 SPDX 3.0。CBOM 不需要自己写解析器，CycloneDX CLI、cdxgen、cryptobom-fabricator 这类工具链已经成熟。

踩坑：

• 不要把 CBOM 当一次性审计。算法在升级、依赖在引入、证书在轮换，CBOM 必须每次 PR 跑一次，diff 超过阈值就 fail
• 不要漏掉二进制依赖。很多团队的密码学藏在 Docker 镜像的 node_modules 里，源码 grep 抓不到
• 不要只看签名算法。同一个 ECDSA-P256 证书可能在不同节点、不同协议层（TLS / S/MIME / 代码签名）出现，盘点必须按“用法”而不是“算法”分类

fibemate 的做法：fibemate 用 tools/cbom-diff.js 做 CI 集成（PR 阶段自动 diff CBOM 变化），用 CycloneDX 1.5 + 自定义 crypto 扩展字段（量子安全强度、迁移优先级直接关联算法注册表）。本文不复述工具调用方式，以你团队的目标工具链为准。

教训：CBOM 的核心价值不是“它存在”，而是“它会 diff”。一份静态 CBOM 文档，不如一条能在 PR 里 fail 的 CBOM diff 流水线。

§4 第三块拼图：CI 策略门禁

为什么：靠人记得“别用 SM2 / 别用 RSA-1024”是不可靠的。Code review 漏看是常态，特别是新员工、跨团队 PR、依赖升级，而这些恰恰是引入量子脆弱算法的高发场景。靠人记，迟早翻车。靠流水线强制，才有可能稳定。

怎么做：CI 门禁分四档，从软到硬：

Lint 规则示例：

• no-js-bigint-in-hotpath：禁止 BigInt 进入密码学热路径（侧信道风险）
• no-md5 / no-sha1 / no-rc4：硬禁用已知弱算法
• no-createCipher：强制走 createCipheriv

CBOM diff 门禁示例：算法注册表中 status: "deprecated-by-pqc" 且被新 PR 引入 = warning；status: "forbidden" = fail。

踩坑：

• 门禁太严会卡正常 PR。比如 no-createCipher 一刀切，会让所有 cipher = crypto.createCipher('aes-256-cbc', key) 这种“旧但还能用”的代码全部 fail，但业务侧没人力立刻改完。要分级：先 warning 跑半年，等存量清得差不多再升级到 fail
• 门禁要可绕过。合规或特殊业务确实需要用某个禁用算法时，PR 里加 # cryptography-waiver: <理由> 注解 + 责任人 approve 才能合，这是工业实践（GitHub 自身在 Dependabot 里就是这么做的）
• 门禁必须可观测。fail 了多少次、哪种 fail 最常见，需要面板；否则半年后没人记得为啥有这个规则

fibemate 的做法：fibemate 用 ESLint + 自定义规则 + --max-warnings 0 强制（CI 红就 fail），配套 no-js-bigint-in-hotpath 规则覆盖 PQC 热路径；同时跑 CodeQL 周扫 + Dependabot 周更。这是 6 块拼图里 fibemate 投入最重的一块，但不是“移植即用”的，每团队的目标环境差异大，规则集要按实际资产调整。

教训：CI 门禁不是“装上 ESLint 就完事”。它是一个持续治理的产品，规则集、阈值、豁免流程、观测面板每个都要单独维护。把它当成一次配置，是放弃它最常见的方式。

§5 第四块拼图：KAT 与自测

为什么：算法实现经常微妙错，一个比特位移、一行错位、一个 magic number 多一位，就能让整个算法的 roundtrip 全失败。或者更糟：通过随机测试，但在生产流量下统计性失败。第二篇 §2 的“延迟被低估”本质上是性能侧的问题，而密码学侧有一类更危险的失败：算法“看起来在工作”，但输出是错的。

怎么做：KAT（Known Answer Tests）是密码学自测的最小可执行动作。三层：

• NIST 标准向量：FIPS 203（ML-KEM）、FIPS 204（ML-DSA）、FIPS 205（SLH-DSA）官方 test vectors，逐字节对比
• 跨实现交叉验证：与独立实现（noble、liboqs、Bouncy Castle）做 round-trip 交叉，确保自己不是唯一实现
• 长跑稳定性测试：1,000~100,000 轮连续 keygen + encaps + decaps，验证无内存泄漏、无状态污染、无随机性退化

KAT 数据集本身不大（一个 NIST vector 文件几百 KB 到几 MB），完全可以塞进 CI。每跑一次 PR 小于 30 秒。

踩坑：

• 多个副本的“同源不同实现”。同一种算法在不同目录下出现 4 份实现是常态（fibemate 实战里有过），其中一份错的概率不低，KAT 必须覆盖所有副本
• 实现对，但 KAT 测的不全。encapsulate(decapsulate(...)) roundtrip 过了不代表实现正确，比如 2-bit 与 1-bit 编码错位能让 roundtrip 全过（因为高位的 noise 被 compress(_, 1) 抹掉了），但跨实现交叉就会暴露（第二份实现按 1-bit 解，自然错位）
• KAT 只测 happy path。必须额外加 negative test：篡改密文 → 得到不同的 ss；篡改签名 → verify 失败；用错 key → decaps 失败。这些比 happy path 更能抓实现错

fibemate 的做法：fibemate 在 ML-KEM-768 上跑过 10,000 轮 KAT（含 noble、liboqs、wasm 三实现交叉），SM2 上跑过 100,000 轮（含 TVLA 侧信道）。KAT 数据与自测脚本都在 packages/pqc-kem/test/ 与 packages/sm2-ref/test/。KAT 实践几乎是 fibemate 投入产出比最高的一块，一次写好，长跑有效。

教训：KAT 是密码学项目的“安全网”，不是“测试通过证书”。它防的不是“算法错”（标准里定义了），而是“实现错”（人手写的错）。两类错都需要 KAT 兜住。

§6 第五块拼图：可观测性面板

为什么：第二篇 §5 提了一个真实事故：升级一周后被问“现在握手里有多少走的是混合 PQ 路径”，可观测性设计缺失导致无法作答。这个事故的根因是“观测后置”，升级动作在前，面板设计在后，结果就是黑盒升级。真空期最不该省的投资，就是升级前先把面板搭好。

怎么做：PQC 迁移的可观测性面板，至少四张图：

• 算法分布：过去 24h 混合 PQ / 纯经典 / 纯 PQC 的占比，按服务、按客户端、按地区拆分
• 握手耗时 p99：按算法拆的握手耗时分布，定位 PQC 路径的退化（第二篇 §2 的延迟问题就是这张图暴露的）
• 协商失败率：按客户端 UA、按错误码拆，定位老客户端割接节奏（第二篇 §4 的“幽灵客户端”靠这张图抓到）
• CBOM 漂移：每周 CBOM diff 趋势（新增算法 / 移除算法 / 版本变化），配 alert

四张图的实现都不复杂：Prometheus + Grafana 是常见组合，OpenTelemetry collector 接 Nginx / HAProxy / Envoy 的 TLS metadata，influxdb 或 clickhouse 存时序数据。难的不是工具，是字段设计，必须在升级动作前就定义清楚要采集哪些字段。

踩坑：

• 只看 L4 指标是不够的。连接数、QPS、错误率这些 L4 指标在升级前后几乎不变；要看到 PQC 路径的差异，必须打 L7 维度（cipher suite、key exchange group、signature algorithm）
• 面板不被消费 = 没做。面板上线后没人看，告警阈值没设，等于 0 投入。要让面板接入 on-call 轮值，至少周会 review 一次
• 观测要覆盖回滚路径。回滚时也要能观测到回滚生效的比例、回滚后的算法分布，否则回滚期间是黑盒

fibemate 的做法：fibemate 的 PQC 控制面板在 www/docs/ 下有 14 个 3D 可视化（v3.3.0），其中几张专门展示 CBOM 漂移与算法分布。这是把“密码学数据可视化”作为对外素材做的；对内工程团队，最低配是 Prometheus + Grafana 四张图。

教训：可观测性面板是 PQC 迁移的“雷达”。升级前没雷达，升级后就只能盲飞。盲飞不致命，但翻车时连事故现场都看不到。

§7 第六块拼图：KMS / HSM / TPM 适配

为什么：PQC 算法计算量大（ML-KEM-768 keygen 软件实现约 1 ms，纯 JS 慢一个数量级），侧信道敏感（BigInt 在 JS 引擎里不是 constant-time）。这两个特征叠加的结果是：纯软件实现要么性能不可接受，要么安全强度打折（用 masking 但仍有 SPA 痕迹）。

长期答案必然是硬件承载，KMS、HSM、TPM 把密钥和算力下沉到硬件边界，软件层只调 API。

本节涉及的厂商时间点变动很快，选型前请以厂商官方文档为准。

怎么做：三类硬件适配路径，时间表差异大：

• TPM：TCG 在 TPM 2.0 v1.85 规范中引入了后量子算法。SEALSQ QVault TPM 按 2026-09-03 官方公告“有望成为首款在硅片上实现该规范的出货设备”（原文为 on track to be the first shipping device），厂商计划 2026 年 11 月进入量产供货。ML-DSA / ML-KEM 在 TPM 硬件内签名与封装，私钥不出安全边界。优势：每个终端都有；难点：API 调用开销对高频服务不友好
• HSM：Thales / Entrust / AWS CloudHSM 等主流厂商已陆续公布 ML-KEM / ML-DSA 支持计划，但各家支持矩阵与时间点差异很大，选型前需逐家核对。先用国际标准算法、再回切国密 PQC 是国内多数项目的实际路径
• KMS：阿里云 / AWS / 腾讯云的托管 KMS 正逐步上线 PQC 算法支持，多以“BYOK + PQC 算法”形式提供（即密钥出 KMS 边界由客户控制），适合：数据加密、对象存储加密这类非高频场景

踩坑：

• 不要把 KMS 当银弹。KMS 解决“密钥托管”，不解决“算法性能”。ML-KEM 在 KMS 里跑也是软件实现，握手延迟该有还是有
• HSM 适配周期 6~12 个月。选型测试、合规评审、灾备演练都需要时间，Q4 2026 是合理启动窗口
• TPM 2.0 v1.85 的硅片要到 2026 年 11 月才计划量产，普及率 2027 年才到主流。现在做规划、当作未来 18 个月的过渡方案，不要现在就押宝

fibemate 的做法：fibemate 在桌面端（Tauri）做的是“软件实现 + 硬件加密”折中方案，双棘轮 + ML-KEM 私钥走 AES-GCM 加密后存 IndexedDB，私钥不出进程；HSM / TPM 集成是规划项。fibemate 不直接做 KMS，但 packages/key-lifecycle/ 模块的密钥轮换、版本化、撤销 API 可以对接任何 KMS 后端。

教训：硬件承载是 PQC 迁移的“长尾答案”。现在做规划，未来 18 个月逐步落地。不要被“算法升级立即可用”的乐观估计误导，工业部署的实际窗口比这长得多。

§8 应急回滚：混合模式的逃生通道

为什么：标准未定、算法实战破解都可能让整套升级翻车。HNDL（Harvest Now Decrypt Later）背景下，今天被截获的密文在 2030 年仍可能被解密。这意味着回滚不只是回到昨天，还要重新评估昨天被捕获的密文是否仍然有效。但工程上回滚能力依然必要：算法实现错、客户端割接翻车、硬件适配翻车，都需要快速回退。

怎么做：回滚能力分三层：

• 算法协商顺序可逆：默认“混合 → 纯经典 → 终止”，回滚时切到“纯经典 → 混合 → 终止”，整个握手链路不重启
• CBOM 时间版本化：每次 CBOM 生成时打 git commit 时间戳，回滚时可对比“哪个版本的算法集被回退”
• 密钥材料版本化：每个密钥带 key_version 字段，回滚时不混用旧版本与新版本密钥
• 回滚脚本演练：每季度演练一次回滚（不是纸上谈兵），演练记录入审计日志

踩坑：

• 回滚脚本第一次跑可能就翻车。生产环境的回滚脚本不是写出来的，是跑出来的；每季度演练是发现脚本 bug 的唯一方法
• 回滚后没人知道回滚生效。必须配回滚后自动 verify（确认当前确实在跑纯经典），否则只是把开关拨回去了，业务还在用混合
• 回滚日志要可审计。回滚是合规事件（特别是金融场景），日志必须可追溯：谁批准、为什么回滚、回滚覆盖哪些服务

fibemate 的做法：fibemate 的混合握手实现保留 preferHybrid / preferClassic 两套配置（运行时切换，无需重新部署），CBC 层和 TLS 层都做了版本标记。fibemate 把回滚演练作为日常巡检的一部分。

教训：回滚不是“事后救火”，而是“工程能力的一种”。真空期里，回滚能力比升级能力更重要，因为升级的失败成本（合规、安全、业务中断）远高于回滚的运维成本。

§9 结语：真空期最该投资的是工具链，不是某个候选算法

写到这里回头看前两篇：第一篇讲“真空期要做什么”，第二篇讲“混合 HTTPS 撞了什么墙”，这一篇讲“工具链怎么搭”。三篇的共同主线只有一个：真空期不是等待期，是准备期。

威胁不等人（Harvest Now, Decrypt Later 在今天已成立），合规不等人（关基密评进入“强制 + 年度评估”），但算法未定，这恰好是把工具链投资到位的窗口期。等到 NGCC 第一轮候选公布时，有工具链的团队可以一周内完成“可插拔预集成”，没工具链的团队要花 6 个月补 CBOM、补 CI 门禁、补观测面板。

工具链的产出不是“某个新功能”，而是“接标准的能力本身”。当标准出来时，能在不动业务代码的前提下把新算法接进去，这就是真空期真正的回报。

6 块拼图不是 checklist，而是工具链产品的最小可投资模块。每块都可以独立启动、独立产出、独立迭代。从哪块开始，取决于团队当前的瓶颈：

• 不知道算法分布 → 先做 CBOM
• 知道算法分布但拦不住 PR 引入 → 先做 CI 门禁
• CI 门禁过了但实现错 → 先做 KAT
• KAT 过了但升级后是黑盒 → 先做面板
• 面板齐了但密钥轮换走不通 → 先做 KMS/HSM
• KMS 上了但回滚心里没底 → 先做回滚演练

每一步都比“等标准出来再说”贵一点，但每一步都比“标准出来后临时补救”便宜一个数量级。这就是真空期最朴素的投资逻辑。

词汇注释

参考实践与延伸阅读

• 算法元数据注册表实例：fibemate packages/algorithm-registry/ 模块（github.com/Lennonhaha/fibemate），覆盖 12 个 PQC、国密、经典算法的统一 schema，可复用到任何技术栈
• CBOM 工具链：CycloneDX CLI / cdxgen（多语言自动生成）/ cryptobom-fabricator（合规导向）；fibemate 内部 tools/cbom-diff.js 用于 CI 集成
• CI 门禁参考配置：fibemate 使用 ESLint + 自定义规则 + --max-warnings 0 + CodeQL 周扫 + Dependabot 周更，规则集随团队资产调整
• KAT 数据来源：NIST FIPS 203 / 204 / 205 官方 test vectors；交叉验证库 noble / liboqs / Bouncy Castle
• 可观测性参考：Prometheus + Grafana + OpenTelemetry collector；L7 维度需手工打字段（cipher suite、key exchange group、signature algorithm）
• KMS / HSM 选型：各云厂商 KMS 的 PQC 支持进度请以官方文档为准；Thales / Entrust HSM 适配周期通常 6~12 个月；TCG TPM 2.0 v1.85 的硅片实现仍处于量产爬坡阶段，普及要到 2027 年。