面向 AI 产品的安全 API 密钥管理

面向 AI 产品的安全 API 密钥管理，不仅仅是在保险库中存放一个提供商凭证。AI 应用会在通常跨越多个提供商和环境的系统之间传递提示词、文件、检索到的上下文、工具参数以及模型输出。一个密钥即使在静态存储时被完美加密，其周围的请求路径仍可能通过浏览器包、调试日志、CI 输出、支持导出文件，或权限过高的路由服务暴露敏感数据。

因此，实际目标更为宽泛：让长期有效的提供商密钥远离不受信任的客户端，为每个工作负载分配最小且有用的身份，控制哪些数据可以跨越每个模型边界，并使轮换与吊销成为常规操作而非破坏性事件。

本指南为平台、安全和 AI 产品团队提供了一个可实施的运行模型。它包括威胁模型、密钥清单模板、控制平面架构、零停机轮换操作手册、日志规则、CI/CD 保护措施、事件响应流程以及生产检查清单。

AI 密钥可能跨越的五个边界

首先，映射秘密或其所授权的数据可能流转到哪些位置。大多数故障都源于团队保护了提供商密钥，却忽略了这些相邻边界之一。

这张边界图把设计问题从“我们把密钥存在哪里？”变成了“哪个身份可以通过哪条路径、使用哪些数据发起哪些请求，以及之后会留下什么证据？”

使用服务端密钥保管模型

长期有效的提供商凭证不应交付给浏览器、移动端、桌面端或扩展客户端。任何发送到终端用户设备上的内容，都应被视为该用户本人或以相同权限运行的恶意软件可以恢复获取。

更安全的模式是：

1. 客户端使用用户会话、设备凭据或短期应用令牌对您的后端进行身份验证。
2. 您的后端对所请求的功能进行授权，并应用按用户或按租户的限制。
3. 网关或服务端集成选择已批准的提供商和模型。
4. 在运行时检索提供商密钥，或通过部署平台将其提供给受信任的工作负载。
5. 提供商响应通过相同的策略边界返回。

客户端永远不需要提供商密钥。它只会在您定义的限制内获得调用您产品的权限。

对于编码代理和本地开发者工具，请使用相同的原则，但采用有意例外模型。开发者可能需要本地凭据，但它应当是可撤销、可归因且范围受限的产品或网关凭据——而不是将共享的组织级提供商密钥复制到公司各处 dotfiles 中。

在轮换任何密钥之前先建立密钥清单

当团队不知道哪个工作负载正在使用某个密钥时，轮换项目就会失败。在更改凭据之前，先创建一份机器可读的清单并指定负责人。

至少记录以下内容：

不要把密钥值放进清单中。只存储元数据以及对受管密钥的引用。

按环境、工作负载和风险分离身份

最常见的反模式是让每个服务共享同一个生产密钥。它在某个仓库、测试运行器、承包商笔记本电脑或支持记录泄露它之前都很方便。然后，团队就无法在不影响无关产品的情况下撤销该密钥。

优先为以下对象使用独立身份：

• 生产、预发布、开发和本地测试。
• 面向客户的流量、内部工具、批处理作业以及评估流水线。
• 可调用工具或处理机密数据的高风险工作流。
• 当合同边界要求隔离时，不同业务单元或租户。
• 紧急或破窗访问，在正常运行期间应保持禁用或受到严格控制。

如果提供商提供了限制功能，请加以使用。限制可能包括允许的 API、模型、来源网络、项目、引荐来源、应用或配额。例如，Google Cloud 的 API 密钥指南建议限制密钥、隔离密钥、删除不需要的密钥、避免提交到仓库，并监控其使用情况。

如果提供商没有提供足够细粒度的控制，请在你自己的网关层面强制实施。中心化网关可以验证调用工作负载，将其映射到经批准的路由，应用预算和速率限制，并将供应商凭据限制在一个经过审查的服务端边界内。关于路由和故障转移设计，请参阅更广泛的AI API 网关架构指南。

将提示词和日志治理视为密钥管理的一部分

API 密钥授权的是一条数据通路。只保护密钥而不控制这条通路，会使主要的 AI 特有风险仍然悬而未决。

