密钥安全与限制

API 密钥拥有调用权限。安全目标不是“永不泄漏”，而是尽量减少泄漏概率，并让泄漏后的影响范围可控。

一项用途一枚密钥

推荐按环境和应用拆分：

• local-development
• staging-service
• production-backend
• cherry-studio
• codex-cli

这样可以单独查看用量、调整额度和撤销，不需要一次更换所有应用。

使用控制项

控制项	适用场景
过期时间	临时测试、活动或短期合作
密钥额度	限制单个应用最大损失
模型限制	应用只需要少数模型
IP 白名单	服务端拥有稳定出口 IP
分组	限定线路、模型范围和倍率

IP 白名单支持时，可填写单个 IP 或 CIDR。配置前确认云服务的实际出口地址，避免把内网地址误当公网出口。

绝对不要放在哪里

• 浏览器前端代码和移动应用包。
• Git 仓库、Issue、聊天记录和公开截图。
• URL 查询参数。
• 错误追踪中的完整请求头。
• 客服工单或屏幕录制中未遮盖的位置。

前端业务需要调用模型时，应由自己的后端保存密钥并代理请求，同时做好用户认证和速率限制。

检测到泄漏

1. 立即在密钥页面禁用或删除泄漏密钥。
2. 查看使用日志，确认异常请求的时间、模型和消费。
3. 创建新密钥，限制额度、模型和 IP。
4. 更新部署 Secret 并重启相关服务。
5. 清理 Git 历史、日志、构建产物和聊天附件中的旧值。

仅删除公开文件中的密钥不够，Git 历史和缓存中可能仍然存在；泄漏后必须轮换。

轮换策略

生产密钥轮换应采用“先新增、后切换、再撤销”：

1. 创建新密钥。
2. 在非生产环境验证。
3. 更新生产 Secret。
4. 观察新密钥有正常请求。
5. 撤销旧密钥。

日志脱敏

可以记录密钥标识的末尾少数字符来定位配置，但不要记录完整值。请求头应在进入应用日志前统一脱敏。