---
url: /docs/deployment/cloudflare.md
---
# 部署边缘服务

## 配置文件

三个服务分别使用 `apps/api/wrangler.jsonc`、`apps/app/wrangler.jsonc` 和 `apps/web/wrangler.jsonc`。生产配置位于文件顶层，预发布在 `env.staging`；Wrangler 的生产选择器是空环境名，根部署脚本已负责转换。

复制新站时修改 Worker 名称和服务绑定，不能把新站入口绑定到旧站的账号接口。`APP_ORIGIN`、公开域名、资源 ID 和发信地址都需要替换占位值。

## 设置秘密

以下是交互写入示例，不把值写入命令历史：

```sh
bun wrangler secret put BETTER_AUTH_SECRET --config apps/api/wrangler.jsonc --env staging
bun wrangler secret put RESEND_API_KEY --config apps/api/wrangler.jsonc --env staging
```

生产选择 `--env=""`。按需配置完整 Google、GitHub 或 Stripe 凭据组；只配置正在使用的集成。两项基础秘密属于必需项，开发捕获邮件模式的临时值不能用于生产。

## 资源绑定

接口绑定 `HYPERDRIVE_CACHED` 和 `HYPERDRIVE_UNCACHED`；公开站绑定 `API_SERVICE` 与 `APP_SERVICE`；公开站和工作台各有静态资源绑定。生产 ID 必须是该环境真实资源，而不是本地占位名称。

创建基础设施与部署应用分开管理。Terraform 可创建 Hyperdrive 等依赖；Wrangler 部署 Worker 代码及绑定，见 [基础设施边界](../adr/002-terraform-wrangler-boundary.md)。

## 构建与发布

```sh
bun build
# 确认配置与迁移后执行
bun deploy:staging
```

脚本检查邮件、公开站和工作台构建目录，再依次部署接口、工作台和公开入口。不要使用缺失或旧构建产物。单个服务命令仅适合明确范围的维护，完整发布优先用统一脚本。

## 排查

绑定失败检查目标服务名称和环境；数据库失败检查两个 Hyperdrive；邮件 403 检查发信域，`onboarding@resend.dev` 不是面向用户的正式发信地址；注册失败还要检查非开发环境的验证邮件流程。

部署完成后实际检查线上会话、日志与请求标识，不能以 Wrangler 上传成功认定产品流程通过。