API Key安全管理与轮换

API Key 怎么安全管理？轮换、限额、防泄露实战

API Key 泄露是 AI 应用里最高频的安全事故之一。OpenAI 官方帮助中心明确提醒：把 key 提交到代码仓库是最常见的凭证泄露途径，一旦出现在公网，账号可能被别人拿去刷额度，产生意外扣费甚至账户被接管。GitGuardian 的统计更扎心------公开仓库里泄露的密钥，三年后仍有约 70% 还能用。所以 key 的管理不能等出了事再补，得在一开始就做对。

还有一个常被忽略的事实：API key 没有有效期、几乎不设权限范围，一旦泄露就等于把"账户的消费能力"直接交给了陌生人。它不像密码能靠改密码兜底，key 本身是明文凭证，谁拿到谁就能用。这也是为什么各家平台都强调"一把 key 只给一个人或一种场景"，而不是全团队共用------共享 key 既违反 OpenAI 的使用条款，也会让泄露后的影响面无法收口。

存储：别把 key 写进代码

核心原则只有一条：key 永远不要出现在源码、客户端、日志里。

环境变量 是最低成本的方案。大多数 SDK（OpenAI 等）会自动读取 OPENAI_API_KEY 这个环境变量，你代码里只管 OpenAI() 即可，不用显式传 key。

python 复制代码

import os
from openai import OpenAI

# SDK 自动读取 OPENAI_API_KEY，代码里不出现明文
client = OpenAI()
resp = client.chat.completions.create(
    model="YOUR_MODEL",
    messages=[{"role": "user", "content": "你好"}],
)
print(resp.choices[0].message.content)

本地开发用 .env 文件，记得把它加进 .gitignore，配合 python-dotenv 加载。密钥管理器是生产环境的标配：AWS Secrets Manager、HashiCorp Vault、Google Secret Manager 这类服务把凭证存在独立位置，运行时才注入，即使代码或镜像泄露，key 也不会跟着出去。它们还顺带提供加密、访问审计和自动轮换能力。

客户端（浏览器、App）里绝不能放 key。任何前端代码都能被用户看见，必须让请求走你自己的后端，由后端持有 key 去调大模型。

用虚拟 Key 做额度与权限隔离

直接把厂商主 key 分发给各个业务、同事、客户，一旦其中一个泄露，你只能整体作废，影响面巨大。更好的做法是架一层接入层，对外发"虚拟 Key"，后端统一持有真实 key。代表方案有 LiteLLM 等（思路一致：自建接入层 + 虚拟密钥 + 额度控制）。

这类接入层的价值不止省 key。它们把真实凭证收口在一处，对外暴露的只是一把把可随时吊销、带预算和模型白名单的虚拟 Key；每把 Key 的消费、限流、调用方都被记录下来，相当于给大模型调用加了一层账号体系和审计面。对有多业务线、要对客户按量计费或做租户隔离的团队，这套结构几乎是必选项。即便暂时不上接入层，至少要做到主 key 只在服务端保留一份，其余环境一律用受限子 key。

下面用 LiteLLM Proxy 演示：管理员用主 key 生成一把虚拟 Key，给它限定可用模型、月度预算、请求频率，应用侧只拿这把虚拟 Key 去调用。

bash 复制代码

# 用主 key 生成虚拟 key，带额度与限频
curl -X POST 'http://localhost:4000/key/generate' \
  -H 'Authorization: Bearer YOUR_MASTER_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "models": ["gpt-4o", "deepseek-v4-flash"],
    "max_budget": 50.0,
    "budget_duration": "30d",
    "rpm_limit": 60,
    "tpm_limit": 100000,
    "duration": "90d"
  }'

应用侧拿到返回的虚拟 Key，像普通 key 一样用，但背后受预算和限频约束：

python 复制代码

from openai import OpenAI

# sk-xxx 是 LiteLLM 发的虚拟 Key，真实厂商 key 只在接入层里
client = OpenAI(
    api_key="YOUR_VIRTUAL_KEY",
    base_url="YOUR_BASE_URL",   # 指向接入层地址，如 http://localhost:4000/v1
)
resp = client.chat.completions.create(
    model="YOUR_MODEL",
    messages=[{"role": "user", "content": "总结这段日志"}],
)
print(resp.choices[0].message.content)

预算跑满后请求会被接入层拒绝（返回 budget exceeded），额度不会无限烧。你还可以给不同团队、环境发不同的虚拟 Key，一把泄露只作废一把，blast radius 被锁死。

定期轮换 + 最小权限

OpenAI 官方建议：每个团队成员用各自独立的 key，不要把一把 key 多人共享；同时按固定节奏轮换------生产 key 大致 90 天一轮，开发 key 30 天一轮，有人离职立即轮换。

