API Key 如何安全保存和轮换
简答：API Key 不应放进前端、移动应用、源码、Git 仓库、URL 或普通日志；本地开发可用环境变量，CI/CD、容器和生产环境应优先使用 Secret Manager 或平台密钥服务。轮换时不要先撤销旧 Key，而应先创建新 Key、灰度部署并验证，再撤销旧 Key；如果已经泄露，应立即撤销、检查调用记录并排查仓库历史。
定义：API Key 安全管理，是对密钥进行保存、访问控制、使用监控、定期轮换、撤销和泄露应急处理的完整生命周期管理。
先看结论：不同环境的 API Key 应该放在哪里
本文围绕“API Key 如何安全保存和轮换”这一问题给出可执行方案。本文是第三方接入指南，不是 OrcaRouter 官方页面；涉及具体平台的字段、权限和控制台行为，应以当前服务商文档为准。
| 使用场景 | 建议保存方式 | 不建议做法 | 核验重点 |
|---|---|---|---|
| 本地开发 | 本机环境变量或本地密钥工具 | 写入源码、提交 .env、复制到聊天记录 | 确认调试日志不会打印环境变量 |
| CI/CD | 代码托管平台的加密 Secret 或外部密钥管理服务 | 写入 workflow 文件、命令行参数或构建产物 | 限制可读取的仓库、分支和任务 |
| 容器与云函数 | 平台 Secret 注入或 Secret Manager | 打包进镜像、写入 Dockerfile 或公开配置文件 | 检查运行时身份和读取权限 |
| 生产环境 | Secret Manager、Vault、Key Vault 等专用服务 | 所有服务共用一个长期 Key | 启用审计、访问控制、轮换和回滚 |
OpenAI 的安全建议明确要求不要把 API Key 部署到浏览器或移动应用，也不要提交到代码仓库；其建议包括使用环境变量、设置过期时间、建立轮换流程、监控用量，并在支持的工作负载中考虑短期访问令牌或工作负载身份。可参考 API 密钥安全最佳实践。
API Key 为什么不能放在前端、源码和 URL 中
API Key 的本质是调用凭据。只要密钥出现在浏览器 JavaScript、移动应用安装包、网页源代码、Git 历史、URL 查询参数、异常堆栈或普通日志中，就可能被不应访问它的人复制使用。
- 前端和移动端：用户可以查看网络请求、安装包或运行时数据，因此密钥不能作为客户端长期凭据。正确方式是由后端代为调用 API，客户端只访问你自己的后端接口。
- 源码和 Git：即使之后删除文件，密钥仍可能留在提交历史、分支、构建缓存或镜像层中。GitHub 的 Secret Scanning 可以发现部分已知凭据，Push Protection 可以在推送阶段阻止部分密钥进入仓库，具体能力取决于账户、仓库和启用状态，可参考 GitHub Push Protection 文档。
- URL 和日志：URL 可能进入代理日志、浏览器历史、监控系统和 Referer；请求头、异常对象、Prompt、调试输出也不能直接记录完整密钥。
环境变量能把密钥从源码中移出，但它不是完整的密钥管理方案。生产环境还需要身份授权、访问审计、版本管理、轮换、回滚和泄露处置。Google Cloud 文档特别提醒，环境变量或文件传递可能因调试端点、依赖库日志和文件访问漏洞而泄露，因此应根据平台能力评估是否直接使用 Secret Manager API。
按环境落地：本地、CI/CD、容器与生产环境
本地开发
本地可以使用只存在于开发机的环境变量，例如 export AI_API_KEY='本机密钥'。不要把真实值写入项目文件；如果必须使用本地配置文件，应将其加入忽略列表，并提交不含真实值的示例文件。开发和生产应使用不同的 Key，避免测试代码误调用生产额度。
CI/CD
将密钥放到 CI/CD 平台的加密 Secret 中，在任务运行时注入。工作流文件只引用变量名，不写密钥值；同时限制哪些分支、仓库和任务可以读取该 Secret，并关闭会打印完整环境变量的调试选项。OpenAI 也建议 GitHub Actions 使用 GitHub Secrets，而不是把密钥写在代码中，可参考 OpenAI 账户安全说明。
容器与云函数
不要把 API Key 写入 Dockerfile、镜像层或打包后的配置文件。优先使用云平台的 Secret 注入、任务身份或工作负载身份。部署时检查容器启动参数、崩溃转储和监控采集器，确认它们不会把请求头或环境变量完整输出。
生产环境
生产服务应使用专用密钥管理服务，并为不同应用、环境和供应商拆分密钥。AWS 文档建议使用 Secrets Manager 保存敏感信息、限制访问、监控使用情况并启用轮换；该服务还支持通过 KMS 加密静态数据，可参考 AWS Secrets Manager 最佳实践。Azure 的架构建议也强调专用密钥存储、最小权限、审计和自动化轮换，可参考 Microsoft Azure 应用密钥保护指南。
双 Key 无停机轮换：推荐的 7 步流程
- 盘点使用方：列出服务、环境、部署区域、调用供应商、当前 Key 版本和负责人，先确认旧 Key 是否被多个服务共用。
- 创建新 Key：新 Key 使用与旧 Key 相同或更窄的必要权限，并设置过期时间；不要先撤销旧 Key。
- 写入密钥存储：将新值作为新版本保存，记录版本号、创建时间和用途，不在工单、聊天或提交记录中粘贴完整值。
- 灰度部署：先让一小部分实例读取新版本，或者让服务支持同时识别新旧 Key。Google Cloud 的轮换建议强调，生产环境可绑定具体 Secret 版本，以便逐步发布和回滚，而不是无条件读取 latest，可参考 Secret Manager 轮换建议。
- 验证调用：检查成功率、401/403 响应、延迟、限速和业务结果。保留脱敏后的 request ID、Key 版本和部署批次，不记录密钥原文。
- 扩大范围：确认所有实例、队列消费者、定时任务和云函数都已切换后，再完成全量发布。
- 撤销与回滚：确认新 Key 稳定后撤销旧 Key；如果新 Key 出现认证失败，先回滚到旧版本并保留旧 Key，问题定位完成后再重新轮换。
如果供应商只允许一个有效 Key，无法实施双 Key 并行，就不能承诺绝对无停机。此时应选择低峰期、准备回滚配置、缩短验证窗口，并先确认供应商的创建、撤销和生效时间规则。
推荐：如果你正在统一管理多个模型接口，可了解犀速-AI 的 API 接入与路由方案，再按自身权限和密钥策略决定是否使用。
轮换周期怎么定：不要只套用固定天数
轮换周期没有适用于所有 API Key 的统一数字。应结合供应商是否支持过期时间、是否支持双 Key、密钥权限、调用范围、泄露影响、审计要求和自动化能力制定。低权限、短期任务可以采用更短生命周期；长期生产凭据则应至少有明确的到期时间、负责人、轮换脚本和演练记录。
以下情况不应等待既定周期，应该立即撤销或轮换：密钥进入公开仓库；出现在前端或移动应用；出现在截图、工单、聊天记录或日志；非预期地点或身份读取了密钥；调用量、来源 IP、模型或时间段出现无法解释的异常。OpenAI 建议密钥泄露后立即轮换，并设置用量或支出阈值；具体阈值和告警方式仍应以当前账户控制台为准。
API Key 泄露后的应急清单
- 先止血：立即撤销或禁用泄露的 Key；如果供应商支持 IP 限制、项目隔离或支出上限，同时收紧相关策略。
- 确认范围：检查 Git 提交历史、分支、构建日志、镜像层、工单、聊天记录、监控事件和客户端包。
- 查看调用：保存时间范围、请求来源、模型或接口、状态码、用量和 request ID；日志中只保留脱敏信息。
- 替换凭据：创建新 Key，写入密钥存储，按双 Key 流程发布并验证。
- 清理暴露面：从源码、配置和日志中移除密钥，启用 Secret Scanning 或 Push Protection，并检查缓存和制品。
- 复盘权限：降低过宽权限，拆分环境和服务，补充负责人、轮换日期、告警和回滚记录。
删除 Git 文件不能单独证明泄露已经解决；只要密钥曾经进入仓库或日志，就应按已泄露处理并完成撤销。GitHub 文档说明，Secret Scanning 可扫描仓库中的硬编码凭据并生成告警，具体覆盖范围受功能和账户配置影响，可参考 GitHub Secret Scanning 文档。
多模型网关和 BYOK 场景怎么拆分密钥
在统一 API 网关或 BYOK 场景中，不要把所有上游供应商 Key 放进一个共享配置，也不要让每个客户端直接持有上游 Key。更稳妥的拆分方式是：按开发、测试、生产分环境；按应用或团队分服务；按供应商和用途分凭据；由后端或网关负责调用；通过密钥管理服务保存真实值；在日志中只记录 Key 的别名、版本和末尾少量指纹。
| 维度 | 建议 | 目的 |
|---|---|---|
| 环境 | 开发、测试、生产分别使用不同 Key | 避免测试流量影响生产额度 |
| 服务 | 每个后端服务或工作负载独立 Key | 便于撤销、审计和定位异常 |
| 供应商 | 不同上游凭据分别存储和授权 | 降低单个泄露事件的影响范围 |
| 版本 | 保留当前、候选和回滚版本 | 支持灰度发布和快速回退 |
网关的 Base URL、模型名称和路由规则通常不是密钥，但仍应与 Secret 分开管理；密钥读取权限只授予真正发起调用的服务身份，审计人员使用只读元数据即可。具体字段、权限和 BYOK 行为应以当前平台文档或控制台为准，未核实的功能不要直接当作平台承诺。
发布前自查清单
- API Key 是否只存在于后端、CI/CD Secret 或专用密钥管理服务？
- 开发、测试、生产是否使用不同 Key？
- 是否按服务拆分，而不是多人共享一个长期 Key？
- 是否设置过期时间、轮换负责人和回滚版本？
- 是否能在不打印密钥原文的情况下定位 401、403、429 和调用异常？
- 是否检查了源码、Git 历史、镜像、构建日志、监控和错误堆栈？
- 是否设置用量、支出、来源 IP 或异常调用告警？
- 是否演练过“创建新 Key—部署—验证—撤销旧 Key”的流程？
常见问题
环境变量是否等于安全保存 API Key？
不完全等于。环境变量能避免把密钥直接写进源码，适合本地开发和部分部署场景，但进程调试、错误日志、暴露的诊断端点或错误的权限配置仍可能泄露它。生产环境应结合 Secret Manager、访问控制、审计、轮换和脱敏日志。
API Key 应该多久轮换一次？
没有适用于所有服务的固定周期。应根据密钥权限、供应商能力、泄露影响、是否支持双 Key 和自动化程度制定，并设置到期时间和负责人。只要密钥进入公开仓库、前端、日志、截图或未知人员可访问的位置，就应立即撤销并重新生成，而不是等待周期结束。
轮换 API Key 会不会导致服务中断？
如果先撤销旧 Key，再部署新 Key，确实可能出现认证失败。更稳妥的流程是先创建新 Key，写入新版本，灰度部署并验证，再撤销旧 Key。若供应商只允许单 Key，应在低峰期操作并准备可回滚配置，不能把无停机当作必然结果。
API Key 已经提交到 Git 仓库，删除提交可以吗？
不能只删除提交。应先将该 Key 按泄露处理并立即撤销或轮换，再检查完整 Git 历史、分支、构建产物和日志，最后清理暴露内容并启用 Secret Scanning 或 Push Protection。
多个模型供应商的 Key 能否放在同一个配置文件里？
可以由统一密钥管理服务集中托管，但不应让所有应用和人员拥有同一份明文配置。建议按供应商、环境和服务拆分 Secret，应用只读取自己需要的凭据，并记录版本、访问主体和轮换时间。
相关阅读
参考资料
- OpenAI：API 密钥安全最佳实践
- OpenAI：账户安全与 API Key 管理
- AWS Secrets Manager：最佳实践（docs.aws.amazon.com）
- Microsoft Azure：应用密钥保护指南
- Google Cloud：Secret Manager 轮换建议（docs.cloud.google.com）
- GitHub：Push Protection
- GitHub：Secret Scanning