在路由请求之前，对载荷进行分类并应用“最小必要”规则：

• 移除凭据、令牌、Cookie、私钥和连接字符串。
• 排除模型不需要的字段。
• 当任务可以在没有直接标识符的情况下完成时，对这些标识符进行令牌化或假名化处理。
• 拒绝不受支持的受监管数据或合同限制数据。
• 将系统指令与不受信任的用户内容或检索内容分离。
• 在代理调用外部系统之前验证工具参数。

日志需要明确的模式。不要依赖开发者记得不要记录请求对象。定义允许哪些字段，然后丢弃或转换其余所有内容。

一个有用的生产事件可以包含：

{
  "request_id": "req_01J...",
  "tenant_id_hash": "tnt_7f2...",
  "workload": "support-chat-api",
  "route_policy": "support-low-risk-v3",
  "provider": "selected-provider",
  "model": "selected-model",
  "input_tokens": 842,
  "output_tokens": 211,
  "latency_ms": 1370,
  "status": 200,
  "key_version": "v12",
  "redaction_policy": "customer-support-v4"
}

默认情况下，它不应包含授权头、原始供应商密钥、完整提示词、上传的文档、未脱敏的工具参数或完整的模型输出。如果为了严格控制的评估或事件而必须捕获载荷，请将其设置为有时间边界、受访问控制，并且与常规遥测明显分离。

OWASP 日志速查表为在应用日志中排除访问令牌、密码、加密密钥及其他敏感数据提供了有用的基线。

设计零停机 API 密钥轮换

轮换只有在能够安全执行时才算是一项控制措施。若运行手册会引发停机，那么它会一直被推迟，直到紧急情况发生。

如果提供方支持重叠凭据，请使用双密钥或版本化密钥序列：

1. 创建新的提供方密钥。 施加与旧密钥相同或更严格的限制。
2. 将其存储为新的密钥版本。 如果你的平台支持版本或别名，不要原地覆盖旧值。
3. 部署可接受新版本的读取方。 更新网关或工作负载，使其解析当前别名或版本。
4. 切换流量并观察。 使用新密钥版本确认成功请求、预期模型、支出、速率限制和错误率。
5. 移除旧的使用方。 检查部署清单、作业、worker 以及灾难恢复环境。
6. 吊销旧密钥。 不要仅仅停止使用它；要在提供方处使其失效。
7. 验证拒绝。 受控测试应确认旧凭据不再可用。
8. 记录证据。 保存时间戳、责任人、受影响的工作负载、验证结果以及下次审查日期。

对于支持密钥版本选择的系统，应用程序应引用稳定别名，而不是硬编码某个密钥版本：

type ProviderCredential = {
  value: string;
  version: string;
};

async function loadProviderCredential(): Promise<ProviderCredential> {
  const activeVersion = await secretStore.resolveAlias("ai/provider/active");
  const value = await secretStore.readVersion("ai/provider", activeVersion);

  return { value, version: activeVersion };
}

不要打印 value、序列化返回对象，或将其附加到错误中。只记录非密钥的版本标识符。

OWASP Secrets Management Cheat Sheet 建议规划完整的密钥生命周期，包括创建、轮换、吊销、过期、审计、备份以及紧急访问（break-glass access）。它还强调在可行时自动化轮换。

防止密钥进入仓库和 CI 日志

一旦凭据被复制到源代码、fixture、构建产物或 CI 转录记录中，密钥管理器就无能为力了。

在三个阶段使用控制措施：

提交前

• 提供带占位符的 .env.example 文件，绝不要放入可用凭据。
• 将本地密钥文件保留在版本控制之外。
• 在 pre-commit 钩子中运行快速密钥扫描器，检查常见提供方模式和高熵值。
• 教育开发者：在后续提交中删除密钥，并不会将其从历史记录中移除。

推送和拉取请求时

• 在可用时启用仓库密钥扫描和推送保护。
• 为公共扫描器无法识别的内部网关令牌添加自定义模式。
• 要求提供有文档记录的绕过理由，并将绕过请求路由至安全审查。
• 扫描生成文件、笔记本、测试快照和基础设施计划，而不仅仅是应用源码。

