部署指南

项目是 Vite Plus + pnpm workspace monorepo，应用在 products/01mvp/apps/web 下。

默认生产路径是 Zeabur + Cloudflare。Zeabur 运行 TanStack Start Docker 服务，Cloudflare 负责域名代理、HTTPS、WAF 和基础访问统计。

部署方式选择

方式	适合场景	入口
Zeabur	默认生产部署，适合 TanStack Start Docker 服务、数据库和域名统一管理	Zeabur 部署
Docker	自有 VPS、K8s，或需要手动维护容器运行时	Docker 部署
Cloudflare Workers	明确要把 TanStack Start 适配到 Workers，并愿意处理兼容性验证	Cloudflare Workers 部署

Vercel 不在推荐列表中，因为免费套餐的并发和额度极低，付费方案性价比偏低。Zeabur + Cloudflare 是成本更低、更可控的替代方案。

Zeabur 部署

01MVP 默认部署路径，包含 Agent Skills 部署流程、环境变量、Docker、数据库和 Cloudflare 代理。

上线统计

用 Cloudflare Web Analytics 看真实访问、来源、热门页面和用户侧性能。

Zeabur Agent Skills

Zeabur Agent Skills 能力参考：安装、能力清单、常见场景和排错。

Docker 部署

用 Dockerfile 部署到自有服务器或容器平台。

Cloudflare Workers 部署

基于 TanStack Start 和 Cloudflare Vite 插件的可选部署路径，适合明确需要 Workers 运行时的项目。

部署前检查清单

在触发任何部署之前，逐项确认以下内容：

环境变量管理

多环境策略

01MVP 项目使用以下环境文件管理本地开发变量：

文件	用途	是否提交到 Git
`products/01mvp/packages/config/.env.example`	01MVP 产品变量模板	是
`products/01mvp/packages/config/.env`	01MVP 本地开发变量，包含真实密钥	否
`packages/config/.env.example`	共享变量模板，列出跨产品通用变量	是
`packages/config/.env`	多产品共享的本地兜底值	否
部署平台 Variables / Secrets	生产、预发等环境真实值	平台托管

必填变量

变量名	说明	示例
`DATABASE_URL`	PostgreSQL 连接串	`postgresql://user:pass@host:5432/prod`
`BETTER_AUTH_SECRET`	Auth 签名密钥	随机生成的强密钥
`VITE_WEB_URL`	站点公开 URL	`https://your-domain.com`
`VITE_SERVER_URL`	API 公开 URL	`https://your-domain.com/api`
`OPENAI_API_KEY`	AI API 密钥	`sk-...`

按需变量

类型	变量
Drop / R2 存储	`DROP_R2_BUCKET_NAME`、`DROP_R2_ENDPOINT`、`DROP_R2_ACCESS_KEY_ID`、`DROP_R2_SECRET_ACCESS_KEY`、`PAGES_BASE_URL`
OAuth 登录	`GOOGLE_CLIENT_ID`、`GOOGLE_CLIENT_SECRET`、`GITHUB_CLIENT_ID`、`GITHUB_CLIENT_SECRET`；微信登录还需 `AUTH_ENABLE_WECHAT=true` 和微信凭据
支付	`STRIPE_SECRET_KEY`、`STRIPE_WEBHOOK_SECRET`、`ZPAY_PID`、`ZPAY_KEY`
邮件	`ZEABUR_EMAIL_API_KEY`、`EMAIL_FROM`、`FEEDBACK_EMAIL_TO`
安全	`AUTH_COOKIE_PREFIX`、`COOKIE_DOMAIN`、`TRUSTED_ORIGINS`、`ENABLE_OPEN_API_DOCS`

敏感变量只在部署平台设置，不要提交到 Git。VITE_ 前缀变量会进入客户端 bundle，只放公开信息。

数据库迁移策略

迁移原则

生产数据库变更必须使用 migration。不要在生产环境运行 db:push，也不要用 Drizzle Studio 手动改表结构。

迁移工作流

开发阶段创建迁移

修改 products/01mvp/packages/db/src/schema 后，创建迁移文件：

vpr @01mvp/product#db:generate

这会在 products/01mvp/packages/db/migrations 下生成 SQL 文件。

提交迁移文件

将生成的 migration 文件提交到 Git，例如 products/01mvp/packages/db/migrations/20260521184410_mighty_epoch/migration.sql。

执行生产迁移

部署新代码前，执行已经提交到 Git 的迁移文件：

vpr @01mvp/product#db:deploy

部署并验证

迁移通过后再部署生产代码。部署完成后检查健康检查、登录、支付、后台等关键路径。

生产环境怎么执行迁移

当前模板默认使用显式迁移：先运行 vpr @01mvp/product#db:deploy，再部署生产代码。关键点是：生产 DATABASE_URL 必须正确，migration 文件必须已经提交到 Git，迁移命令必须先通过。

如果你需要保留运行时兜底迁移，可以设置 RUN_STARTUP_MIGRATIONS=true。这只是兼容兜底，不建议作为主要发布流程。

如果需要在上线前从本机验证生产连接，只输出主机名，不要输出完整密码：

node -e 'const u=new URL(process.env.DATABASE_URL); console.log(u.host, u.pathname)'

迁移注意事项

migration 文件必须随应用代码一起提交。新代码可能依赖新表结构
生产部署前先执行 vpr @01mvp/product#db:deploy
迁移文件只执行一次。Drizzle 会通过迁移记录表跟踪已应用迁移
大表迁移需要评估影响。ALTER TABLE 在大表上可能锁表，生产环境建议在低峰期执行
破坏性变更拆成两次发布。先加新字段或新表并兼容旧代码，部署稳定后再删除旧字段
回滚方案需要提前准备。重要迁移前先备份数据库或准备回滚 SQL

部署后验证

部署完成后，逐项验证以下功能：

常见部署问题

完整检查清单

构建

vpr @01mvp/product#build 通过
Node.js 版本符合 24.x
Drizzle migration 已提交并执行

环境变量

DATABASE_URL 指向生产数据库
BETTER_AUTH_SECRET 已设置为强密钥
VITE_WEB_URL 指向生产域名
VITE_SERVER_URL 指向生产 API
AI、Drop/R2、支付、邮件等按需变量已配置

数据库

migration 文件已提交到 Git
migration 文件已提交
生产启动日志没有 migration 失败

域名和安全

自定义域名已绑定到部署平台
DNS 记录已配置
HTTPS 证书签发成功
边缘 WAF/DDoS 规则已配置
Web Analytics 能看到生产域名访问数据

验证

部署后访问首页正常
登录注册流程正常
核心功能验证通过
支付、邮件、上传等按需功能验证通过