Skip to content

AI-native knowledge base & Evernote/Obsidian alternative with instant sync & native MCP. Free on Cloudflare or self-hosted via Docker.

docs: explain Workers Builds API token setup

yoma48bcbd257635
diff --git a/.env.local.example b/.env.local.example
index 62b10a2d..7ff6b37a 100644
--- a/.env.local.example
+++ b/.env.local.example
@@ -10,8 +10,12 @@ CLOUDFLARE_ACCOUNT_ID=
CLOUDFLARE_API_TOKEN=
# Optional user-scoped API token for configuring Cloudflare Workers Builds.
-# It needs Workers Builds Configuration: Edit and Workers Scripts: Read. It is
-# used only by `bun run deploy:builds:setup` and is never sent to the Worker.
+# Create it at https://dash.cloudflare.com/profile/api-tokens:
+# Create Token -> Create Custom Token -> add Account permissions:
+# - Workers Builds Configuration: Edit
+# - Workers Scripts: Read
+# 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=
# Optional Workers Builds build-token UUID. Set this only when the Cloudflare
diff --git a/docs/cloudflare-workers-builds.md b/docs/cloudflare-workers-builds.md
index 37aa11e7..cc1070ea 100644
--- a/docs/cloudflare-workers-builds.md
+++ b/docs/cloudflare-workers-builds.md
@@ -21,7 +21,14 @@ 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 itself needs a user-scoped token with **Workers Builds Configuration: Edit** and **Workers Scripts: Read**. Put it in `EDGE_EVER_BUILDS_API_TOKEN` (or reuse `CLOUDFLARE_API_TOKEN` if it has those permissions). This token is never uploaded to the Worker or Cloudflare Builds.
+The setup API call itself needs a user-scoped token with **Workers Builds Configuration: Edit** and **Workers Scripts: Read**. Create it at [Cloudflare API Tokens](https://dash.cloudflare.com/profile/api-tokens):
+
+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`.
+
+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-scoped token with the same permissions.
### Manual fallback
diff --git a/docs/cloudflare-workers-builds.zh-CN.md b/docs/cloudflare-workers-builds.zh-CN.md
index 0f41c94f..b0dd5580 100644
--- a/docs/cloudflare-workers-builds.zh-CN.md
+++ b/docs/cloudflare-workers-builds.zh-CN.md
@@ -21,7 +21,15 @@ 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-scoped token,具有 **Workers Builds Configuration: Edit** 与 **Workers Scripts: Read** 权限。把它写入 `EDGE_EVER_BUILDS_API_TOKEN`;若现有 `CLOUDFLARE_API_TOKEN` 同时具备这些权限,也可直接复用。这个 token 不会上传到 Worker 或 Cloudflare Builds。
+配置 API 本身还需要一个 user-scoped token,具有 **Workers Builds Configuration: Edit** 与 **Workers Scripts: Read** 权限。按以下步骤创建:
+
+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>`。
+
+这个 token 仅供 `bun run deploy:builds:setup` 调用,不会上传到 Worker 或 Cloudflare Builds。只有在现有 `CLOUDFLARE_API_TOKEN` 同为 user-scoped 且具备上述权限时,才可直接复用。
### 手动兜底