域名接入 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 记录、其他什么都干不了的令牌。步骤如下。
- 登录 Cloudflare 控制台,右上角头像 →「我的个人资料」→「API 令牌」→「创建令牌」。
- 模板列表里选 Edit zone DNS(编辑区域 DNS)这个现成模板,它预置了
Zone - DNS - Edit和Zone - Zone - Read两项权限,正好是改记录所需,不多不少。 - **Zone Resources(区域资源)**这一项是关键:默认可能是全部域名,把它收敛成「Include → Specific zone → 只选你的目标域名」。这一步决定了这把令牌就算丢了,也只能祸害这一个域名。
- 需要更严的话,再给令牌加有效期(Client IP Filtering 也可以把来源 IP 限制到你服务器的出口 IP,家宽 IP 会变就别加这一项,否则 DDNS 脚本自己会被挡在门外)。
- 点「继续以显示摘要」→「创建令牌」。令牌字符串只显示这一次,当场复制到安全的地方存好——密码管理器、服务器上权限收紧的配置文件,都行;关掉页面就再也看不到,只能重新生成。
WARNING令牌生成后先想好存放位置再复制。最常见的翻车是随手粘进聊天窗口、笔记软件或者提交进了 Git 仓库。令牌一旦进过公开仓库,就按已经泄露处理:立刻吊销重建,不要抱侥幸心理。
准备工作:Zone ID、请求头与令牌验证
调用任何接口前,手里要有三样东西。
第一样是 Zone ID,即域名在 Cloudflare 里的唯一编号。打开控制台进入该域名的概览页,右下角「API」区域里就有 Zone ID,复制下来。也可以用 API 按域名查:
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 提供专门的验证接口,新令牌到手先跑一遍:
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。为了后面命令简洁,先在终端里设两个变量:
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 | 备注,可选,写给人看的 |
查:列出记录
curl -s "https://api.cloudflare.com/client/v4/zones/$CF_ZONE/dns_records" \ -H "Authorization: Bearer $CF_TOKEN" | jq返回的 result 是一个数组,域名下全部记录都在里面。实际用的时候要按条件筛,比如只看某一条 A 记录:
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 脚本读的正是这两个字段。
增:新建记录
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 最干净:
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 留给「整条记录重新定义」的场景。
删:删除记录
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,发现和解析记录不一致,就把记录改过来。
脚本逻辑拆成四步,一步都不多余:
- 查当前公网 IP(问一个外部服务「我从外面看是哪个 IP」)。
- 用 GET 读 Cloudflare 里现有记录的
content。 - 两个 IP 相同 → 什么都不做,直接退出。
- 不同 → 用 PATCH 更新记录,并把这次变更写进日志。
第 3 步的「相同就退出」非常重要:没变化就不发更新请求,既省调用次数,也避免日志被无意义的「更新成功」刷满,更避免频繁写操作触发不必要的传播动作。
完整脚本
在跑脚本的机器上(家里的路由器、旁挂的小主机、NAS 都行,只要能联网、能跑 bash)建一个脚本,比如 /opt/scripts/cf-ddns.sh。查公网 IP 的服务有好几个,选一个稳定的即可;Cloudflare 自家就提供了一个专门的端点 https://www.cloudflare.com/cdn-cgi/trace,返回里有一行 ip=,顺手还能校验出口,本篇就用它:
#!/usr/bin/env bashset -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"; }
# 第一步:查当前公网 IPCUR_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 1fi
# 第二步:读现有记录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 1fi
# 第三步:相同就退出if [ "$CUR_IP" = "$OLD_IP" ]; then exit 0fi
# 第四步:不同才更新,并记日志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 1fi逐段讲解
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 里。编辑当前用户的定时任务:
chmod +x /opt/scripts/cf-ddns.shcrontab -e加一行,每 5 分钟跑一次:
*/5 * * * * /opt/scripts/cf-ddns.sh5 分钟是个均衡的选择:IP 变更后最多 5 分钟新记录就位,再叠加 DNS 本身的缓存时间,实际感知到的中断通常在几分钟内。没必要压到每分钟——运营商换 IP 没那么频繁,过密的轮询只会白白消耗调用次数。
令牌文件单独存放并收紧权限:
sudo mkdir -p /etc/cf-ddnsecho "YOUR_TOKEN" | sudo tee /etc/cf-ddns/token > /dev/nullsudo chmod 600 /etc/cf-ddns/tokensudo chown root:root /etc/cf-ddns/tokenchmod 600 意味着只有 root 能读。令牌文件权限放成 644,等于同机任何用户都能读走你的令牌,这一步偷懒不得。如果脚本以普通用户身份跑,就把文件属主改成那个用户,权限仍然保持 600。
日志方面,脚本只在 IP 真正变化或出错时才写一行,量很小;系统自带的 logrotate 一般会顺带管 /var/log 下的文件,不放心的可以在 /etc/logrotate.d/ 里给它单独加一条按周轮转的规则,一行配置的事,不展开。
WARNING再强调一遍存放纪律:脚本可以进仓库,令牌不行。提交代码前养成看一眼
git diff的习惯;万一令牌已经误提交并推送到了公开仓库,删文件、改历史都不够,唯一有效的补救是去控制台把那把令牌吊销重建。
安全纪律清单
把前面零散说的收成一张表,贴在手边执行:
| 纪律 | 做法 |
|---|---|
| 最小权限 | 用 Edit zone DNS 模板,只给 DNS 编辑,不给多余权限 |
| 按域名收敛 | Zone Resources 只选目标域名,一把令牌只管一个域 |
| 独立存放 | 令牌放单独配置文件,权限 600,不写死在脚本里 |
| 不进仓库 | 脚本与令牌分离;仓库里只放脚本和示例配置 |
| 定期轮换 | 令牌设有效期,到期前生成新令牌、替换、再吊销旧的 |
| 出事能止损 | 每把令牌用途单一,泄露时吊销它不影响其他服务 |
轮换的正确顺序是「先建新的、换上、验证、再删旧的」,反过来做会让服务先断一阵。给不同用途(DDNS、证书签发、面板集成)各发一把令牌,不要一把令牌走天下——分开之后,哪把出了问题、该吊销哪把,一目了然。
排障
401 或 403:令牌无效或权限不够
先跑一遍验证接口,确认令牌本身活着:
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 加四件套。