API 密钥默认在任何地方都能用。白名单把它绑定到你真正运行代码的地方。
原理
API 的边缘节点会把每个请求的来源 IP 和列表比对。地址在列表中,或落在列出的网段内,请求就继续进入正常的密钥校验;否则直接拒绝。
网段用 CIDR 表示法书写:一个地址、一个斜杠,再加前缀长度。RFC 4632 解释说,前缀长度就是固定的前导位数。以 IPv4 为例:
| 条目 | 覆盖范围 |
|---|---|
203.0.113.7 |
一个地址 |
198.51.100.0/24 |
256 个地址,198.51.100.0 到 198.51.100.255 |
10.0.0.0/16 |
65,536 个地址 |
IPv6 的思路相同,只是地址为 128 位,例如 2001:db8::/48。
真正起作用的是你的出口 IP:服务器流量离开时使用的公网地址。在 NAT、负载均衡器或公司代理之后,它往往不是机器自己显示的地址。
为什么重要
API 密钥是持有者令牌(bearer token):谁拿到都能用。密钥会通过提交记录、日志、截图和笔记本电脑泄露。有了白名单,被盗的密钥在攻击者的网络上无法使用,泄露就从一次费用事故变成无关紧要的小事。比如 GitHub 的白名单除了网页登录,也适用于 API 调用和个人访问令牌。
代价是一些运维工作。每新增一台服务器、一个地域或一个 CI 运行器,都要加上它的出口 IP;动态 IP 则需要一条固定的出口路径。
在 BroadNet Inference 上
在账户页面中,每行添加一个 IPv4 或 IPv6 地址或 CIDR 网段,最多 32 条。列表为空表示不限制。新密钥会继承账户列表。单个密钥的 allowed_ips 会替换该密钥的账户列表:
curl -X POST https://inference.broadnet.ai/portal/keys \
-H "Authorization: Bearer $BROADNET_PORTAL_CREDENTIAL" \
-H "Content-Type: application/json" \
-d '{"label":"worker-1","allowed_ips":["203.0.113.7","198.51.100.0/24"]}'
来自其他地址的请求会收到 403。修改列表或吊销密钥后,新请求会在五秒内被拦下。完整步骤见 API 密钥与 IP 白名单,错误码表见错误码与重试。更全面的数据保护要点,参见 ZDR 检查清单。
常见错误
- 把服务器的私网地址(如
10.x.x.x)加进列表,而不是它的公网出口 IP。 - 为了让报错消失而填一个很宽的网段。一个
/8就覆盖 1600 多万个地址。