Cloudflare Workers 部署

准备基础设施复制标题链接

使用支持当前工作负载的 Workers 付费计划与 PostgreSQL 16+（推荐 17/18）。可选择 Neon、Supabase 或其他可由 Hyperdrive 连接的托管 PostgreSQL；按连接限制、区域、TLS、PITR 与恢复能力选择，不依赖特定提供商扩展。将 Worker 放置区域与数据库区域对齐，并实际测试延迟。

1. 为每个环境建立数据库，分别创建迁移角色、应用角色和只读角色。迁移角色管理结构，应用角色仅获业务所需权限，只读角色不可读取密钥列。在安全终端设置密码，API 不使用数据库超级用户。
2. 创建 HYPERDRIVE 绑定，连接应用角色，并关闭查询缓存。迁移使用独立直连凭据。
3. 创建 FILES_PUBLIC 与 FILES_PRIVATE 两个 R2 桶。仅公开桶可以绑定文件域名；私有桶禁用匿名访问、r2.dev 与公开自定义域。
4. 绑定 SQLite 后端 StateShard Durable Object，保留 Wrangler 迁移声明。显式选择 do，设置数据库区域的位置提示和分片数。
5. 按需绑定 EMAIL 与 AI。Email Service 是否可用应在目标账户验证；也可在后台通知提供商列表配置受支持的 HTTP 服务。SMTP 仅限自托管。

完成应用配置复制标题链接

apps/api/wrangler.jsonc 中 ID、桶名、域名和环境块均需替换占位值。精确变量名见运行时参考，业务设置见设置域。使用 apps/api/.env（从 apps/api/.env.example 复制），变量包括 MASTER_KEYS、SITE_HOSTS 和 STATE；运行模式由 NODE_ENV 决定。

必须配置主站与 Origin 允许列表；订阅域名单独列出。独立后台域名需要对应路由与会话策略。主密钥环与 metrics 令牌摘要通过 Workers secrets 配置，绝不放进 vars。主密钥离线保存两份。

Cron 包含 * * * * *（普通队列）与 0 * * * *（重任务）。缺少 Cron 会使过期、续费、保留清理等任务积压。ASSETS 指向门户与后台合并产物；保留 run_worker_first 中 API、订阅与后台回退的规则。

安装数据库与初始化复制标题链接

通过安全环境注入迁移角色的 DATABASE_URL，连接必须直连数据库，不能走 Hyperdrive。首次空库执行：

bun run --cwd packages/db migrate install --seed
bun run --cwd packages/db migrate status

已有安装执行升级流程，不运行 install。部署后访问 /admin/install 创建首个 root、配置 TOTP、站点、业务时区和结算币种。首单后不能更改币种。

GitHub Actions 发布复制标题链接

.github/workflows/deploy.yml 只能手动触发：预发布（staging）可从 develop 或 main 分支部署；生产（production）只能从 main 部署，并由 GitHub Environment 审批保护。为两个 Environment 分别配置 CLOUDFLARE_API_TOKEN、CLOUDFLARE_ACCOUNT_ID、MIGRATOR_DATABASE_URL secrets 和 SITE_URL variable。

流水线顺序为：冻结锁文件安装 → 构建 SPAs 与静态安全响应头 → apps/api/scripts/release/preflight.ts → 迁移 dry-run → expand 迁移 → 上传 Worker version → 全量部署 → apps/api/scripts/release/smoke.ts → 发布记录。任何失败均阻断后续步骤；contract 迁移应单独计划。文档站另行发布，不将文档产物并入业务 Worker。

发布后验证复制标题链接

确认 /healthz、完成安装后的 /readyz、带授权的 /metrics、登录与后台 MFA、测试支付回调、节点注册/配置/用量、Cron 和双桶访问策略。验证 5xx 只暴露通用错误与 request id。预发布必须实际验证 Hyperdrive 事务行为、DO、Email 和节点网络连接，不能用本地模式替代。