4668 字
23 分钟
用 API 管理 DNS 与 DDNS 动态解析

域名接入 Cloudflare、解析记录也都理顺之后,迟早会遇到一个问题:记录一多,控制台点来点去太慢;有些记录天生就该由程序维护,比如家里宽带的公网 IP 三天两头变,靠人盯着改 A 记录根本不现实。这时候就该请出 Cloudflare 的 API 了。

这一篇分两条主线。前半段把 API 的基本功打牢:建一把只够用的 API Token,用 curl 把 DNS 记录的增、删、改、查四件套跑通。后半段落到最经典的实战——DDNS 动态解析:写一个 bash 脚本,发现公网 IP 变了就自动更新记录,再挂上 cron,从此不用再管它。上一篇讲记录本身的时候提到的那些字段(proxied、ttl、记录类型),在这一篇会全部变成 JSON 里的参数,建议先看过 DNS 记录详解与常见坑 再回来,衔接会顺很多。

为什么用 API 管 DNS#

先说清楚边界,免得走偏。API 适合三类事情:

  • 批量操作:几十上百条记录要建、要改、要迁移,控制台一条条点既慢又容易点错,脚本一次跑完,还能先导出备份再动手。
  • 自动化维护:记录的值本身会变,DDNS 是典型;还有证书签发时的 TXT 验证记录、监控探活失败后自动切记录,都属于这类。
  • 给程序调用:你自己的面板、脚本、CI 流程需要读写解析,API 是唯一的正经入口。

反过来,控制台能点完的一次性小事,就别硬上脚本:临时改一条记录、开个代理状态,鼠标点两下比写命令快得多,还不容易出错。API 的价值在重复和自动,不在炫技。

本篇用的全部是 Cloudflare API v4,基础地址固定:

https://api.cloudflare.com/client/v4

所有请求都是 HTTPS 加 JSON,认证靠请求头里的令牌。先把认证这件事做对,后面全是套路。

先建对令牌:Token 与全局 API Key 的区别#

Cloudflare 账户里能拿到的凭据不止一种,新手最容易踩的坑就是抓起全局 API Key 就写进脚本。先把几种凭据摆开对比:

凭据权限范围能否按域名收敛泄露后果结论
API Token创建时逐项勾选,可细到单个域名的单个功能可以,只授权指定 Zone影响面被锁在授权范围内,可单独吊销脚本和程序一律用它
全局 API Key(Global API Key)账户下全部域名、全部功能,等同账户全权不可以等于账户沦陷,能改所有域名、所有设置不要用它写脚本
Origin CA Key只用于签发源站证书不涉及 DNS影响面小,但也管不了记录与本篇无关,别混用

结论只有一句:永远用 API Token,全局 API Key 不进任何脚本。全局 API Key 在控制台「我的个人资料 → API 令牌」页面下方能看到,它和登录邮箱配对使用,权限等同你本人。把全局 API Key 写进脚本,等于把整个 Cloudflare 账户的钥匙挂在脚本里,脚本一旦泄露到公开仓库或日志里,账户下所有域名任人改。Token 则不同:你给它多大权,它就只有多大权,泄露了吊销一把就行,不影响其他服务。

建一把最小权限的 API Token#

目标:一把只允许改某一个域名的 DNS 记录、其他什么都干不了的令牌。步骤如下。

  1. 登录 Cloudflare 控制台,右上角头像 →「我的个人资料」→「API 令牌」→「创建令牌」。
  2. 模板列表里选 Edit zone DNS(编辑区域 DNS)这个现成模板,它预置了 Zone - DNS - Edit 和 Zone - Zone - Read 两项权限,正好是改记录所需,不多不少。
  3. **Zone Resources(区域资源)**这一项是关键:默认可能是全部域名,把它收敛成「Include → Specific zone → 只选你的目标域名」。这一步决定了这把令牌就算丢了,也只能祸害这一个域名。
  4. 需要更严的话,再给令牌加有效期(Client IP Filtering 也可以把来源 IP 限制到你服务器的出口 IP,家宽 IP 会变就别加这一项,否则 DDNS 脚本自己会被挡在门外)。
  5. 点「继续以显示摘要」→「创建令牌」。令牌字符串只显示这一次,当场复制到安全的地方存好——密码管理器、服务器上权限收紧的配置文件,都行;关掉页面就再也看不到,只能重新生成。
