零停机轮换在用的 API 密钥

目标

原子化地替换在用凭证，会在两侧传播速度不一致时全面失败：验证方先学到新钥或签发方先切换，中间的每个请求都挂。正确模型是带重叠态的状态机：双钥有效、流量迁移、旧钥观测归零、然后吊销。没有停机，因为任何一步都不要求两侧在时机上达成一致。

步骤要点

1. 先在不影响 v1 的前提下签发 v2 密钥并存入密钥库，形成双钥并存。
2. 验证方改为按列表受理 v1 与 v2 的签名，传播过程对调用方完全透明。
3. 签发方切到 v2，按密钥维度的指标观察新钥流量上升、旧钥流量衰减。
4. 用指标确认旧钥使用量归零（比日历猜测可靠），以此决定吊销时机。
5. 归零后对 v1 执行带 7 天恢复窗口的删除，轮换结束且保留有界撤销。

排错提示

旧钥用量迟迟不归零多半是某客户端永久缓存了密钥，用按钥指标找到负责人沟通，而不是盲目延长或强吊销；验证方存不下两把钥匙就先重构为密钥列表，单槽验证方只会把轮换逼回大爆炸模式；泄漏应急也要保住“双受理→切换→吊销”的形状，只是压缩到几分钟，直接吊销等于自己制造停机。

适用边界

重叠窗口的长短是业务决策，要在可用性与旧钥暴露面之间权衡；按钥遥测是前置条件，没有它“归零”只是猜测、吊销就是赌博。

代码示例

// Overlap state: accept both
const accepted = await Promise.all([
  secrets.get("prod/payment-signing/v1"),
  secrets.get("prod/payment-signing/v2"),
]);

// Revoke only when observed usage hits zero
// metrics: signing_key_usage{key="v1"} == 0 for 24h