Cloudflare新版界面获取Account ID与API Token实操指南

先说点实际的。Cloudflare 这个牌子做网站的人应该都不陌生CDN、DNS、WAF、证书管理它都是一把好手。平时大家直接在控制台里点点鼠标就能完成大部分操作可一旦你想上自动化——比如用 acme.sh 自动续证书、跑个 DDNS 脚本把家庭宽带的动态 IP 同步到域名解析、或者用 Terraform 统一管理一堆 DNS 记录——你就绕不开两个东西Cloudflare Account ID帐户 ID和 API TokenAPI 令牌。偏偏这两年 Cloudflare 界面改版特别频繁不少原本一眼就能找到的入口换了位置网上很多教程截图还停留在旧版布局。我前阵子帮朋友排查一个脚本反复报错折腾半天发现他连 Account ID 都是从旧教程里抄来的压根不知道新版面板点哪里。所以这篇就把新版界面下获取 Account ID 和创建 API Token 的完整流程、权限理解、常见坑一次性讲清楚。适合刚接触 Cloudflare API、或者被新版界面搞懵的朋友直接照着操作不用再东翻西找。1. 先搞懂这两串字符到底有什么用1.1 Account ID 和 API Token 是什么关系Account ID 是你 Cloudflare 账户在系统里的唯一编号通常是一串 32 位的十六进制字符串长得像a1b2c3d4e5f6...这样。它不是密钥本身不携带任何访问权限把它理解为“门牌号”更合适——API 请求里带上它Cloudflare 才知道你要操作的是哪个账户下的资源。API Token 则是一把真正的钥匙它是 Cloudflare 推出的细粒度 API 凭证体系。每个 Token 可以精确限制到“某个账户下的某类资源只允许某种操作”比如“只允许修改 example.com 的 DNS 记录不允许动其他域名”。相比以前那种一把抓的 Global API KeyToken 的核心价值就是最小权限原则就算某个 Token 泄露了攻击者也只能做你预先划定的那点事影响范围可控不至于整个账户都被人端走。这里有一个新手特别容易混淆的点Account ID 不等于 API Token两者在大多数 API 请求中要一起使用。你可以简单类比Account ID 是银行卡号API Token 是取款密码。卡号可以大大方方给人看密码给了人那问题就大了。1.2 有哪些场景非要这两个东西不可我梳理了一下日常工作中最常见的需求基本可以分为四类证书自动化acme.sh、certbot 的 Cloudflare 插件在申请 Lets Encrypt 证书时需要调用 DNS API 添加 TXT 验证记录。这需要具备 DNS 编辑权限的 Token。DDNS 动态域名家里宽带 IP 是动态的用脚本定时调用 Cloudflare API 把 A 记录更新为当前公网 IP。这类脚本通常会用到 DNS 编辑权限。基础设施即代码Terraform 的 Cloudflare Provider 需要 Account ID 和 Token 来完成资源的声明式管理多人协作时还会把凭证放到 CI/CD 的变量里。第三方工具接入比如部分博客评论系统、监控工具、Caddy 的 DNS challenge、K3s 的云控制器等都支持用 Cloudflare API 做集成。说实话前两类是绝大多数个人站长和自托管玩家的刚需。你只要写过一次 acme.sh 的--dns dns_cf参数就会明白这两个凭证填对有多重要——填错了就是各种401 Unauthorized和403 Forbidden而且报错信息又短又难懂排查全靠猜。注意Global API Key 虽然也能完成上述操作但它相当于你账户的最高权限凭证泄露等于把整个 Cloudflare 账户交给别人。只要能用 API Token 的地方我都强烈建议不用 Global API Key。1.3 新版界面的改造重点Cloudflare 近两年的界面改版核心逻辑是把“账户管理”和“站点/应用管理”分开。旧版里点右上角账户头像就能看到“我的资料 API 令牌”新版里入口位置和叫法都有了变化。比如老的“API 令牌”页面现在被收纳在“我的个人资料”之下不在原本的位置。另一个明显变化是域名概览页的排版右侧栏不再像以前那样直接展示 Account ID 的复制按钮需要进入特定页面才能看到。很多旧教程里教的方法——“进入域名页面右侧往下拉找 Account ID”——在新版页面已经失效了这也是很多人找不到的原因。搞清楚界面变化后下面直接上实操步骤。2. 获取 Account ID三条路径按需选择2.1 路径一从域名详情页复制最快这是新版界面上最直接的入口全程不超过 20 秒登录 Cloudflare 控制台在“账户主页”的域名列表中点击你要操作的域名进入该域名的详情页。看页面右侧的“概览”信息栏找到“帐户 ID”这一行边上有一个复制图标。点击复制图标Account ID 就进剪贴板了。需要注意这里拿到的是当前域名所属账户的 ID。如果你用同一个邮箱注册了多个账户或者加入了多个组织不同域名可能挂在不同账户下。复制前先确认域名归属账户是否正确否则后续 API 调用会提示资源不存在白白浪费时间排查。2.2 路径二从我的个人资料里获取如果域名已经被删除或者你只是想查询账户级信息而不想点进某个域名可以走个人资料路径点击页面右上角的账户头像选择“我的个人资料”。在左侧菜单里找到并点击“API 令牌”。进入 API 令牌页面后页面标题下方会直接给出“帐户 ID”一行小字加复制按钮非常醒目。这个页面其实就是创建 API Token 的同一个页面算是把两个关键信息放在了同一个地方。我一般建议新手记这个入口反正你早晚都要来这里创建 Token顺手把 Account ID 一起复制了省得在两个页面之间来回跳。2.3 路径三用 API 查 API给脚本党如果你的需求是写一个“自动初始化”脚本希望脚本自己发现 Account ID可以调用 Cloudflare 的/accounts接口。这个接口通常要求使用 Global API Key 或具备账户级读取权限的 Token实际使用频率不高但作为自动化兜底手段还是有价值的curl -X GET https://api.cloudflare.com/client/v4/accounts \ -H Authorization: Bearer YOUR_API_TOKEN \ -H Content-Type: application/json返回的 JSON 中result[0].id就是账户 ID。这个方式的适用场景是你在脚本里已经拿到了有账户权限的 Token想动态获取 ID 而不是硬编码。不过说实话Account ID 是静态值不太建议每次请求都去查把它保存成环境变量更稳妥也少一次网络请求。3. 创建 API Token完整流程、权限模板与参数解读3.1 从零开始创建 Token登录 Cloudflare 后打开“我的个人资料 API 令牌”页面。你会看到两个区域一个是“API 密钥”放着 Global API Key另一个是“API 令牌”点击蓝色的“创建令牌”按钮。点击后进入令牌创建页页面提供几排模板卡包括“编辑 Cloudflare DNS”“编辑 Cloudflare 的 Worker”等预设模板。先不急着选仔细看一下右侧的“自定义令牌”选项——这才是最常用的入口。我个人的建议是除非场景和模板完全吻合否则一律走自定义创建因为模板给的权限往往比实际需求大得多。3.2 模板、自定义、持久化三种创建方式的取舍先把这个对比讲清楚很多人建完 Token 都不知道自己建了个什么创建方式权限范围适用场景风险等级预设模板固定组合权限如仅 DNS 编辑快速测试、临时使用低-中自定义令牌按需勾选账户/区域资源和权限正式环境、日常脚本低Global API Key账户全部权限不建议使用极高自定义令牌的创建界面分四个部分令牌名称、权限配置、账户/区域资源限定、客户端 IP 地址过滤。令牌名称随便起但建议起得有意义比如home-ddns-dns-edit后期在审计日志里一眼能认出是干什么的。权限配置是重点下面单独讲。3.3 权限项详解别多给也别少给自定义令牌的权限分为“账户”和“区域”两组每组下面的权限项多达几十个新手很容易看花眼。这里挑最常用的几个说区域 DNS 编辑允许修改 DNS 记录DDNS 脚本、acme.sh DNS 验证都靠它是最常用的权限。区域 区域 读取允许读取区域配置信息比如查看域名列表、SSL 设置等。区域 区域设置 编辑允许修改区域级设置如缓存、安全级别等一般脚本用不到能不勾就不勾。账户 账户设置 读取读取账户基本信息部分自动化初始化脚本可能需要。账户 Cloudflare Tunnel 编辑管理 Tunnels如果你用 cloudflared 跑内网穿透会需要这个权限。账户 Workers 脚本 编辑部署和管理 Workers 脚本时的常见权限。配置完权限后还要在“区域资源”里选择令牌能作用于哪些域名。可以选择“所有区域”或“特定区域”。对于 DDNS 或证书脚本建议只勾选需要的那一个域名把爆炸半径缩到最小。最后一步“客户端 IP 地址过滤”是可选的填入你家的公网 IP 后即使令牌泄露也只有从该 IP 发起的请求才能通过。家里 IP 是动态的话就别填否则下次 IP 变了令牌直接失效你还要一脸懵地排查半天。创建完成后页面只会展示一次令牌明文格式是一串以_开头、包含随机字符的字符串。务必复制保存到密码管理器里关闭页面后就再也看不到完整令牌了。3.4 验证令牌是否可用拿到令牌后不要直接往脚本里塞先手动验证一次。用 curl 调用一个最简单的接口比如列出账户下的区域列表curl -X GET https://api.cloudflare.com/client/v4/zones \ -H Authorization: Bearer YOUR_API_TOKEN \ -H Content-Type: application/json如果返回的 JSON 里success字段为true说明令牌基本可用。如果想更精确地验证令牌是否具备某个域的 DNS 读取权限可以用curl -X GET https://api.cloudflare.com/client/v4/zones?nameexample.com \ -H Authorization: Bearer YOUR_API_TOKEN返回的result[0].id是 Zone ID和 Account ID 是两个不同的东西别搞混。Zone ID 代表某个具体域名Account ID 代表整个账户。API 请求的路径参数里用的往往是 Zone ID而某些账户级接口才用 Account ID。3.5 新版界面还能设置令牌有效期这里补充一个新版界面的细节创建令牌时支持设置有效期最短 1 天最长可以设为无限期。能设置有效期的场景一律建议设置。比如临时给某次调试创建的令牌直接设为 7 天过期到时间自动失效不用你惦记着手动撤销。长期运行的脚本才考虑较长有效期但最好配合定期轮换的习惯。4. 实操过程用官方 API 完成一次“读域名 → 改 DNS”全流程4.1 准备环境变量无论你用哪种工具第一步都是把凭证写进环境变量而不是硬编码在脚本里。以 bash 为例export CF_ACCOUNT_ID你的32位账户ID export CF_API_TOKEN你的令牌明文这样做的理由很简单脚本会到处传参、进版本库一旦硬编码下次不小心 push 到 GitHub 就是安全事故。我见过不止一个开源项目因为硬编码 Cloudflare Token 被机器人扫库后批量删除 DNS 记录教训相当惨痛。4.2 调用 API 前的参数核对在真实调用之前有一个非常容易踩的坑Cloudflare API 的很多接口需要 Zone ID 而不是 Account ID。比如你要改 DNS 记录API 路径是/zones/{zone_id}/dns_records/...这里的zone_id是某个域名的 ID不是账户 ID。获取 Zone ID 的办法是curl -X GET https://api.cloudflare.com/client/v4/zones?nameexample.com \ -H Authorization: Bearer $CF_API_TOKEN \ -H Content-Type: application/json然后把返回结果里的id字段和 Account ID 一起保存。这个环节虽然简单但在我排查过的问题里占比极高——很多人拿着 Account ID 往 Zone ID 的位置填收到 404 后还以为是 Token 权限问题白白浪费半天。4.3 完整示例添加一条 DNS 记录假设你要给ddns.example.com添加一条 A 记录指向1.2.3.4完整的调用如下curl -X POST https://api.cloudflare.com/client/v4/zones/{zone_id}/dns_records \ -H Authorization: Bearer $CF_API_TOKEN \ -H Content-Type: application/json \ --data { type: A, name: ddns, content: 1.2.3.4, ttl: 120, proxied: false }注意proxied这个字段。设成true表示走 Cloudflare CDN 代理外部请求看到的是 Cloudflare 的节点 IP源站 IP 被隐藏设成false则是纯 DNS 解析记录请求直达源站。DDNS 场景下通常不需要代理但如果你有隐藏源站 IP 的需求就要根据实际情况选择别照抄。返回 JSON 中的result.id是新记录的 ID。以后要更新这条记录用PUT /zones/{zone_id}/dns_records/{record_id}带上同样的 JSON 体即可。DDNS 脚本的核心逻辑其实就是“查记录 ID - 比对当前 IP - PUT 更新”理解了这一步写自己的 DDNS 脚本也不算难事。4.4 配合 acme.sh 申请证书的实测记录我再分享一个最常见的自动化场景acme.sh 用 DNS API 验证域名并自动续期证书。先在环境里配置export CF_Token你的令牌 export CF_Account_ID你的账户ID然后执行acme.sh --issue --dns dns_cf -d example.com -d *.example.comacme.sh 会自动调用 Cloudflare API 添加 TXT 记录等验证完成后解析记录。实测中这套流程在带*通配符的域名上特别省心不用每次手动去控制台加 TXT。不过有几个小地方值得注意acme.sh 优先读取CF_Token和CF_Account_ID这两个环境变量变量名不能写错否则它回退到CF_KeyGlobal API Key模式权限模型又变了。另外如果你多个域名挂在同一个账户下证书申请成功率很高但如果是跨账户管理就需要在特定域名下配置对应的变量否则脚本可能拿错域的权限。4.5 配合 Docker 与 Tunnel 的注意事项既然标题延伸到了容器和隧道场景这里多说一句。用cloudflared跑内网穿透时你会需要账户级的 Tunnel 管理权限。Docker 方式下常用配置文件或环境变量传入凭证。部分镜像把 Token 作为启动参数直接传给cloudflared tunnel run --token ...这时候 Token 的权限建议限定为Cloudflare Tunnel 编辑再加上客户端 IP 过滤。这里有一个安全细节Docker 容器内的环境变量会随docker inspect可见如果机器上有多人在用令牌等于半公开。建议用 Docker Secrets 或.env文件并设置权限为 600日志里也不要打印 Token 明文。我见过有人在调试时把--token直接写进docker-compose.yml并提交到公司 Git 仓库最后被安全扫描拦下来——这种事故其实完全可以在写文件的那一刻避免。4.6 代码集成时常见的 API 报错对照很多第三方工具接入 Cloudflare 时报错信息往往不是 Cloudflare 风格的。比如有朋友遇到过类似 “login failed. check api token or gitlab version. log in via git if the version...” 的提示乍一看让人摸不着头脑。这种报错通常意味着工具拿 token 去请求接口时被拒了但具体原因被工具包装了起来。碰到这类提示我的处理顺序是先用 curl 手测一遍 Cloudflare API确认 Token 本身没问题再检查工具配置里的 Token 粘贴是否完整、有没有多出空格最后看工具的文档确认它请求的是哪个接口以及那个接口需要什么权限。工具报错只能作为线索真正可靠的定位方式永远是手动 curl 复现一次把工具层面和 Cloudflare 层面分开看。5. 常见问题排查与避坑实录5.1 API 请求返回 401 和 403 的原因这两个状态码是 API Token 相关报错里出现频率最高的401 Unauthorized几乎可以断定是 Token 本身无效。常见原因包括令牌复制不全尾部少了几位、令牌已过期被自动吊销、令牌被手动删除或者你误把 Global API Key 当作 Token 填入了Authorization请求头。403 ForbiddenToken 能识别但是没有权限。比如你只给了 DNS 编辑权限却去调用修改区域设置的接口或者 Token 限定了某个具体域名但你传入了另一个域名的 Zone ID。快速判断方法用 3.4 节那条最简单的/zones请求测试。如果返回 401优先怀疑令牌本身如果返回 403优先检查权限配置和资源限定。还有一个容易忽视的地方Cloudflare 的 Token 校验有时会滞后几秒。刚创建完 Token 立刻调用偶尔会遇到 401等 5-10 秒重试通常就好了。这不是玄学是服务端缓存导致的脚本里加个重试逻辑更稳妥。5.2 出现 login failed. check api token 类报错怎么排查不少第三方工具接入 Cloudflare 时会直接复用通用 HTTP 客户端的报错信息常见如 “login failed. check api token or gitlab version. log in via git if the version...” 这类提示信息量很少。遇到这种报错我建议按顺序排查确认填入的是 API Token而不是账号密码或 Global API Key。确认请求头格式是否为你工具要求的格式。Cloudflare 官方推荐Authorization: Bearer token但有些老工具会默认用api-key格式需要到工具文档里确认。确认 Token 的权限是否包含目标操作。比如某工具要读取 DNS 记录但你的 Token 只有账户设置读取权限那自然会失败。用 curl 手测一遍把工具层面和 Cloudflare 层面分开避免被工具的报错误导。工具报错只能作为线索真正可靠的定位方式永远是手动 curl 复现一次。这也是我反复强调“先验证 Token 再进工具配置”的原因。5.3 Account ID 和 Zone ID 填写错误的典型症状这是我见过的第二大类问题。把 Account ID 填成 Zone ID或者反过来报错通常不是 401 而是 404因为路径上的资源 ID 根本不存在。如果你收到 404 但确认 Token 没问题立刻去核对是不是用错了 ID。Cloudflare 的 API 文档把这两者区分得很清楚但实际使用者很少会仔细看文档。有个小技巧Account ID 和 Zone ID 都是 32 位十六进制格式上无法通过肉眼区分。稳妥的做法是把常用域名的 Zone ID 和 Account ID 一起记录在密码管理器里或者用一个简单的映射文件别靠记忆。5.4 Token 泄露后的应急处理如果怀疑 Token 泄露别慌张按这三步走立即登录控制台进入“API 令牌”页面点击对应令牌旁边的“撤销”按钮。不用等它自己过期。检查审计日志Audit Log看看 Token 有没有被用来做过异常操作。日志在“管理账户 审计日志”里能看到请求来源 IP、操作类型和时间。创建新的 Token把新 Token 配置到你的脚本里旧 Token 确认已撤销后再删除。坦率地说Token 泄露的应急流程和密码泄露很像核心原则就一条先吊销再排查最后才考虑重建。顺序不能反不要先去翻日志让令牌多活一秒就多一分风险。5.5 新版界面下找不到入口的兜底方案最后再给一个很实用的兜底方案如果你实在找不到新版界面入口可以直接访问dash.cloudflare.com/profile/api-tokens这是个人资料 API 令牌页面的直链。另一个兜底方式是进入任何一个域名的详情页在右侧栏找到“获取您的 API 令牌”之类的链接也能跳转到令牌管理页面。这个方法我一般只告诉记不住菜单层级的朋友但实测下来确实比在界面里点来点去快。建议把这条直链存到浏览器书签里省得每次都要从头找入口。6. 这些细节能让你的 API 体验顺畅很多6.1 把令牌和脚本的生命周期绑定实际操作中我习惯给临时脚本使用短生命周期令牌。比如要在 CI 流水线里跑一次证书申请我会创建只对特定域名有 DNS 编辑权限的令牌流水线结束后立刻撤销。这个习惯让我避免了好几次“令牌躺在环境变量里三五年没人动”的隐患。新版创建界面支持设置令牌有效期最短 1 天。能设置有效期的场景一律设置有效期。长期运行的脚本虽然不太方便频繁换但至少每年轮换一次并把轮换日期记在日历上别指望自己能想起来。6.2 关注 Cloudflare 的审计日志很多人不知道 Cloudflare 有一个很完整的审计日志功能。它记录了账户下每一次 API 调用、每一次设置变更、每一次登录。只要是使用 API Token 的请求日志里都能看到对应的令牌名称。这在你排查“哪个脚本在疯狂刷 API”“某个 Token 为什么有异常请求”时非常有用。建议每周扫一眼尤其是有多个自动化任务在跑的时候。6.3 善用 curl 的调试模式排查 API 问题时我强烈推荐在 curl 后面加-v参数或者用--trace查看完整的 HTTP 报文。很多时候工具不报细节但原始响应体里藏着真正的错误码和错误说明。Cloudflare API 的错误响应格式是统一的{ success: false, errors: [ { code: 9109, message: Invalid access token } ] }看到code字段再去查官方文档的错误码表比自己瞎猜效率高得多。9109 是访问令牌无效9106 通常是权限不足熟悉这几个常用错误码能省大量排查时间。6.4 把常用请求写成脚本函数当你开始频繁使用 Cloudflare API 后建议在~/.bashrc或~/.zshrc里放几个简单的 shell 函数比如cf-zones()列出所有域名、cf-dns-list()列出某个域名的 DNS 记录。每次只改域名参数不用重复敲一长串 curl 命令。这种小工具积累到一定数量后你会发现自己操作 Cloudflare 的速度比在面板里点来点去还快。当然这只适用于你信任的、私人的开发机。在团队共享的机器上还是要规范凭证管理别把 Token 写死在函数里。写到这里关于新版 Cloudflare 界面获取 Account ID 和 API Token 的内容基本都覆盖了。我个人最深的体会是这类操作本身不复杂难点全在细节上——ID 和 Token 的区别、权限的粒度控制、报错信息的解读方式。尤其是权限配置宁可在创建时多花两分钟想清楚“这个脚本到底需要哪些权限”也不要图省事选“所有区域 全部权限”否则后续出事的概率会成倍增加。最后再分享一个小技巧把常用的 API 请求做成一组 shell 函数放在~/.bashrc里比如cf-zones()、cf-dns-list()每次只改域名参数效率会高很多。Cloudflare API 是个很稳定的东西一旦你熟悉了 “Account ID Token Zone ID 对应接口” 这个组合方式后面遇到任何自动化需求都不会再慌。希望这篇能帮你在新版界面下少走几步弯路。