BroadRouter
开始使用

IP 白名单(IP allow list)

更新于

IP 白名单是一种安全控制:只接受来自列出的 IP 地址或 CIDR 网段的请求,拒绝其他所有请求。用在 API 上,它能限制密钥泄露造成的损失,因为密钥在不在列表中的网络上无法使用。

又称: IP 白名单、IP 访问控制、IP 限制、允许的 IP、来源 IP 限制、allowed_ips、IP allow list、IP allowlist、IP whitelist、allowed IPs、IP restriction

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 多万个地址。

常见问题

只靠 IP 白名单能保护好 API 密钥吗?

不能。它只是其中一层。密钥仍要放在服务器上,不要出现在代码和日志里;每个应用用自己的密钥;密钥泄露后要尽快吊销。

我的服务跑在 Serverless 或自动扩缩容的基础设施上,还能用白名单吗?

只有出站流量从已知地址出去时才行。让流量经过有固定 IP 的 NAT 网关或出口代理,再把这些 IP 加进列表。

不在列表里的 IP 会收到什么错误?

在 BroadNet Inference 上是 403。其他 API 通常也返回 403。

以 Markdown 格式阅读问 ChatGPT问 Claude问 Perplexity