AI-native knowledge base & Evernote/Obsidian alternative with instant sync & native MCP. Free on Cloudflare or self-hosted via Docker.
HTML ai-agentcloudflarecloudflare-d1cloudflare-r2cloudflare-workersdockerelectronevernoteevernote-alternativeknowledge-basemcpnote-takingobsidian-alternativeoffline-firstpersonal-knowledge-basepwaself-hostedsqlitetiptapweb-clipper
docs: streamline Cloudflare deployment paths
tianma-if8db37f78a816
diff --git a/.github/workflows/sync-edgeever-upstream.yml b/.github/workflows/sync-edgeever-upstream.ymlindex a3ca9e47..c97103a2 100644--- a/.github/workflows/sync-edgeever-upstream.yml+++ b/.github/workflows/sync-edgeever-upstream.yml@@ -40,6 +40,17 @@ jobs:ref: mainfetch-depth: 0+ - name: Require a GitHub Fork+ shell: bash+ run: |+ set -euo pipefail+ is_fork="$(gh api "repos/${GITHUB_REPOSITORY}" --jq '.fork')"+ if [ "${is_fork}" != "true" ]; then+ echo "This deployment repository must be a GitHub Fork of ${UPSTREAM_REPOSITORY}." >&2+ echo "Create the repository with the EdgeEver Fork flow before enabling upstream updates." >&2+ exit 1+ fi+- name: Resolve upstream versionid: upstreamshell: bashdiff --git a/README.md b/README.mdindex 6558e672..38bd8e73 100644--- a/README.md+++ b/README.md@@ -54,44 +54,24 @@ The public demo resets every Monday at 1:00 AM (China Standard Time) and restore## Deployment-Choose any one of the following three options to complete deployment.+### Option A: Deploy online from a Fork (Recommended)-### Option A: Deploy to Cloudflare (Recommended)--[](https://deploy.workers.cloudflare.com/?url=https://github.com/tianma-if/edgeever)--One-click deployment creates a dedicated GitHub repository and the required Cloudflare resources, then automatically redeploys after the repository's daily upstream sync; see [Deploy EdgeEver with Cloudflare](docs/deploy-cloudflare-button.md) for setup and troubleshooting.+[Fork EdgeEver on GitHub](https://github.com/tianma-if/edgeever/fork), then follow the [online deployment guide](docs/deploy-cloudflare-button.md).### Option B: Deploy with an AI Agent-> 💡 **Note:** Under the hood, AI Agent deployment uses the exact same deterministic CLI commands (Wrangler and Bun scripts) as the manual flow. The AI agent simply executes these standard commands in the terminal on your behalf for convenience; it is not a non-deterministic, black-box deployment.--Copy this prompt into your AI coding assistant, such as Claude Code, Codex, OpenClaw, Antigravity, or Cursor. It uses the same deployment core as the button and manual flows:--**Recommendation:** Before deployment, configure GitHub and Cloudflare MCP servers, plugins, or other supported integrations for your AI Agent.+Copy this prompt into an AI Agent with GitHub and Cloudflare access:```text-Please follow these steps:-1. Create a GitHub repository from https://github.com/tianma-if/edgeever and clone it locally.-2. Follow docs/agent-deploy-cloudflare.md to create Cloudflare resources and run `bun run deploy:manual`.-3. Run `bun run deploy:builds:setup` to connect the deployed Worker to the repository's `main` branch through Cloudflare Workers Builds. If setup needs a token, use a User API Token, not an Account API Token.-4. Verify the first automatic build and the daily upstream-update workflow.+Deploy EdgeEver online:+1. Fork https://github.com/tianma-if/edgeever.+2. Import the Fork into Cloudflare Workers & Pages.+3. Configure D1, R2, the `EDGE_EVER_AUTH_PASSWORD` Worker Secret, and the production `main` build.+4. Start the first build and verify `/api/health`, `/api/openapi.json`, and login.+5. Enable and run `Update deployed EdgeEver` once.```-Agents should follow [AI Agent Cloudflare Deployment](docs/agent-deploy-cloudflare.md).--After the first deployment, see [Cloudflare Workers Builds](docs/cloudflare-workers-builds.md). All installation entry points use the same build, migration, deployment, and verification pipeline.--> Common pitfall: Cloudflare R2, D1, and Workers may still require a Visa card during activation or usage, even when you stay within the free quotas.--### Option C: Manual Deployment--Please refer to the [Cloudflare Manual Deployment Guide](docs/manual-deploy.md) for advanced first-time installation, Cloudflare resource setup, troubleshooting, and emergency recovery. After the first deployment, connect Workers Builds; future repository updates deploy automatically.--The automated helper commands are recommended. The manual template uses `admin` / `admin123` for the initial login, and the password can be changed later in Personal Settings. If you create the Cloudflare resources manually, finish configuring `.env.local`—including the D1 ID, R2 bucket, and the 400-day session limit—before running `bun run deploy:manual`.--Production deployments fail closed: when D1 migrations or the login Secret are missing, the instance shows a diagnosable configuration error and denies access instead of falling back to an unauthenticated workspace. Never insert plaintext passwords into D1; use the recovery command documented in the manual deployment guide.-+Detailed requirements: [AI Agent Cloudflare Deployment](docs/agent-deploy-cloudflare.md).## Multi-Account Logindiff --git a/README.zh-CN.md b/README.zh-CN.mdindex d121b609..405f74e7 100644--- a/README.zh-CN.md+++ b/README.zh-CN.md@@ -52,42 +52,23 @@ EdgeEver 是一个开源、自托管、Cloudflare-native 的现代笔记工作## 部署-以下三种方案任选其一即可完成部署。+### 方案一:Fork 后在线部署(推荐)-### 方案 A:Cloudflare 一键部署(推荐)+[在 GitHub Fork EdgeEver](https://github.com/tianma-if/edgeever/fork),然后查看[在线部署文档](docs/deploy-cloudflare-button.zh-CN.md)。-[](https://deploy.workers.cloudflare.com/?url=https://github.com/tianma-if/edgeever)--一键部署会创建专属 GitHub 仓库和所需 Cloudflare 资源,并在仓库每日同步上游版本后自动触发重新部署;配置与排错见[使用 Cloudflare 一键部署 EdgeEver](docs/deploy-cloudflare-button.zh-CN.md)。--### 方案 B:通过 AI Agent 一句话部署--> 💡 **提示:** AI Agent 部署的底层逻辑与标准的手动部署完全一致。AI 助手只是代为在终端执行标准的、确定性的配置与部署命令(如 `wrangler` 和 `bun` 脚本),并非使用非确定性的黑盒部署方式。--将下方提示词复制给你的 AI 助手(Claude Code、Codex、OpenClaw、Antigravity、Cursor 等)。该入口与一键部署和手动部署共用同一套部署内核。--**建议:** 开始部署前,请先为 AI Agent 配置 GitHub 和 Cloudflare 的 MCP、插件或其他可用集成。+### 方案二:AI Agent 部署+将下方提示词复制给已接入 GitHub 和 Cloudflare 的 AI Agent:```text-请按以下流程操作:-1. 基于 https://github.com/tianma-if/edgeever 创建 GitHub 仓库并克隆到本地。-2. 严格按照 docs/agent-deploy-cloudflare.md 创建 Cloudflare 资源并运行 `bun run deploy:manual`。-3. 运行 `bun run deploy:builds:setup`,通过 Cloudflare Workers Builds 将已部署的 Worker 连接到仓库的 `main` 分支;如需 token,使用 User API Token,不要使用 Account API Token。-4. 验证首次自动构建和每日上游更新工作流。+请在线完成 EdgeEver 部署:+1. Fork https://github.com/tianma-if/edgeever。+2. 将这个 Fork 导入 Cloudflare Workers & Pages。+3. 配置 D1、R2、`EDGE_EVER_AUTH_PASSWORD` Worker Secret 和生产环境 `main` 构建。+4. 启动首次构建,验证 `/api/health`、`/api/openapi.json` 和登录。+5. 启用并手动运行一次 `Update deployed EdgeEver`。```-Agent 应优先按 [AI Agent Cloudflare Deployment](docs/agent-deploy-cloudflare.md) 执行。首次部署后,请参阅 [Cloudflare Workers Builds 自动部署](docs/cloudflare-workers-builds.zh-CN.md)。所有安装入口共用同一套构建、migration、发布和验证流水线。--> 常见踩坑:Cloudflare 的 R2、D1 和 Worker 即使使用免费额度,在开通或使用过程中也可能要求绑定一张 Visa 卡。国内用户可以考虑办理招商银行多币种卡,拿到 Visa 卡后绑定到 Cloudflare 账号即可。--### 方案 C:手动部署--关于高级首次安装、Cloudflare 资源配置、故障排查与紧急修复,请参考 [Cloudflare 手动部署指南](docs/manual-deploy.zh-CN.md)。首次部署后,请配置 Cloudflare Workers Builds;之后仓库更新会自动部署。--推荐优先使用自动化辅助命令。手动配置模板使用 `admin` / `admin123` 作为初始登录账号密码,之后可在个人设置中修改密码。如果选择完全手动创建 Cloudflare 资源,必须先在 `.env.local` 中完成 D1 ID、R2 bucket 和 400 天会话期限等配置,再执行 `bun run deploy:manual`。--生产部署采用安全关闭策略:D1 未迁移或登录 Secret 缺失时,实例会显示可诊断的配置错误并拒绝访问,不会自动退化成免登录模式。请勿直接向 D1 写入明文密码;故障恢复命令见手动部署指南。-+详细要求见:[AI Agent 在线部署约定](docs/agent-deploy-cloudflare.zh-CN.md)。## 多账号登录diff --git a/apps/site/src/components/agent-install-tabs.astro b/apps/site/src/components/agent-install-tabs.astroindex f338c876..0b6d5c08 100644--- a/apps/site/src/components/agent-install-tabs.astro+++ b/apps/site/src/components/agent-install-tabs.astro@@ -6,15 +6,14 @@ const isEnglish = locale === "en-US";const copy = isEnglish? {- chooseOne: "Choose any one of the following three options to complete deployment.",- oneClick: "Option A: Cloudflare one-click",- agent: "Option B: AI Agent",- manual: "Option C: Manual",+ chooseOne: "Choose either option to complete deployment.",+ oneClick: "Option A: Deploy from a Fork",+ agent: "Option B: AI Agent deployment",recommended: "Recommended",oneClickIntro:- "One-click deployment creates a dedicated GitHub repository and the required Cloudflare resources, then automatically redeploys after the repository's daily upstream sync.",- deployButton: "Deploy to Cloudflare",- oneClickGuide: "Setup and troubleshooting",+ "Fork EdgeEver on GitHub, import the Fork into Cloudflare Workers & Pages, and configure the deployment online.",+ forkButton: "Fork EdgeEver on GitHub",+ oneClickGuide: "Open the online deployment guide",oneClickGuideHref:"https://github.com/tianma-if/edgeever/blob/main/docs/deploy-cloudflare-button.md",agentIntro:@@ -26,20 +25,17 @@ const copy = isEnglishcopyFailed: "Copy failed",billingNotice:"Heads up: Cloudflare R2, D1, and Workers may ask you to add a Visa card even when you use the free quotas.",- manualGuide: "Open the complete manual deployment guide",- manualGuideHref: "/en/manual-deploy",promptText:- "Please follow these steps:\n1. Create a GitHub repository from https://github.com/tianma-if/edgeever and clone it locally.\n2. Follow docs/agent-deploy-cloudflare.md to create Cloudflare resources and run `bun run deploy:manual`.\n3. Run `bun run deploy:builds:setup` to connect the deployed Worker to the repository's `main` branch through Cloudflare Workers Builds. If setup needs a token, use a User API Token, not an Account API Token.\n4. Verify the first automatic build and the daily upstream-update workflow.",+ "Deploy EdgeEver online:\n1. Fork https://github.com/tianma-if/edgeever.\n2. Import the Fork into Cloudflare Workers & Pages.\n3. Configure D1 DB, R2 RESOURCES, the EDGE_EVER_AUTH_PASSWORD Worker Secret, and Workers Builds using docs/agent-deploy-cloudflare.md.\n4. Start the first build, verify the health endpoint and login, then run Update deployed EdgeEver once.",}: {- chooseOne: "以下三种方案任选其一即可完成部署。",- oneClick: "方案 A:Cloudflare 一键部署",- agent: "方案 B:AI Agent 一句话部署",- manual: "方案 C:手动部署",+ chooseOne: "以下两种方案任选其一即可完成部署。",+ oneClick: "方案一:Fork 后在线部署",+ agent: "方案二:AI Agent 一句话部署",recommended: "推荐",- oneClickIntro: "一键部署会创建专属 GitHub 仓库和所需 Cloudflare 资源,并在仓库每日同步上游版本后自动触发重新部署。",- deployButton: "Deploy to Cloudflare",- oneClickGuide: "查看配置与排错说明",+ oneClickIntro: "先在 GitHub Fork EdgeEver,再将 Fork 导入 Cloudflare Workers & Pages,在线完成部署配置。",+ forkButton: "在 GitHub Fork EdgeEver",+ oneClickGuide: "查看在线部署文档",oneClickGuideHref:"https://github.com/tianma-if/edgeever/blob/main/docs/deploy-cloudflare-button.zh-CN.md",agentIntro: "将下方提示词复制给你的 AI 助手(Claude Code、Codex、Cursor 等)。",@@ -50,17 +46,15 @@ const copy = isEnglishcopyFailed: "复制失败",billingNotice:"提示:Cloudflare 的 R2、D1 和 Worker 即使使用免费额度,开通或使用时也可能要求绑定 Visa 卡。国内用户可考虑使用招商银行多币种卡绑定。",- manualGuide: "查看完整手动部署指南",- manualGuideHref: "/manual-deploy",promptText:- "请按以下流程操作:\n1. 基于 https://github.com/tianma-if/edgeever 创建 GitHub 仓库并克隆到本地。\n2. 严格按照 docs/agent-deploy-cloudflare.md 创建 Cloudflare 资源并运行 `bun run deploy:manual`。\n3. 运行 `bun run deploy:builds:setup`,通过 Cloudflare Workers Builds 将已部署的 Worker 连接到仓库的 `main` 分支;如需 token,使用 User API Token,不要使用 Account API Token。\n4. 验证首次自动构建和每日上游更新工作流。",+ "请在线完成 EdgeEver 部署:\n1. Fork https://github.com/tianma-if/edgeever。\n2. 将这个 Fork 导入 Cloudflare Workers & Pages。\n3. 按照 docs/agent-deploy-cloudflare.zh-CN.md 配置 D1 DB、R2 RESOURCES、EDGE_EVER_AUTH_PASSWORD Worker Secret 和 Workers Builds。\n4. 启动首次构建,验证健康检查和登录,然后手动运行一次 Update deployed EdgeEver。",};---<section class="not-prose relative left-1/2 my-10 w-[min(92vw,960px)] -translate-x-1/2" data-agent-install-tabs><p class="mb-6 text-center text-lg font-semibold text-slate-700">{copy.chooseOne}</p>- <div class="mx-auto grid max-w-4xl grid-cols-1 border-b border-slate-200 text-sm font-semibold sm:grid-cols-3 sm:text-base">+ <div class="mx-auto grid max-w-4xl grid-cols-1 border-b border-slate-200 text-sm font-semibold sm:grid-cols-2 sm:text-base"><buttonclass="agent-install-tab active relative px-3 py-4 text-brand transition hover:text-brand-text"type="button"@@ -76,13 +70,6 @@ const copy = isEnglisharia-selected="false">{copy.agent}</button>- <button- class="agent-install-tab relative px-3 py-4 text-slate-500 transition hover:text-brand-text"- type="button"- data-tab-target="manual"- aria-selected="false">- {copy.manual}- </button></div><div class="mt-8 overflow-hidden rounded-[28px] bg-slate-100 px-6 py-8 sm:px-10 md:px-14">@@ -90,12 +77,12 @@ const copy = isEnglish<p class="mx-auto max-w-3xl text-center text-lg leading-9 text-slate-600">{copy.oneClickIntro}</p><div class="mt-8 flex flex-col items-center justify-center gap-4 sm:flex-row"><a- class="inline-flex items-center gap-2 rounded-xl bg-[#f48120] px-7 py-3 text-base font-semibold text-white shadow-[0_14px_30px_-18px_rgba(244,129,32,0.85)] transition hover:-translate-y-0.5 hover:bg-[#e87315]"- href="https://deploy.workers.cloudflare.com/?url=https://github.com/tianma-if/edgeever"+ class="inline-flex items-center gap-2 rounded-xl bg-[#24292f] px-7 py-3 text-base font-semibold text-white shadow-[0_14px_30px_-18px_rgba(36,41,47,0.35)] transition hover:-translate-y-0.5 hover:bg-[#161b22]"+ href="https://github.com/tianma-if/edgeever/fork"target="_blank"rel="noopener">- <Icon class="h-5 w-5" name="simple-icons:cloudflare" />- {copy.deployButton}+ <Icon class="h-5 w-5" name="simple-icons:github" />+ {copy.forkButton}</a><aclass="text-sm font-semibold text-brand-text underline decoration-brand-border underline-offset-4 hover:text-brand"@@ -137,16 +124,6 @@ const copy = isEnglish</div></div>- <div class="agent-install-panel hidden" data-tab-panel="manual">- <div class="mx-auto flex justify-center">- <a- class="inline-flex items-center gap-2 rounded-full bg-brand px-8 py-3 text-base font-semibold text-white shadow-[0_14px_30px_-18px_rgb(var(--edgeever-brand-rgb)/0.85)] transition hover:-translate-y-0.5 hover:bg-brand-hover"- href={copy.manualGuideHref}>- {copy.manualGuide}- <Icon class="h-5 w-5" name="bx:bx-right-arrow-alt" />- </a>- </div>- </div></div></section>diff --git a/apps/site/src/content/blog/ai-agent-deploy-cloudflare.md b/apps/site/src/content/blog/ai-agent-deploy-cloudflare.mdindex 62b27865..9bce8a52 100644--- a/apps/site/src/content/blog/ai-agent-deploy-cloudflare.md+++ b/apps/site/src/content/blog/ai-agent-deploy-cloudflare.md@@ -1,10 +1,10 @@---draft: false-title: "EdgeEver Cloudflare 部署指南:三种方案任选其一"-snippet: "选择 Cloudflare 一键部署、AI Agent 或手动部署,在自己的 Cloudflare 账号中运行 EdgeEver。"+title: "EdgeEver Cloudflare 部署指南:两种方案任选其一"+snippet: "选择 Fork 后在线部署或 AI Agent 部署,在自己的 Cloudflare 账号中运行 EdgeEver。"image: {src: "/images/agent-deploy.jpg",- alt: "EdgeEver 的三种 Cloudflare 部署方案"+ alt: "EdgeEver 的两种 Cloudflare 部署方案"}publishDate: "2026-07-02 00:50"category: "Deployment"diff --git a/apps/site/src/content/blog_en/ai-agent-deploy-cloudflare.md b/apps/site/src/content/blog_en/ai-agent-deploy-cloudflare.mdindex 793b03a1..27dfca5d 100644--- a/apps/site/src/content/blog_en/ai-agent-deploy-cloudflare.md+++ b/apps/site/src/content/blog_en/ai-agent-deploy-cloudflare.md@@ -1,10 +1,10 @@---draft: false-title: "Deploy EdgeEver to Cloudflare: choose one of three options"-snippet: "Choose Cloudflare one-click, an AI Agent, or manual deployment to run EdgeEver in your own Cloudflare account."+title: "Deploy EdgeEver to Cloudflare: choose one of two options"+snippet: "Choose online deployment from a GitHub Fork or an AI Agent deployment in your own Cloudflare account."image: {src: "/images/agent-deploy.jpg",- alt: "Three ways to deploy EdgeEver to Cloudflare"+ alt: "Two ways to deploy EdgeEver to Cloudflare"}publishDate: "2026-07-02 00:50"category: "Deployment"diff --git a/apps/site/src/i18n.ts b/apps/site/src/i18n.tsindex 6c31aa9c..d2401097 100644--- a/apps/site/src/i18n.ts+++ b/apps/site/src/i18n.ts@@ -128,8 +128,8 @@ export const siteCopy = {description: "把最关键的上手路径放到显眼位置:先部署自己的实例,再把旧笔记迁过来,最后用 MCP 接入 AI Agent 整理长期知识库。",items: [{- title: "三种方式部署 EdgeEver",- summary: "Cloudflare 一键部署、AI Agent 和手动部署三种方案任选其一,使用同一套可靠的部署流程。",+ title: "两种方式部署 EdgeEver",+ summary: "Fork 后在线部署,或让 AI Agent 代为完成同一套线上配置流程。",href: "/blog/ai-agent-deploy-cloudflare",cta: "查看部署指南",},@@ -251,8 +251,8 @@ export const siteCopy = {description: "The fastest paths into EdgeEver: deploy your own instance, move an existing Evernote archive, then connect MCP-powered AI workflows.",items: [{- title: "Three ways to deploy EdgeEver",- summary: "Choose Cloudflare one-click, an AI Agent, or manual deployment—all three use the same reliable deployment pipeline.",+ title: "Two ways to deploy EdgeEver",+ summary: "Deploy online from a GitHub Fork, or let an AI Agent complete the same online configuration flow.",href: "/blog/ai-agent-deploy-cloudflare",cta: "Read deployment guide",},diff --git a/docs/agent-deploy-cloudflare.md b/docs/agent-deploy-cloudflare.mdindex 258b55e3..2da5214b 100644--- a/docs/agent-deploy-cloudflare.md+++ b/docs/agent-deploy-cloudflare.md@@ -1,37 +1,17 @@# AI Agent Cloudflare Deployment-Use this contract when deploying EdgeEver from a GitHub repository to Cloudflare.+## Steps-## Constraints+1. Fork `tianma-if/edgeever`.+2. Enable the Fork's **Update deployed EdgeEver** workflow.+3. In Cloudflare **Workers & Pages**, import the Fork using the repository root, `main` branch, and existing `wrangler.toml`.+4. Configure D1 `DB`, R2 `RESOURCES`, and the Worker Secret `EDGE_EVER_AUTH_PASSWORD`.+5. Configure Workers Builds:-- Use local deployment only for the first installation or emergency recovery. Routine updates must use Cloudflare Workers Builds.-- Keep account IDs, resource names, API tokens, domains, and passwords in the git-ignored `.env.local`; never hard-code or commit them.-- Use the repository deployment scripts. Do not add a separate GitHub Actions deployment for the Worker.+ ```text+ Build command: bun install --frozen-lockfile && EDGE_EVER_DEPLOYMENT_TRIGGER=main_push EDGE_EVER_DEPLOYMENT_METHOD=cloudflare_workers_builds bun run build:cloudflare+ Deploy command: bun run deploy:cloudflare-builds+ ```-## First Installation--Run in order:--```sh-bun run deploy:setup-bun run deploy:doctor-bun run deploy:manual-```--If the user supplied a custom initial password, replace the first command with:--```sh-EDGE_EVER_PASSWORD='<first-login-password>' bun run deploy:setup-```--Do not deploy until `deploy:doctor` passes. `deploy:manual` uses the same build, migration, Worker deployment, and verification core as Cloudflare one-click deployment and Workers Builds. After deployment, verify that `/api/health` returns `200` with `"ok": true`, then verify `/api/openapi.json` and login. A `database_not_ready` or `auth_not_configured` response means deployment is incomplete and must not be handed off as successful. The default initial login is `admin` / `admin123`.--## Automatic Updates--After the first deployment, run:--```sh-bun run deploy:builds:setup-```--Follow [Cloudflare Workers Builds](cloudflare-workers-builds.md) only when the command requests authorization or an API token. Deployment is complete when the verification build succeeds and future pushes to `main` automatically deploy the instance. Confirm that the repository's **Update deployed EdgeEver** workflow is available and enabled; GitHub disables scheduled workflows by default on public forks. Its default `stable` channel checks formal upstream Releases daily.+6. Start the first build and verify `/api/health`, `/api/openapi.json`, and login.+7. Run **Update deployed EdgeEver** once and confirm that upstream updates work.diff --git a/docs/agent-deploy-cloudflare.zh-CN.md b/docs/agent-deploy-cloudflare.zh-CN.mdnew file mode 100644index 00000000..0d343133--- /dev/null+++ b/docs/agent-deploy-cloudflare.zh-CN.md@@ -0,0 +1,17 @@+# AI Agent 在线部署 EdgeEver++## 步骤++1. Fork `tianma-if/edgeever`。+2. 启用 Fork 中的 **Update deployed EdgeEver** 工作流。+3. 在 Cloudflare **Workers & Pages** 导入 Fork,使用仓库根目录、`main` 分支和现有 `wrangler.toml`。+4. 配置 D1 `DB`、R2 `RESOURCES` 和 Worker Secret `EDGE_EVER_AUTH_PASSWORD`。+5. 配置 Workers Builds:++ ```text+ Build command: bun install --frozen-lockfile && EDGE_EVER_DEPLOYMENT_TRIGGER=main_push EDGE_EVER_DEPLOYMENT_METHOD=cloudflare_workers_builds bun run build:cloudflare+ Deploy command: bun run deploy:cloudflare-builds+ ```++6. 启动首次构建,验证 `/api/health`、`/api/openapi.json` 和登录。+7. 手动运行一次 **Update deployed EdgeEver**,确认上游更新正常。diff --git a/docs/cloudflare-workers-builds.md b/docs/cloudflare-workers-builds.mdindex dcdb681b..c0821d10 100644--- a/docs/cloudflare-workers-builds.md+++ b/docs/cloudflare-workers-builds.md@@ -1,48 +1,21 @@# Cloudflare Workers Builds-Cloudflare Workers Builds deploys EdgeEver whenever `main` changes. Cloudflare one-click deployment connects it automatically; CLI installations use local `bun run deploy:manual` only for first installation or emergency recovery. The official Demo Worker is additionally deployed by the `Deploy Demo on Release` workflow whenever a formal GitHub Release is published. That workflow is restricted to the canonical `tianma-if/edgeever` repository; forks and self-hosted installations must use their own Cloudflare credentials and deployment configuration.-## Setup-Cloudflare one-click installations do not need this setup command. For CLI or Agent installations, complete the [first deployment](manual-deploy.md), then run:--```sh-bun run deploy:builds:setup-```--The command reads the repository remote and `.env.local`, configures the build, and starts one verification build on first setup. It is safe to rerun after instance settings change.--Only complete the following steps when the command asks for them.--### GitHub authorization--Approve installation of the **Cloudflare Workers & Pages** GitHub App for the deployment repository. This is the app's name; an EdgeEver instance does not require a Pages project. The command handles the repository connection after authorization.--### Configuration API token--If `EDGE_EVER_BUILDS_API_TOKEN` is missing, create a custom **User API Token** at [My Profile -> API Tokens](https://dash.cloudflare.com/profile/api-tokens) with:--- **Account** -> **Workers Builds Configuration** -> **Edit**-- **Account** -> **Workers Scripts** -> **Read**--Do not use an Account API Token or a prebuilt template. Limit the token to the relevant account, then save the value shown by Cloudflare once in `.env.local`:--```text-EDGE_EVER_BUILDS_API_TOKEN=<token>-```--Never commit or share this token.----### Deployment API token+Use the build and deploy commands from the [online deployment guide](deploy-cloudflare-button.md), with root directory `/` and production branch `main`.-If the command reports that no deployment API token is available, open **Worker** -> **Settings** -> **Builds** -> **API token** and create or select one that can deploy the Worker and update D1 and R2, then rerun the command. When several are available, select one by name in the terminal.+Authorization:-## Updates and Troubleshooting+1. Approve the **Cloudflare Workers & Pages** GitHub App for the deployment repository.+2. If the Agent integration needs a Cloudflare API token, use a User API Token limited to the target account.+3. Configure the deployment API token in Cloudflare under **Worker -> Settings -> Builds -> API token**.-After setup, every push to `main` makes Cloudflare install dependencies, check and build the app, apply new D1 migrations, deploy the Worker, and verify the result. For the official Demo Worker, publishing a formal Release triggers an immediate deployment from that Release tag through the `Deploy Demo on Release` GitHub workflow; this workflow only runs in the canonical upstream repository. Other self-hosted deployment repositories can use the **Update deployed EdgeEver** workflow, which checks upstream daily: `stable` follows formal Releases by default, while the repository variable `EDGE_EVER_UPDATE_CHANNEL=edge` follows upstream `main`. No Cloudflare deployment secrets or local redeployment are required in GitHub Actions.+## Updates and troubleshooting-If a build fails, inspect its log in the Worker **Deployments** tab. Rerun `bun run deploy:builds:setup` when instance settings change.+- A push to `main` builds, applies D1 migrations, deploys, and verifies EdgeEver.+- **Update deployed EdgeEver** checks the latest formal Release daily.+- Set the GitHub Repository Variable `EDGE_EVER_UPDATE_CHANNEL=edge` to follow upstream `main`.+- Build failure: inspect the Worker **Deployments** log.+- Scheduled update failure: enable and run the workflow from the Fork's **Actions** tab.-Deploy-button repositories begin with a synthetic `source repo import` commit. The first upstream update detects this layout and establishes the upstream history automatically. For repositories created before the updater workflow was introduced, add the current `.github/workflows/sync-edgeever-upstream.yml` from the upstream repository and run it manually once. Do not use this bootstrap path after custom application changes have been committed without reviewing the differences.+Legacy Cloudflare-created repositories with only a `source repo import` commit are bootstrapped on their first update. Do not use this bootstrap path after custom application changes.diff --git a/docs/cloudflare-workers-builds.zh-CN.md b/docs/cloudflare-workers-builds.zh-CN.mdindex e8186642..077a1508 100644--- a/docs/cloudflare-workers-builds.zh-CN.md+++ b/docs/cloudflare-workers-builds.zh-CN.md@@ -1,48 +1,21 @@-# Cloudflare Workers Builds 自动部署--Cloudflare Workers Builds 会在 `main` 发生变化时自动部署 EdgeEver。Cloudflare 一键部署会自动完成连接;CLI 安装只在首次部署或紧急修复时使用本地 `bun run deploy:manual`。官方 Demo Worker 还会在 GitHub 正式 Release 发布后,由 `Deploy Demo on Release` 工作流立即部署。该工作流仅限官方 `tianma-if/edgeever` 仓库执行;Fork 或自托管实例必须使用自己的 Cloudflare 凭据和部署配置。+# Cloudflare Workers Builds## 配置-Cloudflare 一键部署实例不需要执行该配置命令。CLI 或 Agent 安装请先完成[首次部署](manual-deploy.zh-CN.md),然后执行:--```sh-bun run deploy:builds:setup-```--命令会读取仓库 remote 与 `.env.local`、配置自动构建,并在首次配置时启动一次验证构建。实例配置发生变化后可以安全重跑。--只有命令明确提示时,才需要完成下面对应的操作。--### GitHub 授权--为部署仓库安装并授权 **Cloudflare Workers & Pages** GitHub App。这只是应用名称,EdgeEver 实例不需要部署 Pages 项目。授权完成后,命令会继续配置仓库连接。--### 配置 API token+使用[在线部署文档](deploy-cloudflare-button.zh-CN.md)中的构建命令和部署命令,仓库根目录为 `/`,生产分支为 `main`。-如果缺少 `EDGE_EVER_BUILDS_API_TOKEN`,请在 [My Profile -> API Tokens](https://dash.cloudflare.com/profile/api-tokens) 创建自定义 **User API Token**,权限为:+授权:-- **Account** -> **Workers Builds Configuration** -> **Edit**-- **Account** -> **Workers Scripts** -> **Read**--不要使用 Account API Token 或现成模板。将 token 限制到对应账号,然后把 Cloudflare 仅显示一次的值保存到 `.env.local`:--```text-EDGE_EVER_BUILDS_API_TOKEN=<token>-```--不要提交或分享该 token。----### 部署 API token--如果命令提示没有可用的部署 API token,请打开 **Worker** -> **Settings** -> **Builds** -> **API token**,创建或选择一个能够部署 Worker 并更新 D1、R2 的 API token,然后重试。存在多个候选时,直接在终端中按名称选择。+1. 为部署仓库授权 **Cloudflare Workers & Pages** GitHub App。+2. 如果 Agent 集成需要 Cloudflare API Token,使用限制到目标账号的 User API Token。+3. 部署 API Token 在 Cloudflare **Worker -> Settings -> Builds -> API token** 中配置。## 更新与排错-配置完成后,任何推送到 `main` 的提交都会让 Cloudflare 安装依赖、检查并构建应用、执行新的 D1 migration、部署 Worker 并验证结果。官方 Demo Worker 在发布正式 Release 时,会通过 GitHub 的 `Deploy Demo on Release` 工作流从 Release 标签立即部署;该工作流只在官方上游仓库执行。其他自托管部署仓库可以使用 **Update deployed EdgeEver** 工作流每天检查上游:默认 `stable` 跟随正式 Release,设置 Repository Variable `EDGE_EVER_UPDATE_CHANNEL=edge` 后跟随上游 `main`。GitHub Actions 不需要保存 Cloudflare 部署 Secret,也不需要本地重新部署。--构建失败时,在 Worker 的 **Deployments** 页面查看日志。实例配置变化后,重新执行 `bun run deploy:builds:setup`。+- `main` 推送会自动构建、执行 D1 migration、部署并验证。+- **Update deployed EdgeEver** 工作流每天检查上游正式 Release。+- 设置 GitHub Repository Variable `EDGE_EVER_UPDATE_CHANNEL=edge` 后跟随上游 `main`。+- 构建失败:查看 Worker 的 **Deployments** 日志。+- 定时更新失败:在 Fork 的 **Actions** 中启用并手动运行工作流。-一键部署生成的仓库最初只有一个合成的 `source repo import` 提交。第一次上游更新会识别这种结构,并自动建立上游 Git 历史。对于更新工作流加入之前创建的仓库,请从上游仓库添加当前的 `.github/workflows/sync-edgeever-upstream.yml`,提交到 `main`,然后手动运行一次。若仓库已经提交过自定义应用代码,必须先审查差异,不要直接使用该初始化路径。+旧的 Cloudflare 创建仓库如果只有 `source repo import` 提交,第一次更新会自动建立上游历史。已经修改过应用代码的仓库不要直接使用该初始化流程。diff --git a/docs/deploy-cloudflare-button.md b/docs/deploy-cloudflare-button.mdindex b3b59a3f..9fdf875c 100644--- a/docs/deploy-cloudflare-button.md+++ b/docs/deploy-cloudflare-button.md@@ -1,35 +1,34 @@-# Deploy EdgeEver with Cloudflare+# Deploy EdgeEver online from a Fork-The **Deploy to Cloudflare** button is the recommended first-installation path. It creates a repository in your GitHub account, provisions the EdgeEver product Worker, D1 database, and R2 bucket, applies the database migrations, and connects the repository to Cloudflare Workers Builds. It does not deploy the official marketing site in `apps/site`; that site is a separate upstream-only Cloudflare Pages project.+## First installation-[](https://deploy.workers.cloudflare.com/?url=https://github.com/tianma-if/edgeever)+1. [Fork EdgeEver](https://github.com/tianma-if/edgeever).+2. In Cloudflare **Workers & Pages**, import the Fork.+3. Use the repository root and `main` branch. Keep the repository's `wrangler.toml`.+4. Configure:+ - D1 binding: `DB`, database name: `edgeever`+ - R2 binding: `RESOURCES`, with a unique bucket name+ - Worker Secret: `EDGE_EVER_AUTH_PASSWORD`+5. Set the build commands:-## First Installation+ ```text+ Build command: bun install --frozen-lockfile && EDGE_EVER_DEPLOYMENT_TRIGGER=main_push EDGE_EVER_DEPLOYMENT_METHOD=cloudflare_workers_builds bun run build:cloudflare+ Deploy command: bun run deploy:cloudflare-builds+ ```-1. Sign in to Cloudflare and GitHub, then open the button above.-2. Authorize the **Cloudflare Workers & Pages** GitHub App when requested.-3. Choose the destination repository, Worker name, D1 database name, and R2 bucket name.-4. Set `EDGE_EVER_AUTH_PASSWORD` to a strong password that is unique to this instance. The field is a Worker Secret and must not be committed to Git.-5. Save and deploy. Cloudflare runs the repository's common deployment pipeline: build, remote D1 migrations, Worker deployment, and deployment verification.-6. Open the resulting `*.workers.dev` URL. Confirm `/api/health` returns `200` with `"ok": true`, then sign in as `admin` with the password chosen during setup.+6. Start the build. Confirm that `/api/health` returns `200` with `"ok": true`, then test login.+7. In the Fork's **Actions**, enable and run **Update deployed EdgeEver** once.-EdgeEver fails closed. If the D1 migrations or authentication Secret are missing, the instance returns `database_not_ready` or `auth_not_configured` instead of exposing an unauthenticated workspace.+## Update channel-## Automatic Updates+The default follows formal Releases. To follow upstream `main`, create:-The generated repository is connected to Workers Builds, so every push to `main` builds, migrates, verifies, and deploys the instance. It also contains the **Update deployed EdgeEver** workflow, which checks the upstream repository once per day.+```text+EDGE_EVER_UPDATE_CHANNEL=edge+```-The default `stable` channel follows the latest formal GitHub Release. Before publishing an update, the workflow merges it locally and verifies dependency installation, local D1 migrations, automated tests, type checking, and the production web build. A failed merge or check leaves the deployed `main` branch unchanged and attempts to create an Issue with recovery guidance.+## Troubleshooting-To follow the latest upstream `main` instead, create a GitHub repository variable named `EDGE_EVER_UPDATE_CHANNEL` with the value `edge`. You can also run the workflow manually and select either channel for that run.--GitHub may delay scheduled workflows and may disable them for an inactive public repository. If daily updates stop, open the repository's **Actions** tab, enable **Update deployed EdgeEver**, and run it manually once. Do not force-push over update conflicts; resolve them or return to an unmodified deployment repository.--The updater also bootstraps repositories created by the Cloudflare Deploy button. Those repositories start with a synthetic `source repo import` commit instead of the upstream Git history, so the first successful update creates the history connection automatically. If the repository was created before the updater workflow was added, copy the current `.github/workflows/sync-edgeever-upstream.yml` from upstream into the repository, commit it to `main`, and run it manually once from **Actions**. The bootstrap is safe only for an unmodified deployment repository; customized repositories must be reconciled manually first.--## Alternative Entry Points--- Use [AI Agent Cloudflare Deployment](agent-deploy-cloudflare.md) when an agent should perform the same deterministic CLI deployment with custom configuration.-- Use [Cloudflare Manual Deployment](manual-deploy.md) for advanced configuration, troubleshooting, or emergency recovery.--All three entry points share the same product Worker build, migration, deployment, and verification commands. They do not require the official site. After first installation, they converge on Workers Builds and the same automatic-update workflow.+- Build failure: inspect the Worker **Deployments** log.+- No updates: open the Fork's **Actions**, enable **Update deployed EdgeEver**, and run it manually.+- Recovery: [Cloudflare Manual Deployment](manual-deploy.md).diff --git a/docs/deploy-cloudflare-button.zh-CN.md b/docs/deploy-cloudflare-button.zh-CN.mdindex a782e3f0..c28cd5eb 100644--- a/docs/deploy-cloudflare-button.zh-CN.md+++ b/docs/deploy-cloudflare-button.zh-CN.md@@ -1,35 +1,34 @@-# 使用 Cloudflare 一键部署 EdgeEver+# 从 Fork 在线部署 EdgeEver-**Deploy to Cloudflare** 按钮是推荐的首次安装方式。它会在你的 GitHub 账号中创建仓库,为 EdgeEver 产品创建 Worker、D1 数据库和 R2 存储桶,执行数据库 migration,并将仓库连接到 Cloudflare Workers Builds。它不会部署 `apps/site` 中的官方产品官网;该官网是只属于上游仓库的独立 Cloudflare Pages 项目。+## 首次部署-[](https://deploy.workers.cloudflare.com/?url=https://github.com/tianma-if/edgeever)+1. [Fork EdgeEver](https://github.com/tianma-if/edgeever/fork)。+2. 在 Cloudflare **Workers & Pages** 导入这个 Fork。+3. 使用仓库根目录和 `main` 分支,读取仓库中的 `wrangler.toml`。+4. 配置:+ - D1 binding:`DB`,数据库名:`edgeever`+ - R2 binding:`RESOURCES`,bucket 名称自定义且唯一+ - Worker Secret:`EDGE_EVER_AUTH_PASSWORD`+5. 设置构建命令:-## 首次安装+ ```text+ Build command: bun install --frozen-lockfile && EDGE_EVER_DEPLOYMENT_TRIGGER=main_push EDGE_EVER_DEPLOYMENT_METHOD=cloudflare_workers_builds bun run build:cloudflare+ Deploy command: bun run deploy:cloudflare-builds+ ```-1. 登录 Cloudflare 和 GitHub,然后打开上方按钮。-2. 按提示授权 **Cloudflare Workers & Pages** GitHub App。-3. 选择目标仓库名、Worker 名称、D1 数据库名称和 R2 bucket 名称。-4. 为 `EDGE_EVER_AUTH_PASSWORD` 设置仅供当前实例使用的强密码。该字段是 Worker Secret,不得提交到 Git。-5. 保存并部署。Cloudflare 会执行仓库统一的部署流水线:构建、远程 D1 migration、Worker 发布和部署验证。-6. 打开生成的 `*.workers.dev` 地址,确认 `/api/health` 返回 `200` 和 `"ok": true`,然后使用用户名 `admin` 和刚设置的密码登录。+6. 启动构建。部署完成后确认 `/api/health` 返回 `200` 和 `"ok": true`,再测试登录。+7. 在 Fork 的 **Actions** 中启用并运行一次 **Update deployed EdgeEver**。-EdgeEver 采用安全关闭策略。D1 migration 或鉴权 Secret 缺失时,实例会返回 `database_not_ready` 或 `auth_not_configured`,不会暴露免登录工作区。+## 更新通道-## 自动更新+默认跟随正式 Release。跟随上游 `main` 时创建:-生成的仓库会连接 Workers Builds,因此任何推送到 `main` 的提交都会自动构建、迁移、验证并发布。仓库还包含 **Update deployed EdgeEver** 工作流,每天检查一次上游更新。+```text+EDGE_EVER_UPDATE_CHANNEL=edge+```-默认 `stable` 通道跟随最新的正式 GitHub Release。发布更新前,工作流会在本地合并并验证依赖安装、本地 D1 migration、自动化测试、类型检查和生产 Web 构建。合并冲突或验证失败时不会修改线上 `main`,并会尝试创建 Issue 提供恢复提示。+## 排错-如果希望跟随上游最新 `main`,请创建名为 `EDGE_EVER_UPDATE_CHANNEL`、值为 `edge` 的 GitHub Repository Variable。也可以手动运行该工作流,并为本次运行选择任一通道。--GitHub 的定时任务可能延迟,也可能因公共仓库长期无活动而被停用。如果每日更新停止,请打开仓库的 **Actions** 页面,启用 **Update deployed EdgeEver** 并手动运行一次。遇到更新冲突时不要 force push,应解决冲突或恢复为未定制的部署仓库。--该更新工作流也支持 Cloudflare 一键部署生成的仓库。此类仓库最初只有一个合成的 `source repo import` 提交,并不包含上游 Git 历史;第一次成功更新时,工作流会自动建立与上游的历史连接。如果仓库是在更新工作流加入之前创建的,请从上游复制当前的 `.github/workflows/sync-edgeever-upstream.yml` 到该仓库,提交到 `main`,然后在 **Actions** 中手动运行一次。该自动初始化仅适用于未定制的部署仓库;已经修改过代码的仓库需要先人工处理差异。--## 其他部署入口--- 需要由 Agent 使用自定义配置执行同一套确定性 CLI 部署时,使用 [AI Agent Cloudflare Deployment](agent-deploy-cloudflare.md)。-- 高级配置、故障排查或紧急恢复时,使用 [Cloudflare 手动部署指南](manual-deploy.zh-CN.md)。--三个入口共用产品 Worker 的构建、migration、发布和验证命令,不需要部署官方产品官网。首次安装完成后,它们都会汇合到 Workers Builds 和同一套自动更新工作流。+- 构建失败:查看 Cloudflare Worker 的 **Deployments** 日志。+- 更新没有运行:打开 Fork 的 **Actions**,启用 **Update deployed EdgeEver** 并手动运行。+- 恢复部署:[手动部署指南](manual-deploy.zh-CN.md)。diff --git a/docs/manual-deploy.md b/docs/manual-deploy.mdindex 87b9b1f9..4e0737f9 100644--- a/docs/manual-deploy.md+++ b/docs/manual-deploy.md@@ -1,47 +1,30 @@-# Cloudflare Manual Deployment Guide+# Cloudflare Manual Deployment and Recovery-Use this path for advanced first installation, custom configuration, troubleshooting, or emergency recovery. Most users should start with [Deploy to Cloudflare](deploy-cloudflare-button.md). An AI assistant must follow the [AI Agent deployment contract](agent-deploy-cloudflare.md), which invokes the same commands documented here.+Use this page for advanced configuration, troubleshooting, and emergency recovery. Most users should use [Deploy EdgeEver online from a Fork](deploy-cloudflare-button.md); AI Agents should use [AI Agent Cloudflare Deployment](agent-deploy-cloudflare.md).-All entry points share one deployment core:+## First manual deployment-```text-build:cloudflare -> db:migrate:remote -> deploy:worker -> deploy:verify-```--The manual entrypoint adds local configuration checks before that pipeline. Routine updates are handled by Cloudflare Workers Builds rather than a local machine.--## Automated CLI Setup--1. Create a GitHub repository from [tianma-if/edgeever](https://github.com/tianma-if/edgeever), then clone it:-- ```sh- git clone <your repository URL>- cd edgeever- ```--2. Install Node.js 22 or newer and Bun. Wrangler is included in the project and does not need a global installation.--3. Install dependencies and initialize the Cloudflare resources:+1. Fork the repository and clone it locally.+2. Install Node.js 22+ and Bun.+3. Initialize configuration and Cloudflare resources:```shcp .env.local.example .env.localbun install- bun run deploy:setup+ EDGE_EVER_PASSWORD='<initial password>' bun run deploy:setupbun run deploy:doctorbun run deploy:manual```- The template uses `admin` / `admin123` for the initial login. To choose a password during setup, run this instead of the plain setup command:+`deploy:setup` creates or reuses D1 and R2 and writes configuration to the git-ignored `.env.local`. Without `EDGE_EVER_PASSWORD`, the default login is `admin` / `admin123`.- ```sh- EDGE_EVER_PASSWORD='<your password>' bun run deploy:setup- ```--`deploy:setup` uses the project-local Wrangler, starts `wrangler login` when authorization is missing, creates or reuses D1 and R2, and writes the resulting non-secret configuration to the git-ignored `.env.local`. `deploy:manual` runs the doctor, production build, common deployment pipeline, and remote verification.+After deployment, confirm:-## Creating Resources Manually+- `/api/health` returns `200` with `"ok": true`+- `/api/openapi.json` is reachable+- `admin` can log in-If you do not want `deploy:setup` to create resources, run:+## Create resources manually```shcp .env.local.example .env.local@@ -50,7 +33,7 @@ bunx wrangler d1 create edgeeverbunx wrangler r2 bucket create edgeever-resources```-Copy the returned D1 ID and the resource names into `.env.local`:+Write the returned D1 ID and resource names to `.env.local`:```textEDGE_EVER_D1_DATABASE_ID=<database_id>@@ -67,33 +50,18 @@ bun run deploy:doctorbun run deploy:manual```-`.env.local` is read only by local EdgeEver scripts. Never upload it, commit it, or copy it into a Cloudflare build as a file. The standard `bun run deploy` command is reserved for Cloudflare's one-click non-interactive entrypoint; local and Agent deployments use `bun run deploy:manual`.--The deployment pipeline applies remote D1 migrations without an interactive confirmation, deploys the Worker, and verifies required tables and the authentication Secret. It normalizes migration SQL to LF and runs Wrangler with its supported Node.js runtime for consistent behavior across Windows, macOS, and Linux.--EdgeEver fails closed: a production instance without completed D1 migrations or authentication configuration returns `database_not_ready` or `auth_not_configured` instead of exposing an unauthenticated workspace. The instance is ready only when `/api/health` returns `200` with `"ok": true` and login succeeds.+Do not commit `.env.local` or write passwords to D1.## Recovery-- Database not ready: confirm the D1 binding is exactly `DB`, then run `bun run deploy:manual`.-- Authentication not configured: set `EDGE_EVER_AUTH_PASSWORD` in `.env.local`, then run `bun run deploy:manual`.-- Invalid or lost account password: never write plaintext to `users.password_hash`. Run:+- Database not ready: confirm the D1 binding is `DB`, then run `bun run deploy:manual`.+- Authentication not configured: set `EDGE_EVER_AUTH_PASSWORD` in `.env.local`, then redeploy.+- Forgotten admin password:```sh- EDGE_EVER_PASSWORD='<new password of at least 8 characters>' \- bun run auth:reset-password -- --remote --username admin+ EDGE_EVER_PASSWORD='<new password>' bun run auth:reset-password -- --remote --username admin```-The binding names must be exactly `DB` for D1 and `RESOURCES` for R2. Existing installations using `EDGE_EVER_AUTH_PASSWORD_HASH` remain supported; when both password Secrets exist, the hash takes precedence.--## Enable Workers Builds and Automatic Updates--After the first CLI deployment, follow [Cloudflare Workers Builds](cloudflare-workers-builds.md) and run:--```sh-bun run deploy:builds:setup-```--This connects the Worker to the repository's `main` branch and securely copies the build variables required for future migrations and deployment. Every later push to `main` uses the same common deployment pipeline.+## Automatic updates-The repository's **Update deployed EdgeEver** workflow checks upstream formal Releases daily on the default `stable` channel. Set the GitHub repository variable `EDGE_EVER_UPDATE_CHANNEL=edge` to follow upstream `main` instead. GitHub disables scheduled workflows by default on public forks, so open **Actions** and enable this workflow after a fork-based installation. Update conflicts or failed local verification leave the deployed branch unchanged.+After manual deployment, configure [Cloudflare Workers Builds](cloudflare-workers-builds.md) and enable **Update deployed EdgeEver** in the Fork's **Actions**.diff --git a/docs/manual-deploy.zh-CN.md b/docs/manual-deploy.zh-CN.mdindex acda1ea7..f62498fe 100644--- a/docs/manual-deploy.zh-CN.md+++ b/docs/manual-deploy.zh-CN.md@@ -1,47 +1,30 @@-# Cloudflare 手动部署指南+# Cloudflare 手动部署与恢复-该入口用于高级首次安装、自定义配置、故障排查和紧急恢复。大多数用户应优先使用 [Cloudflare 一键部署](deploy-cloudflare-button.zh-CN.md)。AI 助手必须遵循 [AI Agent 部署约定](agent-deploy-cloudflare.md),其底层调用的也是本文命令。+本页只用于高级配置、故障排查和紧急恢复。普通用户请使用[从 Fork 在线部署](deploy-cloudflare-button.zh-CN.md),AI Agent 请使用[AI Agent 在线部署](agent-deploy-cloudflare.zh-CN.md)。-所有入口共用同一套部署内核:+## 首次手动部署-```text-build:cloudflare -> db:migrate:remote -> deploy:worker -> deploy:verify-```--手动入口只是在该流水线外增加本地配置检查。日常更新统一由 Cloudflare Workers Builds 执行,不依赖本地电脑。--## 自动化 CLI 初始化--1. 基于 [tianma-if/edgeever](https://github.com/tianma-if/edgeever) 创建 GitHub 仓库,然后克隆:-- ```sh- git clone <你的仓库 URL>- cd edgeever- ```--2. 安装 Node.js 22 或更高版本以及 Bun。Wrangler 已包含在项目依赖中,无需全局安装。--3. 安装依赖并初始化 Cloudflare 资源:+1. Fork 仓库并克隆到本地。+2. 安装 Node.js 22+ 和 Bun。+3. 初始化配置和 Cloudflare 资源:```shcp .env.local.example .env.localbun install- bun run deploy:setup+ EDGE_EVER_PASSWORD='<首次登录密码>' bun run deploy:setupbun run deploy:doctorbun run deploy:manual```- 模板使用 `admin` / `admin123` 作为初始登录账号密码。如果希望初始化时指定密码,请用下面的命令替代普通 setup:+`deploy:setup` 会创建或复用 D1、R2,并将配置写入被 Git 忽略的 `.env.local`。不设置 `EDGE_EVER_PASSWORD` 时,默认登录为 `admin` / `admin123`。- ```sh- EDGE_EVER_PASSWORD='<你的密码>' bun run deploy:setup- ```--`deploy:setup` 使用项目内置 Wrangler;缺少授权时启动 `wrangler login`,创建或复用 D1、R2,并把非 Secret 配置写入 Git 忽略的 `.env.local`。`deploy:manual` 会执行 doctor、生产构建、统一部署流水线和远端验证。+部署完成后,确认:-## 完全手动创建资源+- `/api/health` 返回 `200` 和 `"ok": true`+- `/api/openapi.json` 可以访问+- `admin` 可以登录-如果不希望 `deploy:setup` 创建资源,请执行:+## 手动创建资源```shcp .env.local.example .env.local@@ -60,40 +43,25 @@ EDGE_EVER_AUTH_PASSWORD=<强密码>EDGE_EVER_SESSION_TTL_DAYS=400```-然后执行:+然后运行:```shbun run deploy:doctorbun run deploy:manual```-`.env.local` 仅供本地 EdgeEver 脚本读取。不得上传、提交到 Git,或作为文件复制到 Cloudflare 构建环境。标准的 `bun run deploy` 专供 Cloudflare 一键部署的非交互入口使用;本地和 Agent 部署使用 `bun run deploy:manual`。--部署流水线会非交互执行远程 D1 migration、发布 Worker,并验证必需数据表和鉴权 Secret。迁移 SQL 会统一为 LF,Wrangler 始终通过其支持的 Node.js runtime 运行,确保 Windows、macOS 和 Linux 行为一致。--EdgeEver 采用安全关闭策略:生产实例未完成 D1 migration 或鉴权配置时会返回 `database_not_ready` 或 `auth_not_configured`,不会暴露免登录工作区。只有 `/api/health` 返回 `200` 和 `"ok": true`,且登录成功,实例才算可用。+不要提交 `.env.local`,也不要把密码写入 D1。## 故障恢复-- 数据库未就绪:确认 D1 binding 名称严格为 `DB`,然后运行 `bun run deploy:manual`。-- 鉴权未配置:在 `.env.local` 设置 `EDGE_EVER_AUTH_PASSWORD`,然后运行 `bun run deploy:manual`。-- 账号密码无效或丢失:不要向 `users.password_hash` 写入明文,请执行:+- 数据库未就绪:确认 D1 binding 为 `DB`,然后运行 `bun run deploy:manual`。+- 鉴权未配置:在 `.env.local` 设置 `EDGE_EVER_AUTH_PASSWORD`,然后重新部署。+- 忘记管理员密码:```sh- EDGE_EVER_PASSWORD='<至少 8 位的新密码>' \- bun run auth:reset-password -- --remote --username admin+ EDGE_EVER_PASSWORD='<新密码>' bun run auth:reset-password -- --remote --username admin```-D1 和 R2 的 binding 名称必须分别为 `DB` 和 `RESOURCES`。已有实例仍可使用 `EDGE_EVER_AUTH_PASSWORD_HASH`;两个密码 Secret 同时存在时优先使用 hash。--## 开启 Workers Builds 和自动更新--CLI 首次部署完成后,按照 [Cloudflare Workers Builds 自动部署](cloudflare-workers-builds.zh-CN.md) 执行:--```sh-bun run deploy:builds:setup-```--该命令会把 Worker 连接到仓库 `main` 分支,并安全复制后续 migration 和部署所需的构建变量。此后任何推送到 `main` 的提交都会使用同一套部署内核。+## 自动更新-仓库中的 **Update deployed EdgeEver** 工作流默认使用 `stable` 通道,每天检查上游正式 Release。设置 GitHub Repository Variable `EDGE_EVER_UPDATE_CHANNEL=edge` 后可改为跟随上游 `main`。GitHub 默认会禁用公共 Fork 中的定时工作流,因此通过 Fork 安装后需要打开 **Actions** 并启用该工作流。更新冲突或本地验证失败时不会修改已部署分支。+手动部署完成后,按 [Cloudflare Workers Builds](cloudflare-workers-builds.zh-CN.md) 配置自动部署,并在 Fork 的 **Actions** 中启用 **Update deployed EdgeEver**。diff --git a/docs/promotion/promotion_article_juejin.md b/docs/promotion/promotion_article_juejin.mdindex 3f9f030e..718248f8 100644--- a/docs/promotion/promotion_article_juejin.md+++ b/docs/promotion/promotion_article_juejin.md@@ -85,22 +85,25 @@ EdgeEver 内置了 **REST API**、**OpenAPI 协议** 以及 **Remote MCP (ModelEdgeEver 的部署简单到了极致,甚至你都不需要打开终端。-### 方式 A:AI Agent 一句话部署(推荐)+### 方式 A:Fork 后在线部署(推荐)-将下面这段话,复制给你的 AI 助手(如 Claude Code, Cursor, Antigravity 等):+先 Fork EdgeEver 上游仓库,然后在 Cloudflare Workers & Pages 中导入自己的 Fork,在线配置 D1、R2、Worker Secret 和构建命令。部署完成后,启用仓库中的上游更新工作流,后续版本会自动同步、验证并部署。++[Fork EdgeEver](https://github.com/tianma-if/edgeever/fork) 后,参考[在线部署文档](../deploy-cloudflare-button.zh-CN.md)完成配置。++### 方式 B:AI Agent 一句话部署++将下面这段话复制给你的 AI 助手(如 Claude Code、Cursor、Antigravity 等):```text-请按以下流程操作:-1. Fork EdgeEver 上游仓库:https://github.com/tianma-if/edgeever-2. 使用 Fork 后的仓库,将 EdgeEver 安装并部署到 Cloudflare。-3. 为 Fork 仓库配置从上游仓库同步更新的机制,使其能够定期或按需获取上游仓库的最新代码与产品特性。+请先 Fork https://github.com/tianma-if/edgeever,然后克隆这个 Fork。+严格按照 docs/agent-deploy-cloudflare.md 创建 Cloudflare 资源、完成首次部署,并配置 Workers Builds 和 Update deployed EdgeEver 工作流。+验证健康检查、首次构建和上游自动更新都成功后,再向我报告部署完成。```-AI 助手将自动帮你在 Cloudflare 上建好 D1、R2,配置好 Worker 路由并一键发布上线。--### 方式 B:手动部署(10 秒搞定)+AI 助手会代为在 Cloudflare 上创建 D1、R2,配置 Worker Secret,完成部署,并接通持续更新链路。-如果你喜欢自己动手,只需在本地拉下代码,运行几条简单的辅助命令:+高级恢复时才需要手动运行部署命令:```sh# 1. 复制环境变量diff --git a/tests/deployment-entrypoints.test.ts b/tests/deployment-entrypoints.test.tsindex 55218422..b9b6a668 100644--- a/tests/deployment-entrypoints.test.ts+++ b/tests/deployment-entrypoints.test.ts@@ -22,7 +22,7 @@ describe("Cloudflare deployment entrypoints", () => {expect(scripts["deploy:cloudflare-builds"]).toBe("bun run deploy:ci");});- test("one-click deployment declares the required authentication Secret", () => {+ test("online deployment declares the required authentication Secret", () => {const example = readRepositoryFile(".dev.vars.example");expect(example).toMatch(/^EDGE_EVER_AUTH_PASSWORD=\s*$/m);@@ -35,6 +35,8 @@ describe("Cloudflare deployment entrypoints", () => {expect(workflow).toContain("github.repository != 'tianma-if/edgeever'");expect(workflow).toContain("UPSTREAM_REPOSITORY: tianma-if/edgeever");+ expect(workflow).toContain("Require a GitHub Fork");+ expect(workflow).toContain(".fork");expect(workflow).toContain("EDGE_EVER_UPDATE_CHANNEL");expect(workflow).toContain("stable)");expect(workflow).toContain("edge)");@@ -45,4 +47,30 @@ describe("Cloudflare deployment entrypoints", () => {expect(workflow).toContain("--allow-unrelated-histories");expect(workflow).toContain("non_workflow_changes");});++ test("public deployment documentation exposes only Fork and Agent paths", () => {+ const englishReadme = readRepositoryFile("README.md");+ const chineseReadme = readRepositoryFile("README.zh-CN.md");++ expect(englishReadme).not.toContain("deploy.workers.cloudflare.com");+ expect(englishReadme).not.toContain("Option C: Manual Deployment");+ expect(englishReadme).toContain("Fork EdgeEver");+ expect(chineseReadme).not.toContain("deploy.workers.cloudflare.com");+ expect(chineseReadme).not.toContain("方案 C:手动部署");+ expect(chineseReadme).toContain("Fork EdgeEver");+ });++ test("AI Agent deployment remains fully online", () => {+ const englishAgentDoc = readRepositoryFile("docs/agent-deploy-cloudflare.md");+ const chineseAgentDoc = readRepositoryFile("docs/agent-deploy-cloudflare.zh-CN.md");++ expect(englishAgentDoc).toContain("Workers & Pages");+ expect(englishAgentDoc).toContain("Update deployed EdgeEver");+ expect(englishAgentDoc).not.toContain("bun run deploy:manual");+ expect(englishAgentDoc).not.toContain("deploy:setup");+ expect(englishAgentDoc).not.toContain(".env.local");+ expect(chineseAgentDoc).toContain("Workers & Pages");+ expect(chineseAgentDoc).not.toContain("bun run deploy:manual");+ expect(chineseAgentDoc).not.toContain("bun run deploy:manual");+ });});