SoleAPI

API Key 安全怎么保护：从存储到泄露处置的完整指南

更新于 2026-10-26 · soleapi.cyou

简答：API Key 安全保护的核心是“不进前端、不进仓库、不进 URL”，并按应用和环境拆分密钥，使用 Secret 管理、权限限制、用量监控与定期轮换。若已经泄露，应先撤销或停用旧 Key，再检查调用记录、费用和代码历史，最后用新 Key 完成替换。

定义：API Key 是用于识别调用方并授予 API 访问权限的凭证，通常属于 bearer credential，拿到它的人可能以相同权限发起调用，因此不能把它当作普通配置字符串处理。

先做这张安全对照表：API Key 应该放在哪里

API Key 安全的第一原则，是让密钥只出现在真正需要发起服务端请求的环境中。OpenAI 帮助中心明确建议使用环境变量，并提醒不要把 Key 直接打包进移动应用；Google Cloud 文档也建议不要把密钥写入客户端代码或代码仓库。

场景推荐做法应避免的做法
本地开发使用本地环境变量或未提交的 .env 文件，并加入 .gitignore把真实 Key 写进源码、示例配置或截图
CI/CD使用平台提供的加密 Secrets，在构建或部署时注入把 Key 写进工作流 YAML、命令行参数或公开日志
云端生产使用云 Secret 管理服务或等效的加密凭证存储把生产 Key 固定写在镜像、仓库或普通配置文件中
网页前端由自有后端代理调用第三方 API把 Key 放进 JavaScript、浏览器存储或前端请求头
移动端和桌面端由受控服务端完成鉴权和 API 调用把长期有效的服务端 Key 内置到安装包
第三方工具确认用途、权限和保管方式后，通过加密 Secret 配置在聊天、工单、论坛或不明工具中直接粘贴 Key

环境变量只是降低误提交概率，并不等于绝对安全：拥有服务器进程权限、读取部署配置或查看调试日志的人，仍可能接触到密钥。因此生产环境还要叠加权限限制、日志脱敏、访问审计和轮换机制。

按开发、测试、部署、生产四个阶段保护密钥

1. 开发阶段：让密钥离开代码仓库

  1. 在本机创建未纳入版本控制的 .env 文件。
  2. 使用明确的变量名，例如 OPENAI_API_KEY、ANTHROPIC_API_KEY 或项目自定义名称。
  3. 将 .env 加入 .gitignore，同时提交一个只含占位符的 .env.example。
  4. 检查调试输出，避免打印完整请求头、环境变量对象和异常对象。

Claude 帮助中心给出了使用环境变量和 dotenv 的示例，并特别提醒本地 .env 文件应加入 Git 忽略配置。示例中的变量名只适用于对应 SDK 或项目，接入其他服务时应以该服务的官方文档为准。

2. 测试和 CI/CD：用加密 Secret 注入

测试环境和生产环境不要共用同一个 Key。为不同应用、环境或团队成员分别创建凭证，可以缩小泄露后的影响范围，也便于追踪调用来源。Google Cloud 文档建议按团队成员和应用隔离密钥，并定期创建新 Key、更新应用后删除旧 Key。

3. 部署阶段：检查镜像、日志和配置导出

4. 生产阶段：最小权限加监控

API Key 通常只能证明“持有者有这个凭证”，不能天然区分每个最终用户，也不能替代细粒度授权。对于支持范围限制、来源限制、额度或速率控制的服务，应按实际业务配置。NIST 的 API 防护指南将 API 安全放在开发与运行全生命周期中考虑，强调根据风险逐步实施基础和高级控制。

传输和调用时，重点防住五条泄露路径

  1. 不要放进 URL 查询参数。URL 可能出现在浏览器历史、代理记录、网关访问日志和监控系统中。Google Cloud 文档明确建议避免通过查询参数传递 API Key，并改用受支持的请求头或客户端库。
  2. 不要放进前端代码。网页、移动端和桌面端发布后都可能被用户查看、调试或提取。前端需要调用时，让前端请求自己的后端，再由后端添加第三方凭证。
  3. 不要打印完整请求头。调试 HTTP 客户端、反向代理、错误追踪和 APM 工具时，应对 Authorization、x-api-key 等字段做掩码。
  4. 不要把 Key 粘贴到聊天、工单或代码审查评论。Claude 帮助中心建议不要在公开讨论、邮件或支持工单中分享 API Key，也提醒第三方工具可能获得对应账户的访问能力。
  5. 不要只依赖一把长期有效的万能 Key。按应用、环境和用途拆分凭证，并为支持这些能力的服务设置 API 范围、来源、额度或速率限制。

需要区分的是：API Key、OAuth 访问令牌、JWT、服务账号凭证和短期 Token 不是同一种机制。API Key 适合标识调用项目或服务，但通常不适合直接承载复杂的最终用户授权；当服务支持 OAuth、IAM 或短期凭证时，应根据官方认证模型选择，而不是仅因为接入简单就长期使用一把高权限 Key。