WARNING

令牌生成后先想好存放位置再复制。最常见的翻车是随手粘进聊天窗口、笔记软件或者提交进了 Git 仓库。令牌一旦进过公开仓库,就按已经泄露处理:立刻吊销重建,不要抱侥幸心理。

准备工作:Zone ID、请求头与令牌验证#

调用任何接口前,手里要有三样东西。

第一样是 Zone ID,即域名在 Cloudflare 里的唯一编号。打开控制台进入该域名的概览页,右下角「API」区域里就有 Zone ID,复制下来。也可以用 API 按域名查:

Terminal window
curl -s "https://api.cloudflare.com/client/v4/zones?name=example.com" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json"

第二样是请求头。Token 的认证头写法固定:

Authorization: Bearer YOUR_TOKEN

注意这和全局 API Key 的老式写法(X-Auth-Email 加 X-Auth-Key 两个头)完全不同,本篇全程只用 Bearer 这一种。

第三样是先验明令牌可用。Cloudflare 提供专门的验证接口,新令牌到手先跑一遍:

Terminal window
curl -s "https://api.cloudflare.com/client/v4/user/tokens/verify" \
-H "Authorization: Bearer YOUR_TOKEN"

返回 JSON 里 success 为 true、result.status 为 active,说明令牌有效。下面所有命令里,把 YOUR_TOKEN 换成你的令牌、ZONE_ID 换成你的 Zone ID。为了后面命令简洁,先在终端里设两个变量:

Terminal window
export CF_TOKEN="YOUR_TOKEN"
export CF_ZONE="ZONE_ID"

curl 四件套:记录的增删改查#

DNS 记录的接口路径是 /zones/{zone_id}/dns_records,单条记录再拼上记录 ID。返回 JSON 的结构统一:success 表示成败,errors 数组放错误信息,result 是数据本体。每条记录的关键字段先认识一下:

字段含义
id记录的唯一 ID,改和删都要靠它定位
name完整主机名,如 home.example.com
type记录类型,如 A、AAAA、CNAME、TXT
content记录的值,A 记录就是 IP 地址
proxied是否走 Cloudflare 代理(橙云),true / false
ttl生存时间,1 表示自动;开了代理时实际由 Cloudflare 接管
comment备注,可选,写给人看的

查:列出记录#

Terminal window
curl -s "https://api.cloudflare.com/client/v4/zones/$CF_ZONE/dns_records" \
-H "Authorization: Bearer $CF_TOKEN" | jq

返回的 result 是一个数组,域名下全部记录都在里面。实际用的时候要按条件筛,比如只看某一条 A 记录:

Terminal window
curl -s "https://api.cloudflare.com/client/v4/zones/$CF_ZONE/dns_records?type=A&name=home.example.com" \
-H "Authorization: Bearer $CF_TOKEN" | jq '.result[0] | {id, name, type, content, proxied, ttl}'

jq 在这里是刚需:原始 JSON 又长又挤,提取出 id 和 content 才能接着往下用——DDNS 脚本读的正是这两个字段。

增:新建记录#

Terminal window
curl -s -X POST "https://api.cloudflare.com/client/v4/zones/$CF_ZONE/dns_records" \
-H "Authorization: Bearer $CF_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"type": "A",
"name": "home",
"content": "203.0.113.10",
"ttl": 1,
"proxied": false,
"comment": "DDNS 家宽入口"
}' | jq

几个参数说明:name 可以只写子域名前缀(home),也可以写全名,效果一样;ttl 传 1 是自动;DDNS 用的记录建议 proxied 设为 false(灰云直连),原因后面排障部分会讲——开了代理后,从外面查到的就不是你的真实 IP 了。创建成功后,返回的 result.id 就是这条记录的 ID,记下来,改和删都用它。

改:更新记录#

全量更新用 PUT,请求体要带上记录的完整定义;只改个别字段用 PATCH。DDNS 只换 IP,用 PATCH 最干净:

