API Key 与轮换

一把 Key 两个值、轮换有重叠窗口、IP 白名单可选 —— 三件事各有一个容易踩的坑。

创建时我方一次性下发两个值：

值	用途	我方存的是	丢了怎么办
`api_key`	换令牌（`POST /v1/connect/token`）	只有哈希	只能重发一把新的
`signing_key`	请求验签	明文（对称算法要求）	可以取回

⚠ 这两个值不可互换。拿 signing_key 去换令牌会得到 401，

而那个 401 与「Key 过期了」长得一模一样 —— 排查时先确认拿的是哪一个。

轮换不是「立刻作废旧的」。我方保留旧 Key 一段重叠窗口：


       轮换
        │
旧 Key  ├────────────┤          ← 窗口内仍然可用
新 Key  ├──────────────────────►
        └── 重叠窗口 ──┘

为什么需要它：你的服务是多实例的，配置不会在同一毫秒生效。没有重叠窗口的话，轮换那一刻总有几个实例还拿着旧 Key 在打 —— 表现是一阵 401，而它看起来像我方出了故障。

窗口结束后旧 Key 立刻失效，不再有第二次宽限。

配了就只有名单内的地址能用这把 Key。没配不是不安全 —— 签名本身已经保证了请求不可伪造；白名单挡的是「Key 泄漏之后的滥用」。

⚠ 如果你的服务跑在无固定出口 IP 的环境（Serverless、容器编排的弹性节点），

不要配白名单。配了之后节点漂移的表现是间歇性 403，

而那种间歇性最难排查。