API 密钥安全:先让泄露可控,再谈怎么藏
API 密钥的关键判据不是藏得多好,而是泄露后能否快速失效、损失上限是否可控。文章按暴露面梳理泄露路径,给出分环境分调用方、服务端代理出口、额度上限、日志脱敏与轮换预演等做法,并把泄露后的处置顺序确定为先吊销再取证。API.PLUS 是否提供子密钥、额度上限等能力,需以官方文档为准。
- 密钥一旦随请求进入终端设备,就等于公开;混淆和打包压缩不构成保护。
- 泄露后的第一动作是吊销,而不是先排查;排查需要时间,吊销立即生效。
- 每枚密钥绑定单一环境和调用方,是把轮换成本与爆炸半径同时压下来的前提。
先给结论:API 密钥安全的第一判据不是“藏得好不好”,而是泄露之后多久能失效、损失上限是多少。把这两个问题答清楚,防护动作才有优先级;只讨论隐藏方式,通常会在第一次真实泄露时全部失效。
本文讨论与具体平台无关的通用做法。API.PLUS 是否提供子密钥、单密钥额度上限、来源限制或用量明细等能力,本次材料未提供,需以官方文档为准;下文涉及平台能力的地方会明确标出。
先分清密钥承担的两类风险#
同一枚密钥往往同时是两种东西:身份凭证(证明请求来自谁)和计费入口(按调用量产生费用)。二者的处置逻辑不同:身份被冒用要看它能读到什么,计费被透支要看额度有没有上限。很多泄露事故的损失集中在后者——攻击者不需要理解业务,只需要循环调用。
按暴露顺序盘点泄露面#
有一个简单判据:如果密钥会随请求出现在终端用户的设备上,它就已经是公开的。打开浏览器开发者工具的 Network 面板能看到,就说明任何用户都能看到。打包压缩、变量名混淆、Base64 编码都不改变这个事实。
| 暴露面 | 典型形态 | 终端用户可见 |
|---|---|---|
| 前端与客户端包体 | 打包产物中的常量、移动端包体、桌面端分发包 | 是 |
| 版本库与历史 | 配置文件误提交、示例文件里的真实值 | 取决于仓库可见性,删除提交不等于删除历史 |
| 日志与错误上报 | 完整请求头被打印、APM 采集、工单截图 | 否,但扩散范围不可控 |
| CI/CD 与构建缓存 | 流水线变量、构建产物、镜像层 | 否,但可被有仓库权限者读取 |
| 第三方中转与代理 | 把密钥交给非自控的转发服务 | 否,但等于把凭证托管给他人 |
四个优先动作#
- 每枚密钥绑定单一环境和单一调用方。开发、预发、生产分开,不同服务分开。这不是洁癖:它同时压低了爆炸半径和轮换成本——轮换一枚只影响一个调用方,才可能真的定期做。
- 密钥只出现在服务端,客户端走自建出口。浏览器和移动端调用自己的后端,由后端持有上游密钥。下面是一个仅示意形态的转发骨架,未执行,运行环境需自行替换。
- 给每枚密钥设额度上限和可观测维度。如果平台支持按密钥维度的用量统计与配额,就一定要开;不支持的,需要在自建出口按密钥记账。
- 提前演练一次吊销。知道吊销入口在哪、多久生效、会影响哪些调用方——这三件事在事故当下现查,代价通常比演练高得多。
// 未执行的示例:仅示意“密钥只留在服务端”的转发形态
// 适用环境:支持 env 绑定的边缘运行时(如 Cloudflare Workers);其他运行时需改写
export default {
async fetch(request, env) {
const url = new URL(request.url);
if (url.pathname !== "/v1/echo") {
return new Response("Not Found", { status: 404 });
}
const upstream = await fetch("https://api.example.com/v1/echo", {
method: "POST",
headers: {
// UPSTREAM_API_KEY 由运行时的环境变量注入,不进代码库
"authorization": `Bearer ${env.UPSTREAM_API_KEY}`,
"content-type": "application/json",
},
body: await request.text(),
});
return new Response(upstream.body, { status: upstream.status });
},
};
注意这个骨架只演示了密钥位置,没有做鉴权、限流和响应过滤。真实出口还需要决定“哪些请求允许转发”,否则代理本身会变成新的滥用入口。示例中的 api.example.com 与 YOUR_KEY 均为占位。
日志与错误上报的脱敏#
这是最容易被忽略的一环:密钥没有提交到代码库,却出现在日志平台的请求头快照里。做法是在采集层做白名单而非黑名单——只记录明确列出的字段,而不是“把看起来像密钥的都删掉”。黑名单总会有漏项,白名单不会。
泄露之后:先吊销,再取证#
顺序值得单独强调。排查需要时间,吊销立即生效,而这段时间里的每一次调用都在计费。先吊销或轮换,再回头确认泄露路径,是损失最小的做法。吊销之后再做的三件事:
- 按密钥维度拉取用量,确认异常调用的时间窗与调用量;若平台不提供该维度明细,只能退化为服务端出口侧的日志。
- 定位泄露路径,判断是同一枚密钥在多处复用(常见)还是单点泄露。
- 检查同批次签发的其他密钥是否也需要轮换。
检测信号#
用量曲线出现阶跃、调用来源突然变化、失败率骤升(常见于密钥已失效但调用方未更新),这三类信号通常在账单之前出现。前提是密钥的用量是可分维度观测的——如果所有调用共用一枚密钥,这些信号会被正常流量淹没。
边界#
本文给出的是与平台无关的通用实践。具体到 API.PLUS,子密钥、额度上限、来源限制、用量明细与吊销生效时间等能力,本次材料未涵盖,需查阅官方文档后据实调整;在没有确认之前,不应假定某项保护已经存在。