Cloudflare API Token 使用教程：最小权限、工具对接与轮换

Cloudflare 自动化不应继续使用拥有全部账户权限的 Global API Key。长期 CI/CD 优先使用属于账户的 Account API Token；需要代表当前用户执行临时脚本，或者目标产品暂不支持账户级 Token 时，使用 User API Token。权限只开放实际操作涉及的 Account、Zone 和产品资源，并将凭证存入受控 Secret 系统。

本文依据 2026-09-17 可访问的 Cloudflare 官方文档编写。文章没有登录真实账户、创建 Token、调用账户 API、运行 Wrangler 或执行远程部署；Dashboard 字段、权限组合和命令结果需要在目标账户中验收，验证等级为 documented。

三类 API 凭证

凭证	身份归属	权限模型	推荐用途
Global API Key	用户	继承用户的广泛账户权限	遗留兼容；新自动化不使用
User API Token	用户	当前用户权限的受限子集	本地脚本、临时操作、需要用户主体的产品
Account API Token	账户	独立配置的账户级服务身份	CI/CD、长期集成、共享自动化

Cloudflare 的 Token 格式文档给出了不同凭证的可识别格式，但旧格式凭证仍可能存在。泄漏扫描、资产盘点和轮换不能只搜索新前缀，还应检查历史 Secret、CI 配置、密码管理器与本地环境文件。

Account API Token 不属于某位员工，适合避免人员离职或成员权限变化导致自动化中断。创建和管理账户级 Token 需要相应的账户管理权限；Cloudflare 当前文档要求 Super Administrator 角色。无法获得该角色时，不应借用他人的高权限凭证，应由账户管理员建立用途明确的 Token。

权限与资源范围

Cloudflare 权限按资源类别组织：

范围	常见对象	示例权限
User	当前用户自身	User Details、Memberships、API Tokens
Account	账户级产品	Workers Scripts、Cloudflare Pages、KV、D1、R2
Zone	已接入的域名	DNS、Workers Routes、缓存与安全配置

选择权限时同时回答两个问题：

1. 自动化需要做什么操作，是读取、部署、修改还是删除？
2. 操作只针对哪个账户、Zone、项目或资源？

只部署一个不使用绑定资源的 Worker，通常从 Account · Workers Scripts · Edit 开始。使用自定义域路由时再增加 Zone 的 Workers Routes 权限；使用 KV、D1 或 R2 时，只增加实际绑定资源所需权限。Pages 项目使用 Cloudflare Pages 对应权限，不应因为同属开发者平台就用 Workers Scripts 代替。

模板与自定义权限

Dashboard 提供 Edit Cloudflare Workers 等 Token 模板。模板适合建立可工作的起点，但可能同时包含 Workers Scripts、Routes、KV、R2、日志或账户读取能力。项目没有使用某项能力时，应在创建前移除对应权限。

推荐决策顺序：

1. 写出自动化需要调用的命令或 API。
2. 从官方端点文档确认所需权限。
3. 选择 Custom Token，逐条加入权限。
4. 把 Account Resources 和 Zone Resources 限制到目标范围。
5. 只有无法确定权限组合时才从官方模板开始，再逐条收窄。

权限名称可能在 Dashboard 和 API 文档中分别显示为 Edit 或 Write。配置时以当前界面与端点文档为准，不根据旧截图猜测名称。

选择 User 或 Account Token

场景	建议凭证	原因
GitHub Actions、GitLab CI、Jenkins	优先 Account API Token	不绑定个人账户；先核对所有目标端点都支持账户级 Token
Terraform、Pulumi 等基础设施自动化	按目标资源的兼容矩阵选择	全部端点兼容时使用 Account Token；否则拆分凭证范围
Worker 运行时调用 Cloudflare API	独立、最小权限的兼容 Token	与部署凭证分离，并按实际端点选择 User 或 Account Token
本地临时脚本	User API Token 或 Wrangler OAuth	操作主体明确，任务完成后可删除
Dashboard 内置 Workers Builds	按当前官方限制使用 User API Token	官方配置文档当前说明该路径只支持 User Token

