API Key 安全管理和用量监控：从创建到泄露应急

更新于 2026-10-23 · standardcompute.cyou

简答：API Key 应按项目和环境隔离，放在后端或 Secret Manager 中，禁止进入浏览器、移动端和代码仓库；同时记录请求量、Token、费用、错误和来源变化，发现异常后立即停用并轮换。

定义：API Key 安全管理，是对密钥的创建、权限限制、存储、使用、监控、轮换、停用和泄露应急进行全生命周期控制。

先做这一步：把 API Key 分层并移出代码

本文是面向开发者的通用接入指南，不代表任何 API 平台官方。无论你使用单一模型服务、OpenAI Compatible 接口还是 API Router，第一步都不是把 Key 填进前端，而是先确定它属于哪个项目、环境和应用。

OpenAI 的官方安全建议明确要求不要把 API Key 部署到浏览器或移动应用，也不要提交到代码仓库；Google Cloud 文档同样建议不要把 Key 放进客户端代码或仓库，并建议通过服务端转发请求。可参考 OpenAI API Key 安全建议 和 Google Cloud API Key 管理最佳实践。

一套可执行的 API Key 安全管理流程

1. 建立用途边界：为开发、测试、生产、个人项目和团队项目分别定义用途。每把 Key 只服务于一个清晰的应用或环境，避免出现无法解释的共用 Key。
2. 限制可用范围：如果平台支持项目、权限、API 白名单、来源 IP 或额度限制，应按实际部署位置配置。限制的目标是缩小泄露后的影响，而不是替代后端鉴权。
3. 只在服务端读取：应用启动时从环境变量、Secret Manager 或部署平台的密钥注入功能读取 Key。前端只调用你自己的后端，不直接携带供应商 Key。
4. 避免进入日志：不要打印完整请求头、完整环境变量或包含认证信息的 URL。调试时只输出 Key 是否为空和长度，不输出任何片段。
5. 接入提交前检查：在代码仓库启用 Secret Scanning 或 Push Protection。GitHub 文档说明，Push Protection 会在推送过程中检测硬编码密钥，并在发现凭据泄露时阻止推送；可参考 GitHub Security Features。
6. 建立轮换流程：先创建新 Key，再更新部署配置并验证请求，确认新 Key 生效后再撤销旧 Key。不要先删除旧 Key 再寻找替代配置，否则可能造成服务中断。

轮换不是简单地“改一个字符串”，而是同时更新密钥管理系统、部署环境、CI/CD 变量和必要的本地配置。对于支持自动轮换的 Secret Manager，应先确认目标服务允许轮换，并验证应用能够重新读取新值。AWS 文档将轮换定义为同时更新密钥存储和目标服务凭据的过程，详见 AWS Secrets Manager 密钥轮换说明。

环境变量与 Secret Manager 怎么选

环境变量适合本地开发、简单部署和短期测试。它能避免把 Key 直接写进源代码，但仍需要保护运行环境、CI/CD 日志和部署配置。环境变量不是加密系统，也不能自动解决权限分配、审计和轮换问题。

Secret Manager适合生产环境、多人协作和多实例部署。它通常把密钥从应用源码中分离，应用在运行时读取；部分产品还支持访问控制、审计和自动轮换。AWS 官方文档说明，Secrets Manager 可用于管理 API Key、应用凭据和其他 Secret，并支持通过运行时读取减少硬编码凭据。选择哪种方式，应根据部署平台已提供的能力、团队权限模型和轮换要求决定。

无论使用哪种方式，都应遵循三条原则：应用只读取必要的 Secret；开发、测试和生产不共用同一把 Key；日志、错误追踪和构建产物中不得出现完整认证信息。

用量监控应该看哪些指标

用量监控的目标不是只看一个总费用，而是能够回答“谁在什么时间、通过哪个项目、调用了什么模型、产生了多少请求和 Token、为什么出现异常”。如果平台提供按项目、按 Key 或按成员统计，应优先使用这些维度。

OpenAI 官方安全资料建议查看 Usage 页面、关注使用是否符合团队工作，并在怀疑滥用时立即轮换 Key；Google Cloud 官方资料也建议通过监控和日志发现未授权使用，并按成员或应用隔离 Key，以便审计和缩小影响范围。

预算、额度、速率限制和自动停用不是一回事

• 预算或费用提醒：用于提示消耗接近预设范围，通常不等于立即阻断请求。
• 用量额度：用于限制某个项目、Key 或账户在指定周期内的消耗，具体周期和生效方式必须以平台文档为准。
• 速率限制：控制单位时间内的请求或 Token 规模，触发后可能返回限流错误。
• 自动停用或断路器：由你的网关或业务系统根据异常规则暂停请求，需要明确恢复条件和人工复核流程。

