diff --git a/.env.local.example b/.env.local.example index 6e495322..027749c1 100644 --- a/.env.local.example +++ b/.env.local.example @@ -13,9 +13,12 @@ CLOUDFLARE_API_TOKEN= # Do NOT use an Account API Token: the Workers Builds Configuration API accepts # user-scoped tokens only. Create it at https://dash.cloudflare.com/profile/api-tokens # (My Profile -> API Tokens, not Manage Account -> Account API Tokens): +# Do not choose a prebuilt template (including Edit Cloudflare Workers). Instead: # Create Token -> Create Custom Token -> add Account permissions: # - Workers Builds Configuration: Edit # - Workers Scripts: Read +# Verify that exact two-permission summary before creating it. Cloudflare shows the +# value once: save it here privately, never commit, screenshot, or share it. # Limit it to the Cloudflare account that hosts this instance and set an expiry. # It is used only by `bun run deploy:builds:setup` and is never sent to the Worker. EDGE_EVER_BUILDS_API_TOKEN= diff --git a/docs/assets/cloudflare-workers-builds-user-token.svg b/docs/assets/cloudflare-workers-builds-user-token.svg new file mode 100644 index 00000000..b4d1d112 --- /dev/null +++ b/docs/assets/cloudflare-workers-builds-user-token.svg @@ -0,0 +1,28 @@ + + Cloudflare User API Token permissions for EdgeEver Workers Builds + A redacted Cloudflare Create Custom Token form. It selects Account Workers Builds Configuration Edit and Account Workers Scripts Read. + + + Create Custom Token + Token name + + edgeever automated deployment + Permissions + Select only these two Account permissions. + + + Account + + Workers Builds Configuration + + Edit + + Account + + Workers Scripts + + Read + + User API Token + not Account API Token + diff --git a/docs/cloudflare-workers-builds.md b/docs/cloudflare-workers-builds.md index fe47a9d1..383557f9 100644 --- a/docs/cloudflare-workers-builds.md +++ b/docs/cloudflare-workers-builds.md @@ -21,12 +21,17 @@ Cloudflare requires two account-level authorizations that cannot be safely autom 1. Install and authorize the **Cloudflare Workers & Pages** GitHub App for the fork. An Agent can open the Cloudflare dashboard and complete this browser consent; a user only needs to approve the GitHub authorization. 2. Ensure the Worker has a Workers Builds **build token** with permission to deploy Workers and apply D1 migrations. If the setup command reports that it cannot choose a token, open **Worker** -> **Settings** -> **Builds** -> **API token**, create/select the token, then set its UUID as `EDGE_EVER_BUILDS_BUILD_TOKEN_UUID` in `.env.local` and rerun the command. -The setup API call requires a **User API Token**, not an **Account API Token**. Workers Builds Configuration API accepts user-scoped tokens only. Create it at [Cloudflare API Tokens](https://dash.cloudflare.com/profile/api-tokens) under **My Profile** -> **API Tokens** (not **Manage Account** -> **Account API Tokens**) with **Workers Builds Configuration: Edit** and **Workers Scripts: Read**: +The setup API call requires a **User API Token**, not an **Account API Token**. Workers Builds Configuration API accepts user-scoped tokens only. Create it at [Cloudflare API Tokens](https://dash.cloudflare.com/profile/api-tokens) under **My Profile** -> **API Tokens** (not **Manage Account** -> **Account API Tokens**). Do not use a prebuilt template, including `Edit Cloudflare Workers`: none includes Workers Builds Configuration. -1. Select **Create Token** -> **Create Custom Token**. -2. Under **Account**, add `Workers Builds Configuration: Edit` and `Workers Scripts: Read`. -3. Restrict the token to the Cloudflare account hosting this instance and set a suitable expiry. -4. Create it, then put the value in `.env.local` as `EDGE_EVER_BUILDS_API_TOKEN`. +![Redacted Cloudflare User API Token permissions](assets/cloudflare-workers-builds-user-token.svg) + +1. Select **Create Token**, scroll to the bottom, and select **Create Custom Token**. +2. Name it, for example `edgeever automated deployment`. +3. Add **Account** -> **Workers Builds Configuration** -> **Edit**, then select **Add more**. +4. Add **Account** -> **Workers Scripts** -> **Read**. +5. Under **Account Resources**, leave **Include / All accounts** or restrict it to the account for this instance; set a suitable expiry. +6. Select **Continue to summary** and verify that the summary contains exactly `Workers Builds Configuration: Edit, Workers Scripts: Read`, then select **Create Token**. +7. Cloudflare shows the token value once. Save it locally as `EDGE_EVER_BUILDS_API_TOKEN=` in `.env.local`; never commit, screenshot, or share it. This token is used only by `bun run deploy:builds:setup` and is never uploaded to the Worker or Cloudflare Builds. You may instead reuse `CLOUDFLARE_API_TOKEN` only if it is a User API Token with the same permissions. diff --git a/docs/cloudflare-workers-builds.zh-CN.md b/docs/cloudflare-workers-builds.zh-CN.md index a2fc8245..4471566c 100644 --- a/docs/cloudflare-workers-builds.zh-CN.md +++ b/docs/cloudflare-workers-builds.zh-CN.md @@ -21,13 +21,18 @@ Cloudflare 有两项账号级授权，仓库脚本不能、也不应该绕过： 1. 为 Fork 安装并授权 **Cloudflare Workers & Pages** GitHub App。Agent 可以打开 Cloudflare 页面完成操作，用户只需确认 GitHub 授权。 2. 确保 Worker 已有可部署 Worker 且可执行 D1 migration 的 Workers Builds **build token**。若命令提示无法选择 token，请打开 **Worker** -> **Settings** -> **Builds** -> **API token**，创建/选择该 token，将其 UUID 填入 `.env.local` 的 `EDGE_EVER_BUILDS_BUILD_TOKEN_UUID`，然后重试命令。 -配置 API 本身必须使用 **User API Token**，不能使用 **Account API Token**：Workers Builds Configuration API 仅接受 user-scoped token。请在 [Cloudflare API Tokens](https://dash.cloudflare.com/profile/api-tokens) 的 **My Profile** -> **API Tokens** 中创建，切勿进入 **Manage Account** -> **Account API Tokens**。它需要 **Workers Builds Configuration: Edit** 与 **Workers Scripts: Read** 权限。按以下步骤创建： +配置 API 本身必须使用 **User API Token**，不能使用 **Account API Token**：Workers Builds Configuration API 仅接受 user-scoped token。请在 [Cloudflare API Tokens](https://dash.cloudflare.com/profile/api-tokens) 的 **My Profile** -> **API Tokens** 中创建，切勿进入 **Manage Account** -> **Account API Tokens**。它需要 **Workers Builds Configuration: Edit** 与 **Workers Scripts: Read** 权限。不要选择页面上的任何现成模板（包括 `Edit Cloudflare Workers`），它们不包含 Workers Builds Configuration 权限。按以下实际界面步骤创建： + +![Cloudflare User API Token 权限（脱敏界面图）](assets/cloudflare-workers-builds-user-token.svg) 1. 打开 [Cloudflare API Tokens](https://dash.cloudflare.com/profile/api-tokens)。 -2. 点击 **Create Token** -> **Create Custom Token**。 -3. 在 **Account** 权限中添加 `Workers Builds Configuration: Edit` 与 `Workers Scripts: Read`。 -4. 将 token 限制为当前实例所属的 Cloudflare account，并设置合适的过期时间。 -5. 创建后把值写入 `.env.local`：`EDGE_EVER_BUILDS_API_TOKEN=`。 +2. 点击 **Create Token**，滚到最下方并选择 **Create Custom Token**。 +3. 给 token 命名，例如 `edgeever自动化部署`。 +4. 第一行权限选择 **Account** -> **Workers Builds Configuration** -> **Edit**；点击 **Add more**。 +5. 第二行选择 **Account** -> **Workers Scripts** -> **Read**。 +6. 在 **Account Resources** 保持 **Include / All accounts**，或限缩到当前实例所属账号；TTL 按自己的安全策略设置。 +7. 点击 **Continue to summary**，确认摘要恰好是 `Workers Builds Configuration: Edit, Workers Scripts: Read`，再点击 **Create Token**。 +8. Cloudflare 只会显示一次 token 值：立即保存到本机 `.env.local`，写为 `EDGE_EVER_BUILDS_API_TOKEN=`，不要提交、截图或发送给他人。 这个 token 仅供 `bun run deploy:builds:setup` 调用，不会上传到 Worker 或 Cloudflare Builds。只有在现有 `CLOUDFLARE_API_TOKEN` 同为 User API Token 且具备上述权限时，才可直接复用。