API 密钥安全：泄露入口、判定边界与服务端防护实践
API 密钥应默认放在服务端，并假定它可能泄露：先把密钥从浏览器、URL、日志和仓库历史中移除，再让它可分环境、可撤销、可轮换。判定泄露看的是密钥是否出现在未授权者可读的位置，而不是它有没有被滥用。API.PLUS 是否提供分项目密钥、有效期、审计或告警能力，本文材料未提供，需以官方文档核实。
- 密钥泄露的判定标准是暴露位置，而非是否已产生异常调用。
- 前端打包产物、URL 参数、CI 日志和错误上报是最容易被忽略的四个入口。
- 轮换能否安全执行，取决于是否先有一份调用方清单。
API 密钥的安全性不能靠“小心保管”来保证。更可操作的默认假设是：密钥可能已经泄露，因此工程上要做的是限制它出现的位置、缩短它的有效窗口、并在泄露发生后能定位影响范围。本次材料只提供了主题标题，没有 API.PLUS 的具体机制说明，涉及平台能力的地方下文会标注待核实。
密钥通常从哪些位置漏出去#
泄露很少来自“被黑客攻破”，更多来自开发者把密钥放在了不该放的地方。以下位置值得逐一自查：
| 位置 | 暴露方式 | 处理方向 |
|---|---|---|
| 浏览器或移动端代码 | 打包产物、反编译、开发者工具网络面板 | 改为请求自建服务端，由服务端持有密钥 |
| 代码仓库历史 | 提交记录、分支、fork、CI 日志 | 启用 secret scanning，历史中的密钥按已泄露处理 |
| URL 查询参数 | 代理日志、浏览器历史、Referer、截图 | 改用请求头传递 |
| 错误上报与调试输出 | 异常堆栈、请求体快照、工单附件 | 上报前脱敏，禁止打印完整请求头 |
这四类入口的共同点是：一旦密钥进入，撤回成本远高于当初避免它的成本。尤其是仓库历史，删除当前文件并不等于删除历史提交中的字符串。
什么情况应当判定为泄露#
判定标准建议放在“位置”而不是“后果”上：只要密钥出现在了未授权方可以读取的地方——公开仓库、客户端产物、共享日志、聊天记录、工单截图——就应当按已泄露处理。是否真的被滥用，是另一个问题，需要看服务端的调用记录与用量趋势；API.PLUS 是否提供这类审计与告警能力，本文材料未提供，待核实。
把“还没被用”当作“没泄露”，会让轮换被无限推迟，而推迟期间密钥一直有效。
防护实践#
- 密钥只在服务端。浏览器、小程序、桌面客户端都不应持有长期密钥；客户端调用自己的后端，由后端附加密钥并限制可调用的接口范围。
- 分环境、分用途。开发、测试、生产各用独立密钥；一个服务一个密钥，避免一处泄露牵连全部调用方。
- 不进 URL。URL 会进入访问日志、代理与历史记录，改用请求头传递。
- 日志脱敏。对
Authorization一类请求头、请求体中的密钥字段做统一过滤，错误上报同样适用。 - 仓库侧拦截。提交前钩子加平台侧 secret scanning，两者互补：前者拦新提交，后者能发现历史与 fork。
- 保留撤销能力。每个密钥都要能回答三个问题：谁发的、谁在用、怎么停。回答不了，轮换就无法安全执行。
一个最小结构示例#
下面的示例仅示意“密钥留在服务端、由后端转发”的结构，未实际执行，也未针对任何真实端点验证；YOUR_KEY 与 example.com 均为占位。
// 未执行示例：Node.js + Express，仅示意结构
import express from "express";
const app = express();
const API_KEY = process.env.UPSTREAM_API_KEY; // 由部署环境注入
app.get("/proxy/resource", async (req, res) => {
const upstream = await fetch("https://api.example.com/v1/resource", {
headers: { Authorization: `Bearer ${API_KEY}` },
});
res.status(upstream.status).send(await upstream.text());
});
app.listen(3000);这段代码只解决了“密钥不下发到客户端”。它没有解决鉴权（谁能调用这个代理）、限流和日志脱敏，实际部署时需另行处理，否则代理本身会变成新的公开入口。
轮换的顺序比轮换本身更重要#
安全的轮换一般按这个顺序：先签发新密钥并部署，确认新密钥的调用正常，再吊销旧密钥，最后确认旧密钥的请求已归零。前提是事先有一份调用方清单，否则轮换时无法判断哪些流量会中断。
如果平台是否支持多密钥并存、密钥有效期设置、吊销生效延迟，本文材料未提供，需以 API.PLUS 官方文档为准（待核实）。在确认之前，不要把“可以随时轮换”写进应急预案。
容易自我误判的几点#
- 用了环境变量不代表安全：环境变量仍可能被打进镜像、写进部署日志或被本地脚本打印。
- 删掉前端代码里的密钥不代表完成：已发布的旧版本仍可被下载。
- 密钥没被滥用不代表无需处理：判定依据是暴露位置。
本文不含外部引用链接：本次材料未提供可核验的来源，涉及平台具体能力的描述均标为待核实。
