适用场景什么时候会用到这个接口家庭宽带或小型办公室的网络出口 IP 通常由运营商动态分配重启光猫、路由器或长时间在线后 IP 都可能变化。如果域名解析记录还停留在旧 IP 上远程访问就会失败。Cloudflare DNS 更新DDNS接口解决的正是这类问题通过 Cloudflare API Token 更新指定域名的 A/AAAA 记录让域名始终指向当前的公网 IP。典型使用场景包括家庭宽带 DDNS路由器或内网主机定时对比本机 IP 与解析记录不一致时调用接口更新。办公室外网 IP 自动同步将办公网络出口 IP 映射到子域名配合端口映射实现远程接入。临时主机的动态解析云服务器或开发机 IP 变化后快速把域名切到新地址。这类任务不需要完整的 Cloudflare API 客户端一个轻量 HTTP 请求即可完成适合放在脚本、定时任务或小型服务中。接口能力边界在使用前需要明确该接口能做什么、不能做什么避免后续踩坑。支持记录类型A 与 AAAA分别对应 IPv4 与 IPv6。默认解析为 A 记录。更新粒度按根域名 主机记录定位一条 DNS 记录例如home.example.com中的home为主机记录example.com为根域名。TTL 范围120 至 86400 秒默认 120 秒。CDN 代理可选开启 Cloudflare 橙色云代理默认关闭。鉴权方式请求头携带 API Key接口内部使用请求体中的 Cloudflare Token 执行更新。Token 仅作转发使用不会持久化。需要强调的是该接口自身不负责探测公网 IP。若请求体中的ip为空具体行为以文档为准工程实践中建议先通过其它渠道获取本机公网 IP再显式传入ip这样行为更可控。请求参数与鉴权该接口的完整请求地址为POST https://v1.apizero.cn/api/cf-dnsHeader 参数参数名类型必填说明Authorizationstring是接口访问凭据在调用平台申请后获得Content-Typestring是设置为application/json在 curl 示例中通常使用X-API-Key传递 API Key实际以你的调用平台所要求的 Header 为准也可以统一放在Authorization字段中。请求体字段字段类型必填默认值说明domainstring是无根域名例如example.comhoststring是无主机记录例如、www或homeipstring是无要设置的 IP 地址tokenstring是无Cloudflare API Token需具备目标域名 DNS 编辑权限typestring否A记录类型可选A或AAAAttlnumber否120TTL范围 120 至 86400proxiedboolean否false是否启用 CDN 代理其中domain、host、ip、token四个字段构成一次最小可用请求。type在更新 IPv6 记录时必须显式传入AAAA。最小可运行 curl 示例下面是一个完整的 POST 请求示例。将$APIZERO_API_KEY替换为你自己的 API Key并将domain、host、ip、token换成真实值curl -sS \ -X POST \ -H X-API-Key: $APIZERO_API_KEY \ -H Content-Type: application/json \ -d { domain: example.com, host: home, ip: 5.6.7.8, token: your_cloudflare_api_token, type: A, ttl: 120, proxied: false } \ https://v1.apizero.cn/api/cf-dns如果希望更新 IPv6 记录将type改为AAAA并传入 IPv6 格式的ipcurl -sS \ -X POST \ -H X-API-Key: $APIZERO_API_KEY \ -H Content-Type: application/json \ -d { domain: example.com, host: home, ip: 240e:390:1234:5678::1, token: your_cloudflare_api_token, type: AAAA, ttl: 300, proxied: false } \ https://v1.apizero.cn/api/cf-dns注意host字段填写表示根域名本身填写www或其它子域名前缀时不要带圆点。返回字段解读一个典型的成功响应如下{ code: 0, data: { changed: true, full_name: home.example.com, message: DNS 记录更新成功, new_ip: 5.6.7.8, old_ip: 1.2.3.4, type: A }, msg: 成功 }各字段含义如下字段说明code业务状态码0表示成功msg状态描述文本data.changed本次请求是否实际更改了 DNS 记录。若新旧 IP 相同可能为falsedata.full_name更新完成的完整域名由host与domain拼接而成data.message接口返回的说明信息data.new_ip更新后的 IP 地址data.old_ip更新前的旧 IP 地址。首次创建记录时可能为空data.type记录类型A或AAAA判断一次请求是否成功建议先看code是否为0再结合data.changed决定是否需要后续操作。例如定时任务中如果changed为false说明域名解析已经是目标 IP无需重复更新其它系统。常见错误与排查思路实际接入中以下问题出现频率较高。1. 鉴权失败现象接口返回与鉴权相关的错误码。排查步骤确认 Header 中的 API Key 是否与调用平台中生成的值一致。确认是否同时正确设置了Content-Type: application/json。如果 Header 同时使用了Authorization与X-API-Key确认平台要求的是哪一种。2. Cloudflare Token 无权限现象请求已到达平台但 Cloudflare 侧拒绝更新。排查步骤登录 Cloudflare 控制台检查 Token 是否包含目标区域的 DNS 编辑权限。确认 Token 对应的域名是请求体中的domain。如果 Token 设置了 IP 白名单确认当前调用出口 IP 在白名单内。3. 域名或主机记录不存在现象接口提示找不到记录。排查步骤确认domain是根域名而不带www前缀。确认host在 Cloudflare 中已存在对应解析记录。若记录不存在该接口是否能自动创建以文档为准。检查host是否误带了圆点例如home.这种写法通常是错误的。4. IP 格式不匹配现象type为A但传入了 IPv6 地址或反之。排查步骤确认type与ip格式一致。如果使用脚本自动获取 IP注意区分 IPv4 与 IPv6避免拿到的地址来自不同的网络出口设备。工程化接入注意事项定时更新频率该接口 QPS 为 5 次/秒。DDNS 场景中不建议高频轮询通常每 5 到 10 分钟执行一次即可。更新前先比较本地获取的公网 IP 与当前 DNS 解析结果只有不一致时才调用接口既能减少无效请求也能降低触发限流的概率。获取公网 IP 的方式接口本身不负责探测公网 IP因此客户端需要自行获取。常见方法包括# 获取 IPv4 curl -4 -sS https://api.ipify.org # 获取 IPv6 curl -6 -sS https://api.ipify.org获取到 IP 后再将其组装进 Cloudflare DNS 更新请求体中。注意使用公共 IP 查询服务时应选择可信来源并评估其稳定性。失败重试策略敏感信息管理Cloudflare API Token 是敏感凭据应避免硬编码在脚本或代码仓库中。建议通过环境变量、密钥管理服务或配置文件注入。示例export CLOUDFLARE_API_TOKENyour_cloudflare_api_token然后在脚本中读取TOKEN${CLOUDFLARE_API_TOKEN}日志记录每次更新应记录时间、域名、旧 IP、新 IP 以及接口返回的code和changed字段。这样在 DNS 解析异常时可以快速定位是更新失败、IP 获取错误还是 Cloudflare Token 权限变更。参考文档接口文档https://apizero.cn/aidocs/cf-dns原始 Markdown 文档https://apizero.cn/aidocs/cf-dns/raw.md