Terminal window
curl -s -X PATCH "https://api.cloudflare.com/client/v4/zones/$CF_ZONE/dns_records/RECORD_ID" \
-H "Authorization: Bearer $CF_TOKEN" \
-H "Content-Type: application/json" \
-d '{"content": "203.0.113.20"}' | jq

注意一个细节:如果这条记录是经控制台或脚本以 PUT 方式整体维护的,用 PUT 时漏写某个字段,可能把该字段重置成默认值。所以日常脚本里优先 PATCH 做局部修改,PUT 留给「整条记录重新定义」的场景。

删:删除记录#

Terminal window
curl -s -X DELETE "https://api.cloudflare.com/client/v4/zones/$CF_ZONE/dns_records/RECORD_ID" \
-H "Authorization: Bearer $CF_TOKEN" | jq

删除没有二次确认,接口返回成功就是真删了。批量清理前先用 GET 把整域记录导出来存一份 JSON 当备份,这是能后悔的唯一办法。

四件套到此齐了。把它们串起来,就是 DDNS。

DDNS 实战:IP 一变就自动更新#

需求与思路#

家宽、4G 路由、没有固定公网 IP 的小服务器,都有同一个麻烦:运营商隔段时间就换一次公网 IP,home.example.com 指过去就成了空门牌。DDNS(动态 DNS)干的就是一件事:周期性检查当前公网 IP,发现和解析记录不一致,就把记录改过来。

脚本逻辑拆成四步,一步都不多余:

  1. 查当前公网 IP(问一个外部服务「我从外面看是哪个 IP」)。
  2. 用 GET 读 Cloudflare 里现有记录的 content。
  3. 两个 IP 相同 → 什么都不做,直接退出。
  4. 不同 → 用 PATCH 更新记录,并把这次变更写进日志。

第 3 步的「相同就退出」非常重要:没变化就不发更新请求,既省调用次数,也避免日志被无意义的「更新成功」刷满,更避免频繁写操作触发不必要的传播动作。

完整脚本#

在跑脚本的机器上(家里的路由器、旁挂的小主机、NAS 都行,只要能联网、能跑 bash)建一个脚本,比如 /opt/scripts/cf-ddns.sh。查公网 IP 的服务有好几个,选一个稳定的即可;Cloudflare 自家就提供了一个专门的端点 https://www.cloudflare.com/cdn-cgi/trace,返回里有一行 ip=,顺手还能校验出口,本篇就用它:

#!/usr/bin/env bash
set -euo pipefail
# ===== 配置区 =====
CF_TOKEN_FILE="/etc/cf-ddns/token"
CF_ZONE="ZONE_ID"
CF_NAME="home.example.com"
CF_TYPE="A"
LOG_FILE="/var/log/cf-ddns.log"
CF_TOKEN="$(cat "$CF_TOKEN_FILE")"
API="https://api.cloudflare.com/client/v4"
log() { echo "$(date '+%F %T') $*" >> "$LOG_FILE"; }
# 第一步:查当前公网 IP
CUR_IP="$(curl -s https://www.cloudflare.com/cdn-cgi/trace | grep -E '^ip=' | cut -d= -f2)"
if [ -z "$CUR_IP" ]; then
log "ERROR 拿不到当前公网 IP,本轮跳过"
exit 1
fi
# 第二步:读现有记录
RESP="$(curl -s "$API/zones/$CF_ZONE/dns_records?type=$CF_TYPE&name=$CF_NAME" \
-H "Authorization: Bearer $CF_TOKEN")"
OLD_IP="$(echo "$RESP" | jq -r '.result[0].content // empty')"
REC_ID="$(echo "$RESP" | jq -r '.result[0].id // empty')"
if [ -z "$REC_ID" ]; then
log "ERROR 记录 $CF_NAME 不存在,请先在控制台或用 POST 创建"
exit 1
fi
# 第三步:相同就退出
if [ "$CUR_IP" = "$OLD_IP" ]; then
exit 0
fi
# 第四步:不同才更新,并记日志
UPD="$(curl -s -X PATCH "$API/zones/$CF_ZONE/dns_records/$REC_ID" \
-H "Authorization: Bearer $CF_TOKEN" \
-H "Content-Type: application/json" \
-d "{\"content\": \"$CUR_IP\"}")"
if [ "$(echo "$UPD" | jq -r '.success')" = "true" ]; then
log "OK $CF_NAME: $OLD_IP -> $CUR_IP"
else
log "ERROR 更新失败: $(echo "$UPD" | jq -c '.errors')"
exit 1
fi

