SudoCode

AI API Key 安全与用量监控完整指南

更新于 2026-10-25 · sudocode.cyou

简答：AI API Key 应只在服务端使用，并通过环境变量、Secret Manager 或 CI/CD Secrets 注入，不能放进前端、移动端、公开仓库或 URL。上线前按项目和环境拆分 Key，同时监控请求量、Token、费用、模型、延迟和错误率，设置供应商侧限额；一旦疑似泄露，先撤销旧 Key，再核查日志、替换部署并复盘来源。

定义：AI API Key 安全与用量监控，是围绕密钥创建、授权、存储、调用、审计、限额、轮换和撤销建立的一套生命周期管理流程。

先做这张检查表：哪些做法安全，哪些需要改

如果你正在接入 OpenAI、Gemini、Claude 或其他 OpenAI Compatible API，可以先按下面的优先级检查。各厂商文档都把公开代码仓库、客户端代码、第三方工具和缺少用量限制视为需要重点关注的风险来源：OpenAI 账户安全说明help.openai.com、Claude API Key 安全说明support.claude.com。

检查项推荐做法需要避免
存储位置环境变量、云端 Secret Manager、CI/CD 加密变量硬编码到源码、配置文件或聊天记录
调用位置由后端或受控 API 网关代发请求浏览器、移动端直接携带长期主 Key
URL 传输使用厂商要求的请求头或 SDK把 Key 放在 URL 查询参数中
权限隔离按供应商、项目、应用、环境和团队拆分所有服务共用一个长期 Key
费用控制设置预算提醒、硬上限、速率限制和配额只依赖网关限流，不设置供应商侧控制
泄露响应撤销旧 Key、核查日志、替换部署、复盘来源只删除代码中的 Key，不撤销供应商侧凭证

Google Cloud 文档明确建议为 API Key 添加限制、避免使用查询参数、删除不再使用的 Key、不要提交到代码仓库，并通过监控和日志识别异常使用：Google Cloud API Key 管理最佳实践docs.cloud.google.com。

API Key 生命周期：从创建到撤销怎么安排

1. 创建前先确定边界

不要先生成一个全能 Key，再把它复制到所有项目。建议先登记四个字段：供应商、项目或租户、运行环境、用途。例如分别建立开发、测试和生产用途，并给每个应用或功能分配独立凭证。这样做的目的不是增加配置数量，而是让异常用量能够定位到具体应用，并在泄露时只撤销受影响的范围。OpenAI 建议按功能、团队、产品或项目使用不同 API Key；Claude 也建议区分开发、测试和生产环境。相关说明见OpenAI 安全文档help.openai.com和Claude Key 安全文档support.claude.com。

2. 存储时使用 Secret，而不是普通配置

本地开发可以使用环境变量或被 Git 忽略的 .env 文件；生产环境应优先使用云平台 Secret Manager、KMS 或 CI/CD 的加密变量。Claude 文档示例使用环境变量加载 Key，并提醒将 .env 加入版本控制忽略文件；OpenAI 文档也建议使用环境变量和 GitHub Secrets：Claude 环境变量与 Secret 建议support.claude.com、OpenAI Key 存储建议help.openai.com。

一个最小化的本地配置示例是：

export OPENAI_API_KEY='只在当前终端会话中读取的密钥'

应用代码只读取环境变量，不要把真实值写入仓库。日志、异常堆栈、请求录制和调试输出也不要打印完整 Key；如必须关联请求，可记录 Key 的短哈希或资产编号，而不是原文。

3. 部署时做双 Key 轮换

  1. 创建新 Key，并登记创建时间、用途、所属应用和负责人。
  2. 将新 Key 写入 Secret Manager 或部署平台的加密变量。
  3. 发布应用并执行一次健康检查，确认请求、流式响应和错误处理正常。
  4. 观察新 Key 的请求量和错误率，确认没有继续使用旧 Key。
  5. 删除旧 Key，并在资产清单中记录撤销时间和原因。

Google Cloud 文档给出的轮换逻辑也是先创建新 Key、更新应用、再删除旧 Key；这比直接删除正在使用的 Key 更适合需要连续服务的应用：Google Cloud Key 轮换说明docs.cloud.google.com。

前端、移动端和浏览器调用：为什么通常要改成后端代理

