or
+ ### Manual Deployment -Please refer to the [Cloudflare Manual Deployment Guide](docs/manual-deploy.md) for step-by-step instructions on manual installation and updating. +Please refer to the [Cloudflare Manual Deployment Guide](docs/manual-deploy.md) for first-time manual installation, Cloudflare resource setup, and emergency recovery. After the first deployment, connect Workers Builds; future updates arrive through GitHub **Sync fork** or pushes to `main`. -The automated helper commands are recommended. If you create the Cloudflare resources manually, finish configuring `.env.local`—including the D1 ID, R2 bucket, password hash, and the 400-day session limit—before running `bun run deploy`. +The automated helper commands are recommended. If you create the Cloudflare resources manually, finish configuring `.env.local`—including the D1 ID, R2 bucket, password hash, and the 400-day session limit—before running `bun run deploy`. Use that command only for first installation and emergency recovery; Workers Builds handles routine updates. ## Features diff --git a/README.zh-CN.md b/README.zh-CN.md index 07d63834..12e32779 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -27,26 +27,29 @@ EdgeEver 想填补这个空白：保留熟悉的笔记体验，同时提供开 ### 通过AI Agent 一句话部署 -将下方提示词复制给你的 AI 助手（Claude Code、Codex、Antigravity、Cursor、Trae 等），它会自动完成安装 +将下方提示词复制给你的 AI 助手（Claude Code、Codex、Antigravity、Cursor、Trae 等），它会完成首次安装并配置后续自动更新。 **建议：** 开始部署前，请先为 AI Agent 配置 GitHub 和 Cloudflare 的 MCP、插件或其他可用集成，以便 Agent 完成仓库 Fork、Cloudflare 资源创建、应用部署和 Workers Builds 自动部署连接。 ```text 请按以下流程操作： 1. Fork EdgeEver 上游仓库：https://github.com/tianma-if/edgeever -2. 使用 Fork 后的仓库，将 EdgeEver 安装并部署到 Cloudflare。 -3. 通过 Cloudflare Workers Builds 将已部署的 Worker 连接到 Fork 仓库的 `main` 分支，使 GitHub Sync fork 后能自动构建、迁移数据库并发布新版。 +2. 使用 Fork 后的仓库创建 Cloudflare 资源并完成 EdgeEver 首次部署。 +3. 运行 `bun run deploy:builds:setup`，通过 Cloudflare Workers Builds 将已部署的 Worker 连接到 Fork 仓库的 `main` 分支；如需 token，使用 User API Token，不要使用 Account API Token。 +4. 后续 GitHub Sync fork 或任何推送到 `main` 的更新，都必须自动构建、执行 D1 migration 并发布该实例。 ``` Agent 应优先按 [AI Agent Cloudflare Deployment](docs/agent-deploy-cloudflare.md) 执行。首次部署后，请参阅 [Cloudflare Workers Builds 自动部署](docs/cloudflare-workers-builds.zh-CN.md)；官方实例和 Fork 使用同一套发布流程。 > 常见踩坑：Cloudflare 的 R2、D1 和 Worker 即使使用免费额度，在开通或使用过程中也可能要求绑定一张 Visa 卡。国内用户可以考虑办理招商银行多币种卡，拿到 Visa 卡后绑定到 Cloudflare 账号即可。 +或
+ ### 手动部署 -关于手动安装和更新的详细步骤，请参考 [Cloudflare 手动部署指南](docs/manual-deploy.zh-CN.md)。 +关于首次手动安装、Cloudflare 资源配置与紧急修复，请参考 [Cloudflare 手动部署指南](docs/manual-deploy.zh-CN.md)。首次部署后，请配置 Cloudflare Workers Builds；之后通过 GitHub **Sync fork** 或推送 `main` 自动更新。 -推荐优先使用自动化辅助命令。如果选择完全手动创建 Cloudflare 资源，必须先在 `.env.local` 中完成 D1 ID、R2 bucket、密码 hash 和 400 天会话期限等配置，再执行 `bun run deploy`。 +推荐优先使用自动化辅助命令。如果选择完全手动创建 Cloudflare 资源，必须先在 `.env.local` 中完成 D1 ID、R2 bucket、密码 hash 和 400 天会话期限等配置，再执行 `bun run deploy`。该命令仅用于首次安装和紧急修复；日常更新由 Workers Builds 自动完成。 ## 功能 diff --git a/apps/site/src/components/agent-install-tabs.astro b/apps/site/src/components/agent-install-tabs.astro index ca1c737b..f54cf104 100644 --- a/apps/site/src/components/agent-install-tabs.astro +++ b/apps/site/src/components/agent-install-tabs.astro @@ -9,7 +9,7 @@ const copy = isEnglish manual: "Manual install", agent: "Install with AI Agent", agentIntro: - "Copy the prompt below to your AI assistant (Claude Code, Codex, Cursor, Trae, and similar tools). It can complete the installation for you.", + "Copy the prompt below to your AI assistant (Claude Code, Codex, Cursor, Trae, and similar tools). It will complete the first installation and set up automatic updates.", promptLabel: "Prompt", copyPrompt: "Copy prompt", copying: "Copying...", @@ -20,12 +20,12 @@ const copy = isEnglish manualGuide: "Open the complete manual deployment guide", manualGuideHref: "/en/manual-deploy", promptText: - "Please follow these steps:\n1. Fork the EdgeEver upstream repository: https://github.com/tianma-if/edgeever\n2. Use the forked repository to install and deploy EdgeEver to Cloudflare.\n3. Configure a mechanism for the fork to sync updates from the upstream repository, so it can receive the latest product features periodically or on demand.", + "Please follow these steps:\n1. Fork the EdgeEver upstream repository: https://github.com/tianma-if/edgeever\n2. Use the forked repository to create the Cloudflare resources and complete EdgeEver's first deployment.\n3. Run `bun run deploy:builds:setup` to connect the deployed Worker to the fork's `main` branch through Cloudflare Workers Builds. Use a User API Token, not an Account API Token, when the setup requires one.\n4. After that, GitHub Sync fork or any push to `main` must automatically build, apply D1 migrations, and deploy the instance.", } : { manual: "手动部署", agent: "通过 AI Agent 部署", - agentIntro: "将下方提示词复制给你的 AI 助手（Claude Code、Codex、Cursor、Trae 等），它会自动完成部署。", + agentIntro: "将下方提示词复制给你的 AI 助手（Claude Code、Codex、Cursor、Trae 等），它会完成首次部署并配置后续自动更新。", promptLabel: "提示词", copyPrompt: "复制提示词", copying: "复制中...", @@ -36,7 +36,7 @@ const copy = isEnglish manualGuide: "查看完整手动部署指南", manualGuideHref: "/manual-deploy", promptText: - "请按以下流程操作：\n1. Fork EdgeEver 上游仓库：https://github.com/tianma-if/edgeever\n2. 使用 Fork 后的仓库，将 EdgeEver 安装并部署到 Cloudflare。\n3. 为 Fork 仓库配置从上游仓库同步更新的机制，使其能够定期或按需获取上游仓库的最新代码与产品特性。", + "请按以下流程操作：\n1. Fork EdgeEver 上游仓库：https://github.com/tianma-if/edgeever\n2. 使用 Fork 后的仓库创建 Cloudflare 资源并完成 EdgeEver 首次部署。\n3. 运行 `bun run deploy:builds:setup`，通过 Cloudflare Workers Builds 将已部署的 Worker 连接到 Fork 仓库的 `main` 分支；如需 token，使用 User API Token，不要使用 Account API Token。\n4. 后续 GitHub Sync fork 或任何推送到 `main` 的更新，都必须自动构建、执行 D1 migration 并发布该实例。", }; --- diff --git a/apps/site/src/content/blog/edgeever-major-update.md b/apps/site/src/content/blog/edgeever-major-update.md index 4571cc79..cb116e07 100644 --- a/apps/site/src/content/blog/edgeever-major-update.md +++ b/apps/site/src/content/blog/edgeever-major-update.md @@ -74,13 +74,6 @@ EdgeEver 提供： 1. 打开你自己的 EdgeEver Fork 仓库。 2. 点击 GitHub 页面上的 **Sync fork**，同步官方仓库的最新代码。 -3. 回到本地项目目录重新部署： +3. 已配置 Cloudflare Workers Builds 时，产生的 push 会自动构建、执行 D1 migration 并发布，无需回到本地重新部署。 -```sh -git pull -bun install -bun run deploy:doctor -bun run deploy -``` - -同步 Fork 只会更新 GitHub 仓库里的代码，不会自动更新已经部署到 Cloudflare 的实例。同步后必须重新执行部署命令。 +如果是较早安装的实例、尚未连接 Workers Builds，请先按 [Cloudflare Workers Builds 自动部署](/manual-deploy#开启自动更新) 完成一次连接；之后再使用 **Sync fork** 更新。 diff --git a/apps/site/src/content/blog_en/edgeever-major-update.md b/apps/site/src/content/blog_en/edgeever-major-update.md index 99d01da5..b44d7750 100644 --- a/apps/site/src/content/blog_en/edgeever-major-update.md +++ b/apps/site/src/content/blog_en/edgeever-major-update.md @@ -74,13 +74,6 @@ If you deployed from a fork: 1. Open your own EdgeEver fork on GitHub. 2. Click **Sync fork** on GitHub to sync the latest code from upstream. -3. Return to your local project and redeploy: +3. If Cloudflare Workers Builds is connected, the push automatically builds, applies D1 migrations, and deploys. No local redeployment is needed. -```sh -git pull -bun install -bun run deploy:doctor -bun run deploy -``` - -Syncing the fork only updates the code in GitHub. It does not automatically update the instance already deployed on Cloudflare. You still need to run the deployment command again. +For an older instance that is not yet connected to Workers Builds, complete the one-time [Workers Builds setup](/en/manual-deploy#enable-automatic-updates) before using **Sync fork** for future updates. diff --git a/docs/agent-deploy-cloudflare.md b/docs/agent-deploy-cloudflare.md index bfad03c7..154b5fd7 100644 --- a/docs/agent-deploy-cloudflare.md +++ b/docs/agent-deploy-cloudflare.md @@ -20,7 +20,7 @@ Chinese version: - Read `AGENTS.md`, `README.md`, `.env.local.example`, and this file first. - Do not create a new Git branch. Work on `main`. -- Prefer `bun run deploy:setup`, `bun run deploy:doctor`, and `bun run deploy` for initial installation. Then connect the Worker to Cloudflare Workers Builds for all routine updates. +- Treat deployment as two required phases: use `bun run deploy:setup`, `bun run deploy:doctor`, and `bun run deploy` only for the initial installation; then run `bun run deploy:builds:setup` so all routine updates use Cloudflare Workers Builds. - Do not hard-code a personal Worker name, D1 database ID, R2 bucket name, account ID, API token, or domain in source files. - Use `.env.local` for local/private deployment values. It is git-ignored. - If the Cloudflare MCP or Cloudflare plugin is available, it may be used to inspect or create resources. If not, use Wrangler through the scripts in this repo. @@ -107,7 +107,7 @@ Chinese version: bun run deploy:builds:setup ``` - It reads the fork remote and `.env.local`, then creates or updates the Cloudflare repository connection, production trigger, build commands, cache, watch paths, and build variables. The configuration API requires a **User API Token** (`My Profile` -> `API Tokens`), not an Account API Token; set it as `EDGE_EVER_BUILDS_API_TOKEN`. The agent should complete the Cloudflare GitHub App authorization in the browser when available. If Cloudflare requires a build-token choice, use the exact Dashboard path and retry command shown in [Cloudflare Workers Builds](cloudflare-workers-builds.md). + It reads the fork remote and `.env.local`, then creates or updates the Cloudflare repository connection, production trigger, build commands, cache, watch paths, and build variables. The configuration API requires a **User API Token** (`My Profile` -> `API Tokens`), not an Account API Token; it must have `Workers Builds Configuration: Edit` and `Workers Scripts: Read`, and be set as `EDGE_EVER_BUILDS_API_TOKEN`. The agent should complete the Cloudflare GitHub App authorization in the browser when available. If Cloudflare requires a build-token choice, use the exact Dashboard path and retry command shown in [Cloudflare Workers Builds](cloudflare-workers-builds.md). Once connected, a GitHub **Sync fork** push automatically migrates and deploys the user's own instance. Do not configure the repository's GitHub Actions Worker deployment for this purpose. @@ -151,4 +151,5 @@ After deployment, report: - login username - whether the password was user-provided or generated - where to create the EdgeEver MCP token in the app +- confirmation that Workers Builds is connected and that future `main` pushes automatically migrate and deploy - any custom domain or Cloudflare DNS step that remains diff --git a/docs/manual-deploy.md b/docs/manual-deploy.md index c13692c8..8f79e846 100644 --- a/docs/manual-deploy.md +++ b/docs/manual-deploy.md @@ -1,6 +1,6 @@ # Cloudflare Manual Deployment Guide -If you are comfortable with Cloudflare and the command line, or prefer customized control over the deployment process, follow this guide for manual deployment and future updates. +If you are comfortable with Cloudflare and the command line, or prefer customized control over first installation and resource setup, follow this guide for manual deployment. Cloudflare Workers Builds handles routine updates; local deployment is only for first installation and emergency recovery. > 💡 **Tip**: If you are deploying using an AI assistant (such as Claude Code, Codex, Antigravity, Cursor, or Trae), the agent should follow the [AI Agent Cloudflare Deployment](https://github.com/tianma-if/edgeever/blob/main/docs/agent-deploy-cloudflare.md) runbook. @@ -70,8 +70,12 @@ Before running `bun run deploy`, copy the D1 `database_id`, R2 bucket name, and ## Enable Automatic Updates -After the first deployment, connect the Worker to your fork with [Cloudflare Workers Builds](cloudflare-workers-builds.md). This is the standard production deployment path for every EdgeEver instance. +After the first deployment, connect the Worker to the fork's `main` branch. Cloudflare Workers Builds is the standard production deployment path for every EdgeEver instance. Follow [Cloudflare Workers Builds](cloudflare-workers-builds.md) to create the configuration-only **User API Token** (not an Account API Token), save it privately as `EDGE_EVER_BUILDS_API_TOKEN` in `.env.local`, then run: -After the one-time connection, click **Sync fork** whenever you want upstream updates. The resulting push automatically builds the web app, applies new remote D1 migrations, and deploys the Worker. No GitHub Actions secrets or local redeployment are required. +```sh +bun run deploy:builds:setup +``` + +The command configures the Git repository connection, production trigger, build variables, and the deployment token needed for D1 migrations. Afterwards, use **Sync fork** or push to `main`; Cloudflare automatically builds the web app, applies new remote D1 migrations, and deploys the Worker. No GitHub Actions secrets or local redeployment are required. Keep `bun run deploy` available for first installation and emergency recovery. diff --git a/docs/manual-deploy.zh-CN.md b/docs/manual-deploy.zh-CN.md index 7fc44f04..44455030 100644 --- a/docs/manual-deploy.zh-CN.md +++ b/docs/manual-deploy.zh-CN.md @@ -1,6 +1,6 @@ # Cloudflare 手动部署指南 -如果你熟悉 Cloudflare 和命令行，或者想自定义/精细控制部署流程，可以按照以下指南进行手动部署与后续更新。 +如果你熟悉 Cloudflare 和命令行，或者想自定义/精细控制首次安装与资源配置，可以按照以下指南进行手动部署。日常更新统一由 Cloudflare Workers Builds 完成；本地部署仅用于首次安装和紧急修复。 > 💡 **提示**：如果是通过 AI 助手（Claude Code、Codex、Antigravity、Cursor、Trae 等）进行部署，AI 助手应优先参考 [AI Agent Cloudflare Deployment](https://github.com/tianma-if/edgeever/blob/main/docs/agent-deploy-cloudflare.md) 约定。 @@ -70,8 +70,12 @@ bun run deploy ## 开启自动更新 -首次部署完成后，请按 [Cloudflare Workers Builds 自动部署](cloudflare-workers-builds.zh-CN.md) 将 Worker 连接到 Fork。它是所有 EdgeEver 实例的标准生产发布路径。 +首次部署后，必须将 Worker 连接到 Fork 的 `main` 分支；Cloudflare Workers Builds 是所有 EdgeEver 实例的标准生产发布路径。请先按 [Cloudflare Workers Builds 自动部署](cloudflare-workers-builds.zh-CN.md) 创建仅供配置使用的 **User API Token**（不是 Account API Token），将它私下写入 `.env.local` 的 `EDGE_EVER_BUILDS_API_TOKEN`，然后执行： -一次连接完成后，只需在 Fork 页面点击 **Sync fork**。产生的 push 会自动构建 Web、应用新的远程 D1 migration 并发布 Worker；不需要再配置 GitHub Actions Secrets，也不需要本地重新部署。 +```sh +bun run deploy:builds:setup +``` + +该命令会配置 Git 仓库连接、生产触发器、构建变量和 D1 migration 所需的部署 token。完成后，只需在 Fork 页面点击 **Sync fork**，或推送到 `main`；Cloudflare 会自动构建 Web、应用新的远程 D1 migration 并发布 Worker。不需要 GitHub Actions Secrets，也不需要本地重新部署。 请保留 `bun run deploy` 作为首次安装和紧急修复的入口。