vmail/docs/ai-deploy.md

1. 目标与部署产物

本文档用于让 AI 助手直接读取并执行部署Github项目：https://github.com/oiov/vmail 。目标是将 vmail 部署到 Cloudflare Workers + D1，并启用以下能力：

• 站点统计增长率（today vs yesterday）
• Turnstile 可选（未配置密钥时自动 bypass）
• 站点密码访问控制（PASSWORD 可选）
• API Key 每分钟限速（环境变量可配置，默认 100）

部署后关键接口合同：

• GET /config 返回：turnstileEnabled、sitePasswordEnabled、apiRateLimitPerMinute、openApiEnabled
• GET /api/stats 返回：totals、today、yesterday
• POST /auth/unlock、GET /auth/status、POST /auth/logout

2. 前置条件与账号准备

在开始前确认：

• 已安装 Node.js 18+ 与 pnpm
• 已安装 Wrangler CLI（npx wrangler --version 可运行）
• 已登录 Cloudflare（npx wrangler login）
• 已在 Cloudflare 创建 D1 数据库并拿到：
  • D1_DATABASE_NAME
  • D1_DATABASE_ID
• 准备好站点域名配置 EMAIL_DOMAIN（支持逗号分隔多域名）

推荐在仓库根目录执行全部命令。

3. 必填与可选环境变量

需要在部署环境中提供以下变量（与 wrangler.toml 对齐）：

• EMAIL_DOMAIN（必填）
• COOKIES_SECRET（必填，建议高强度随机字符串）
• TURNSTILE_KEY（可选）
• TURNSTILE_SECRET（可选）
• PASSWORD（可选；为空时站点默认公开）
• API_RATE_LIMIT_PER_MINUTE（可选；非法值或缺省回退到 100）
• ENABLE_OPENAPI（可选；默认开启，设置为 false 时禁用 API Key 创建与 /api/v1/*）

行为说明：

• 当 TURNSTILE_KEY 和 TURNSTILE_SECRET 任一缺失时，前后端都进入“无需人机验证”模式。
• 当 PASSWORD 为空时，前端不会出现站点解锁门禁；有值时需要先解锁站点。
• API_RATE_LIMIT_PER_MINUTE 作用于 v1 API Key 中间件，按“每个 API Key、每分钟固定窗口”限流。
• 当 ENABLE_OPENAPI=false 时，/api/api-keys 与 /api/v1/* 会统一返回 403 OPENAPI_DISABLED，/api-docs 页面仅展示提示。

4. 数据库迁移与基础初始化

项目 D1 迁移目录为：worker/drizzle。

建议顺序：

1. 确保 wrangler.toml 的 D1 绑定配置正确。
2. 执行迁移到远端 D1（根据你的 Cloudflare 环境选择对应命令）。
3. 确认新增表存在：
   • daily_stats
   • api_rate_limits

api_rate_limits 采用复合主键：

• api_key_id
• window_start_epoch_sec

该设计用于支持原子 UPSERT 计数，避免并发下限流计数漂移。

5. 构建与部署步骤

按以下顺序执行：

1. 安装依赖：pnpm install
2. 本地构建：pnpm build
3. 部署 Worker（按你的环境执行 wrangler deploy）
4. 如有自定义域名或路由，完成 Cloudflare 路由绑定

构建成功标准：

• frontend 构建完成
• worker 打包无阻断错误
• 允许存在体积告警（chunk size warning）但不应有构建失败

6. 部署后验收清单（可直接给 AI 执行）

最小验收用例：

1. 配置合同：
   • 请求 GET /config
   • 断言返回字段包含：
     • turnstileEnabled
     • sitePasswordEnabled
     • apiRateLimitPerMinute
     • openApiEnabled
2. 统计合同：
   • 请求 GET /api/stats
   • 断言返回结构含 totals/today/yesterday
3. 站点密码：
   • PASSWORD 为空时：页面可直接访问
   • PASSWORD 有值时：
     • 未解锁访问页面受限
     • POST /auth/unlock 成功后可访问
     • GET /auth/status 返回 unlocked: true
4. Turnstile 可选：
   • 未配置密钥时，创建邮箱地址流程可直接通过
   • 配置密钥后，需有效 token
5. API 限速：
   • 使用同一 API Key 连续请求 v1 API
   • 超过阈值返回 429
   • 响应头包含：X-RateLimit-Limit、X-RateLimit-Remaining、Retry-After
   • 若 ENABLE_OPENAPI=false：/api/api-keys 与 /api/v1/* 返回 403
6. 前端展示：
   • 首页 SiteStats 卡片显示增长率（today vs yesterday）
   • /api-docs 在 openApiEnabled=false 时展示禁用提示

7. 常见问题与回滚策略

常见问题：

• 迁移失败：优先检查 D1 绑定、数据库 ID、迁移目录是否正确。
• 站点一直锁定：检查 PASSWORD 是否设置、浏览器是否保存了解锁 cookie。
• 限速不生效：确认请求走的是 v1 API，并携带 API Key。
• Turnstile 状态异常：确认前后端读取的是同一组环境变量。

回滚策略：

1. 先回滚 Worker 版本（代码回滚）。
2. 若需要回滚数据结构，按 D1 迁移策略执行逆向迁移或恢复备份。
3. 回滚后重复执行“部署后验收清单”中的 1~3 项，确保服务可用。