Workers Builds 指 Dashboard 内置 Git 集成，不等于外部 GitHub Actions。外部 CI 使用 Wrangler 部署时，可以采用 Account API Token，并显式提供 Account ID。

Account Token 仍有产品兼容边界。创建长期自动化凭证前，逐个核对实际调用端点是否支持 Account Token；不要因为某个 Worker 部署命令兼容，就推断同一流程中的所有 Cloudflare 产品都兼容。存在不兼容端点时，优先拆分任务和凭证，只为对应端点使用受限 User Token。

创建 Account API Token

进入 Cloudflare Dashboard 的账户级 API Token 管理入口，确认当前账户和操作者角色，然后执行：

1. 选择创建 Account API Token。
2. 使用 Custom Token，或选择官方模板后收窄权限。
3. 将 Account Resources 限制为目标账户。
4. 只有需要域名路由、DNS 或其他 Zone 能力时才加入 Zone 权限。
5. 评估 Token 的有效期和客户端 IP 过滤；外部托管 Runner 没有固定出口时，不应配置无法满足的固定 IP 条件。
6. 在摘要页核对权限和资源范围，再创建 Token。
7. 将只显示一次的 Token 立即写入受控 Secret 系统。

不要把 Token 放进命令历史、聊天、Issue、日志、截图、Markdown、wrangler.toml 或普通环境变量文件。需要向 CI 添加 Secret 时，在目标平台的 Secret 设置界面输入值，不通过仓库文件中转。

创建 User API Token

User API Token 从个人 Profile 的 API Tokens 入口创建。步骤与账户级 Token 相似，但可选权限来自当前用户能够访问的资源，Token 生命周期也会受到用户成员关系和账户状态影响。

适合 User Token 的场景包括：

• 本地一次性维护脚本。
• 需要读取当前用户详情或成员关系的诊断。
• Cloudflare 官方明确尚未支持 Account Token 的产品路径。

团队长期部署不应依赖某位成员的 User Token。确实只能使用 User Token 时，应记录所有者、用途、失效条件、轮换责任人与替代路径。

配置 Wrangler

CI 中常用两个 Secret：

CLOUDFLARE_API_TOKEN
CLOUDFLARE_ACCOUNT_ID

Account ID 不是登录密码，但应与 Token 的资源范围保持一致。多账户环境中，Token 限定账户与 CLOUDFLARE_ACCOUNT_ID 不一致时，可能出现凭证有效但资源访问被拒绝。

本地可以通过无回显输入把凭证交给 Wrangler，避免真实 Token 出现在 shell 历史中：

export CLOUDFLARE_ACCOUNT_ID='<cloudflare-account-id>'
printf 'Cloudflare API Token: ' >&2
IFS= read -rs CLOUDFLARE_API_TOKEN
printf '\n' >&2
export CLOUDFLARE_API_TOKEN
npx wrangler whoami
unset CLOUDFLARE_API_TOKEN
unset CLOUDFLARE_ACCOUNT_ID

whoami 用于确认 Wrangler 当前采用的身份和账户，不应把完整输出直接贴进公开 Issue。使用 Account Token 时还可以在 Wrangler 配置中声明 account_id，避免工具需要通过用户成员关系推断目标账户。

wrangler deploy --dry-run 只能检查本地构建和配置，不会证明远程 Token 有效或权限足够。权限验证必须执行一个受控的真实 API 请求或部署，并核对目标资源与审计记录。

配置外部 CI

Cloudflare 的 Workers GitHub Actions 文档使用 API Token 和 Account ID 作为 Secret。工作流应把 Secret 作为 Action 输入或进程环境提供，不打印值：

name: Deploy Worker

on:
  push:
    branches: [main]

permissions:
  contents: read

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: production
    steps:
      - uses: actions/checkout@v7

      - name: Deploy Worker
        uses: cloudflare/wrangler-action@v4
        with:
          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}

使用前核对 Cloudflare 官方 CI 文档与 Action 当前版本。生产部署还应在 GitHub Environment 中限制分支、配置审批和并发，不让 Fork Pull Request 获得部署 Secret。

