API 密钥就像系统的“万能钥匙”；一旦泄露，轻则被薅费用、被刷配额，重则造成数据泄露与供应链攻击。本文给出一套可直接落地的密钥治理方案：以最少权限为核心、配合允许列表（白名单）与零停机撤销/轮换流程，并覆盖密钥发现、存储、分发、审计与应急响应的实操清单。
你将获得
- 一套“最少权限 + 允许列表 + 撤销/轮换”的密钥治理基线
- 漏洞/泄露后的标准化撤销与验证步骤（零停机思路）
- CI/CD 与日常开发中的密钥防泄露实践与工具位
- 可直接复制的检查清单与 FAQ
术语说明
文中将“白名单/黑名单”替换为更清晰与包容的“允许列表/拒绝列表”（allowlist/denylist）；多个国家级安全机构与社区已采用该措辞。
一、为什么 API 密钥必须“像生产数据一样被保护”
密钥一旦外泄，攻击者可冒充合法服务调用接口、拖垮配额并侧向移动。OWASP 明确建议集中化存储、发放、审计与轮换密钥，避免硬编码、日志泄露与随意共享。
二、原则一：最少权限（Least Privilege）
最少权限是所有密钥治理的底座：只给任务所需的最小访问范围与最短有效期，并随使用情况持续收紧。
策略落地要点
- 以托管策略起步，逐步生成基于实际访问行为的“最小权限策略”；结合条件限制进一步收敛访问面（资源 ARN、来源账户、加密上下文等）。
- 使用细粒度令牌/密钥：例如 GitHub 的“细粒度 PAT”只对特定仓库与权限生效，替代老的“广域作用域”。
- 能用临时凭证就不要发长效密钥：云上优先使用角色/STS 临时凭证，减少长期 Access Key 的暴露面与轮换负担。
三、原则二：允许列表（白名单）与来源约束
密钥经常需要在前端或边缘环境中使用；此时必须叠加来源约束来“绑住”密钥的可用场景。
常见做法
- 按调用来源限制：Web 使用 HTTP 引用者（Referrer）限制，后端/服务器使用固定 IP/CIDR 限制，移动端绑定包名与签名指纹等。
- 按 API 功能限制：同一密钥只允许访问必要的 API 集合，避免“一把钥匙开所有门”。
Google 的官方指南明确建议：始终为 API Key 同时配置“应用类型限制 + API 功能限制”。
四、原则三：撤销与轮换（可零停机）
密钥不该“用到天荒地老”。成熟做法是：自动化周期轮换 + 事件驱动撤销，且通过“双活过渡”实现零停机替换。
为什么双活
Vault/业界实践建议在轮换窗口内让新旧版本并行，以保证业务在配置分发与缓存失效期间不中断。
示例：支付网关的无缝轮换
通过控制台一键生成新 Key、设定过期时间、观察新 Key 生效，再在过渡期结束后撤销旧 Key。Stripe 的官方与工程博客均给出具体步骤与“零停机”要点。
频率建议
在具备自动化时，很多团队选择≤90 天的轮换周期；若具备动态临时凭证，可进一步缩短。频率应结合风险与运维成本评估。
五、发现泄露时的“应急撤销流程”模板
- 立即拉黑可疑来源并降权：在 API 网关/防火墙侧封禁异常 IP/UA，临时关闭非必需权限。
- 生成新密钥：在提供方控制台创建新 Key，并记录到案（含用途、创建人、到期时间）。
- 安全分发与灰度：将新 Key 写入秘密管理系统，逐环境灰度发布并验证调用成功；维持新旧双活直至灰度完成。
- 撤销旧密钥：在控制台或 API 中吊销旧 Key，并确认不再被接受。对云 Access Key，先禁用后删除。
- 证据留存与溯源：审计日志、调用日志与 CI/CD 产物留存，梳理泄露路径（代码库、日志、工单、聊天记录等）。OWASP 建议集中审计与取证。
- 全量扫描与阻断再泄露：开启或强化代码托管平台的 Secret Scanning/Push Protection，处理告警直到“清零”。
- 对外沟通与复盘：若涉及第三方或合规义务，按流程通报并形成改进项与复发防控措施。
如使用 Stripe 等第三方服务，官方亦提供“泄露后旋转”的逐步操作教程，可直接套用。
六、密钥的安全存储与分发
- 集中化秘密管理：使用 Vault/云 Secret Manager/KMS 统一存储、发放、审计与轮换，不要写在代码、镜像或环境变量里长期滞留。
- 临时凭证优先：服务到服务优先使用短期令牌/角色凭证，避免长效静态 Key。
七、开发与 CI/CD 的“防泄露三板斧”
- 预防：用占位符 + 本地注入，不把真实密钥写进仓库与示例配置。
- 发现：开启 GitHub/GitLab 的 Secret Scanning 与 Push Protection；必要时做一次历史全量扫描。
- 响应：对告警做有效性校验、分级处置并追踪至关闭。
八、常见反模式（请避免）
- 用 API Key 充当用户登录/身份认证。OWASP 指出：API Key 不是用户认证机制；需要身份时请用 OAuth 2.0 + OIDC 等标准方案。
- 在前端公开长效、高权限的 Key，且无任何来源或 API 限制。Google 明确指出 API Key 通常可被客户端获取，泄露后可能无限期可用，必须加限制或改用更好的授权机制。
九、治理检查清单
- 资产盘点：枚举所有密钥、用途、负责人、到期时间、权限范围
- 最少权限：仅授予必要 API/资源与最小作用域；避免“*”通配
- 来源限制：按应用类型与 API 功能双重限制（Web Referrer / 服务器 IP / 包名签名）
- 轮换与撤销：建立自动轮换与双活过渡；具备“一键吊销 + 验证”流程
- 存储与分发：秘密集中管理，部署时注入；日志与崩溃报告默认脱敏
- 开发流程：开启 Secret Scanning、Push Protection 与历史扫描；提交前本地钩子校验
- 监控与审计：定期回顾未使用密钥与过度权限、异常调用、跨账户访问
- 培训与术语：统一使用“允许列表/拒绝列表”等更清晰与包容的称谓
十、FAQ
Q1：到底该多久轮换一次？
推荐“自动化驱动 + 风险导向”。常见做法是不超过 90 天；如果用临时凭证或具备强自动化，可更频繁。关键在于能“随时旋转、零停机”。
Q2：我的后端是弹性 IP，怎么做来源限制？
无法固定 IP 时，可叠加其他强约束：按 API 功能限制、服务到服务改用短期令牌或 mTLS，辅以网关/WAF 行为策略与速率限制。谷歌也强调对 Key 至少要做应用类型与 API 双重限制。
Q3：API Key 能不能当用户登录用？
不建议。应使用 OAuth 2.0 授权访问、OIDC 做身份层，API Key 只用于应用识别或低风险场景。
Q4：如何判断仓库里是否有密钥泄露？
开启 GitHub/GitLab 的 Secret Scanning/Push Protection，并对历史做一次全量扫描；对告警逐条核实、撤销并轮换相关密钥。