实际配置时，不要把“收到提醒”误认为“请求已经停止”。建议至少设置一条预算提醒、一条请求量异常规则和一条连续错误规则；阈值应根据历史用量、业务高峰和可接受的中断范围自行确定，不应直接照搬其他项目。

发现 API Key 泄露后的处理顺序

1. 立即停用或撤销旧 Key：优先切断继续调用的可能，不要等待完整调查结束。
2. 检查使用记录：查看请求时间、项目、模型、Token、费用、错误、来源 IP 或其他平台提供的审计字段。
3. 核对泄露位置：检查代码仓库历史、构建日志、CI/CD 变量、前端资源、容器镜像、工单和聊天记录。
4. 创建替代 Key：按正确的项目和环境重新生成，并更新 Secret Manager、环境变量和部署配置。
5. 验证最小请求：只验证新 Key 是否能完成预期 API 调用，不要在命令行输出认证头或响应中的敏感内容。
6. 清理与复盘：移除代码和日志中的旧值，检查是否存在缓存或构建产物，并补上提交扫描、权限限制和轮换流程。

如果平台支持 IP 白名单、Key 过期时间或按项目统计，应在替换过程中一并启用或核对。OpenAI 官方资料明确建议怀疑 Key 泄露时立即轮换，并同步更新生产应用；Google Cloud 官方资料则建议删除不再使用的 Key、隔离 Key 并定期轮换。

安全自查清单

• 是否每个环境都有独立 Key？
• 是否能在不查看完整 Key 的情况下确认配置已注入？
• 浏览器、移动端和公开仓库中是否完全没有长期 Key？
• 是否启用了仓库 Secret Scanning 或 Push Protection？
• 是否能按项目、应用、成员或 Key 查看用量？
• 是否记录请求量、Token、费用、错误率、延迟和来源变化？
• 是否有新 Key 先上线、旧 Key 后撤销的轮换流程？
• 是否明确谁负责发现异常、谁负责停用和谁负责复盘？

如果以上问题有多项无法回答，优先补齐可观测性和轮换流程，再继续扩大模型或应用接入范围。

补充说明：API Key 不等于完整用户认证

API Key 通常用于识别调用方、关联项目或授权 API 请求，但它不自动替代终端用户登录、会话管理、权限校验和业务审计。对于面向用户的应用，建议由后端验证用户身份和业务权限，再由后端使用受控的 API Key 调用模型服务。

Google Cloud 文档区分了普通 API Key 与绑定服务账号的授权 Key，并提醒不同凭据类型的身份和权限含义不同。对于其他 API 平台，不要直接套用这一分类；应以对应平台的认证文档为准。

常见问题

API Key 可以直接放在前端代码里吗？

不建议。浏览器和移动端中的 Key 可以被用户或恶意程序获取。更安全的做法是让前端请求自己的后端，由后端保存并使用 API Key。

环境变量是否等于绝对安全？

不是。环境变量能减少硬编码和误提交，但运行环境、部署配置、CI/CD 日志仍可能泄露密钥。生产环境还应考虑访问控制、审计和轮换。

多个项目可以共用一把 API Key 吗？

技术上可能可用，但不利于权限隔离、用量归因和泄露后的止损。更合理的做法是按项目、应用或环境拆分，并保留清晰的使用记录。

API Key 泄露后应该先查日志还是先撤销？

先停用或撤销旧 Key，再检查用量和日志。调查不能替代止损；完成排查后，应创建替代 Key、更新部署并复盘泄露路径。

应该多久轮换一次 API Key？

没有适用于所有平台和项目的统一周期。应结合平台是否支持过期时间、应用风险、部署成本和团队流程制定计划；只要怀疑泄露，就应立即轮换。

监控 API 用量时最少要记录什么？

至少记录请求量、输入和输出 Token、费用或额度消耗、错误率、延迟、调用项目、模型和时间范围；若平台提供来源信息，也应纳入异常排查。

相关阅读

• 查看更多 AI API 接入与排错指南
• Dify 接入兼容 API 的配置步骤

参考资料

1. OpenAI：Best Practices for API Key Safety
2. Google Cloud：Best practices for managing API keys（docs.cloud.google.com）
3. GitHub Docs：GitHub security features
4. AWS Secrets Manager：Rotate secrets（docs.aws.amazon.com）
5. AWS Secrets Manager：What is AWS Secrets Manager（docs.aws.amazon.com）