通过 Cloudflare DNS API 实现 DDNS 动态域名解析

一、什么是 DDNS？为何选择 Cloudflare 实现动态域名解析？

DDNS（Dynamic Domain Name System） 是一种将动态公网 IP 自动映射到固定域名的技术，适用于：

• 家庭宽带环境（IP 经常变化）
• 自建服务器、NAS、远程办公
• 自定义域名访问不固定 IP 的主机

而传统的花生壳、DynDNS 等 DDNS 服务或功能有限、或需付费、或不支持自定义域名。

Cloudflare 提供了企业级的 免费 DNS API 接口，搭配脚本即可实现稳定的 DDNS 系统，优势包括：

• ✅ 永久免费使用
• ✅ 支持自定义域名与子域名
• ✅ 全球 CDN 与安全加持
• ✅ API 支持自动化集成
• ✅ 广泛支持 Linux、路由器、Docker 等部署场景

核心关键词：Cloudflare DNS API、DDNS 动态域名解析、动态 DNS 搭建、自定义域名、家庭服务器远程访问

二、准备工作：Cloudflare 配置与 API 权限管理

2.1 注册 Cloudflare 并添加域名

1. 注册 Cloudflare 账号
2. 添加已有域名（例如 yourdomain.com）
3. 设置 NS 记录至 Cloudflare 提供的解析服务器
4. 等待 DNS 生效后，即可使用 API 管理 DNS 记录

2.2 获取 API Token（推荐方式）

前往 API Tokens 页面：

• 点击“Create Token”
• 模板选择：“Edit Zone DNS”

• 权限配置：

  • Zone → Zone → Read
  • Zone → DNS → Edit
• 设置资源范围为你要管理的域名（例如 yourdomain.com）
• 生成后复制 API_TOKEN，妥善保管

⚠️ 避免使用全局 API Key，限制权限更安全

三、Cloudflare DNS API 核心概念

使用 DDNS 前，我们需要了解 3 个基本参数：

你可以通过如下 API 获取这些信息：

获取 Zone ID

curl -X GET "https://api.cloudflare.com/client/v4/zones?name=yourdomain.com"
  -H "Authorization: Bearer $CF_API_TOKEN"
  -H "Content-Type: application/json"

获取 DNS Record ID

curl -X GET "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/dns_records?type=A&name=sub.yourdomain.com"
  -H "Authorization: Bearer $CF_API_TOKEN"
  -H "Content-Type: application/json"

四、实现动态更新逻辑（Bash 脚本）

以下脚本实现：

• 获取当前公网 IP
• 对比 Cloudflare DNS 中的记录
• 若不一致则自动调用 API 更新

#!/bin/bash

CF_API_TOKEN="你的API密钥"
ZONE_ID="你的Zone ID"
RECORD_ID="你的DNS记录ID"
RECORD_NAME="sub.yourdomain.com"# 获取当前公网 IP
CURRENT_IP=$(curl -s https://api.ipify.org)# 获取现有 A 记录 IP
DNS_IP=$(curl -s -X GET "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/dns_records/$RECORD_ID"
  -H "Authorization: Bearer $CF_API_TOKEN"
  -H "Content-Type: application/json" | jq -r '.result.content')# 若 IP 变化，更新记录
if [ "$CURRENT_IP" != "$DNS_IP" ]; then
  echo "IP changed: $DNS_IP → $CURRENT_IP. Updating..."
  curl -s -X PUT "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/dns_records/$RECORD_ID"
    -H "Authorization: Bearer $CF_API_TOKEN"
    -H "Content-Type: application/json"
    --data "{type:A,name:$RECORD_NAME,content:$CURRENT_IP,ttl:120}"
else
  echo "IP unchanged: $CURRENT_IP"
fi

✅ 支持设置为 cron 定时任务，每 5 分钟运行一次，持续保持域名可达

五、Python 实现 DDNS 更新

Python 实现更加灵活，适合日志处理、异常重试、Webhook 推送等场景：

import requests
import os

API_TOKEN = os.getenv("CF_API_TOKEN")
ZONE_ID = os.getenv("CF_ZONE_ID")
RECORD_ID = os.getenv("CF_RECORD_ID")
RECORD_NAME = "sub.yourdomain.com"def get_public_ip():
    return requests.get("https://api.ipify.org").text.strip()def get_dns_ip():
    url = f"https://api.cloudflare.com/client/v4/zones/{ZONE_ID}/dns_records/{RECORD_ID}"
    headers = {"Authorization": f"Bearer {API_TOKEN}"}
    res = requests.get(url, headers=headers).json()
    return res["result"]["content"]def update_dns(ip):
    url = f"https://api.cloudflare.com/client/v4/zones/{ZONE_ID}/dns_records/{RECORD_ID}"
    headers = {"Authorization": f"Bearer {API_TOKEN}", "Content-Type": "application/json"}
    data = {
        "type": "A",
        "name": RECORD_NAME,
        "content": ip,
        "ttl": 120
    }
    res = requests.put(url, headers=headers, json=data)
    return res.json()if __name__ == "__main__":
    current_ip = get_public_ip()
    dns_ip = get_dns_ip()
    if current_ip != dns_ip:
        print(f"IP changed: {dns_ip} → {current_ip}")
        update_dns(current_ip)
    else:
        print("IP unchanged.")

六、部署自动化更新任务

6.1 使用 cron 定时执行脚本（Linux/Mac）

crontab -e

添加如下条目：

*/5 * * * * /home/user/ddns_update.sh > > /var/log/ddns.log 2 > &1

6.2 Docker 容器化部署（推荐）

可将 DDNS 脚本打包为 Docker 镜像，部署在树莓派、NAS、路由器、云主机等环境中：

FROM python:3.10
COPY ddns.py /app/
WORKDIR /app
RUN pip install requests
CMD ["python", "ddns.py"]

在 Uptime Kuma、OpenWRT、Home Assistant 中均有集成方式

七、常见问题与排查指南

八、拓展与增强方案

• ✅ 支持 IPv6（AAAA 记录）更新

• ✅ 多域名/多子域批量 DDNS 管理

• ✅ 接入日志系统（如 Promtail + Grafana）

• ✅ 更新成功后发送 Telegram / 邮件通知

• ✅ 与其他设备同步 IP 状态（双活同步）

• ---

九、总结与建议

通过 Cloudflare DNS API，我们可以轻松构建一个 高可用、零费用、可定制的 DDNS 动态域名解析服务。适用于家庭宽带、办公服务器、自建站点、IoT 设备远程管理等场景。