把 API Key 当作生产凭证
API Key 属于持有者凭证，拿到 Key 的人通常可以持续调用服务，直到它被撤销、到期或受到限制。因此 Key 安全是产品能力，而不只是文档备注。
安全体系需要结合预防、检测和恢复：减少泄露概率、快速识别异常用量，并让客户能够顺利轮换和撤销凭证。
使用足够随机的 Key
Key 应足够长，并通过密码学安全随机源生成。可以使用简短前缀识别环境或产品，但密钥部分不可预测。
- 测试与生产使用不同前缀。
- 完整密钥只在创建时展示一次。
- 服务端只保存密钥部分的哈希。
限制每个 Key 能做什么
权限范围和环境限制能够缩小泄露后的影响。报表 Key 不应修改数据，浏览器 Key 应限制域名和权限，服务器 Key 也应设置配额与轮换规则。
| 控制项 | 作用 | 示例 |
|---|---|---|
| 权限范围 | 限制操作 | read:usage、write:messages |
| 配额 | 控制成本 | 每月 5 万次请求 |
| IP 白名单 | 限制来源 | 仅允许后端 IP |
| 域名限制 | 降低浏览器滥用 | 仅 app.example.com |
| 到期时间 | 强制轮换 | 90 天临时 Key |
谨慎记录日志
日志应记录 Key ID、前缀、工作区、路由、用量、状态和耗时，但不能保存完整 Key。请求体、Header、链路追踪和客服导出都应清理敏感信息。
准备凭证泄露响应流程
Key 泄露后，客户需要快速撤销并创建替代凭证。产品应展示近期用量、受影响权限和可疑流量。自动检测可以监控公开代码、日志和异常峰值，但手动撤销仍必须简单。
- 允许新旧 Key 短时重叠后再撤销。
- 高权限 Key 变更时通知工作区管理员。
- 说明确认泄露后的账单争议处理方式。