密钥安全与轮换

明文只出现一次

创建密钥时页面会显示一次完整明文，关掉之后我们也拿不回来 —— 服务端只存哈希，不存原文，日志里也不记。

丢了就轮换一把新的。不要开工单要原文，客服同样没有。

三道自选的闸

每把密钥都可以单独配，互相独立：

设置	作用	被它挡住时
IP 白名单	只允许指定来源调用	401 invalid_api_key
模型白名单	只允许这把密钥调指定模型	model_not_allowed
预算上限	这把密钥最多花多少	budget_exceeded

⚠️ 被 IP 白名单挡住时返回的是和「密钥无效」完全相同的错误码。 这是有意的：专用错误码等于告诉捡到密钥的人「key 是好的，只是网络不对」。 所以排查 401 时先确认来源 IP，不要反复重建密钥。

关于模型白名单：它和你套餐允许的模型取交集。被挡住时看 message 里的措辞 —— 「…by your plan」是套餐不够，「…for this API key」是套餐够但这把密钥被限制了， 后者升套餐没有用。

轮换

轮换会生成一把新密钥，旧的进入宽限期，期间两把都能用， 方便你把线上服务逐个切过去。

⚠️ 同一时间最多两把有效。 如果你在宽限期内又轮换了一次， 更早的那一把会立刻失效 —— 不会等它自己的宽限期走完。 所以先把服务切完，再考虑下一次轮换。

怀疑泄露时不要轮换，直接吊销：吊销是立即生效的，没有宽限期。

密钥不该出现在哪

• 前端代码、移动端 App 包体（都能被反编译出来）
• 公开仓库、CI 日志、报错截图
• 发给我们的工单正文 —— 排查从来不需要你的密钥明文，只需要 request_id