最小可运行示例：Cloudflare DNS DDNS 接口实战与错误处理

适用场景家庭宽带用户的公网 IP 经常随重拨而变化如果域名托管在 Cloudflare每次 IP 变更后手动去面板修改 DNS 记录显然不现实。Cloudflare DNS 更新DDNS接口专为此而生只需提供 Cloudflare API Token 和目标域名接口即可自动查询并更新对应的 AIPv4或 AAAAIPv6记录。适合以下场景家庭 NAS / 自建服务器通过 DDNS 保持外网访问域名始终指向最新公网 IP。办公室远程访问固定域名指向动态 IP配合端口转发实现远程办公。物联网设备摄像头、工控机等需要外网可达的场景。接口能力边界本接口是对 Cloudflare DNS API 的轻量封装仅做 Token 转发不持久化任何凭据。QPS 限制为 5 次/秒满足个人或小团队日常需求。每次调用只能更新一条记录由domainhost决定支持设置 TTL 与 CDN 代理开关。接口地址POST https://v1.apizero.cn/api/cf-dns参数与鉴权鉴权方式调用时需要携带平台分配的 API Key通过 HTTP HeaderX-API-Key传递。示例中的$APIZERO_API_KEY需替换为你自己的密钥。请求体字段请求体为 JSON 对象必填参数如下字段名类型必填说明domainstring是根域名例如example.comhoststring是主机记录例如、www、homeipstring是要设置的新 IP 地址IPv4 或 IPv6传空字符串时接口可能自动检测来源 IP但推荐显式传入tokenstring是Cloudflare API Token需拥有 DNS 编辑权限可选参数字段名类型默认值说明typestringA记录类型可选A(IPv4) 或AAAA(IPv6)ttlnumber120TTL 值范围 120–86400 秒proxiedbooleanfalse是否启用 Cloudflare CDN 代理橙色云curl 可运行示例以下是最小可运行示例假设你已经准备好$APIZERO_API_KEY、Cloudflare Token、域名和主机记录curl -sS \ -X POST \ -H X-API-Key: $APIZERO_API_KEY \ -H Content-Type: application/json \ -d { domain: example.com, host: home, ip: 203.0.113.42, token: YOUR_CLOUDFLARE_API_TOKEN, type: A, ttl: 120, proxied: false } \ https://v1.apizero.cn/api/cf-dns将203.0.113.42替换为当前公网 IPYOUR_CLOUDFLARE_API_TOKEN替换为从 Cloudflare 控制台创建的 API Token权限需包含Zone.DNS:Edit。如果想只更新 IPv6 记录将type改为AAAAip传入 IPv6 地址即可。返回值解读成功响应的 HTTP 状态码为 200返回 JSON 格式{ code: 0, msg: 成功, data: { changed: true, full_name: home.example.com, message: DNS 记录更新成功, new_ip: 203.0.113.42, old_ip: 1.2.3.4, type: A } }字段说明字段说明code业务状态码0表示成功非0表示异常msg人类可读的消息data.changed布尔值表示 DNS 记录是否被实际修改若新旧 IP 相同则falsedata.full_name完整的 DNS 记录名称例如home.example.comdata.message操作描述data.new_ip更新后的 IP 地址data.old_ip更新前的 IP 地址首次创建可能为空data.type记录类型常见错误排查错误现象可能原因排查方法返回{code:1,msg:参数错误}请求体缺少必填字段或格式错误检查 JSON 合法性及domain、host、ip、token是否齐全返回{code:2,msg:Token 验证失败}平台 API Key 无效或未携带确认X-API-Key头部是否正确设置Cloudflare 返回 403 / 无权限Cloudflare API Token 权限不足在 Cloudflare 控制台检查 Token 「API Token」的权限是否包含目标域名的 DNS:Edit记录未更新changed: false传入的ip与现有记录相同确认新 IP 是否确实不同或强制重新创建先删除记录自动检测 IP 不准确未传入ip值且网络存在多层 NAT始终显式传入当前公网 IP可通过ifconfig.me或ip.sb获取工程化注意事项定期获取公网 IP在自动化脚本中建议先通过第三方服务如curl -s ifconfig.me获取当前公网 IP再传入接口避免依赖接口自动检测的不确定性。防止频繁调用每次脚本执行前比较缓存中的旧 IP仅当 IP 变化时才调用更新接口减少 API 消耗和 Cloudflare 写入频率。日志记录将每次调用的结果包括old_ip、new_ip、changed状态写入本地日志文件便于回溯。错误重试对于网络抖动或临时超时建议设置 3 次重试每次间隔 5 秒。安全存储Cloudflare API Token 和平台 API Key 切勿硬编码在公开仓库中使用环境变量或加密配置。跨平台兼容如果同时需要更新 IPv4 和 IPv6可以分别构造两条请求type 不同注意时间窗口不要重叠导致冲突。参考文档接口文档页https://apizero.cn/aidocs/cf-dns原始 Markdown 说明https://apizero.cn/aidocs/cf-dns/raw.mdCloudflare API Token 创建指南https://dash.cloudflare.com/profile/api-tokens