KaisouMail 文档
首页
快速开始
部署
Cloudflare Token
Storybook
GitHub
首页
快速开始
部署
Cloudflare Token
Storybook
GitHub
简体中文

Cloudflare Token 权限

推荐配置（正式环境）

用途 存放位置 密钥名 值
运行时域名管理 Cloudflare kaisoumail-api Worker secret CLOUDFLARE_RUNTIME_API_TOKEN runtime token
部署流水线 GitHub repository secret CLOUDFLARE_DEPLOY_API_TOKEN deploy token

项目已经支持拆分 token，不需要改代码。 另外，直接在 /domains 里绑定新域名还需要 GitHub repository secret CLOUDFLARE_ACCOUNT_ID。deploy workflow 会把它注入 API Worker 运行时变量；这不是 token 权限，但如果缺失，/api/meta 会返回 cloudflareDomainBindingEnabled=false。

Runtime token 示意配置

支持👤
← 返回以查看所有令牌
创建自定义令牌
正式环境 / runtime token
给 kaisoumail-api Worker 用，只负责域名目录和 Email Routing 管理。
令牌名称
为您的 API 令牌指定描述性名称。
cfm-runtime
权限
按 KaisouMail 对应场景把权限配全即可。
资源
权限
权限级别
区域▾
Zone▾
编辑▾
区域▾
Email Routing Rules▾
编辑▾
区域▾
Zone Settings▾
编辑▾
帐户资源
按这个示意选择范围即可。
包括▾
目标 Cloudflare 帐户▾
区域资源
推荐覆盖当前项目会管理到的所有目标区域。
包括▾
该帐户内所有 zones（含待新建 zone）▾
把这把 token 填到 Cloudflare Worker secret：CLOUDFLARE_RUNTIME_API_TOKEN。

Deploy token 示意配置

支持👤
← 返回以查看所有令牌
创建自定义令牌
正式环境 / deploy token
给 GitHub Actions 用，只负责部署、Pages 和远程 D1 migration。
令牌名称
为您的 API 令牌指定描述性名称。
cfm-deploy
权限
按 KaisouMail 对应场景把权限配全即可。
资源
权限
权限级别
帐户▾
D1▾
编辑▾
帐户▾
Workers 脚本▾
编辑▾
帐户▾
Workers R2 存储▾
编辑▾
帐户▾
Cloudflare Pages▾
编辑▾
区域▾
Workers Routes▾
编辑▾
帐户资源
按这个示意选择范围即可。
包括▾
目标 Cloudflare 帐户▾
区域资源
推荐覆盖当前项目会管理到的所有目标区域。
包括▾
用于 Worker Routes 的区域▾
把这把 token 填到 GitHub repository secret：CLOUDFLARE_DEPLOY_API_TOKEN。

快速上手（单人试用）

如果你只是单人试用、自建环境、临时验证或低风险内部演示，可以只配一把共享 token：

  • Cloudflare kaisoumail-api Worker secret：CLOUDFLARE_API_TOKEN
  • GitHub repository secret：CLOUDFLARE_API_TOKEN

这把共享 token 需要同时覆盖运行时和部署两侧权限。

支持👤
← 返回以查看所有令牌
创建自定义令牌
快速上手 / shared token
单人试用时可共用；同一把 token 同时给 Worker 和 GitHub Actions。
令牌名称
为您的 API 令牌指定描述性名称。
cfm
权限
按 KaisouMail 对应场景把权限配全即可。
资源
权限
权限级别
区域▾
Zone▾
编辑▾
区域▾
Email Routing Rules▾
编辑▾
区域▾
Zone Settings▾
编辑▾
帐户▾
D1▾
编辑▾
帐户▾
Workers 脚本▾
编辑▾
帐户▾
Workers R2 存储▾
编辑▾
帐户▾
Cloudflare Pages▾
编辑▾
区域▾
Workers Routes▾
编辑▾
帐户资源
按这个示意选择范围即可。
包括▾
目标 Cloudflare 帐户▾
区域资源
推荐覆盖当前项目会管理到的所有目标区域。
包括▾
该帐户内所有 zones（含待新建 zone）▾
把同一个 token 同时填到 Worker secret 和 GitHub repository secret：CLOUDFLARE_API_TOKEN。

