部署 | SoarStarter

模板部署到 Cloudflare Workers。目标不是 Vercel、Docker 或长时间运行的 Node 服务器：Vite 构建 Worker bundle，Wrangler 通过 D1 与 R2 绑定发布它。

质量门禁

每次生产部署前运行模板检查：

pnpm check
pnpm test
pnpm build

check 运行 Biome lint 与格式诊断。
test 单次运行 Vitest 测试套件。
build 验证 Vite/TanStack Start 生产 bundle。

不要在检查失败或数据库迁移未审查时部署。

构建与部署流水线

pnpm deploy 等同于：

vite build && wrangler deploy

构建期间，@cloudflare/vite-plugin 会重新生成 dist/server/wrangler.json。生成的部署配置将 main 指向 index.js，assets 指向构建后的客户端目录，覆盖根 wrangler.jsonc 中面向源码的 main 和 assets 值。Wrangler 随后部署这份生成配置。

根配置还定义：

compatibility_date —— 固定 Worker 运行时行为，升级时应有意评审。
compatibility_flags: ["nodejs_compat"] —— Creem 签名代码等依赖 node:crypto 与 Buffer，因此需要该标志。
observability.enabled: true —— 启用 Worker 调用可观测性。

一次性 Cloudflare 设置

登录 Wrangler

pnpm wrangler login

CI 中应使用限制权限的 Cloudflare API token，而不是交互式登录。

创建 D1 与 R2 资源

pnpm wrangler d1 create soar-tanstack
pnpm wrangler r2 bucket create soar-tanstack-uploads

将返回的 D1 database_id 复制到 wrangler.jsonc。如果使用其他资源名，请同时更新配置与 db:migrate 包脚本。

检查绑定与 Worker 名称

wrangler.jsonc 应指向你的资源：

{
	"name": "your-worker-name",
	"d1_databases": [
		{
			"binding": "DB",
			"database_name": "soar-tanstack",
			"database_id": "your-d1-database-id",
			"migrations_dir": "drizzle"
		}
	],
	"r2_buckets": [
		{ "binding": "UPLOADS", "bucket_name": "soar-tanstack-uploads" }
	]
}

应用远程 D1 迁移

先备份已有数据库并审查 drizzle/，然后运行：

pnpm db:migrate

它会把已提交迁移应用到 soar-tanstack --remote，不会使用 drizzle-kit push。

配置生产值

在 wrangler.jsonc 的 vars 中设置 BETTER_AUTH_URL，然后为每个已启用服务交互式增加密钥：

pnpm wrangler secret put BETTER_AUTH_SECRET
pnpm wrangler secret put GITHUB_CLIENT_ID
pnpm wrangler secret put GITHUB_CLIENT_SECRET
pnpm wrangler secret put GOOGLE_CLIENT_ID
pnpm wrangler secret put GOOGLE_CLIENT_SECRET
pnpm wrangler secret put RESEND_API_KEY
pnpm wrangler secret put OPENAI_API_KEY
pnpm wrangler secret put REPLICATE_API_TOKEN
pnpm wrangler secret put CREEM_API_KEY
pnpm wrangler secret put CREEM_WEBHOOK_SECRET
pnpm wrangler secret put CREEM_SERVER_IDX

VITE_CREEM_PRODUCT_* 与 VITE_IS_DEMO 应设置在 CI/构建环境，而不是通过 wrangler secret put。

部署

pnpm deploy

记录部署版本与 URL，然后针对该 URL（而不是 localhost）执行下方冒烟测试。

应用的四个配置平面

平面	生产来源	示例
绑定	`wrangler.jsonc`	D1 `DB`、R2 `UPLOADS`
非敏感运行时变量	`wrangler.jsonc` → `vars`	`BETTER_AUTH_URL`
服务端密钥	`wrangler secret put`	Auth/OAuth、Resend、OpenAI、Replicate、Creem
构建时值	CI/构建环境	`VITE_CREEM_PRODUCT_*`、`VITE_IS_DEMO`

.env 与 .dev.vars 是本地文件，部署时绝不会上传。某值在本地工作，不代表它已配置到正确的生产平面。还要记住修改 VITE_* 后必须重新构建。

远程 Drizzle Kit HTTP 凭据形成第五个“仅工具”平面，运行中的 Worker 不需要它。详见环境变量。

自定义域名与规范 origin

模板使用 Wrangler 自定义域名路由：

"routes": [
	{ "pattern": "app.example.com", "custom_domain": true }
],
"vars": {
	"BETTER_AUTH_URL": "https://app.example.com"
}

该域名必须位于部署账户可访问的 Cloudflare zone 中。BETTER_AUTH_URL 必须与公开 origin 完全一致（协议、主机和任何非标准端口）。OAuth 回调与 Creem Webhook 也要更新到相同 origin。

上线前检查

生产冒烟测试

英文页面无前缀；/zh 页面正常，并在认证过程中保留语言环境。
注册、验证邮件、登录、重置、退出与受保护跳转正常。
真实/测试模式支付完成，签名 Webhook 只更新一次 D1。
Dashboard 与认证用户 API 拒绝未登录访问。
文档、博客和法律内容可渲染。
对话与每个已启用媒体生成器执行生产访问/用量策略。
登录后上传能写入 R2，Worker 能返回对象。
Worker 日志没有绑定、密钥、兼容性或未捕获运行时错误。

运维

按恢复目标定期导出 D1，并在依赖备份前实际测试恢复。
通过 pnpm wrangler tail 查看实时日志；除内置可观测性外，还应连接错误报告与告警。
监控 Worker 错误/延迟、D1 查询/容量、R2 用量、邮件投递、AI 成本与 Webhook 失败。
使用 wrangler secret put 轮换密钥，验证新值后撤销旧服务商凭据，并维护事故安全的轮换手册。
需要零停机发布时，以新旧 Worker 都兼容的顺序部署 schema 变更。

部署