From 4672481369ee9231030807dfd723040ca709ec3b Mon Sep 17 00:00:00 2001 From: yoma Date: Sat, 11 Jul 2026 11:15:35 +0800 Subject: [PATCH] Clarify manual Cloudflare deployment --- README.md | 4 +- README.zh-CN.md | 4 +- docs/agent-deploy-cloudflare.md | 3 +- docs/manual-deploy.en-US.md | 76 ----------------------------- docs/manual-deploy.md | 77 ++++++++++++++++------------- docs/manual-deploy.zh-CN.md | 85 +++++++++++++++++++++++++++++++++ 6 files changed, 136 insertions(+), 113 deletions(-) delete mode 100644 docs/manual-deploy.en-US.md create mode 100644 docs/manual-deploy.zh-CN.md diff --git a/README.md b/README.md index 06b754ad..b3dab97b 100644 --- a/README.md +++ b/README.md @@ -41,7 +41,9 @@ Agents should follow [AI Agent Cloudflare Deployment](docs/agent-deploy-cloudfla ### Manual Deployment -Please refer to the [Cloudflare Manual Deployment Guide](docs/manual-deploy.en-US.md) for step-by-step instructions on manual installation and updating. +Please refer to the [Cloudflare Manual Deployment Guide](docs/manual-deploy.md) for step-by-step instructions on manual installation and updating. + +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`. ## Features diff --git a/README.zh-CN.md b/README.zh-CN.md index c02d7dd3..cfd24020 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -43,7 +43,9 @@ Agent 应优先按 [AI Agent Cloudflare Deployment](docs/agent-deploy-cloudflare ### 手动部署 -关于手动安装和更新的详细步骤，请参考 [Cloudflare 手动部署指南](docs/manual-deploy.md)。 +关于手动安装和更新的详细步骤，请参考 [Cloudflare 手动部署指南](docs/manual-deploy.zh-CN.md)。 + +推荐优先使用自动化辅助命令。如果选择完全手动创建 Cloudflare 资源，必须先在 `.env.local` 中完成 D1 ID、R2 bucket、密码 hash 和 400 天会话期限等配置，再执行 `bun run deploy`。 ## 功能 diff --git a/docs/agent-deploy-cloudflare.md b/docs/agent-deploy-cloudflare.md index 99be3c96..143ffd5f 100644 --- a/docs/agent-deploy-cloudflare.md +++ b/docs/agent-deploy-cloudflare.md @@ -86,7 +86,7 @@ Chinese version: bun run deploy ``` - `bun run deploy` builds the web app, applies remote D1 migrations, and deploys the Worker. During deploy, `scripts/run-wrangler.mjs` uploads `EDGE_EVER_AUTH_PASSWORD_HASH` as a Worker secret via a generated `.env.wrangler.generated*.secrets` file. + `bun run deploy` builds the web app, applies remote D1 migrations, and deploys the Worker. During deploy, `scripts/run-wrangler.mjs` uploads `EDGE_EVER_AUTH_PASSWORD_HASH` as a Worker Secret via a generated `.env.wrangler.generated*.secrets` file, then synchronizes it again with `wrangler secret put` after a successful deployment so the first login does not depend on the bulk secrets upload alone. 7. Verify the result. @@ -109,6 +109,7 @@ EDGE_EVER_D1_DATABASE_NAME=edgeever EDGE_EVER_R2_BUCKET_NAME=edgeever-resources EDGE_EVER_R2_PREVIEW_BUCKET_NAME=edgeever-resources-preview EDGE_EVER_AUTH_USERNAME=admin +EDGE_EVER_SESSION_TTL_DAYS=400 EDGE_EVER_CUSTOM_DOMAIN=notes.example.com ``` diff --git a/docs/manual-deploy.en-US.md b/docs/manual-deploy.en-US.md deleted file mode 100644 index 6c74ada7..00000000 --- a/docs/manual-deploy.en-US.md +++ /dev/null @@ -1,76 +0,0 @@ -# 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. - -> 💡 **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](agent-deploy-cloudflare.md) runbook. - -## Deployment Steps - -1. **Fork the official repository**: - Visit and fork the official repository: [https://github.com/tianma-if/edgeever](https://github.com/tianma-if/edgeever) - -2. **Clone your fork**: - ```sh - git clone - cd edgeever - ``` - -3. **Deploy with the automated helper commands**: - ```sh - # Copy the configuration template - cp .env.local.example .env.local - - # Install dependencies - bun install - - # Initialize deployment resources and set the first login password - EDGE_EVER_PASSWORD='' bun run deploy:setup - - # Check the deployment environment and configurations - bun run deploy:doctor - - # Deploy to Cloudflare - bun run deploy - ``` - -### Creating Cloudflare Resources Manually - -If you prefer not to use the automated `deploy:setup` helper, you can create the resources manually using Cloudflare CLI (Wrangler): - -```sh -# Copy configuration template and install dependencies -cp .env.local.example .env.local -bun install - -# Create the D1 database -bunx wrangler d1 create edgeever - -# Create the R2 bucket -bunx wrangler r2 bucket create edgeever-resources - -# Generate the password hash -bun run auth:hash -- - -# Deploy -bun run deploy -``` - -After creation, copy the D1 `database_id` and the generated password hash into your local `.env.local` file. - ---- - -## Updating to the Latest Version - -When a new version is released, you can sync your fork and redeploy to apply updates: - -1. Open your EdgeEver fork on GitHub. -2. Click **Sync fork** to pull the latest official code into your fork. -3. Pull the updates locally and redeploy: - ```sh - git pull - bun install - bun run deploy:doctor - bun run deploy - ``` - -> ⚠️ **Important**: Syncing the fork on GitHub only updates your repository code. It does not redeploy your Cloudflare instance. You must redeploy locally (or via an Agent) for the updates to take effect. diff --git a/docs/manual-deploy.md b/docs/manual-deploy.md index b2c7e135..2d57a137 100644 --- a/docs/manual-deploy.md +++ b/docs/manual-deploy.md @@ -1,71 +1,80 @@ -# Cloudflare 手动部署指南 +# Cloudflare Manual Deployment Guide -如果你熟悉 Cloudflare 和命令行，或者想自定义/精细控制部署流程，可以按照以下指南进行手动部署与后续更新。 +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. -> 💡 **提示**：如果是通过 AI 助手（Claude Code、Codex、Antigravity、Cursor、Trae 等）进行部署，AI 助手应优先参考 [AI Agent Cloudflare Deployment](agent-deploy-cloudflare.md) 约定。 +> 💡 **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](agent-deploy-cloudflare.md) runbook. -## 部署步骤 +## Deployment Steps -1. **Fork 官方仓库**： - 访问并 Fork 官方仓库：[https://github.com/tianma-if/edgeever](https://github.com/tianma-if/edgeever) +1. **Fork the official repository**: + Visit and fork the official repository: [https://github.com/tianma-if/edgeever](https://github.com/tianma-if/edgeever) -2. **Clone 你的 Fork 仓库**： +2. **Clone your fork**: ```sh - git clone <你的 Fork 仓库 URL> + git clone cd edgeever ``` -3. **使用自动化辅助命令部署**： +3. **Deploy with the automated helper commands**: ```sh - # 复制配置文件模板 + # Copy the configuration template cp .env.local.example .env.local - - # 安装依赖 + + # Install dependencies bun install - - # 执行部署初始化，并设置首次登录密码 - EDGE_EVER_PASSWORD='<你的密码>' bun run deploy:setup - - # 诊断部署环境与配置 + + # Initialize deployment resources and set the first login password + EDGE_EVER_PASSWORD='' bun run deploy:setup + + # Check the deployment environment and configurations bun run deploy:doctor - - # 执行部署 + + # Deploy to Cloudflare bun run deploy ``` -### 完全手动创建 Cloudflare 资源 +### Creating Cloudflare Resources Manually -如果你不想使用 `deploy:setup` 自动化脚本，也可以完全手动使用 Cloudflare CLI (Wrangler) 创建资源： +If you prefer not to use the automated `deploy:setup` helper, you can create the resources manually using Cloudflare CLI (Wrangler): ```sh -# 复制配置文件模板并安装依赖 +# Copy configuration template and install dependencies cp .env.local.example .env.local bun install -# 手动创建 D1 数据库 +# Create the D1 database bunx wrangler d1 create edgeever -# 手动创建 R2 存储桶 +# Create the R2 bucket bunx wrangler r2 bucket create edgeever-resources -# 生成密码 hash（用于后台验证） -bun run auth:hash -- <你的密码> +# Generate the password hash +bun run auth:hash -- -# 执行部署 +# Edit .env.local and fill in at least the generated resource and password values +# EDGE_EVER_D1_DATABASE_ID= +# EDGE_EVER_R2_BUCKET_NAME=edgeever-resources +# EDGE_EVER_AUTH_PASSWORD_HASH= +# EDGE_EVER_SESSION_TTL_DAYS=400 + +# Validate the completed configuration before deploying +bun run deploy:doctor bun run deploy ``` -部署完成后，将 D1 创建命令返回的 `database_id` 以及生成的密码 hash 手动填入本机 `.env.local` 文件中。 +Before running `bun run deploy`, copy the D1 `database_id`, R2 bucket name, and generated password hash into your local `.env.local` file. Keep the session lifetime at the template default of `400` days; the server also caps larger values at 400 days. + +`bun run deploy` builds the web app, applies remote D1 migrations, deploys the Worker, and uploads `EDGE_EVER_AUTH_PASSWORD_HASH` as a Worker Secret. After a successful deployment, the script also synchronizes that Secret through `wrangler secret put` to ensure the first login works. Verify the deployment by signing in with `EDGE_EVER_AUTH_USERNAME` and the original password used to generate the hash. --- -## 更新到最新版 +## Updating to the Latest Version -当官方仓库发布新版本时，如果你的实例是通过 Fork 部署的，可以按照以下步骤拉取最新代码并更新： +When a new version is released, you can sync your fork and redeploy to apply updates: -1. 打开你自己的 EdgeEver Fork 仓库页面。 -2. 点击页面上的 **Sync fork**，将官方仓库的最新代码同步到你的 Fork。 -3. 在本地项目目录中拉取更新并重新部署： +1. Open your EdgeEver fork on GitHub. +2. Click **Sync fork** to pull the latest official code into your fork. +3. Pull the updates locally and redeploy: ```sh git pull bun install @@ -73,4 +82,4 @@ bun run deploy bun run deploy ``` -> ⚠️ **注意**：同步 Fork 仅仅更新了你 GitHub 仓库里的代码，并不会自动更新已经部署在 Cloudflare 的 Worker/Pages 实例。必须在本地（或通过 Agent）重新执行部署命令，更新才会生效。 +> ⚠️ **Important**: Syncing the fork on GitHub only updates your repository code. It does not redeploy your Cloudflare instance. You must redeploy locally (or via an Agent) for the updates to take effect. diff --git a/docs/manual-deploy.zh-CN.md b/docs/manual-deploy.zh-CN.md new file mode 100644 index 00000000..9e78b0dd --- /dev/null +++ b/docs/manual-deploy.zh-CN.md @@ -0,0 +1,85 @@ +# Cloudflare 手动部署指南 + +如果你熟悉 Cloudflare 和命令行，或者想自定义/精细控制部署流程，可以按照以下指南进行手动部署与后续更新。 + +> 💡 **提示**：如果是通过 AI 助手（Claude Code、Codex、Antigravity、Cursor、Trae 等）进行部署，AI 助手应优先参考 [AI Agent Cloudflare Deployment](agent-deploy-cloudflare.md) 约定。 + +## 部署步骤 + +1. **Fork 官方仓库**： + 访问并 Fork 官方仓库：[https://github.com/tianma-if/edgeever](https://github.com/tianma-if/edgeever) + +2. **Clone 你的 Fork 仓库**： + ```sh + git clone <你的 Fork 仓库 URL> + cd edgeever + ``` + +3. **使用自动化辅助命令部署**： + ```sh + # 复制配置文件模板 + cp .env.local.example .env.local + + # 安装依赖 + bun install + + # 执行部署初始化，并设置首次登录密码 + EDGE_EVER_PASSWORD='<你的密码>' bun run deploy:setup + + # 诊断部署环境与配置 + bun run deploy:doctor + + # 执行部署 + bun run deploy + ``` + +### 完全手动创建 Cloudflare 资源 + +如果你不想使用 `deploy:setup` 自动化脚本，也可以完全手动使用 Cloudflare CLI (Wrangler) 创建资源： + +```sh +# 复制配置文件模板并安装依赖 +cp .env.local.example .env.local +bun install + +# 手动创建 D1 数据库 +bunx wrangler d1 create edgeever + +# 手动创建 R2 存储桶 +bunx wrangler r2 bucket create edgeever-resources + +# 生成密码 hash（用于后台验证） +bun run auth:hash -- <你的密码> + +# 编辑 .env.local，至少填入刚创建的资源和密码配置 +# EDGE_EVER_D1_DATABASE_ID= +# EDGE_EVER_R2_BUCKET_NAME=edgeever-resources +# EDGE_EVER_AUTH_PASSWORD_HASH=<上一步生成的 hash> +# EDGE_EVER_SESSION_TTL_DAYS=400 + +# 确认配置完整后再部署 +bun run deploy:doctor +bun run deploy +``` + +必须在执行 `bun run deploy` **之前**，将 D1 创建命令返回的 `database_id`、R2 bucket 名称和生成的密码 hash 写入本机 `.env.local`。会话有效期建议保留模板中的 `400` 天；服务端也会把更大的值限制为 400 天。 + +`bun run deploy` 会构建 Web 应用、执行远程 D1 migration、部署 Worker，并将 `EDGE_EVER_AUTH_PASSWORD_HASH` 作为 Worker Secret 上传。部署脚本还会在成功后通过 `wrangler secret put` 再同步一次该 Secret，确保首次登录可用。部署完成后，请使用 `.env.local` 中的 `EDGE_EVER_AUTH_USERNAME` 和生成 hash 时使用的原始密码登录验证。 + +--- + +## 更新到最新版 + +当官方仓库发布新版本时，如果你的实例是通过 Fork 部署的，可以按照以下步骤拉取最新代码并更新： + +1. 打开你自己的 EdgeEver Fork 仓库页面。 +2. 点击页面上的 **Sync fork**，将官方仓库的最新代码同步到你的 Fork。 +3. 在本地项目目录中拉取更新并重新部署： + ```sh + git pull + bun install + bun run deploy:doctor + bun run deploy + ``` + +> ⚠️ **注意**：同步 Fork 仅仅更新了你 GitHub 仓库里的代码，并不会自动更新已经部署在 Cloudflare 的 Worker/Pages 实例。必须在本地（或通过 Agent）重新执行部署命令，更新才会生效。