长期 API Key 一旦随 JavaScript、移动端安装包或浏览器请求发给用户，就很难再被视为私密凭证。OpenAI 明确提醒不要把 API Key 嵌入移动应用；Google Cloud 也建议由客户端把请求传给服务端，再由服务端添加凭证并发起请求：OpenAI 不要发布 API Keyhelp.openai.com、Google Cloud 客户端与服务端边界说明docs.cloud.google.com。

推荐的基本结构是：

如果业务确实需要从 Web 或移动端直接调用 Gemini 相关能力，应额外配置应用限制、API 限制、用户认证、App Check、速率限制和预算告警。Firebase AI Logic 的安全清单将这些措施分为应用验证、请求加固、监控、限额和账单控制几个层次：Firebase AI Logic 安全清单firebase.google.com。具体能否使用某种客户端方案，要以对应供应商和 SDK 的官方文档为准。

用量监控应该记录什么：从 Key 维度定位异常

只看总账单通常不够，因为它无法直接回答“哪个 Key、哪个应用、哪个模型造成了变化”。建议在网关或后端统一记录以下字段；如果供应商控制台能够直接提供某字段，应优先使用供应商侧数据进行核对。

维度建议记录的字段用途
身份供应商、项目、Key 资产编号、应用、环境、团队定位责任边界和撤销范围
请求请求时间、请求 ID、接口路径、模型、状态码分析调用增长和错误变化
用量输入 Token、输出 Token、缓存或推理相关字段（仅在供应商返回时记录）核对计费和模型使用结构
性能首字节时间、总耗时、超时次数、流式中断次数区分供应商问题、网络问题和应用问题
安全用户或租户编号、来源地域、来源 IP 的脱敏值、客户端版本识别异常来源和版本回归
结果成功率、401、403、404、429、5xx 及超时比例区分凭证、权限、模型、限流和服务异常

OpenAI 建议在组织或项目层级设置多个支出阈值，并配置通知；Claude 建议定期查看 Usage 和 Logs，并结合支出限制、速率限制或自动充值设置进行控制：OpenAI 用量与支出监控help.openai.com、Claude Usage、Logs 与限额support.claude.com。

告警规则怎么设：先判断异常，再决定是否撤销

告警不应只设置一个“费用超过某金额”的条件。可以从相对变化和组合条件开始，阈值需要结合自己的正常基线调整，下面是可执行的规则模板：

网关限流不能替代供应商侧限额：网关只能控制经过自己的请求，无法覆盖绕过网关的旧部署、泄露 Key 的外部调用或供应商账户层面的其他项目。因此应同时配置应用层限流、供应商侧配额、预算告警和硬上限。供应商侧控制项的名称、是否立即生效和是否允许超出，应以各自官方控制台说明为准。

代码仓库与 CI/CD：把泄露检查前移

在提交前和合并前做两层检查：第一层是本地扫描，第二层是 CI/CD 阻断。Claude 官方安全文档建议使用代码托管平台的 Secret Scanning，也提到可以使用 Gitleaks 等 SAST 工具，并将扫描集成到 CI/CD：Claude 仓库扫描建议support.claude.com。

  1. 将 .env、本地配置、导出的调试文件加入忽略规则。
  2. 为常见 Key 前缀、Bearer 凭证和高熵字符串配置扫描规则。
  3. 在 Pull Request 阶段阻止新增疑似密钥进入主分支。
  4. 检查日志、测试快照、Issue、构建产物和 Docker 镜像中是否包含凭证。
  5. 扫描命中后不要只删除当前行；如果 Key 曾经进入远程仓库，应立即按泄露流程撤销并轮换。

需要注意，删除 Git 当前文件中的字符串不等于从历史提交中消除泄露风险。是否需要清理仓库历史、通知协作者或联系供应商，应根据实际暴露范围处理。

疑似泄露后的无停机应急流程

