okooooooo/edgeever
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: clarify Workers Builds token setup

Browse Source
This commit is contained in:
yoma committed 2026-07-14 15:48:34 +08:00
1 parent b6d052b430
commit eb81d12226
4 files changed
+51 -10
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

.env.local.example
+3
View File
@@ -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=
docs/assets/cloudflare-workers-builds-user-token.svg
+28
View File
@@ -0,0 +1,28 @@
<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="500" viewBox="0 0 1200 500" role="img" aria-labelledby="title desc">
<title id="title">Cloudflare User API Token permissions for EdgeEver Workers Builds</title>
<desc id="desc">A redacted Cloudflare Create Custom Token form. It selects Account Workers Builds Configuration Edit and Account Workers Scripts Read.</desc>
<rect width="1200" height="500" fill="#f7f8fa"/>
<rect x="70" y="42" width="1060" height="410" rx="10" fill="#fff" stroke="#d8dde5"/>
<text x="120" y="100" font-family="Arial, sans-serif" font-size="28" font-weight="700" fill="#1d2733">Create Custom Token</text>
<text x="120" y="145" font-family="Arial, sans-serif" font-size="16" fill="#4a5565">Token name</text>
<rect x="120" y="160" width="700" height="44" rx="5" fill="#fff" stroke="#8a96a8"/>
<text x="136" y="189" font-family="Arial, sans-serif" font-size="17" fill="#273142">edgeever automated deployment</text>
<text x="120" y="250" font-family="Arial, sans-serif" font-size="22" font-weight="700" fill="#1d2733">Permissions</text>
<text x="120" y="281" font-family="Arial, sans-serif" font-size="15" fill="#4a5565">Select only these two Account permissions.</text>
<g font-family="Arial, sans-serif" font-size="16" fill="#273142">
<rect x="120" y="305" width="170" height="46" rx="5" fill="#fff" stroke="#8a96a8"/>
<text x="137" y="334">Account</text>
<rect x="304" y="305" width="420" height="46" rx="5" fill="#fff" stroke="#8a96a8"/>
<text x="321" y="334">Workers Builds Configuration</text>
<rect x="738" y="305" width="150" height="46" rx="5" fill="#eef7f4" stroke="#159570"/>
<text x="755" y="334" fill="#087257">Edit</text>
<rect x="120" y="367" width="170" height="46" rx="5" fill="#fff" stroke="#8a96a8"/>
<text x="137" y="396">Account</text>
<rect x="304" y="367" width="420" height="46" rx="5" fill="#fff" stroke="#8a96a8"/>
<text x="321" y="396">Workers Scripts</text>
<rect x="738" y="367" width="150" height="46" rx="5" fill="#eef7f4" stroke="#159570"/>
<text x="755" y="396" fill="#087257">Read</text>
</g>
<text x="926" y="333" font-family="Arial, sans-serif" font-size="15" fill="#687386">User API Token</text>
<text x="926" y="394" font-family="Arial, sans-serif" font-size="15" fill="#687386">not Account API Token</text>
</svg>
Side by Side

After

Width:  |  Height:  |  Size: 2.3 KiB

docs/cloudflare-workers-builds.md
+10 -5
View File
@@ -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=<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.
docs/cloudflare-workers-builds.zh-CN.md
+10 -5
View File
@@ -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=<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>`，不要提交、截图或发送给他人。
这个 token 仅供 `bun run deploy:builds:setup` 调用，不会上传到 Worker 或 Cloudflare Builds。只有在现有 `CLOUDFLARE_API_TOKEN` 同为 User API Token 且具备上述权限时，才可直接复用。