适用场景在 CDN 优选、反向代理、流量分流或防火墙白名单配置中运维人员经常需要获取 CDN 服务商的官方公网 IP 段。手动收集官网文档既繁琐又容易遗漏。CDN 优选 IP 接口提供了一种统一入口目前支持CloudFlare、AWS CloudFront、Gcore三家主流 CDN 的 IPv4 和 IPv6 段数据以 CIDR 格式返回可直接用于 iptables、Nginx、HAProxy 等组件的规则中。接口能力边界数据源来源于各 CDN 官方发布的 IP 范围文档定期更新具体更新频率以文档为准。支持协议IPv4v4和 IPv6v6一次查询只能选择一种协议版本。服务商目前仅包含 CloudFlare、CloudFrontAWS、Gcore。数字代号同样支持1→CloudFlare2→CloudFront3→Gcore。QPS 限制10 次/秒超出后可能返回限流错误。鉴权可通过X-API-Key请求头携带 API Key不传则使用匿名额度具体匿名额度上限以官方文档为准。请求参数与鉴权接口地址GET https://v1.apizero.cn/api/cdn-ipsQuery 参数参数名必填类型说明server是stringCDN 服务商可选值cloudflare、cloudfront、gcore兼容数字 1/2/3type是stringIP 协议版本可选值v4、v6Header 参数参数名必填类型说明X-API-Key否stringAPI Key匿名调用可不传注意server和type均为必填参数缺少任意一个都会返回 400 错误。curl 请求示例以下是一个获取 CloudFlare IPv4 段的完整 curl 命令假设 API Key 已设置为环境变量APIZERO_API_KEYcurl -sS \ -X GET \ -H X-API-Key: $APIZERO_API_KEY \ https://v1.apizero.cn/api/cdn-ips?servercloudflaretypev4若不传 API Key去掉-H行即可会走匿名额度curl -sS \ https://v1.apizero.cn/api/cdn-ips?servercloudflaretypev4调整参数快速获取不同数据CloudFront IPv6servercloudfronttypev6Gcore IPv4servergcoretypev4或server3typev4返回值解读成功响应的 HTTP 状态码为 200Content-Type 为application/json正文结构如下{ 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... }字段说明字段类型含义codeinteger业务状态码0 表示成功非 0 表示错误msgstring描述信息成功时为“成功”失败时包含错误原因data.countinteger返回的 IP 段数量data.ipsarray of stringCIDR 格式的 IP 段列表data.serverstring服务商名称首字母大写data.typestring协议版本v4或v6data.update_timestring数据的最后更新时间UTC8request_idstring请求追踪 ID可用于排查问题常见错误与排查1. 参数缺失请求缺少server或type返回类似{code: 400, msg: 参数缺失: server}排查检查 URL query 是否完整。2. 服务商不支持传了不支持的server值如aliyun返回{code: 404, msg: 不支持的服务商}排查使用cloudflare、cloudfront、gcore或对应的数字代号。3. 协议版本错误type传了v4或v6之外的字符串如v7返回{code: 400, msg: type 只支持 v4 或 v6}4. 限流超出 10 QPS 或匿名额度耗尽返回 429 或业务错误。排查降低请求频率或添加 API Key 提高额度。工程化封装从 curl 到可复用模块单条 curl 适合快速验证但接入生产环境时需要进行工程封装。以下从错误处理、缓存策略、并发控制、配置化四个维度给出建议并附 Python 封装示例不限于该 API但可直接用于 CDN 优选 IP。第一步抽象请求函数将 URL 拼接、鉴权、超时、重试封装为一个独立函数对外只暴露server和type参数。import requests import time from typing import List, Dict, Optional class CDNOptimizer: BASE_URL https://v1.apizero.cn/api/cdn-ips def __init__(self, api_key: Optional[str] None, max_retries: int 3): self.api_key api_key self.max_retries max_retries self.session requests.Session() if api_key: self.session.headers.update({X-API-Key: api_key}) def get_ips(self, server: str, ip_type: str) - List[str]: 获取指定 CDN 的 IP 段列表 :param server: cloudflare / cloudfront / gcore 或 1/2/3 :param ip_type: v4 / v6 :return: IP 段列表 params {server: server, type: ip_type} for attempt in range(self.max_retries): try: resp self.session.get(self.BASE_URL, paramsparams, timeout10) data resp.json() if data.get(code) 0: return data[data][ips] else: # 业务错误不再重试 raise RuntimeError(fAPI error: {data.get(msg)}) except (requests.exceptions.RequestException, ValueError) as e: if attempt self.max_retries - 1: raise time.sleep(0.5 * (attempt 1)) # 指数退避第二步增加缓存以减少重复调用因为 CDN IP 段更新频率并不高通常按天或周建议缓存数分钟甚至数小时避免频繁触发限流。import functools import cachetools cachetools.cached(cachecachetools.TTLCache(maxsize100, ttl3600)) def get_ips_cached(server: str, ip_type: str) - List[str]: # 实际调用上面定义的 get_ips假设 CDNOptimizer 实例已存在 return optimzer.get_ips(server, ip_type)第三步并发批量获取所有服务商的 IP当需要同时获取多个 CDN 的 IP 时使用线程池或 asyncio 并发请求注意控制 QPS 不超过限制。from concurrent.futures import ThreadPoolExecutor, as_completed servers [cloudflare, cloudfront, gcore] types [v4, v6] with ThreadPoolExecutor(max_workers4) as executor: futures [] for s in servers: for t in types: futures.append(executor.submit(optimzer.get_ips, s, t)) for future in as_completed(futures): ips future.result() # 处理结果如写入文件或更新配置注意同时发起超过 10 个请求可能触发 QPS 限制建议添加time.sleep(0.1)或信号量控制请求间隔。第四步将结果写入运维工具可读的格式用于防火墙直接输出 CIDR 列表给iptables或ufw。用于 Nginx 白名单生成allow 173.245.48.0/20;语句。用于 CI/CD 流水线将结果转为 YAML 或 JSON 配置文件。工程化注意点API Key 安全不要硬编码在代码仓库使用环境变量或密钥管理服务如 Vault。数据更新时机在启动时或定时任务中拉取最新数据不要每次请求都调用接口。降级策略若接口不可用应使用上一次成功获取的缓存数据并记录告警。日志记录每次请求的request_id和响应时间方便定位问题。限流处理如果服务端返回 429应等待一定时间后重试避免持续失败。参考文档CDN 优选 IP 接口文档接口原始文档Markdown