如何通过 Cloudflare DNS API 实现自动化域名管理

一、为什么要使用 Cloudflare DNS API？

在自动化部署、DevOps 工作流和现代网站架构中，自动化 DNS 管理 是一项关键能力。无论你是为开发环境配置子域名，还是为 Let’s Encrypt 签发 SSL 证书自动验证 DNS，Cloudflare 的 DNS API 都提供了强大支持。

主要优势：

✅ 免费使用，适合个人开发者与企业级项目
✅ 可精细控制权限的 API Token
✅ 支持 A、CNAME、MX、TXT 等所有记录类型
✅ 完美集成 CI/CD、GitOps、Terraform 等自动化工具链
✅ 支持 DDNS（动态域名解析）功能

> 核心关键词：Cloudflare DNS API、自动化域名管理、动态 DNS、CI/CD DNS 配置、DevOps DNS 工具

二、准备工作：API Token 与域名接入

2.1 将域名接入 Cloudflare

注册或登录 Cloudflare 控制台
添加你已有的域名，例如 example.com
更换域名 DNS 到 Cloudflare 提供的 NS（在域名注册商后台操作）

2.2 创建 API Token

打开 Cloudflare 控制台 → Profile → API Tokens
点击 “Create Token” → 使用 “Edit zone DNS” 模板
设置权限：
- Zone.Zone: Read
- Zone.DNS: Edit
限制 Token 的作用域为某个指定域名
生成后复制保存 CF_API_TOKEN

> 长尾关键词：Cloudflare API Token 最小权限、Cloudflare DNS 权限配置

三、获取 Zone ID 与 DNS Record ID

在 Cloudflare 的 API 调用中，管理 DNS 记录需要两个重要参数：

zone_id：你的域名在 Cloudflare 的唯一标识
record_id：DNS 记录的唯一 ID

获取 Zone ID：

curl -X GET "https://api.cloudflare.com/client/v4/zones?name=example.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?name=sub.example.com" \
  -H "Authorization: Bearer $CF_API_TOKEN" \
  -H "Content-Type: application/json"

> 相关关键词：Cloudflare DNS record ID 获取、zone id 查询方式

四、Bash 脚本：自动更新 DNS A 记录

以下 Bash 脚本支持自动检测公网 IP 并更新 DNS A 记录，适合用于 DDNS 或开发测试环境的动态绑定。

#!/bin/bash

CF_API_TOKEN="your_api_token"
ZONE_ID="your_zone_id"
RECORD_NAME="home.example.com"
RECORD_TYPE="A"

# 获取当前公网 IP
IP=$(curl -s https://api.ipify.org)

# 获取 record ID
RECORD_ID=$(curl -s -X GET "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/dns_records?type=$RECORD_TYPE&name=$RECORD_NAME" \
  -H "Authorization: Bearer $CF_API_TOKEN" | jq -r '.result[0].id')

# 获取记录当前值
OLD_IP=$(curl -s -X GET "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/dns_records/$RECORD_ID" \
  -H "Authorization: Bearer $CF_API_TOKEN" | jq -r '.result.content')

# 判断是否需要更新
if [ "$IP" != "$OLD_IP" ]; then
  echo "Updating $RECORD_NAME: $OLD_IP → $IP"
  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\":\"$RECORD_TYPE\",\"name\":\"$RECORD_NAME\",\"content\":\"$IP\",\"ttl\":120}"
else
  echo "IP address unchanged."
fi

> 长尾关键词：Cloudflare DDNS 脚本、动态 A 记录更新、Shell 自动同步 DNS

五、Python 实现：更适合复杂业务逻辑

如果需要更好的结构与异常处理，可以使用 Python 脚本：

import os, requests

API_TOKEN = os.getenv("CF_API_TOKEN")
ZONE_ID = os.getenv("CF_ZONE_ID")
RECORD_NAME = "dev.example.com"

def get_public_ip():
    return requests.get("https://api.ipify.org").text.strip()

def get_record_id():
    url = f"https://api.cloudflare.com/client/v4/zones/{ZONE_ID}/dns_records?name={RECORD_NAME}"
    headers = {"Authorization": f"Bearer {API_TOKEN}"}
    response = requests.get(url, headers=headers).json()
    return response["result"][0]["id"], response["result"][0]["content"]

def update_record(record_id, new_ip):
    url = f"https://api.cloudflare.com/client/v4/zones/{ZONE_ID}/dns_records/{record_id}"
    data = {
        "type": "A",
        "name": RECORD_NAME,
        "content": new_ip,
        "ttl": 120
    }
    headers = {
        "Authorization": f"Bearer {API_TOKEN}",
        "Content-Type": "application/json"
    }
    response = requests.put(url, headers=headers, json=data)
    return response.json()

if __name__ == "__main__":
    ip = get_public_ip()
    record_id, old_ip = get_record_id()
    if ip != old_ip:
        print(f"IP changed: {old_ip} → {ip}")
        update_record(record_id, ip)
    else:
        print("No IP change.")

> 关键词扩展：Python 自动化 DNS 管理、Cloudflare Python API 示例、动态 DNS 实现方式

六、CI/CD 集成：用 GitHub Actions 自动同步 DNS 记录

结合 GitOps 与 Infrastructure as Code，我们可以在代码变更时自动修改 DNS 配置：

name: Update Cloudflare DNS
on:
  push:
    branches:
      - main

jobs:
  update_dns:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v3

      - name: Update DNS record
        run: |
          curl -X PUT "https://api.cloudflare.com/client/v4/zones/${{ secrets.CF_ZONE_ID }}/dns_records/${{ secrets.CF_RECORD_ID }}" \
          -H "Authorization: Bearer ${{ secrets.CF_API_TOKEN }}" \
          -H "Content-Type: application/json" \
          --data '{"type":"A","name":"prod.example.com","content":"1.2.3.4","ttl":120}'

> 长尾关键词：GitHub Actions 自动修改 DNS、Cloudflare CI 自动化、DNS 记录 GitOps 管理

七、结合 Terraform 实现全面 DNS 自动化

Terraform 支持 Cloudflare Provider，推荐用于管理多个域名与环境的 DNS 配置：

provider "cloudflare" {
  api_token = var.cf_api_token
}

resource "cloudflare_record" "dev_a" {
  zone_id = var.zone_id
  name    = "dev"
  value   = var.ip
  type    = "A"
  ttl     = 120
}

执行：

terraform init
terraform apply

> 扩展关键词：Terraform Cloudflare DNS 配置、IaC 自动化 DNS 管理、Cloudflare DevOps 工具集成

八、常见问题与排查建议

问题	解决方式
403 Forbidden，API 无权限	检查 Token 权限是否包含 DNS Edit
API 调用成功但记录未更新	检查是否使用了正确的 record_id
TTL 设置后无效	最低 120 秒，无法设置为 0
多记录冲突	指定唯一的 `name` 和 `type`
动态 IP 变更后未同步	脚本未设置定时任务，请结合 cron 或 systemd 定时运行