API Key 泄露怎么办：15 分钟应急清单

如果 Key 已经出现在公开仓库、前端代码、日志、截图或聊天记录中，应按“先止损、再调查、后恢复”的顺序处理，不要等到确认已经产生费用后才行动。

  1. 立即停用或撤销旧 Key。如果服务支持冻结、删除或禁用，先阻断继续调用；不要只删除仓库中的那一行文本。
  2. 检查调用记录和用量。查看异常时间、地域、模型、接口、请求量和费用变化。OpenAI 帮助中心提醒，暴露的 API Key 可能导致未授权使用、费用或违反服务条款的活动。
  3. 限制潜在损失。在服务支持的情况下，收紧额度、速率、来源和 API 范围；同时暂停自动充值或降低消费上限时，要确认不会影响正在运行的业务。
  4. 排查泄露范围。搜索当前代码、Git 历史、构建产物、镜像层、CI 日志、错误追踪、聊天记录和文档附件。已提交到 Git 的密钥不能仅靠删除最新提交来处理。
  5. 创建替代 Key 并完成切换。先将新 Key 写入 Secret 管理系统，验证应用能够正常调用，再删除或撤销旧 Key。
  6. 保留事件记录。记录发现时间、泄露位置、旧 Key 处置时间、异常调用和修复动作，便于后续复盘。

如果怀疑的不只是 API Key，而是账户登录凭证也被暴露，还要按照对应平台的账户安全流程修改密码、撤销会话并启用多因素认证。不要把“换密码”当成 API Key 轮换的替代方案，两者需要分别处理。

无停机轮换与上线前自查

推荐的无停机轮换顺序

  1. 创建新 Key，并为它设置与旧 Key 相同或更小的权限范围。
  2. 把新 Key 写入 Secret 管理系统，保留旧 Key 作为短暂回退选项。
  3. 部署应用，让新实例先读取新 Key。
  4. 观察健康检查、错误率、调用量和业务日志，确认切换成功。
  5. 撤销旧 Key，删除不再使用的配置和备份。
  6. 更新应急文档，注明新 Key 的负责人、用途和轮换日期。

上线前 10 项检查

本页是独立的通用接入指南，不代表 SoleAPI 官方；具体字段、控制台路径、认证方式和限制能力，应以对应服务商的官方文档为准。

常见问题

API Key 可以放在前端吗？

不建议放置长期有效的服务端 API Key。浏览器、移动端和桌面端中的凭证都可能被查看或提取，前端应调用自有后端，由后端完成第三方 API 鉴权。OpenAI 帮助中心明确提醒不要把 API Key 嵌入移动应用。

放进环境变量后就绝对安全吗？

不是。环境变量主要避免把密钥直接写入源码，但拥有进程、部署配置、日志或主机权限的人员和工具仍可能读取它。生产环境还应配合 Secret 管理、最小权限、日志脱敏、用量监控和定期轮换。

把 Key 从 GitHub 文件中删除后，风险就消失了吗？

不一定。提交历史、Fork、缓存、构建日志和复制过的文本可能仍保留旧值。实际泄露时应先撤销或禁用旧 Key，再排查仓库历史和部署产物，最后创建新 Key。

API Key 多久轮换一次比较合适？

没有适用于所有项目的固定周期。应结合凭证权限、暴露面、人员变动和服务要求制定周期；一旦出现在公开位置、日志或不受信任工具中，应立即撤销并重新创建，而不是等到计划周期。

API Key 和 OAuth Token、JWT 有什么区别？

API Key 常用于识别项目或调用方，OAuth Token 通常用于代表用户或应用授予范围化访问，JWT 是一种可携带声明的令牌格式。具体选择取决于服务端认证和授权设计，不能因为名称相似就互换使用。

常见问题

API Key 可以放在前端吗？

不建议。前端代码、移动端和桌面端安装包都可能被查看或提取，推荐由自有后端代理调用第三方 API。

环境变量能保证 API Key 绝对安全吗？

不能。环境变量能减少误提交，但还需要 Secret 管理、最小权限、日志脱敏、访问审计和轮换。

API Key 泄露后第一步做什么？

先撤销或停用旧 Key，再检查调用记录和费用，收紧限制，排查代码历史与日志，最后创建新 Key 并完成切换。

API Key 应该多久轮换一次？

应根据权限和暴露面制定周期；一旦进入公开仓库、前端、日志或不受信任工具，应立即撤销并重新创建。

API Key 和 OAuth Token 是一回事吗？

不是。API Key 多用于识别调用方，OAuth Token 通常承载范围化授权，具体选择应以服务端认证模型和官方文档为准。

相关阅读

参考资料

  1. Guidelines for API Protection for Cloud-Native Systems - March 2026 Update（nist.gov）
  2. API key best practices: keep your keys safe and secure（support.claude.com）
  3. Keeping your OpenAI account secure
  4. Best practices for managing API keys（docs.cloud.google.com）
  5. Protect APIs with registration, permissions, and consent