逐段讲解#

  • set -euo pipefail:任何一步命令失败就整体退出,避免拿着空值继续往下跑,把错带进更新请求里。
  • 令牌从文件读:CF_TOKEN_FILE 指向单独的配置文件,脚本本身可以放心进 Git、放心给人看;令牌文件单独管控权限,下文细说。
  • 查 IP 用 cdn-cgi/trace:它返回多行键值对,grep '^ip=' 取出 IP 那一行。也可以换成 https://ifconfig.me/ip、https://icanhazip.com 这类纯文本服务,任选其一,别在脚本里堆一串备用源把逻辑搞复杂——真要高可用,cron 下一轮自然会重试。
  • 拿不到 IP 就退出:CUR_IP 为空说明本机网络都不通,这时候更新记录毫无意义,还可能把空值写进去,绝不能拿空值或异常值去更新记录,宁可这一轮跳过。
  • GET 时带 type 和 name 过滤:服务端先筛一遍,jq 再取 .result[0],拿到的就是目标记录的现值和 ID。取不到记录说明这条记录还没建过,脚本不负责自动创建——先用上一节的 POST 或在控制台建好,避免脚本行为超出预期。
  • 比较在本地做:先比对、后请求,这是整个脚本的核心纪律。
  • 更新用 PATCH 只传 content:只改 IP,其他字段(代理状态、TTL、备注)一概不动。
  • 结果以 success 字段为准:不要只看 curl 的退出码——HTTP 层通了、业务层也可能失败,失败时把返回 JSON 的 errors 数组原样记进日志,排障时全靠它定位。

让它自动跑:cron 与权限#

脚本手动跑通一次后,挂到 cron 里。编辑当前用户的定时任务:

Terminal window
chmod +x /opt/scripts/cf-ddns.sh
crontab -e

加一行,每 5 分钟跑一次:

*/5 * * * * /opt/scripts/cf-ddns.sh

5 分钟是个均衡的选择:IP 变更后最多 5 分钟新记录就位,再叠加 DNS 本身的缓存时间,实际感知到的中断通常在几分钟内。没必要压到每分钟——运营商换 IP 没那么频繁,过密的轮询只会白白消耗调用次数。

令牌文件单独存放并收紧权限:

Terminal window
sudo mkdir -p /etc/cf-ddns
echo "YOUR_TOKEN" | sudo tee /etc/cf-ddns/token > /dev/null
sudo chmod 600 /etc/cf-ddns/token
sudo chown root:root /etc/cf-ddns/token

chmod 600 意味着只有 root 能读。令牌文件权限放成 644,等于同机任何用户都能读走你的令牌,这一步偷懒不得。如果脚本以普通用户身份跑,就把文件属主改成那个用户,权限仍然保持 600。

日志方面,脚本只在 IP 真正变化或出错时才写一行,量很小;系统自带的 logrotate 一般会顺带管 /var/log 下的文件,不放心的可以在 /etc/logrotate.d/ 里给它单独加一条按周轮转的规则,一行配置的事,不展开。

WARNING

再强调一遍存放纪律:脚本可以进仓库,令牌不行。提交代码前养成看一眼 git diff 的习惯;万一令牌已经误提交并推送到了公开仓库,删文件、改历史都不够,唯一有效的补救是去控制台把那把令牌吊销重建。

安全纪律清单#

把前面零散说的收成一张表,贴在手边执行:

纪律做法
最小权限用 Edit zone DNS 模板,只给 DNS 编辑,不给多余权限
按域名收敛Zone Resources 只选目标域名,一把令牌只管一个域
独立存放令牌放单独配置文件,权限 600,不写死在脚本里
不进仓库脚本与令牌分离;仓库里只放脚本和示例配置
定期轮换令牌设有效期,到期前生成新令牌、替换、再吊销旧的
出事能止损每把令牌用途单一,泄露时吊销它不影响其他服务