假如你发现 Key 出现在公开仓库、前端构建产物、第三方工具配置或异常日志中，不要等待账单变化再处理。可按下面顺序执行：

  1. 确认范围：记录 Key 所属供应商、项目、应用、环境、暴露位置和首次发现时间。
  2. 准备替代凭证：先创建新 Key，并将它写入 Secret Manager 或 CI/CD 加密变量。
  3. 发布并验证：确认健康检查、正常请求、错误处理和流式响应均使用新 Key。
  4. 撤销旧 Key：在供应商控制台删除或停用受影响凭证。OpenAI 和 Claude 的官方说明都建议对疑似泄露的 Key 立即撤销或删除，并检查异常用量：OpenAI 泄露 Key 处理步骤help.openai.com、Claude 泄露 Key 处理步骤support.claude.com。
  5. 核查用量和日志：查看请求量、Token、费用、模型、来源和错误率，保存异常时间段的证据。
  6. 修复来源：清理代码、构建产物、日志或第三方工具配置，并增加扫描和提交阻断。
  7. 复盘与回滚：记录原因、影响范围、撤销时间和验证结果；如果新 Key 出现问题，回滚应用版本，但不要恢复已暴露的旧 Key。

OpenAI 文档还建议在疑似账户或 API Key 被入侵时检查安全历史、退出活动会话并联系支持；不同供应商的支持渠道和审计能力不同，具体以对应控制台和帮助文档为准。

个人开发者、小团队和企业团队怎么分级

团队阶段最低可执行方案进一步完善
个人开发者环境变量、.gitignore、独立开发 Key、供应商预算提醒、定期手动检查用量本地 Secret 扫描、双 Key 轮换、后端代理
小团队按项目和环境拆分 Key，CI/CD Secrets，Pull Request 扫描，应用级日志和告警Secret Manager、Key 资产清单、供应商侧硬上限和速率限制
企业团队集中式 KMS、细粒度权限、审计日志、自动轮换、统一 API Gateway按租户计量、异常检测、事件响应演练、供应商多账号隔离

分级的核心不是一开始就采购复杂系统，而是先把长期 Key 从客户端和代码仓库中移出，再建立资产清单、用量监控、告警和轮换闭环。Google Cloud 文档将 API Key 限制、监控日志、人员隔离和定期轮换列为基础做法；Claude 文档则进一步建议使用集中式 KMS 管理访问控制、审计和轮换：Google Cloud API Key 最佳实践docs.cloud.google.com、Claude KMS 建议support.claude.com。

本文适用范围与核验提醒

本文为 SudoCode 站点的第三方整理，不代表 OpenAI、Google、Anthropic 或其他模型服务商官方。不同供应商的 Key 类型、权限限制、计费字段、日志保留、预算硬上限和撤销生效时间可能不同；本文没有核实任何未列出的平台具体功能，接入前应打开对应供应商的官方控制台和文档核对。

常见问题

AI API Key 可以放在前端或移动端吗？

长期主 Key 不建议放在前端、浏览器或移动端，因为用户可以通过源码、网络请求或安装包分析获得它。更稳妥的结构是客户端请求自己的后端，由后端读取 Secret 并调用模型接口。若使用特定客户端直连方案，应按对应官方文档配置应用限制、用户认证、速率限制和预算控制。

把 API Key 放进环境变量就绝对安全吗？

不是。环境变量只是降低硬编码和提交仓库的风险，进程、日志、错误追踪、构建产物和部署平台权限仍可能暴露凭证。生产环境还需要限制读取权限、脱敏日志、使用 Secret Manager、扫描仓库，并定期轮换。

发现 Key 泄露后，先删代码还是先删 Key？

先创建替代 Key并完成部署验证，再立即撤销受影响的旧 Key，同时检查用量和日志。只删除代码而不撤销旧 Key，无法阻止已经获得凭证的人继续调用。OpenAI 和 Claude 的官方说明都建议对疑似泄露的 Key 进行删除或撤销并核查异常活动。

只设置 API 网关限流，是否还需要供应商侧限额？

仍然需要。网关只覆盖经过网关的请求，不能约束绕过网关的旧版本、泄露 Key 的外部调用或同一供应商账户下的其他应用。建议同时设置应用层限流、供应商配额、预算告警和硬上限。

用量监控至少要看哪些指标？

至少看请求数、输入和输出 Token、费用、模型、Key 或项目、用户或租户、来源地域、延迟、超时、流式中断以及 401、403、404、429 和 5xx 比例。字段能否由供应商直接提供，要以对应官方控制台和 API 返回为准。

相关阅读

参考资料

  1. Keeping your OpenAI account secure
  2. Best practices for managing API keys（docs.cloud.google.com）
  3. 使用 Gemini API 密钥
  4. API key best practices: keep your keys safe and secure（support.claude.com）
  5. Security checklist for using Firebase AI Logic（firebase.google.com）