通过 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 并添加域名

注册 Cloudflare 账号
添加已有域名（例如 yourdomain.com）
设置 NS 记录至 Cloudflare 提供的解析服务器
等待 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 个基本参数：

参数名	说明
Zone ID	Cloudflare 分配给域名的唯一标识
Record ID	子域名（A 记录）在 Cloudflare 中的 ID
API Token	授权调用 DNS 接口的密钥

你可以通过如下 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 中均有集成方式

七、常见问题与排查指南

问题	排查建议
A 记录未更新	确保 API Token 权限为 Zone.DNS Edit
`Record ID` 获取失败	检查 `type=A` 与 `name=sub.domain.com` 参数是否正确
IP 检测始终为空或错误	更换 IP 获取接口，如 `https://ifconfig.me`
更新太频繁被限流（429）	设置合适的运行间隔（建议 ≥ 300 秒）
DNS 更新但访问失败	检查 ISP 是否封锁 80/443 端口，或设置端口转发