适用场景

在互联网架构中，CDN 节点的 IP 地址段并非一成不变。网络运维、安全团队或反向代理部署者常需要一份简洁、权威的 CDN 官方 IP 列表，用于以下典型场景：

• 防火墙白名单：只允许来自特定 CDN 节点的流量回源，防止源站被绕过攻击。
• CDN 优选：根据 IP 段信息，在客户端或代理层手动选择延迟最低的 CDN 节点（配合智能 DNS 或性能探测）。
• 流量分流：在网关或负载均衡器上，根据请求来源 IP 归属的 CDN，将不同运营商流量导向不同后端。
• 反向代理缓存：若 CDN 自身作为源站的缓存层，需要知晓公网出口 IP，以避免回源请求被源站限速。

本接口提供 CloudFlare、AWS CloudFront、Gcore 三家主流 CDN 服务商的官方 IPv4 与 IPv6 地址段（CIDR 格式）。数据来源为各厂商官方公告，经定期同步与校验后开放查询。

接口能力边界

维度	说明
端点	GET https://v1.apizero.cn/api/cdn-ips
请求方法	GET
请求频次 (QPS)	10 次/秒（匿名与 API Key 共用额度）
所支持的 CDN 厂商	cloudflare、cloudfront、gcore (也接受数字 1 / 2 / 3)
协议版本	IPv4 (v4) / IPv6 (v6)
鉴权方式	可选：在 Header 中携带 X-API-Key；未传时走匿名额度
响应格式	JSON（外层 code、msg、data 结构）
数据更新频率	以文档页或原始文档为准

注意：当前接口不承诺覆盖所有 CDN 厂商，且数据更新可能存在延迟。请以各 CDN 官方最新公告为准。

请求参数与鉴权

Query 参数（必填）：

参数名	类型	必填	说明
server	string	是	CDN 厂商标识：cloudflare / cloudfront / gcore；也支持数字 1、2、3（分别对应上列顺序）
type	string	是	IP 协议版本：v4 或 v6

Header 参数（可选）：

参数名	类型	必填	说明
X-API-Key	string	否	API 密钥；未携带则使用匿名额度（额度以服务端限制为准）

匿名调用同样可用，但可能存在总额度限制。建议生产环境按照文档指引申请 API Key 并作为环境变量传递。

curl 请求示例

以下示例获取 CloudFlare 的 IPv4 地址段（请替换 $APIZERO_API_KEY 为你的真实密钥，若只做测试可先省略 -H 行）：

curl -sS \
  -X GET \
  -H "X-API-Key: $APIZERO_API_KEY" \
  "https://v1.apizero.cn/api/cdn-ips?server=cloudflare&type=v4"

如果你想测试 Gcore 的 IPv6 地址段，可以把参数改为：

curl -sS \
  -X GET \
  -H "X-API-Key: $APIZERO_API_KEY" \
  "https://v1.apizero.cn/api/cdn-ips?server=gcore&type=v6"

若使用数字标识，server=1 等价于 server=cloudflare，依此类推。

使用 Python requests 库接入

import requests
import os

api_key = os.environ.get("APIZERO_API_KEY", "")  # 优先从环境变量读取
url = "https://v1.apizero.cn/api/cdn-ips"
params = {"server": "cloudfront", "type": "v4"}
headers = {}
if api_key:
    headers["X-API-Key"] = api_key

resp = requests.get(url, params=params, headers=headers)
data = resp.json()

if data.get("code") == 0:
    ips = data["data"]["ips"]
    print(f"成功获取 {len(ips)} 条 CIDR 记录")
    for cidr in ips:
        print(cidr)
else:
    print("请求失败:", data.get("msg"))

返回结构解读

成功时 HTTP 状态码为 200，响应体如下（格式化后）：

{
  "code": 0,
  "data": {
    "count": 15,
    "ips": [
      "173.245.48.0/20",
      "103.21.244.0/22",
      "103.22.200.0/22"
    ],
    "server": "CloudFlare",
    "type": "v4",
    "update_time": "2026-05-06 07:55:00"
  },
  "msg": "成功",
  "request_id": "mota..."
}

关键字段说明：

字段	类型	说明
code	int	业务状态码：0 表示成功；非零时参考 msg 字段
msg	string	业务消息，失败时携带错误描述
data.count	int	返回的 IP 段数量
data.ips	array of strings	CIDR 列表，如 "173.245.48.0/20"
data.server	string	实际查询的 CDN 厂商（经过标准化，首字母大写）
data.type	string	查询的 IP 版本
data.update_time	string	该厂商此协议版本的最新更新时间（ISO 格式）
request_id	string	本次请求的唯一标识，可用于日志排查

ips 列表注意事项

• 部分厂商的 IPv6 段可能较多，count 字段对应实际返回的条目数。
• CIDR 前缀均为各厂商官方公布的最新段，但可能存在合并或拆分。具体网络规划请自行验证。
• 响应中的 update_time 仅代表本接口同步该数据的时间，非厂商原始发布时间。

常见错误与处理

HTTP 状态	业务 code	可能原因	建议处理方式
200	1001	server 参数不合法（非 cloudflare/cloudfront/gcore 或对应数字）	检查参数名称与枚举值
200	1002	type 参数不合法（非 v4 或 v6）	检查参数值大小写与拼写
200	1003	请求频率超过 QPS 上限（10 次/秒）	增加本地重试间隔，或使用指数退避
200	1004	匿名额度耗尽（未传 API Key 且当日限额用完）	携带有效的 X-API-Key 或等待次日重置（以文档为准）
401	–	传入了无效的 X-API-Key	检查密钥字符串是否完整、未过期
429	–	触发全局速率限制	降低请求频率，加入本地队列
5xx	–	服务端异常	稍后重试，若持续出现请查看文档页或联系支持

所有业务错误均会返回 msg 说明，建议生产环境统一判断 code 而非仅依赖 HTTP 状态码。

工程化注意事项

1. 缓存策略：CDN IP 段极少每天变动，建议将获取到的列表缓存至本地（内存 / Redis / 文件），设置缓存 TTL 为 6-24 小时，减少对接口的重复调用。
2. 批量获取：若同时需要多个厂商或多个协议版本，应使用并行请求（注意控制并发数不超过 QPS），避免串行等待。
3. 错误重试：对 429 或 5xx 响应，采用指数退避（如 200ms、600ms、1.8s）最多 3 次。业务错误（1001-1004）无需重试。
4. Key 管理：API Key 应按环境变量或配置仓库管理，不要硬编码在代码中。定期轮换密钥。
5. 日志记录：记录 request_id 和 update_time，便于追踪数据源变更。
6. 兼容性：部分厂商的 CIDR 列表可能包含 /32 或 /128 单 IP 段，防火墙或网络组配置时需确认是否支持此类写法。

参考文档

• CDN 优选 IP 接口文档 — 包含最新的请求示例、参数说明以及更新日志。
• 原始 Markdown 文档 — 适用于程序化下载或离线查阅。

本文所涉及的接口地址、参数、QPS 及错误码均以上述正式文档为最终依据。文中提供的 curl 与 Python 示例已在对应环境验证，但生产使用前建议进行充分测试。