API 密钥认证与安全：Bearer、IP 白名单与密钥保管

2026-07-26 · 阅读约 6 分钟

接口能不能用，第一步就是认证。本接口用的是最常见的 Bearer 方案，但一对密钥用得对不对，直接关系到你的额度会不会被别人刷爆。本文把认证结构讲透，再给一份实战安全清单：密钥怎么放、IP 白名单怎么设、泄露了怎么补救。

一、认证结构：一行说清楚

每个请求都要带一个 Authorization 头，格式是固定的：

Authorization: Bearer pk_xxx:sk_xxx

Bearer 后面是一对密钥用英文冒号连接：前半段是 API Key，后半段是 Secret Key。两段缺一不可，冒号也不能少或换成别的符号。

二、pk 与 sk 的角色分工

注册后在控制台生成密钥，会拿到成对的两把钥匙，作用完全不同：

密钥	前缀	作用	机密程度
API Key	`pk_`	标识「你是哪个账号」，相当于用户名	半公开，本身不构成凭证
Secret Key	`sk_`	证明「确实是你」，相当于密码	绝对机密，泄露即等于账号被接管

关键点：真正需要严防死守的是 sk_。它一旦落到别人手里，对方就能冒用你的账号发请求、消耗你的额度。pk_ 单独拿到做不了什么，但习惯上两把一起保管更省心。

三、Secret Key 只显示一次

出于安全考虑，Secret Key 只在生成时完整显示一次，之后控制台不再展示明文。这意味着：

生成的当下就把它存进你的密钥管理方案（环境变量、密钥托管服务等），别只是瞄一眼。
忘了或没存住，没有「找回」入口，只能重新生成一对新的，旧的作废。
不要把它写进聊天记录、工单、截图 —— 这些地方都可能被留存或转发。

四、绝不放前端：一律服务端调用

最常见也最致命的错误，是把 Bearer pk_xxx:sk_xxx 直接写进网页 JS、App 或小程序。前端代码人人可见、可抓包、可反编译，写进去就等于公开：

// ❌ 错误：密钥出现在浏览器 / App / 小程序代码里 = 已泄露
fetch('https://api.kuaidichaxunapi.com/v1/tracking/trace', {
  headers: { 'Authorization': 'Bearer pk_xxx:sk_xxx' }, // 谁都看得到
});

正确做法是让密钥只存在于服务端，从环境变量读取，前端只跟你自己的后端说话：

// ✅ 正确：密钥从服务端环境变量读取，前端永远看不到
const auth = 'Bearer ' + process.env.KUAIDI_PK + ':' + process.env.KUAIDI_SK;
const res = await fetch('https://api.kuaidichaxunapi.com/v1/tracking/trace', {
  method: 'POST',
  headers: { 'Authorization': auth, 'Content-Type': 'application/json' },
  body: JSON.stringify({ items: [{ courierCode: 'cainiao', trackingNumber: 'CGD0000123456' }] }),
});

小程序场景的代理写法见微信小程序快递查询， Node 服务端代理见Node.js 对接篇。命令行里也一样，用环境变量而不是把明文写进脚本：

curl -X POST https://api.kuaidichaxunapi.com/v1/tracking/trace \
  -H "Authorization: Bearer $KUAIDI_PK:$KUAIDI_SK" \
  -H "Content-Type: application/json" \
  -d '{"items":[{"courierCode":"cainiao","trackingNumber":"CGD0000123456"}]}'

五、IP 白名单：再加一道锁

即使密钥保管得当，也建议在控制台给密钥配置 IP 白名单：只允许你指定的服务器 IP 使用这对密钥调用接口。这样即便密钥不慎泄露，来自白名单之外的请求也会被拒绝，把损失挡在门外。

后端固定出口 IP 的场景（自有服务器、固定公网 IP 的云主机）最适合开白名单。
把生产服务器的公网出口 IP 加进白名单；调试机器的 IP 用完及时移除。
出口 IP 会变的环境（部分 Serverless、动态 IP）要先确认出口地址是否稳定，再决定是否启用。

六、密钥泄露了怎么办

怀疑或确认 Secret Key 泄露（误提交到 Git、贴进公开渠道、被抓包等），按这个顺序处理：

立即在控制台重新生成一对新密钥，旧密钥随即失效 —— 这是最有效的止血。
把服务端环境变量换成新密钥并重新部署，确认线上调用恢复正常。
清理泄露源：从 Git 历史中彻底移除、删掉公开渠道里的明文。
配合 IP 白名单收窄可用来源，降低同类事故的影响面。

因为 Secret Key 本就只显示一次，「重新生成」是唯一且干净的补救方式，不必纠结「能不能改回来」。

七、测试密钥与正式密钥的区别

首页的在线演示用的是公开测试密钥，方便你注册前先跑通流程，但它有严格限制：每个 IP 每天仅 20 次，且响应里会带一个 demoUsage 字段提示剩余次数。它只适合体验，不能拿去跑生产。

真正上线要用注册后在控制台生成的正式密钥：邮箱注册即可、无需企业认证，免费额度每月 10000 次，且支持 IP 白名单等安全设置。别把测试密钥写进正式项目，也别把正式 Secret Key 用在任何公开演示里。

八、安全检查清单

☐ Secret Key 生成当下就存进环境变量 / 密钥托管，绝不写进前端、Git、截图、工单。
☐ 所有调用都走服务端，前端只访问你自己的后端代理。
☐ 给密钥配置 IP 白名单，只放行生产服务器的出口 IP。
☐ 制定泄露预案：能第一时间重新生成密钥并重新部署。
☐ 测试密钥只用于体验，生产一律用正式密钥。
☐ 定期回顾谁有权限接触密钥，人员变动后及时轮换。

认证之外的完整字段与错误码见接口文档；支持的快递公司见快递公司页。还没有密钥就先注册，几分钟就能拿到自己的正式密钥。