LiteLLM 支持自动轮换，在生成虚拟 Key 时打开 auto_rotate 并设 rotation_interval 即可，老 key 还能通过 grace_period 保留一段过渡期，实现无停机切换：

bash 复制代码

curl -X POST 'http://localhost:4000/key/generate' \
  -H 'Authorization: Bearer YOUR_MASTER_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"models": ["gpt-4o"], "auto_rotate": true, "rotation_interval": "30d"}'

最小权限贯穿始终：一把 key 只给当前业务必需的模型、必需的环境；在厂商后台设好月度支出硬上限和告警阈值（如 50% / 80% / 100%）；不同项目用 project-scoped key 隔离，开发 key 泄露不会波及生产。

落到团队管理上，建议按"人 / 环境 / 业务线"三维拆 key：每个成员一把个人 key（离职即吊销，不影响他人），开发、预发、生产各用独立 key（生产 key 绝不下放给本地调试），不同产品线用各自 project 隔离消费与模型白名单。这样任何一把 key 出事，影响都被锁在最小范围，审计时也能直接对到人和服务。OpenAI 官方也明确不建议多人共享同一把 key，而是邀请成员加入账户、各自领取独立 key 并分别赋权。

日志审计不能少

没有审计，泄露可能几周都没人发现。OpenAI 官方建议定期在 Usage 页面核对用量，留意非工作时间的异常调用、平时不用的模型突然被调。用 LiteLLM 这类接入层时，可开启审计日志（store_audit_logs: true），每把虚拟 Key 的调用、消费、限流都会被记录，出事能直接定位到哪把 key、哪个调用方。CI 里加一个密钥扫描（如 detect-secrets、TruffleHog）作为 pre-commit 钩子，能在提交前拦住明文 key。detect-secrets 通过 pip install detect-secrets 安装后生成基线，后续每次提交比对差异；TruffleHog 还能对接 Git 历史做全量回溯扫描，并带 OpenAI 校验器确认 key 是否仍然有效。GitHub 自身的 Secret Scanning 则会在检测到 OpenAI key 时直接通知平台做联动处置。把扫描接进 pre-commit 和 CI 两道关卡，能从"提交前"和"合并前"两端堵住泄露。

把整套策略也落成一份可执行的 runbook：谁有权发 key、轮换周期怎么排、泄露时第一步打给谁、吊销入口在哪。安全流程最怕"人人知道但没人负责"，把动作写死成清单，出事时才能不靠临场发挥。

泄露后的应急处理

怀疑或确认 key 已经泄露，按这个顺序做：

先吊销，再排查。OpenAI 官方明确说：发现泄露不要先调查，先去 API Keys 页面删掉那把 key。等待确认的那几分钟，账号可能已经被刷了。
查用量与账单。在 Usage / Billing 页面看有没有非你发起的请求、异常时间段的调用、平时不用的模型，确认损失范围。
清 git 历史 。如果 key 提交过仓库，光删文件不够------它还在历史提交里。用 git-filter-repo 或 BFG Repo-Cleaner 从完整历史里擦掉，再强制推送。
发新 key 并设限。重新生成 key，立刻在后台设支出上限，存进环境变量或密钥管理器，绝不写回代码。
补监控。加上预算告警和密钥扫描，避免第二次。

补充一点：OpenAI 会在公网或应用商店里扫到泄露 key 时自动停用它，但这只是兜底、不能依赖------自动扫描有延迟，坏人往往几分钟内就把额度刷光。主动权始终在你手里，发现即吊销才是最快止血的方式。

快速排错表

现象	可能原因	处理
账单出现陌生高额扣费	key 泄露被滥用	立即吊销 + 查用量
公开仓库搜到自己 key	误提交明文	吊销 + 清 git 历史
前端请求 401 但 key 是对的	key 被写进客户端暴露	改为后端代理调用
虚拟 Key 突然全失败	预算 `max_budget` 跑满	调高预算或等周期重置
轮换后部分服务报错	老 key 仍被引用	确认全部实例已切到新 key
CI 卡住提示 secret	pre-commit 扫出 key	移出代码改用环境变量

配置检查清单

key 只存在于环境变量或密钥管理器，源码 / 镜像 / 日志均无明文
.env 已加入 .gitignore，本地加载走 python-dotenv
浏览器 / App 等客户端不直接持有 key，请求经自有后端
对外分发使用虚拟 Key（LiteLLM 等），并设预算与限频
每把 key 限定最小必要模型与权限范围
厂商后台已设月度支出硬上限与多级告警
生产 key 按约 90 天、开发 key 约 30 天定期轮换
启用审计日志（如 LiteLLM store_audit_logs）与 CI 密钥扫描
制定泄露应急流程：先吊销 → 查账 → 清历史 → 换新 key → 补监控