GitHub 将推送保护（push protection）说明为一种在推送过程中进行扫描并在检测到密钥进入仓库之前阻止它们的方法。检测到并不是保留密钥的理由：任何已确认提交的凭据都应视为已暴露，并立即轮换。

在 CI/CD 期间

• 优先使用工作负载身份或短期联合身份验证，而不是存储的云凭据。
• 只向需要它的作业和步骤暴露密钥。
• 屏蔽已知的密钥值，但不要将屏蔽作为主要控制手段。
• 在检索密钥时关闭 shell 跟踪。
• 防止不受信任的 fork 代码访问部署密钥。
• 检查制品、缓存、崩溃转储和测试报告，防止意外捕获敏感信息。

监控使用情况，但不要记录密钥本身

良好的监控应回答“是谁使用了哪种权限？”而不记录权限本身。

跟踪：

• 工作负载、环境、租户或项目，以及密钥版本。
• 提供商、模型、路由策略和回退路径。
• 请求次数、令牌量、支出、延迟和错误类别。
• 在有用时记录源网络或部署身份。
• 对密钥管理器的访问，包括被拒绝的读取。
• 密钥创建、限制变更、轮换、吊销和删除。
• 来自意外环境、地理位置、模型或时间窗口的突然使用。

围绕行为而不仅仅是总支出设置告警。被盗的低预算密钥仍可能泄露提示词或探查内部工作流。相反，合法的批处理作业可能会造成支出激增，但并不意味着凭据被攻破。将提供商使用情况与应用请求 ID、网关策略决策、部署事件以及密钥管理器审计日志关联起来。

对于与凭据控制相辅相成的流量控制，请使用 LLM 速率限制指南 和 LLM API 回退路由实战手册。

使用从暴露到吊销的事件时钟

当密钥可能已暴露时，首要目标是遏制影响——而不是证明攻击者是否使用了它。

按以下顺序执行：

1. 声明该凭据可疑。 记录它可能在何时何地泄露。
2. 通过正常受控流程创建替代凭据。 不要为了加快事件处理而在聊天中粘贴新密钥。
3. 将合法工作负载切换到替代凭据。 使用预先准备好的轮换流程。
4. 吊销可疑密钥。 如果立即吊销会造成无法接受的损害，则在完成切换的同时隔离路径并降低限制。
5. 搜索每一个复制位置。 检查源代码历史、CI 日志、构件、容器层、支持系统、仪表板、笔记本、本地配置和备份。
6. 审查已授权的数据路径。 确定该密钥可能访问哪些提示、输出、文件、工具或模型——不仅仅是其计费范围。
7. 关联活动。 比较提供商使用情况、网关日志、部署、密钥读取和用户活动。
8. 通知正确的负责人。 根据所涉及的数据和合同，联动安全、平台、法务、隐私和客户团队。
9. 消除根本原因。 补上缺失的扫描器、限制、身份边界或日志过滤器。
10. 衡量时钟。 记录检测、替换、流量切换、吊销和验证所需的时间。

最具可操作性的指标通常是 暴露到吊销时间：在组织已获得可信的泄露证据后，可疑凭据仍可使用多长时间。缩短这一时间间隔需要预先准备好的责任归属、清单、自动化和经过测试的轮换流程，而不是更长的政策文档。

面向多提供商 AI 产品的参考架构

安全的多提供商架构可以组织为五层：

1. 客户端身份层： 在不暴露提供商凭据的情况下验证用户、设备、代理或应用程序身份。
2. 应用授权层： 验证产品权益、租户边界、功能访问和预算。
3. 数据策略层： 对提示、文件、检索到的上下文和工具参数进行分类和脱敏。
4. 网关与路由层： 选择已批准的模型，应用配额，记录非机密归属信息，并处理故障转移。
5. 提供商凭据层： 存储隔离的供应商凭据，轮换版本，并且只向受信任的路由工作负载暴露。

这种设计限制了影响范围。被入侵的客户端令牌不会自动泄露提供商密钥。被入侵的工作负载身份不应授予对所有提供商的访问权限。泄露的提供商凭据不应授权所有环境。日志记录故障不应同时暴露密钥和完整载荷。

