API 密钥安全：泄露风险从哪里来，防护要落到哪几步
API 密钥是“持有即授权”的凭证，防护重点在于缩小暴露面、按用途拆分并最小化权限、保证可轮换与可追溯。前端、仓库、日志、共享渠道和中间层是常见泄露面；泄露后应先在服务端吊销，再排查调用范围并修复根因。API.PLUS 平台侧的具体密钥管理能力需以官方文档为准。
- 密钥一旦离开受控进程就无法收回，防护靠缩小暴露面、缩短有效期、可追溯、可轮换。
- 前端产物、代码仓库与 CI、日志与错误上报、共享文档、代理中间层是常见泄露渠道。
- 发生泄露时，先吊销或轮换，再查调用记录和修根因；只删代码里的字符串不够。
API 密钥的本质是“持有即授权”：服务端只认这串字符，不认持有者是谁。因此密钥安全的目标是：缩小暴露面、按用途拆分并最小化权限、让每次使用可追溯、让泄露后的处置可以预先演练；它靠的只是把密钥藏好。本文讨论通用工程实践；API.PLUS 平台侧具体提供哪些密钥管理能力（权限作用域、自助轮换、调用审计、限额告警），需以官方文档和账户后台为准，本文不代为确认。
密钥通常从哪些地方泄露#
- 客户端产物：前端打包文件、移动端安装包、桌面客户端里硬编码的密钥，解包或抓包即可读出。
- 仓库与 CI：提交历史、示例配置文件、构建日志里被打印的变量。
- 日志与错误上报：密钥写在 URL query 中，被访问日志、代理日志、浏览器历史留存；请求头被完整记录；异常堆栈带出配置。
- 共享渠道：截图、工单、聊天记录、协作文档。
- 中间层：代理、网关、第三方 SDK 转发时落盘或转发给上游。
这些渠道的共同点是：密钥一旦离开受控进程，就无法真正“收回”，只能吊销。判断严重程度时，看三个维度比看“泄露了几个字符”更有用。
| 维度 | 要问的问题 | 处置方向 |
|---|---|---|
| 权限范围 | 这把密钥能读、能写、能删，还是能产生费用？ | 按用途拆分，只给当前任务需要的最小权限 |
| 有效期与吊销 | 能否自助轮换？吊销是否立即生效？ | 缩短有效期，把轮换写进常规流程 |
| 可审计性 | 能否定位到具体时间、来源和调用量？ | 开启审计与用量告警，保留排查线索 |
防护要落到哪几步#
密钥不进客户端
浏览器、移动端、桌面端都不适合保存长期密钥，因为用户设备不受你控制。让前端调用自己的服务端，由服务端持有密钥并代为请求；客户端只拿到自己的会话凭证。
一用途一密钥，最小权限
不要用同一把密钥同时承担读数据、写数据和后台任务。按环境（开发、预发、生产）和用途分别签发，泄露时影响面才可控，轮换也不必牵动全部调用方。
轮换要能演练
轮换流程如果没有提前跑过，出事时就会变成手工事故。至少明确：新密钥如何下发、旧密钥保留多久、如何确认旧密钥已无调用。建议定期做一次无停机轮换演练，把步骤写成别人能重放的清单。
日志默认脱敏
把密钥放在请求头而不是 URL query 中，能减少它被访问日志和浏览器历史记录带走的概率；同时在日志、错误上报、链路追踪里对 Authorization 一类字段做统一脱敏，而不是依赖每个开发者自觉。
异常用量要能看见
泄露往往先表现为用量曲线异常。按密钥维度统计调用量并设置阈值告警，比事后翻日志更早发现问题。
一个最小对照示例（未执行）#
以下代码仅示意结构，未实际运行；域名与密钥均为占位符，请勿直接用于生产。
// 反例：未执行示例。长期密钥被打进前端产物
const KEY = 'YOUR_KEY';
fetch('https://api.example.com/v1/items', {
headers: { Authorization: `Bearer ${KEY}` }
});
// 正例：未执行示例。服务端代调用，密钥来自环境变量
// 运行环境说明：Node.js 18+（内置 fetch），未实际执行
export async function handler(req, res) {
const r = await fetch('https://api.example.com/v1/items', {
headers: { Authorization: `Bearer ${process.env.API_PLUS_KEY}` }
});
res.status(r.status).send(await r.text());
}
注意，环境变量只是把密钥从代码里挪走，并不构成安全边界：进程被读取、变量被打印到 CI 日志，同样会泄露。
确认泄露之后#
- 先在服务端吊销或轮换密钥，让它立即失效。
- 查调用审计与用量记录，确定时间窗、来源和涉及的接口。
- 评估被访问数据的范围，判断是否需要通知相关方。
- 修复根因：移除硬编码、清理仓库历史、给日志加脱敏。
- 补上检测：仓库密钥扫描、用量告警、轮换演练。
只从代码里删掉字符串不等于密钥失效——这一步顺序不能颠倒。
需要向平台核实的事项#
使用 API.PLUS 时，以下能力的有无与具体形式待核实：密钥能否按用途拆分并收敛权限、是否支持自助轮换与即时吊销、是否提供调用审计与异常告警、限额与计费如何归属到单把密钥。这些直接决定上面的流程能否落地，建议以官方文档和账户后台的实际选项为准。
把这些规则写成团队可重放的步骤——“密钥怎么发、怎么换、出事怎么查”——比一次性提醒更接近可执行的安全。
