API 密钥管理最佳实践

API 密钥出问题的方式，绝大多数不是被密码学攻破，而是被误提交、误粘贴、误打印。因此密钥管理的重点不是选择更强的算法，而是把「密钥出现在什么位置」这件事管住。

下面按密钥的生命周期分五个环节，每一环给出可执行的做法与常见反例。

一、生成：格式与熵

密钥应包含两部分：可公开的标识段与必须保密的随机段。这样服务端可以先按标识查出记录，再比对随机段，便于审计与吊销；
随机段必须用密码学安全随机源生成，长度建议 128 位以上（约 22 个以上随机字符），不要使用时间戳、自增 ID、用户名等可猜测内容；
不要用自己发明的算法生成密钥，也不要为了「好记」而引入字典词；
服务端只保存随机段的摘要（配合独立盐），明文只在创建时返回一次——这样即使数据库泄露，攻击者也不能直接使用其中的密钥。

二、存储：密钥不该出现在哪里

不要提交到版本库。这是最高频的泄露来源，且一旦提交，即使后续删除，历史记录里仍然存在；
不要写进前端代码或打包产物。浏览器端的一切内容都视为公开；
不要写进截图、工单、聊天记录。粘贴即外发；
正确做法：本地用环境变量或密钥管理服务；服务器上用权限受限的配置文件或编排平台的密钥机制；不同环境使用不同的密钥。

三、使用：传输位置很关键

令牌应当放在请求头，而不是 URL 参数。原因是 URL 会流入多个持久化位置：

服务器访问日志与反向代理日志通常完整记录请求行，包括查询串；
浏览器历史记录与书签；
跳转到第三方资源时，来源地址可能被带入来源信息；
错误上报与监控系统会把完整 URL 一并采集。

四、轮换：如何做到不中断

轮换的目标是「旧密钥失效，业务不中断」。可行的做法是允许多把密钥同时有效：先创建新密钥并部署到调用方，确认新密钥产生实际调用量后，再吊销旧密钥并观察一段时间。

把这一步做进流程而不是靠临时操作，关键在于提前准备好两件事：一是系统支持同时存在多把有效密钥；二是能按密钥维度看到调用量与最近使用时间，从而判断旧密钥是否真的没人用了。

本站的密钥控制台正是按这个流程设计的：用任意一把有效密钥登录后，可以按密钥查看调用量与最近使用时间、自助签发新密钥（继承当前套餐与限额，不会提升权限），等新密钥确实产生流量后再吊销旧的；如果某把密钥写进了不该出现的位置，也可以立刻自助吊销而不必等管理员处理。因为服务端只保存密钥摘要，控制台不提供「找回密钥」——登录入口本身就是密钥，遗失时只能重新签发。

五、吊销与最小权限

吊销必须立即生效，不能依赖缓存过期——因此密钥配置的缓存需要支持主动清除；
每把密钥只授予必要的权限范围，避免一把密钥走遍所有接口；
为用户自助生成场景设置配额上限与速率限制，避免单把密钥被滥用拖垮服务；
对无效密钥的尝试做限流：否则攻击者可以用大量随机密钥制造请求，形成低成本的压力来源；
记录密钥的最后使用时间与来源，便于发现异常使用。

六、常见错误清单

把密钥放在 URL 查询串里，导致它出现在日志与监控系统中；
用同一个密钥贯穿开发、测试、生产环境；
密钥泄露后只改代码不吊销，旧密钥仍然有效；
把「哈希后的密钥」当作可以直接使用的凭据（服务端存摘要、客户端用明文，不应混淆）；
对无效密钥不做任何限流，使错误尝试成为可放大的资源消耗。

七、延伸

涉及摘要算法的选择与「为什么不能明文存密钥」的原理，见《MD5、SHA-1、SHA-256 怎么选》；需要确认一段内容是否被改动过时可用在线哈希计算工具做本地比对。生成高强度随机字符串可参考 UUID 与密码生成工具。