Flatkey 的产品定位是一个与 OpenAI 兼容的端点，以及在多个模型提供商之间统一访问。这可以减少应用需要维护的特定供应商集成数量，但网关并不会免除你保护客户端身份验证、对请求数据进行分类、配置日志、分配责任人以及测试吊销的责任。请在生产上线前评估你账户和架构可用的确切控制措施。你可以从 Flatkey 集成指南 开始，并查看 当前模型访问和定价。

生产检查清单

在上线前以及每季度的控制审查期间使用此清单。

保管与身份

• 不会在浏览器、移动端、桌面端或扩展代码中交付任何长期有效的提供商密钥。
• 每个生产工作负载都有可识别的责任人和凭证路径。
• 生产、预发布、开发、评估和本地访问相互隔离。
• 尽可能用工作负载或网关身份替换共享的人类密钥。
• 提供商和网关限制被设置为尽可能窄的实际范围。

存储与交付

• 真实来源是受管理的密钥存储或受控的部署绑定。
• 应用仅在运行时获取密钥，并且不会打印或序列化它们。
• CI 作业只接收所需步骤所必需的密钥。
• 密钥访问和管理更改都经过审计。
• 紧急访问有文档记录、受时间限制并经过测试。

数据与可观测性

• 授权头和密钥值被排除在日志、追踪、错误和支持导出之外。
• 提示词、输出、文件和工具参数日志遵循允许列表模式。
• 脱敏在多提供商路由之前完成。
• 使用情况可以归因到工作负载、环境、路由、提供商、模型和密钥版本。
• 告警覆盖异常路由和身份以及支出。

轮换与响应

• 存在经过测试的双密钥或版本化密钥轮换运行手册。
• 旧密钥已在提供商处吊销，并验证为不可用。
• 密钥扫描和推送保护覆盖仓库和生成的产物。
• 一旦怀疑泄露，就会立即启动遏制措施，而不会等待滥用证据。
• 在演练和事件之后会衡量从暴露到吊销的时间。

常见问题

什么是面向 AI 产品的安全 API 密钥管理？

这是控制用于调用 AI 模型的凭证完整生命周期和请求路径的实践。它包括服务端保管、工作负载身份、最小权限、密钥存储、路由策略、提示词和日志治理、轮换、监控以及事件响应。

AI API 密钥应该存储在环境变量中吗？

环境变量可以作为一种交付机制，但它不是完整的管理系统。该密钥仍然需要受控的真实来源、受限的部署访问、轮换、审计，以及防止进程转储、日志、调试端点和继承的子进程。若平台原生密钥注入或运行时检索能更好地改善这些控制，应优先采用。

AI API 密钥应该多久轮换一次？

利用提供商的能力、你的威胁模型、合同以及内部政策来定义轮换间隔。比起随意选一个日历数字，更重要的是证明轮换是自动化或已演练的，旧密钥会被撤销，可疑密钥可以立即替换，并且过期凭证不会在无人察觉的情况下继续存在。

浏览器可以使用受限密钥直接调用 AI 提供商吗？

某些提供商支持针对特定 API 的面向客户端限制，但生产环境中的 AI 产品应假设已交付的凭证可能会被恢复。后端或网关通常能在用户授权、配额、提示词脱敏、提供商选择、滥用响应以及密钥撤销方面提供更强的控制。

一个网关密钥比多个提供商密钥更安全吗？

它可以减少应用代码中的凭证扩散，但也会将权限集中到网关上。网关凭证必须具备作用域限制、可追溯性、速率限制、监控、可轮换性，并且要防止被客户端获取。其背后的提供商凭证仍然需要隔离和生命周期管理。

如果 API 密钥出现在 Git 历史中，我们应该怎么做？

将其视为已泄露。撤销或轮换它，替换合法使用者，审查提供商和网关活动，从活动分支和相关工件中移除该值，并添加预防性扫描。重写历史并不会让仍然有效的凭证变得安全。

来源与延伸阅读

• OWASP Secrets Management Cheat Sheet
• OWASP Logging Cheat Sheet
• GitHub: 关于推送保护
• Google Cloud: 管理 API 密钥的最佳实践