轮换的正确顺序是「先建新的、换上、验证、再删旧的」,反过来做会让服务先断一阵。给不同用途(DDNS、证书签发、面板集成)各发一把令牌,不要一把令牌走天下——分开之后,哪把出了问题、该吊销哪把,一目了然。

排障#

401 或 403:令牌无效或权限不够#

先跑一遍验证接口,确认令牌本身活着:

Terminal window
curl -s "https://api.cloudflare.com/client/v4/user/tokens/verify" \
-H "Authorization: Bearer $CF_TOKEN" | jq

验证通过但具体操作还是报错,就去看失败响应里的 errors 数组:里面有错误码和一句说明文字,对照着查——是权限不足、Zone ID 写错、还是记录 ID 不存在,基本都能从说明里读出来。最常见的三种情况:建令牌时 Zone Resources 没勾上这个域名;模板选错,只给了 Read 没给 Edit,查得到改不动;复制令牌时多了空格或少了一截。不要只盯着 HTTP 状态码猜,errors 才是官方给的诊断书。

更新成功但解析没变#

先分清你查的是什么。如果这条记录开了橙云代理(proxied: true),外部查询到的本来就是 Cloudflare 边缘节点的 IP,而不是你源站的 IP——这是代理的工作方式,不是更新没生效,记录里的 content 才是源站地址,判断更新成功与否要回 API 里看 content,别拿 dig 的结果对。DDNS 场景通常要的是直连,所以前面建记录时建议 proxied: false。

如果确认是灰云直连、API 里 content 也已经是新 IP,但解析还是旧的,那就是缓存与 TTL:各级递归解析器会按 TTL 缓存旧答案,没过期之前问谁都是旧值。用 dig home.example.com @1.1.1.1 和换几个公共解析器交叉验证,确认只是缓存未过期,剩下的只能等。想让以后切换更快,可以把这条记录的 TTL 设短一些(比如 120 秒),代价是查询量略增,家宽场景完全无所谓。关于 TTL 与代理状态对解析的影响,DNS 记录详解与常见坑 里有完整的展开。

脚本每轮都在「更新」:比较逻辑写错#

症状是日志里每 5 分钟一条变更记录,IP 看起来还没变过。九成是比较的双方对不上:CUR_IP 混进了空格、换行或 IPv6 地址(比如查 IP 的服务在双栈环境下返回了 IPv6,而记录是 A 类型),或者 jq 取值时取到了另一条同名记录。排查方法:临时在脚本里把 CUR_IP 和 OLD_IP 都打进日志,跑一轮,眼见为实。修好之后记得把调试输出撤掉。

记录莫名其妙被改回去#

如果发现记录总被「改回」旧 IP,先想想是不是有两台机器、两个脚本在同时维护同一条记录,或者旧路由器上还留着一份 DDNS 配置在跑。两个自动化互相打架时,表现就是记录来回横跳。自动化工具只留一份,这是纪律。

小结#

  • 凭据只用 API Token 并按最小权限、按域名收敛,全局 API Key 永不进脚本。
  • 接口套路固定:Bearer 认证头、/zones/{id}/dns_records 路径、GET 查、POST 增、PATCH 局部改、DELETE 删,结果一律看返回 JSON 的 success 与 errors。
  • DDNS 脚本的灵魂是「先比较、无变化就退出」,配合 cron 每 5 分钟一轮,就是零维护的动态解析。
  • 令牌独立文件存放、权限 600、定期轮换、用途单一,泄露时能一把吊销干净止损。

到这里,Cloudflare 的「手点控制台」阶段就算毕业了:记录能批量管、能自动维护,后面无论是给面板做集成,还是把解析变更纳入自己的运维流程,地基都是这一篇的 Token 加四件套。

用 API 管理 DNS 与 DDNS 动态解析
https://www.anexns.cloudns.org/posts/cloudflare-api-token-ddns/
作者
Anexns
发布于
2026-11-15
许可协议
CC BY-NC-SA 4.0