📚 离职知识库

Cloudflare API 令牌治理

建「通用部署令牌」时整理。以后建 token、排查 Authentication error 直接照这份文档。 本文合并两份来源：通用部署令牌的配置说明 + API 令牌权限对照表。

#一、通用部署令牌的定位

一把有效期很长（如设到 2030-01-01）的「通用部署令牌」，用途：所有 Cloudflare 项目的 GitHub Actions 自动部署共用这一把，不再一个项目一把。

  • 令牌值：<KEY>（cfut_ 前缀，创建后只显示一次，绝不写进代码、绝不提交进仓库）
  • 账户资源：账户（ID <ID>）
  • 区域资源：所有区域 —— 以后新买的域名自动覆盖，不用回来改
  • 客户端 IP 筛选：无（GitHub Actions 出口 IP 不固定，填了必挂）

#二、先理解令牌的两个维度

Cloudflare 的 API 令牌是个二维的东西，两者交叉生效，缺一边都会失败：

维度 位置 回答什么问题
权限 表单中间那一大块 这把钥匙能做什么动作
资源 下面「帐户资源 / 区域资源」 这把钥匙能开哪些门

踩过的坑：动作有、门不对，照样报 Authentication error [code: 10000]。详见文末「典型故障」。

#三、三个层级

权限每一行最左边的下拉框，是在选层级：

层级 指什么 典型对象
帐户（Account） 整个 CF 账号底下的东西，跟具体哪个域名无关 Workers 代码、D1、KV、R2、Pages
区域（Zone） CF 管一个域名叫一个「区域」 每个域名是一个区域
用户（User） 你这个人本身的账号信息 邮箱、账号详情、API 令牌本身

编辑 vs 读取：编辑 = 能读能改；读取 = 只能看。按最小权限原则，只查不改的给读取就行。

#四、通用部署令牌的 8 行权限逐行解释

覆盖 Workers 全家桶的日常部署需求。

# 层级 权限 级别 干什么用 不给会怎样
1 帐户 Workers 脚本 编辑 上传和更新 Worker 代码本身，包括打包好的前端静态资源（assets） wrangler deploy 第一步就挂，什么都传不上去
2 帐户 D1 编辑 操作 D1 数据库：建表、改数据、把库绑定给 Worker 用 D1 的项目部署时绑不上库
3 帐户 Workers KV 存储 编辑 KV 键值存储，存配置、缓存、简单状态 用 KV 的项目部署失败
4 帐户 Workers R2 存储 编辑 R2 对象存储，存图片、文件、备份 用 R2 的项目部署失败
5 区域 Workers 路由 编辑 ⭐ 写「某个域名的请求交给哪个 Worker 处理」这条绑定，即 wrangler.jsonc 里的 routes / custom_domain 代码传上去了，但域名不指向它
6 区域 DNS 编辑 加改域名解析记录，绑自定义域时用 新子域得手动去后台点
7 区域 区域 读取 让 wrangler 能列出你名下有哪些域名、查到每个域的 zone id 工具找不到域名，很多操作报错
8 用户 用户详细信息 读取 读你账号的邮箱 日志里出现 Unable to retrieve email for this user... missing the User->User Details->Read permission? 警告。不影响功能，纯粹为了日志干净

为什么前 4 行是「帐户」、中间 3 行是「区域」：Worker 代码、数据库、存储桶都挂在账号底下，跟哪个域名无关；而路由和 DNS 天然属于某一个具体域名，所以归「区域」。

#五、资源怎么选才「通用」

项 选法 说明
帐户资源 包括 → 你的账户 只有一个账户，选它
区域资源 包括 → 所有区域（或「某账户的所有区域」） ⭐ 关键。选「特定区域」的话，每买一个新域名就得回来改一次 token；选「所有区域」以后自动覆盖
客户端 IP 筛选 留空 GitHub Actions 的出口 IP 不固定，填了必挂
TTL 留空或拉到很远 CF 默认会给一个几个月后的过期日，到期后所有自动部署一起静默失效，报错跟权限不足一模一样，极难排查

#六、为什么 GitHub Actions 必须要这个东西

本机敲 wrangler deploy 时，wrangler 用的是 wrangler login 浏览器授权留下的凭据——那是你本人的身份。

但 Actions 跑在 GitHub 的一台临时机器上，它不是你，没有浏览器，没法弹窗授权。所以必须提前给它一把钥匙：API 令牌，存在仓库 Secret 里（CLOUDFLARE_API_TOKEN + CLOUDFLARE_ACCOUNT_ID），Actions 拿着它去调 Cloudflare API。

给某个仓库配上（在仓库目录下执行，回车后粘贴令牌值）：

gh secret set CLOUDFLARE_API_TOKEN     # 回车后粘贴令牌值，再回车
gh secret set CLOUDFLARE_ACCOUNT_ID    # 值为账户 ID
gh secret list                          # 确认

#七、典型故障：Actions 红了但 Worker 其实已经更新

真实案例。日志长这样：

Uploaded <项目名> (4.60 sec)          ← 代码其实传成功了
✘ [ERROR] A request to the Cloudflare API (/zones/<zone_id>/workers/routes) failed.
  Authentication error [code: 10000]

根因：仓库 Secret 里放的是当初给别的项目建的 token，它的「区域资源」只包含那个项目的域名，不含本项目要绑的域名。

为什么这么迷惑：前面上传代码几步都是帐户级权限，token 有，所以全过；一碰到区域级的挂路由，钥匙上没有这扇门，才失败。于是 Worker 明明更新了，job 却是红的。

排查口诀：

  1. 看报错 URL 里的 /zones/<id>/ —— 说明失败在区域级，去查 token 的区域资源和区域权限

  2. 看 /accounts/<id>/ —— 失败在帐户级，查帐户权限

  3. 想知道那个 zone id 是哪个域名：

    curl -s -H "Authorization: Bearer $TOKEN" \
  https://api.cloudflare.com/client/v4/zones/<zone_id> | jq -r .result.name

验证令牌本身是否有效：

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

#八、几个常见附加权限（按需加）

层级 权限 什么时候需要
帐户 Cloudflare Pages 用 Pages（不是 Workers）托管静态站时
帐户 Workers 可观测性 要用 API 拉 Worker 日志 / 指标
帐户 Queues 用 Cloudflare Queues
帐户 Workers AI 调 Workers AI 模型
区域 缓存清除 部署后要自动清 CDN 缓存
区域 页面规则 / 转换规则 用规则做重定向、改请求头

#九、安全提醒

  • 这个 token 权限大、覆盖全账号，只放 GitHub Secret 和本地配置文件，绝不写进代码、绝不提交进仓库
  • 令牌值创建后只显示一次，妥善离线保存
  • 工作项目和个人项目的凭据建议分开，泄露时爆炸半径小一些
  • 怀疑泄露：CF 后台 → 用户 API 令牌 → 该 token 的 ··· → 轮换（Roll），会换新值，记得同步更新所有仓库的 Secret

来源：配置信息/cloudflare-通用部署令牌.md；沉淀/Cloudflare API 令牌权限对照表.md（整理于 2026-08-18）

相关笔记