---
title: "什么是 API 密钥的 IP 白名单？附 CIDR 示例 | BroadRouter"
description: "IP 白名单只接受来自列出的地址或 CIDR 网段的请求。它如何保护大模型 API 密钥、CIDR 怎么写，以及云上出口 IP 的常见坑。"
url: https://broadrouter.com/zh/glossary/ip-allow-list/
lang: zh-Hans
updated: 2026-11-14
publisher: BroadRouter (a BroadNet site); API by BroadNet Inference, https://inference.broadnet.ai
---

本页由英文原文借助 AI 翻译。 [阅读英文原文](https://broadrouter.com/glossary/ip-allow-list/) (2026-11-14 更新).

# IP 白名单（IP allow list）

更新于 2026-11-14

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 密钥](https://broadrouter.com/zh/glossary/api-key/)是持有者令牌（bearer token）：谁拿到都能用。密钥会通过提交记录、日志、截图和笔记本电脑泄露。有了白名单，被盗的密钥在攻击者的网络上无法使用，泄露就从一次费用事故变成无关紧要的小事。比如 GitHub 的白名单除了网页登录，也适用于 API 调用和个人访问令牌。

代价是一些运维工作。每新增一台服务器、一个地域或一个 CI 运行器，都要加上它的出口 IP；动态 IP 则需要一条固定的出口路径。

## 在 BroadNet Inference 上

在账户页面中，每行添加一个 IPv4 或 IPv6 地址或 CIDR 网段，最多 32 条。列表为空表示不限制。新密钥会继承账户列表。单个密钥的 `allowed_ips` 会替换该密钥的账户列表：

```bash
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 白名单](https://broadrouter.com/zh/guides/api-keys-ip-allow-lists/)，错误码表见[错误码与重试](https://broadrouter.com/zh/guides/errors-and-retries/)。更全面的数据保护要点，参见 [ZDR 检查清单](https://broadrouter.com/zh/blog/zero-data-retention-llm-api-checklist/)。

## 常见错误

-   把服务器的私网地址（如 `10.x.x.x`）加进列表，而不是它的公网出口 IP。
-   为了让报错消失而填一个很宽的网段。一个 `/8` 就覆盖 1600 多万个地址。

## 常见问题

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

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

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

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

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

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

## 另请参阅

-   [API 密钥（API key）](https://broadrouter.com/zh/glossary/api-key/) (术语)
-   [零数据保留（ZDR）](https://broadrouter.com/zh/glossary/zero-data-retention/) (术语)
-   [速率限制（rate limit）](https://broadrouter.com/zh/glossary/rate-limit/) (术语)
-   [用 IP 白名单把 API 密钥锁定到你的服务器](https://broadrouter.com/zh/guides/api-keys-ip-allow-lists/) (指南)
-   [BroadNet Inference 错误码，以及什么时候该重试](https://broadrouter.com/zh/guides/errors-and-retries/) (指南)
-   [零数据保留大模型 API：10 个问题的核对清单](https://broadrouter.com/zh/blog/zero-data-retention-llm-api-checklist/) (文章)

用你的真实业务负载试一试。 新账户可获得 US$5 初始额度，用于 Gemma和转写。DeepSeek、GLM和Qwen3.8 需要先充值。

[开始使用](https://inference.broadnet.ai/account/?utm_source=broadrouter&utm_medium=referral&utm_campaign=zh-glossary-ip-allow-list&utm_content=page-cta) ·

**来源**

-   [RFC 4632：无类别域间路由（CIDR）](https://www.rfc-editor.org/rfc/rfc4632)
-   [GitHub 文档：管理组织允许的 IP 地址](https://docs.github.com/en/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/managing-allowed-ip-addresses-for-your-organization)
-   [BroadNet Inference API 参考：IP 白名单 （英文）](https://inference.broadnet.ai/docs?utm_source=broadrouter&utm_medium=referral&utm_campaign=zh-glossary-ip-allow-list&utm_content=sources#ip-allow-lists)
