笙亿网络策划

如何使用 Cloudflare API Token 实现动态域名解析 DDNS？

约 6 分钟读完 1 阅
文章导读
使用 Cloudflare API Token 实现 DDNS 的核心是调用 Cloudflare API v4 接口更新 DNS 记录，适合家庭宽带 IP 频繁变动的场景。操作时需严格限制 Token 权限为 Zone:DNS:Edit，避免泄露导致域名被篡改。
📋 目录
  1. A 命令速用版
  2. B 为什么会这样
  3. C 分步处理
  4. D 怎么验证是否生效
  5. E 常见坑
  6. F 常见问题
  7. G 参考来源
A A

使用 Cloudflare API Token 实现 DDNS 的核心是调用 Cloudflare API v4 接口更新 DNS 记录，适合家庭宽带 IP 频繁变动的场景。操作时需严格限制 Token 权限为 Zone:DNS:Edit，避免泄露导致域名被篡改。

先说结论：通过脚本定期获取本地 IP 并调用 Cloudflare API 更新解析记录，是实现 DDNS 的标准方案。

  • 适合自有域名托管在 Cloudflare 的用户
  • 先创建仅限 DNS 编辑权限的 API Token
  • 验收通过 dig 命令确认解析生效

命令速用版

以下 curl 命令可直接用于测试更新 A 记录，需替换占位符为实际值。

curl -X PUT "https://api.cloudflare.com/client/v4/zones/ZONE_ID/dns_records/RECORD_ID" \
-H "Authorization: Bearer API_TOKEN" \
-H "Content-Type: application/json" \
`--data` "{\"type\":\"A\",\"name\":\"sub.example.com\",\"content\":\"1.2.3.4\",\"ttl\":120,\"proxied\":false}"

该命令适用场景为手动验证 API 连通性，生产环境建议封装为 Shell 或 Python 脚本并加入 IP 比对逻辑。

为什么会这样

API Token 机制允许用户生成权限范围受限的密钥，比全局 API Key 更安全。Cloudflare API v4 设计为 RESTful 风格，直接对 DNS 记录资源进行 PUT 请求即可覆盖旧 IP 地址，无需删除重建。

使用 Token 而非账号密码或全局 Key，能确保即使密钥泄露，攻击者也无法修改账户设置或删除域名，仅能修改指定区域的 DNS 解析。这是最小权限原则在 DDNS 场景的标准实践。

分步处理

第一步：创建 API Token。登录 Cloudflare 控制台，进入 My Profile > API Tokens，点击 Create Token，选择 Edit zone DNS 模板或自定义权限，确保权限包含 Zone:DNS:Edit，区域限制为具体域名。

第二步：获取 Zone ID 和 Record ID。调用 GET /zones 接口获取域名对应的 Zone ID，调用 GET /zones/:zone_id/dns_records 获取具体子域名的 Record ID，这两个 ID 是更新记录的必需参数。

第三步：编写更新脚本。脚本逻辑应包含获取本地公网 IP、比对当前解析 IP、仅在 IP 变化时调用 PUT 接口，避免频繁请求触发 API 速率限制。

第四步：配置定时任务。Linux 系统使用 crontab 每 5 分钟执行一次脚本，Docker 环境可部署专用 DDNS 容器并挂载配置文件，确保进程常驻。

如何使用 Cloudflare API Token 实现动态域名解析 DDNS？

怎么验证是否生效

使用 dig 命令查询公共 DNS 服务器，确认返回 IP 与本地公网 IP 一致。执行 dig @1.1.1.1 sub.example.com，观察 ANSWER SECTION 中的 IP 地址是否更新。

登录 Cloudflare 控制台 DNS 面板，检查对应记录的 Content 列是否显示最新 IP，同时查看 API Token 使用日志，确认是否有成功的 PUT 请求记录。

常见坑

权限范围过大风险。创建 Token 时若选择 All zones 而非指定域名，一旦泄露可能导致所有托管域名被篡改，务必在 Token 设置中限定具体 Zone。

IPv6 支持问题。部分脚本默认仅获取 IPv4 地址，若本地宽带为 IPv6 优先，需修改脚本调用 IPv6 检测接口并更新 AAAA 记录。

API 速率限制。Cloudflare 对 API 请求有速率限制，脚本必须加入 IP 比对逻辑，避免每次执行都强制调用 API，防止触发 429 Too Many Requests 错误。

常见问题

API Token 和全局 API Key 有什么区别？

API Token 可限定权限范围和有效期，全局 Key 拥有账户完全控制权。DDNS 场景必须使用 API Token，避免密钥泄露导致账户被接管。

TTL 设置多少合适？

建议设置为 Auto 或 120 秒。过短的 TTL 会增加 DNS 查询负担，过长的 TTL 会导致 IP 变更后生效延迟，120 秒是动态解析的常用平衡值。

多个子域名需要多个 Token 吗？

不需要。一个拥有 Zone:DNS:Edit 权限的 Token 可以管理该 Zone 下所有 DNS 记录，但建议在脚本中区分不同 Record ID 进行更新。

参考来源

  • Cloudflare Developer Documentation, API Tokens, https://developers.cloudflare.com/fundamentals/api/get-started/create-token/
  • Cloudflare Developer Documentation, DNS Records, https://developers.cloudflare.com/api/resources/dns/