API 密钥安全:泄露从哪里发生,防护该按什么顺序做
API 密钥通常是无第二因素的长期凭证,泄露后可直接被第三方冒用。风险主要来自前端代码、仓库与 CI 日志、URL 与错误上报、工单截图等扩散面。防护应按顺序收敛:密钥不进客户端、按调用方拆分并最小授权、让泄露可被发现、提前准备轮换与撤销流程。本文不包含对任何平台控制台的实测,具体能力以官方文档为准。
API 密钥泄露的后果,通常比密码泄露更直接:它一般没有第二因素,没有登录地点提示,也不会触发“异地登录”这类告警,拿到字符串就能调用。防护的重点因此不是“保管得更小心”,而是缩小暴露面、让每个密钥可界定、可撤销、可观测。
泄露从哪里发生#
多数事故并不来自被攻破的服务器,而来自密钥出现在不该出现的地方:
- 客户端包:前端 JS、移动端、小程序包被反编译或直接查看网络请求,硬编码的密钥等于公开。
- 仓库与 CI 日志:提交历史、构建输出、调试打印、CI 变量回显。
- URL 与错误上报:把密钥拼进查询串,随后被访问日志、代理日志、APM 与异常平台原样收走。
- 人:工单截图、聊天记录、文档表格、共享的
.env文件。 - 依赖与脚本:第三方 SDK、示例代码、临时抓包脚本把密钥落盘。
按顺序做的四层防护#
第一层:密钥不出服务端
浏览器和移动端只调用你自己的后端,由后端持有密钥并转发请求。若某个 API 必须在客户端直连,需要换用面向公开客户端的设计(如短期令牌、按用户授权),而不是把长期密钥发下去。NEXT_PUBLIC_、VITE_ 这类前缀的环境变量会被打进产物,等同于公开。
第二层:每个密钥可界定
- 按调用方拆分:一个服务、一个环境、一个用途各一把,便于单独撤销而不影响其他系统。
- 最小权限:只开需要的接口范围与配额;能只读就不要给写权限。
- 可归因:密钥带标签(负责人、环境、创建时间),并记录在密钥管理服务或配置中心,而不是散落在聊天记录里。
第三层:让泄露能被发现
- 在提交前与 CI 中做密钥模式扫描,拦截误提交;历史提交里发现过的密钥要视为已泄露,直接轮换。
- 日志与错误上报统一脱敏:请求头、查询串、响应体在落盘前过滤敏感字段。
- 监控用量异常:调用量突增、来源 IP 或地区突变、出现从未用过的接口,都是值得告警的信号。
第四层:提前准备轮换与撤销
密钥必须能换。可行做法是同时持有新旧两把密钥,先让调用方切到新密钥,确认旧密钥无流量后再停用;否则出事时只能全量停机。撤销流程要写下来:谁能撤、撤销后哪些服务受影响、如何通知。缺少这套流程时,团队往往会在泄露后拖延数小时才处理。
一个最小的后端代理示例#
下面的结构只解决“密钥留在服务端”这一件事,未执行,仅作示意;实际需按所用框架和 SDK 调整,并对转发路径做白名单,避免变成任意请求的开放代理。
// 未执行示例:仅示意结构
import express from "express";
const app = express();
// 真实值放在密钥管理服务或部署环境变量中,不写入仓库
const KEY = process.env.API_KEY;
// 占位地址,非真实端点
const UPSTREAM = "https://api.example.com/v1";
const ALLOWED = new Set(["weather", "geo"]);
app.get("/api/:name", async (req, res) => {
if (!ALLOWED.has(req.params.name)) return res.status(404).end();
const r = await fetch(`${UPSTREAM}/${req.params.name}?${new URLSearchParams(req.query)}`, {
headers: { Authorization: `Bearer ${KEY}` },
});
res.status(r.status).type("application/json").send(await r.text());
});
边界与待核实项#
本文讨论的是通用工程实践,不包含对 API.PLUS 控制台的实测,也不涉及具体定价或性能。密钥有效期、配额、IP 白名单、按密钥限额与撤销生效时间等能力,各家实现差异较大,需以官方文档为准;本文发布时未能核验这些细节,标注为待核实。
一条可执行的判断标准是:如果今天这把密钥被贴到公开仓库,你能否在十分钟内定位影响范围并完成替换?不能,就说明防护还停在“保管”层面。