API Key 的安全问题,基本上不是“配置项怎么写”的问题,而是“谁能拿到这把 Key”。如果调用方是浏览器页面、移动端 App、桌面客户端或任何用户能接触到的环境,那么无论你把 Key 放在配置文件、混淆字符串还是加密字段里,最终都可能被取出来。可用的判断标准只有一条:Key 是否只在你可控的服务端进程里出现。做不到这一条,剩下的参数调优意义有限。
API Key 的安全边界在于“谁能拿到”,与填写位置无关。只要调用方是浏览器、App 或不可信客户端,Key 就不应下发给客户端;建议把 Key 放在服务端进程的环境变量或密钥管理里,前端只持有自己的登录凭证,由服务端转发调用。判断是否做对看三点:打包产物里搜不到 Key、前端请求头里没有鉴权 Key、Key 的模型权限和额度被单独限制。暂时做不到时,先加额度上限和轮换机制过渡。
先确认当前场景和目标
动手前先把下面几件事确认清楚,否则很容易配出一个“看起来安全”的方案。第一,Key 的持有人是谁:只有你自己的服务端进程,还是也包括浏览器、App、合作方脚本、某个同事的本地环境。第二,调用方是否可约束:来自内网的定时任务,和来自公网任意用户的请求,处理方式完全不同。第三,这把 Key 在供应商侧能否设置权限范围,比如限定可用模型、设置消费上限、限定来源 IP,不同平台的支持程度不一样,需要到控制台确认。第四,Key 泄露后能不能快速轮换,以及有多少地方需要同步改。
目标也要说清楚:如果你只是自己本地跑脚本,把 Key 放进本机环境变量、不提交到代码库就够;如果是要给前端或 App 提供 AI 能力,那目标就是“客户端永远拿不到 Key”,这基本意味着必须加一层服务端转发。判断条件可以简化成一句:只要请求的发起方不是你独占的机器,就按需要转发层来设计。

按这个顺序处理
顺序上建议从“Key 放在哪”开始,再处理“谁能用”,最后处理“出事怎么办”,反过来做容易返工。
- 把 Key 移出代码仓库和前端产物。存放在服务端环境变量或密钥管理服务里,进程启动时读取,缺失就直接启动失败,避免带着空 Key 跑起来却在上游报错。本地开发用各自的
.env,把.env、*.local写进.gitignore。 - 加一层服务端转发。前端只带自己的登录凭证(Session、JWT 之类)调用你自己的接口,由服务端在请求头里补上
Authorization或x-api-key。这样 Key 的生命周期和你的账号体系绑定。 - 一把 Key 一个用途。测试和生产分开,不同应用分开,不同人分开。共用一把 Key 时,一旦泄露你无法判断来源,也无法只停掉其中一处。
- 在供应商侧收缩权限。能配模型白名单就配,能设消费上限就设,能限制来源 IP 就限制到你服务端的出口地址。转发层自己也做一次模型名校验,避免调用方直接透传任意模型名。
- 不要放进 URL 参数。Query String 会进访问日志、浏览器历史和 Referer,只走请求头。
- 日志脱敏。打印请求头时把
Authorization、x-api-key、api-key统一打码;上游的错误响应不要原样返回给前端,避免响应体里带回账号或配额信息。
下面是一个最小的转发骨架,用通用写法示意,实际路径和字段按你所用的接口调整:

# .env 只放在服务器上,不进仓库
AI_API_KEY=替换成你自己的密钥
AI_API_BASE=https://你的接口域名/v1
import os, httpx
from fastapi import FastAPI, Request, HTTPException
app = FastAPI()
KEY = os.environ["AI_API_KEY"] # 启动时读取,缺失即启动失败
BASE = os.environ["AI_API_BASE"]
ALLOWED_MODELS = {"你的模型名A", "你的模型名B"}
@app.post("/ai/chat")
async def chat(request: Request):
body = await request.json()
if body.get("model") not in ALLOWED_MODELS:
raise HTTPException(400, "model not allowed")
async with httpx.AsyncClient(timeout=60) as client:
resp = await client.post(
f"{BASE}/chat/completions",
headers={"Authorization": f"Bearer {KEY}"}, # Key 只在这一处出现
json=body,
)
if resp.status_code >= 400:
raise HTTPException(502, "upstream error") # 不回传上游原文
return resp.json()
改完后怎么验证
验证的重点是“找得到 / 找不到”,不是跑一次成功就结束。可以做这几个动作:

- 在前端打包产物里搜索 Key 的片段(取 Key 中一段有辨识度的字符去搜),预期结果是零命中。如果搜到了,说明注入方式没改干净。
- 打开浏览器开发者工具的 Network 面板,触发一次 AI 请求,看请求头里是否出现
Authorization或x-api-key。预期只看到你自己的登录凭证,看不到供应商 Key。 - 故意用一个错误的 Key 启动服务,确认服务端是否直接启动失败或明确报错,而不是静默返回空结果。
- 用不在白名单里的模型名调用一次转发接口,预期被自己的服务拒绝,而不是透传到上游。
- 翻一遍服务端日志,搜索 Key 的前几位,预期日志里只有打码后的形式。
- 在测试环境把 Key 换成新的一把,重启服务后确认新 Key 生效、旧 Key 在供应商侧已停用。这一步能暴露“某个地方还硬编码着旧 Key”。
预期信号是:客户端侧看不到 Key、服务端侧只有一处引用、换 Key 只需要改一个环境变量。如果换 Key 需要改多处代码或通知多人,说明还没收敛好。
容易忽略的边界
- 客户端内置 Key 无法真正保密。移动端和桌面端可以被逆向,往里面塞 Key 只能当作“公开信息”处理,最多靠供应商的额度限制兜底。
- 短期凭证方案不是每家都有。如果供应商不提供临时 Token 或前端直连的安全模式,就只能自建转发,没有别的折中。
- 环境变量并非绝对隔离。同一台机器、同一个容器里的其他进程可能读到环境变量;多租户或共享主机需要更细的权限隔离,这时用独立的密钥管理服务更稳妥。
- 转发层会引入新的问题。流式响应、超时、重试都要自己处理,长连接和取消请求容易出问题,上线前要单独验证流式返回是否正常。
- 停用 Key 不等于立刻全断。已经建立的连接、缓存过的响应、客户端本地缓存的会话不会同步失效,评估泄露影响时要考虑这个时间差。
- 回退方案要提前想。如果短期内搭不了转发层,至少先给 Key 设置消费上限、限定模型和来源地址,并准备一个缩短轮换周期的流程。这只是止血,不解决客户端暴露 Key 的根本问题。
另外,如果请求内容集中到你自己的服务器再转发,日志留存和数据范围会变化,涉及用户内容的部分要按所在环境的合规要求单独确认。