适用场景动态 DNSDDNS是家庭宽带、自建服务器或物联网设备连接互联网时的刚需。多数家用宽带公网 IP 会周期性变化或重启后变更此时需要自动将域名解析记录更新到最新 IP。Cloudflare DNS 更新接口以下简称cf-dns提供了通过 API Token 直接操作 DNS 记录的能力配合定时任务即可实现自托管 DDNS。常见场景包括家庭 NAS、远程桌面等需要固定域名访问的服务。办公室外网 IP 变化的自动化同步。临时测试环境需要在公网暴露端口且 IP 不固定。接口能力边界协议HTTPS 仅 POST 方法。QPS 限制5 请求/秒超出后可能被限流。鉴权方式通过 Token 传递Token 仅作转发使用服务端不持久化。支持的记录类型AIPv4和 AAAAIPv6默认 A。TTL 范围120 秒2 分钟到 86400 秒24 小时默认 120。代理开关可启用 Cloudflare CDN 代理proxied默认关闭。记录更新行为若记录已存在且 IP 相同changed字段为false不产生实际修改。请求参数与鉴权请求地址POST https://v1.apizero.cn/api/cf-dnsHeader 参数参数名类型必填说明X-API-Keystring是调用方的 API Key用于接口认证Content-Typestring是固定为application/json注意此处的X-API-Key与 Cloudflare 的 API Token 不同。前者是调用本接口的凭证后者是请求体中token字段使用的 Cloudflare 凭据。请求体JSON字段名类型必填说明domainstring是根域名如example.comhoststring是主机记录如或www或homeipstring是要设置的 IP 地址IPv4 或 IPv6tokenstring是Cloudflare API Token需具备对应 DNS 编辑权限typestring否A或AAAA默认Attlnumber否120 至 86400默认 120proxiedboolean否是否开启 CDN 代理默认falsecurl 示例与代码接入基本 curl 调用以下命令将home.example.com的 A 记录更新为5.6.7.8curl -sS \ -X POST \ -H X-API-Key: ${YOUR_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: 300, proxied: false } \ https://v1.apizero.cn/api/cf-dns请将${YOUR_API_KEY}替换为接口分配的 API Key将YOUR_CLOUDFLARE_API_TOKEN替换为 Cloudflare 实际 Token。若只更新 IPv6 记录将type改为AAAA并传入对应 IPv6 地址即可。Python 封装示例import requests import json def update_dns(api_key, token, domain, host, ip, record_typeA, ttl120, proxiedFalse): url https://v1.apizero.cn/api/cf-dns headers { X-API-Key: api_key, Content-Type: application/json } payload { domain: domain, host: host, ip: ip, token: token, type: record_type, ttl: ttl, proxied: proxied } resp requests.post(url, headersheaders, jsonpayload) resp.raise_for_status() return resp.json() # 使用示例 result update_dns( api_keyyour_api_key, tokenyour_cf_token, domainexample.com, hosthome, ip5.6.7.8 ) print(result)上述代码中requests库需要预先安装pip install requests。建议在实际工程中加入超时和重试逻辑。返回值解读成功响应HTTP 200{ code: 0, msg: 成功, data: { changed: true, full_name: home.example.com, message: DNS 记录更新成功, new_ip: 5.6.7.8, old_ip: 1.2.3.4, type: A } }字段类型说明codeint业务状态码0 代表成功msgstring中文状态描述data.changedboolean是否实际修改了记录IP 不同则truedata.full_namestring完整的域名主机记录 根域名data.messagestring操作结果描述data.new_ipstring更新后的 IPdata.old_ipstring更新前的原 IPdata.typestring记录类型A或AAAA当changed为false时old_ip与new_ip相同message提示“IP 无变化无需更新”。错误响应非 0 的code表示操作失败例如{ code: 1001, msg: Token 无效或权限不足, data: null }常见错误码及含义见下文。常见错误与排查现象可能原因排查方式返回code: 1001Cloudflare Token 无效或缺少 DNS 编辑权限在 Cloudflare Dashboard 检查 Token 权限确认zone:edit作用域返回code: 1002域名不在 Cloudflare 账号下或未添加确认domain参数正确且已添加到 Cloudflare返回code: 1003JSON 参数缺失如domain或token未传检查请求体字段名拼写确保必填字段已提供返回code: 1004IP 格式不合法不是有效的 IPv4 或 IPv6验证传入 IP 是否为标准格式IPv6 需解压缩HTTP 401X-API-Key无效或未提供检查请求头中的 Key 是否正确HTTP 429超过 QPS5 请求/秒增加调用间隔或使用令牌桶限流HTTP 5xx临时服务异常等待后重试建议使用指数退避策略工程化注意事项从一次 curl 调用演进到生产级 DDNS 客户端需要关注以下几个维度1. IP 获取与变化检测不要每次重复调用 API 而无需更新。建议先通过外部服务如ip.sb或icanhazip.com获取当前公网 IP与本地缓存的上一次有效 IP 进行比较。只有当 IP 变化时才触发更新请求。这可以大幅减少 API 调用量避免触及 QPS 限制。2. 重试与退避网络波动或服务端临时异常可能导致失败。采用指数退避重试策略首次失败后等待 1 秒重试第二次 2 秒第三次 4 秒……最大间隔不超过 60 秒最多重试 3~5 次。注意区分可重试的错误如 HTTP 5xx、超时与不可重试的错误如 Token 无效、参数错误后者应直接告警。3. 日志与告警记录每次请求的完整信息时间戳、请求体、响应体、是否成功、耗时。当连续失败超过阈值时通过邮件或即时通讯机器人通知运维人员。日志格式建议采用结构化 JSON便于后续分析。4. 配置外部化将 API Key、Cloudflare Token、域名列表等敏感信息放在环境变量或配置管理服务中不要硬编码在代码仓库。示例export CF_DDNS_API_KEYyour_api_key export CF_DDNS_TOKENyour_cf_token export CF_DDNS_DOMAINexample.com export CF_DDNS_HOSThome5. 定时调度DDNS 客户端通常以定时任务形式运行。Linux 下推荐使用 systemd timer 或 crontab间隔建议 5~10 分钟取决于 IP 变动频率。Windows 可使用任务计划程序。注意避免同时执行多个实例导致竞态。6. 多域名/多记录支持如果需要对多个域名执行更新可在单个客户端中循环调用。但注意控制总 QPS例如 3 个域名每个更新速度不应超过 1.6 次/秒建议增加time.sleep(0.3)间隔。7. 测试环境分离在投入生产前使用测试域名如test.example.com验证流程。确认 API Key、Token 权限、IP 读取均正确后再切换生产。参考文档Cloudflare DNS 更新接口官方文档: https://apizero.cn/aidocs/cf-dns原始 Markdown 文档: https://apizero.cn/aidocs/cf-dns/raw.md