读取顺序

面向 优先读取 回退读取
API Worker 运行时 CLOUDFLARE_RUNTIME_API_TOKEN CLOUDFLARE_API_TOKEN
部署流水线 CLOUDFLARE_DEPLOY_API_TOKEN CLOUDFLARE_API_TOKEN

如果显式拆分 token 和共享 token 同时存在，项目优先使用显式拆分的那一组。

Runtime token 最小权限

运行时代码会调用：

  • GET /zones
  • POST /zones
  • GET /zones/:zone_id
  • DELETE /zones/:zone_id
  • POST /zones/:zone_id/email/routing/enable
  • POST /zones/:zone_id/email/routing/dns
  • POST /zones/:zone_id/email/routing/rules
  • DELETE /zones/:zone_id/email/routing/rules/:rule_id
  • GET /zones/:zone_id/email/routing/rules/catch_all
  • PUT /zones/:zone_id/email/routing/rules/catch_all

所以 runtime token 只需要：

权限 用途
Zone: Zone: Edit 列出、校验、创建、删除项目直绑 zone
Zone: Email Routing Rules: Edit 创建/删除邮箱 routing rule
Zone: Zone Settings: Edit 启用 Email Routing

Scope 要覆盖所有要接入 KaisouMail 的 zones。 在 Cloudflare 的自定义 token 界面里，Zone: Zone: Edit 已经覆盖 /zones 这条链路需要的读/list 能力，不需要再额外添加一条 Zone: Zone: Read。

Catch All 补充说明

  • 引入 Catch All 后，项目不需要新增 secret 名；仍然使用现有的 CLOUDFLARE_RUNTIME_API_TOKEN，共享模式下仍可回退到 CLOUDFLARE_API_TOKEN。
  • Cloudflare 官方 API 文档说明：
    • GET /zones/:zone_id/email/routing/rules/catch_all 接受 Email Routing Rules Read 或 Email Routing Rules Write
    • PUT /zones/:zone_id/email/routing/rules/catch_all 需要 Email Routing Rules Write
  • KaisouMail 运行时本来就要求 Zone: Email Routing Rules: Edit， 所以 Catch All 开关不会增加 runtime token 的最小权限集合。

Deploy token 最小权限

部署流程会做：

  • wrangler deploy
  • wrangler pages deploy
  • remote D1 migration

所以 deploy token 需要：

权限 用途
Account: D1: Edit 远程 D1 migration
Account: Workers Scripts: Edit 发布 Worker
Account: Workers R2 Storage: Edit 校验并绑定 R2 bucket
Account: Cloudflare Pages: Edit 发布 Pages
Zone: Workers Routes: Edit 绑定 Worker 自定义域路由

共享 token 并集权限

如果你选择快速上手的共享 token，它必须同时具备：

  • Zone: Zone: Edit
  • Zone: Email Routing Rules: Edit
  • Zone: Zone Settings: Edit
  • Account: D1: Edit
  • Account: Workers Scripts: Edit
  • Account: Workers R2 Storage: Edit
  • Account: Cloudflare Pages: Edit
  • Zone: Workers Routes: Edit

常见报错

Authentication error

优先检查这两项：

  1. token 是否具备 Zone: Zone Settings: Edit
  2. token 的 scope 是否覆盖目标 zone

域名目录能看到 zone，但不能启用

这通常表示 token 只有读取能力，没有对应 zone 的写权限。能列出 zone，不代表能启用 Email Routing。

相关阅读

官方文档

ON THIS PAGE