适用场景当你的家庭宽带或云服务器使用动态公网 IP每次重启或拨号后 IP 都会变化。手动修改 DNS 记录不仅繁琐还容易出错。Cloudflare DNS 更新 API 可以让你通过脚本或定时任务自动同步域名解析记录实现 DDNS动态 DNS效果。典型场景包括内网穿透将 home.yourdomain.com 指向家里的 NAS 或路由器远程办公通过固定子域名访问办公室内网服务游戏服务器IP 变化后自动更新无需通知玩家接口能力边界本接口基于用户自有的 Cloudflare API Token 工作不持久化 Token每次请求均需提交 Token。接口只负责将指定域名的 A 或 AAAA 记录更新为当前 IP不做 IP 自动检测——你需要自己获取本机公网 IP例如通过curl ifconfig.me并传入请求。关键限制QPS5 次/秒超出会限流仅支持 AIPv4和 AAAAIPv6记录域名的 DNS 必须托管在 Cloudflare且 Token 拥有该域的编辑权限不支持泛域名如 *.example.com的更新请求参数与鉴权请求地址POST https://v1.apizero.cn/api/cf-dnsHeader 参数参数类型必填说明Authorizationstring是你的 API Key格式为Bearer key从 API Zero 平台获取Content-Typestring是固定为application/json该接口使用 API Zero 网关转发因此请求头中需要携带 Authorization 密钥非 Cloudflare Token。Cloudflare Token 通过请求体中的token字段传入。请求体JSON字段类型必填说明示例domainstring是根域名已在 Cloudflare 托管example.comhoststring是主机记录如根或wwwhomeipstring否为空则自动获取请求来源 IP要设置的 IP 地址空字符串tokenstring是Cloudflare API Token具有编辑 DNS 权限your_cloudflare_tokentypestring否记录类型A或AAAA默认AAttlnumber否TTL 值单位秒范围 120–86400默认 120120proxiedboolean否是否启用 Cloudflare CDN 代理默认falsefalse注意如果不传ip字段或传空字符串接口会自动将请求来源的公网 IP 作为目标 IP。这通常适用于服务器端脚本直接调用但如果你在 NAT 后运行脚本请求来源 IP 可能不是你的真实公网 IP建议显式传入ip。curl 最小可运行示例以下是一个完整的 curl 命令请先替换$APIZERO_API_KEY和$CLOUDFLARE_TOKEN为实际值curl -sS -X POST \ -H Authorization: Bearer $APIZERO_API_KEY \ -H Content-Type: application/json \ -d { domain: yourdomain.com, host: home, ip: , token: $CLOUDFLARE_TOKEN } \ https://v1.apizero.cn/api/cf-dns示例解析$APIZERO_API_KEY从 API Zero 文档页或控制台获取。$CLOUDFLARE_TOKEN在 Cloudflare 控制台创建的 API Token权限需包含 Zone.DNS (Edit)。domain和host组合后为home.yourdomain.com。ip留空服务端自动获取请求来源 IP。响应会告诉你 DNS 记录是否已变更、新旧 IP 等信息。如果希望显式指定 IP将ip值改为实际公网 IP例如1.2.3.4。返回值解读成功响应的 HTTP 状态码为 200Content-Type 为 application/json。{ 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: 成功 }字段类型说明codenumber状态码0 表示成功非 0 表示出错msgstring描述信息与 code 对应data.changedbooleanDNS 记录是否实际发生了变更如 IP 相同则为 falsedata.full_namestring完整的主机名host.domaindata.messagestring操作结果文本描述data.new_ipstring更新后的 IP 地址data.old_ipstring更新前的 IP 地址如果原记录不存在则为空data.typestring记录类型常见错误与排查1. 401 Unauthorized检查Authorization头是否正确设置格式为Bearer key。确认 API Key 未过期。2. 403 或 400 错误无效的 Token 或域名请求体中的token字段未传或无效。域名未在 Cloudflare 托管或 Token 缺少对应 Zone 的权限。建议先在 Cloudflare 控制台用 Token 手动测试GET /zonesAPI 是否成功。3. 返回 code 非 0例如 -1通常是因为domain或host格式错误或者 Cloudflare API 返回异常。查看msg字段根据描述调整参数。4. IP 未更新如果你传了ip但值与当前记录相同changed为 false接口不会重复调用 Cloudflare API。如果使用自动 IP 检测不传 ip请确认客户端公网 IP 与 DNS 记录不同。工程化注意事项定时任务集成推荐在服务器上编写 bash 脚本配合 crontab 每 5–10 分钟检查并更新 IP#!/bin/bash # ddns.sh APIZERO_KEYyour_apizero_key CF_TOKENyour_cloudflare_token DOMAINyourdomain.com HOSThome get_current_ip() { curl -sS https://ifconfig.me } CURRENT_IP$(get_current_ip) curl -sS -X POST \ -H Authorization: Bearer $APIZERO_KEY \ -H Content-Type: application/json \ -d { \domain\: \$DOMAIN\, \host\: \$HOST\, \ip\: \$CURRENT_IP\, \token\: \$CF_TOKEN\ } \ https://v1.apizero.cn/api/cf-dns幂等性同一 IP 重复请求不会产生额外计费或副作用。接口内部会先查询当前记录仅当 IP 不同时才调用 Cloudflare API 更新。限流与重试QPS 上限为 5如果你的定时任务间隔小于 1 秒建议增加 sleep 或使用指数退避。失败时建议重试 2–3 次。安全性始终使用 HTTPS。绝不在代码中硬编码 Token推荐使用环境变量或密钥管理服务。Cloudflare Token 应限制为最小权限仅允许编辑指定域名的 DNS 记录。参考文档接口官方文档https://apizero.cn/aidocs/cf-dns原始文档https://apizero.cn/aidocs/cf-dns/raw.md