部署 | TanStack Start + Cloudflare

从根目录 .env 和资源命名开始，审查 plan、发布、验证、CI 与已有环境恢复。

部署前先确认边界

Flare 原生部署到 Workers，不使用 OpenNext 或 Next.js 的部署命令。apps/web/wrangler.jsonc 是本地开发配置；远程目标由 muse CLI 生成。不要直接拿本地 Wrangler 配置发布到生产。

在线演示：flare.musemvp.com。这是 MuseMVP 的实例，不是你的部署目标。下文的资源名称应替换为自己的产品名称，已有环境升级则必须保留原身份。

1. 准备账户与域名

使用 Node 22.12+、pnpm 10.26.2。Cloudflare Token 需有 Worker、D1、R2 与 Queues 的相关编辑权限；自定义域名还需对应 zone 权限。准备已验证发件域和 Email Sending，检查 Workers AI、Queues 等服务在自己账户可用。

复制根目录示例并填写自己的值：

cp .env.example .env

CLOUDFLARE_ACCOUNT_ID=your-account-id
CLOUDFLARE_API_TOKEN=your-deployment-token
APP_URL=https://app.your-domain.com
AUTH_SECRET=replace-with-a-random-secret-at-least-32-characters
MAIL_FROM=Your Product <[email protected]>
ADMIN_EMAIL=[email protected]

APP_URL 使用无路径的 HTTPS origin；不填可推导 workers.dev 地址。已有生产 AUTH_SECRET 应保留。ADMIN_EMAIL 不创建账号，账号注册并验证后才提升管理员。Token 不能写入应用 .dev.vars 或前端。

2. 确认五个资源名称

编辑 packages/cli/src/target-resources.ts 的 production 配置：

配置字段	当前演示资源	新产品示例
worker	flare-musemvp-com	your-product-web
database	flare-musemvp-com-d1	your-product-d1
bucket	flare-musemvp-com-r2	your-product-r2
queue	flare-musemvp-com-queue	your-product-queue
deadLetterQueue	flare-musemvp-com-dlq	your-product-dlq

名称使用小写字母开头、字母数字和连字符，长度 2 至 63，各类型在配置中使用不同名称。修改 product.slug 并不会覆盖显式生产资源名。

新产品应创建自己的资源。已有环境升级必须保留原账户、D1 和 R2 名称；随意改名可能生成空库或新 bucket，历史数据不会自动搬过去。preview 与 production 独立规划，不复用生产数据做本地测试。

3. 诊断与只读计划

pnpm muse:doctor --target production --json
pnpm muse:deploy --target production --plan --json

doctor 检查输入与能力，plan 查询远程清单和待执行迁移，不创建资源。审查 account、origin、资源动作、迁移、风险及阻断项。升级时出现意外 create，应先检查账户和名称。

CLI 不生成迁移、不自动旋转已有密钥。先在开发阶段执行 db:generate 并审查 SQL。待执行迁移中的高风险 DROP、TRUNCATE、DELETE、UPDATE SET 会阻断自动部署，需要独立审查、备份与处理。

4. 执行发布

pnpm muse:deploy --target production --yes --json

CLI 先执行 build、type-check、单元、规范和 Workers 检查，再创建或采用目标资源。随后构建目标配置，清除构建中复制的本地 .dev.vars，执行远程迁移，上传密钥并发布 Worker。

部署状态保存在 .muse/<target>.deployment.json，生成配置位于 apps/web/.muse/<target>.wrangler.json，均不提交。已有状态会检查账户一致性；不能通过手工篡改状态绕过账户错误。

执行失败先查看发生阶段。检查失败发生在资源创建前，不应凭“deploy 失败”就认定远程已产生资源；发布后 smoke 失败也不代表发布没有发生。

5. 核对公开 smoke 与人工验收

pnpm muse:verify --target production --json

当前公开探测包括 /api/health、/、/zh、/auth/login、/pricing。确认 HTTP 状态及 health 的 production 环境；自定义域首次发布可能需要等待 DNS 生效后再 verify。

退出码：0 表示命令或 smoke 成功，1 为操作失败，2 为阻断，3 为 smoke 失败。若脚本只接受 JSON stdout，使用 pnpm --silent 执行对应命令。

smokePassed 不等于人工 verified。必须另外完成：

自己的注册、验证码投递、密码恢复、OAuth / Turnstile。
R2 上传下载、权限隔离、API Key 撤销。
真实 Workers AI、任务队列、积分结算与失败补偿。
每个启用支付网关的测试购买、签名事件、取消及退款。

不需要支付时保持 billing.enabled 为空；不要为了部署通过填写虚构商品或密钥。

CI 与 Workers Builds

远程构建不会读取电脑上的 .env。在构建环境设置相同的加密变量，使用 Node 22 与仓库锁定的 pnpm。先 pnpm build，再由 muse CLI 发布；CLI 的部署前检查仍保留，不能改成原始 wrangler deploy 绕过计划和资源管理。

环境优先级为进程变量、根目录 .env、目标 secrets JSON 默认值。配置变更不生效时先检查是否被 CI 同名变量覆盖。

换电脑、升级与回滚

保留生产密钥、准确资源名、账户和部署记录；Git 拉取不会恢复这些忽略文件。CLI 可根据精确名称重新发现已有资源，但仍应先审查 plan。不要提交密钥来解决多人协作问题。

Worker 回滚不会回滚 D1 数据和迁移。发布前保持 schema 向后兼容，并为风险数据变更准备独立恢复方案。生产验收记录参考源码 docs/DEPLOYMENT-RUNBOOK.zh-CN.md，但每次发布都要记录自己的提交和结果。

出现阻断时阅读排障指南，不要通过删除检查或资源来获得绿色状态。

部署

本页目录