Pages Direct Upload 或 REST API 使用 Cloudflare Pages 权限；Workers 部署使用 Workers Scripts 权限。同一个工作流同时管理两类资源时，可以拆成两个 Token，避免任一环节泄漏后同时获得两类写权限。

验证 Token

Cloudflare 为 User Token 与 Account Token 提供不同的验证端点。先确认 Token 的所有者类型，再从环境变量读取凭证。

验证 User API Token：

curl --request GET \
  "https://api.cloudflare.com/client/v4/user/tokens/verify" \
  --header "Authorization: Bearer ${CLOUDFLARE_API_TOKEN}"

验证 Account API Token：

curl --request GET \
  "https://api.cloudflare.com/client/v4/accounts/${CLOUDFLARE_ACCOUNT_ID}/tokens/verify" \
  --header "Authorization: Bearer ${CLOUDFLARE_API_TOKEN}"

成功响应中的 status 应为 active。该结果只证明 Token 当前有效，不证明权限能够完成目标操作。完整验收包括：

1. 验证端点返回成功，且状态为 active。
2. 使用目标命令读取或修改指定资源。
3. 确认没有访问未授权账户、Zone 或项目。
4. 检查部署、资源状态和审计记录。
5. 从另一个无权限路径验证越权操作被拒绝。

不要为了通过一次失败调用逐步扩大到全部账户和全部权限。应从错误中的端点、资源和权限范围定位缺口。

轮换与撤销

把每个 Token 记录为一项受管凭证：用途、所有者、创建时间、允许资源、存放位置、轮换周期和下次检查时间都应可追踪。

常规轮换采用并行切换：

1. 创建权限相同或更小的新 Token。
2. 更新 CI、Worker Secret 和受控本地环境。
3. 使用新 Token 完成一次目标操作和业务验收。
4. 撤销旧 Token。
5. 再次运行任务，确认没有遗漏引用。

发现泄漏时不等待常规窗口：立即撤销凭证，检查审计日志和相关资源，创建替代 Token，更新引用并验证。删除 Git 历史中的明文不能让已经泄漏的 Token 自动恢复安全。

配额与失败处理

Cloudflare 对 Token 数量和 API 请求速率设有限制，具体数值可能调整。批量自动化应识别 HTTP 429、读取重试信息并采用受限退避，不使用无限快速重试。

现象	核对顺序
Token verify 失败	Secret 是否完整、是否已撤销或过期、环境变量是否被旧值覆盖
认证成功但资源 403	Account ID、Token 资源范围、产品权限和 Zone 范围
Wrangler 找不到账户	显式提供 Account ID，确认没有依赖 User Memberships 推断
本地成功、CI 失败	CI Secret 层级、Environment 遮蔽、Runner 网络和工作目录
Workers 成功、Pages 失败	是否只配置了 Workers Scripts，缺少 Cloudflare Pages 权限
Dashboard 构建失败	确认使用的是 Workers Builds，并核对当前支持的 Token 类型
请求返回 429	停止密集重试，读取限流响应并降低并发

上线检查

• [ ] 已选择 User 或 Account Token，而不是 Global API Key。
• [ ] Token 用途、所有者和失效条件有记录。
• [ ] 权限只覆盖需要的产品和操作。
• [ ] Account 与 Zone 资源范围已收窄。
• [ ] Token 只存放在受控 Secret 系统。
• [ ] CI 同时使用正确的 Account ID。
• [ ] 本地 dry-run 与真实权限验证被明确区分。
• [ ] Fork PR 无法读取部署 Secret。
• [ ] 已完成一次目标操作和业务验收。
• [ ] 已验证无权限操作会被拒绝。
• [ ] 已定义轮换、泄漏响应和撤销流程。

参考资料

• Create API token
• Account API tokens
• API token permissions
• API token templates
• API limits
• Token formats
• Verify Account API token
• Verify User API token
• Workers CI/CD with GitHub Actions
• Workers Builds configuration
• Pages API