部署指南

01MVP Starter Kit 是一个 pnpm workspace + Turborepo monorepo。

部署前检查清单

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

• 本地 pnpm build 构建成功，无 TypeScript 错误
• pnpm db:status 确认所有 migration 已提交到 Git
• .env.local 中所有必填变量已同步到生产环境
• BETTER_AUTH_URL 和 NEXT_PUBLIC_SITE_URL 指向生产域名（非 localhost）
• OAuth 回调 URL 已在第三方平台更新为生产域名
• 数据库连接串可从部署平台网络访问
• S3 存储桶权限已配置（公开读、私有写）
• AI API Key 余额充足
• 支付 Webhook 地址已配置为生产域名
• 邮件服务 API Key 已配置

Vercel 部署

Vercel 是 01MVP 的首选部署平台。以下是从零到上线的完整流程。

第一步：导入项目

apps/01mvp-web

pnpm --filter 01mvp-web build

Vercel 环境变量

在 Vercel Dashboard 中进入项目 Settings > Environment Variables 页面配置。

每个变量可以针对不同环境设置不同值：

环境变量完整清单

核心变量（必填）

S3 存储（必填）

AI 服务（必填）

OAuth 登录（按需）

支付（按需）

邮件（按需）

可选变量

Production vs Preview 环境差异

自定义域名

类型: CNAME
名称: www（或其他子域名）
值: cname.vercel-dns.com

类型: A
名称: @（根域名）
值: 76.76.21.21

BETTER_AUTH_URL=https://你的域名.com
NEXT_PUBLIC_SITE_URL=https://你的域名.com

Docker 部署

ZBPACK_APP_DIR=apps/01mvp-web
ZBPACK_DOCKERFILE_NAME=01mvp-web

docker build -f Dockerfile.01mvp-web -t 01mvp-web:latest \
  --build-arg DATABASE_URL="postgresql://..." \
  --build-arg BETTER_AUTH_SECRET="your-secret" \
  --build-arg BETTER_AUTH_URL="https://your-domain.com" \
  --build-arg NEXT_PUBLIC_SITE_URL="https://your-domain.com" \
  --build-arg S3_ENDPOINT="https://cos.ap-guangzhou.myqcloud.com" \
  --build-arg S3_REGION="ap-guangzhou" \
  --build-arg S3_ACCESS_KEY_ID="your-key" \
  --build-arg S3_SECRET_ACCESS_KEY="your-secret" \
  --build-arg S3_BUCKET="your-bucket" \
  --build-arg NEXT_PUBLIC_S3_ENDPOINT="https://your-bucket.cos.ap-guangzhou.myqcloud.com" \
  --build-arg OPENAI_API_KEY="your-key" \
  --build-arg OPENAI_BASE_URL="https://api.deepseek.com" \
  --build-arg OPENAI_MODEL="deepseek-v4-flash" \
  .

docker run -d \
  --name 01mvp-web \
  -p 7001:7001 \
  -e DATABASE_URL="postgresql://..." \
  -e BETTER_AUTH_SECRET="your-secret" \
  -e BETTER_AUTH_URL="https://your-domain.com" \
  -e NEXT_PUBLIC_SITE_URL="https://your-domain.com" \
  01mvp-web:latest

version: '3.8'
services:
  01mvp-web:
    build:
      context: .
      dockerfile: Dockerfile.01mvp-web
    ports:
      - "7001:7001"
    environment:
      - DATABASE_URL=postgresql://user:pass@db:5432/mvp
      - BETTER_AUTH_SECRET=your-secret
      - BETTER_AUTH_URL=https://your-domain.com
      - NEXT_PUBLIC_SITE_URL=https://your-domain.com
    restart: unless-stopped
    depends_on:
      - db

  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: user
      POSTGRES_PASSWORD: pass
      POSTGRES_DB: mvp
    volumes:
      - pgdata:/var/lib/postgresql/data

volumes:
  pgdata:

Cloudflare

目前可以用 Cloudflare 管理 DNS/CDN。直接部署到 Cloudflare Workers 需要走 @opennextjs/cloudflare 路径，并单独验证数据库、文档资产和运行时兼容性，暂不作为默认生产路径。

环境变量管理

多环境策略

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

最佳实践

1. 敏感变量只在部署平台设置：DATABASE_URL、BETTER_AUTH_SECRET、API Key 等永远不要出现在代码或 Git 中
2. 公开变量用 NEXT_PUBLIC_ 前缀：这些变量会被打包到客户端 bundle，不包含敏感信息
3. 生产环境使用独立数据库：不要让生产环境和开发环境共用同一个数据库
4. 定期轮换密钥：BETTER_AUTH_SECRET 泄露后需要重新生成并重新部署
5. Preview 环境隔离：Preview 部署应使用独立的测试数据库，避免污染生产数据

同步变量到 Vercel

可以使用 Vercel CLI 批量导入环境变量：

# 安装 Vercel CLI
npm i -g vercel

# 从 .env 文件导入到 Production 环境
vercel env pull .env.vercel.production --environment=production

# 手动添加单个变量
vercel env add DATABASE_URL production

也可以在 Vercel Dashboard 中直接从 .env 文件粘贴批量添加。

数据库迁移策略

迁移原则

迁移工作流

pnpm db:migrate

pnpm db:deploy

# 检查迁移状态
pnpm db:status

# 或使用 Prisma Studio 直接查看表结构
pnpm db:studio

迁移注意事项

• 永远先迁移，后部署应用。新代码可能依赖新表结构，反过来部署会直接报错
• 迁移脚本应该是幂等的。虽然 Prisma Migrate 会跟踪已应用的迁移，但确保迁移 SQL 本身可重复执行
• 大表迁移需要评估影响。ALTER TABLE 在大表上可能锁表，生产环境建议在低峰期执行
• 回滚方案：Prisma Migrate 没有内置回滚。重要迁移前先备份数据库，或手动编写回滚 SQL

接入已有数据库

如果数据库已有表结构，第一次纳入 Prisma Migrate 管理时：

# 1. 确认当前数据库状态
pnpm db:status

# 2. 创建初始迁移（不执行）
pnpm db:migrate --create-only --name init

# 3. 标记为已应用（不实际执行 SQL）
pnpm db:migrate --name init --skip-generate

或使用：

prisma migrate resolve --applied <migration_name>

部署后验证

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

常见部署问题

部署检查清单

以下是完整的部署检查清单：

Vercel 配置

• Root Directory 设为 apps/01mvp-web 或构建命令为 pnpm --filter 01mvp-web build
• Node.js 版本为 22.x
• Framework Preset 为 Next.js

环境变量

• DATABASE_URL 指向生产数据库
• BETTER_AUTH_SECRET 已设置（非默认值）
• BETTER_AUTH_URL 指向生产域名
• NEXT_PUBLIC_SITE_URL 指向生产域名
• S3 相关变量全部配置
• AI 相关变量全部配置
• 支付 Webhook 地址更新为生产域名
• OAuth 回调地址更新为生产域名

数据库

• migration 文件已提交到 Git
• pnpm db:deploy 已在生产数据库执行
• pnpm db:status 确认所有迁移已应用

域名

• 自定义域名已在 Vercel 添加
• DNS 记录已配置
• HTTPS 证书自动签发成功
• 域名和 NEXT_PUBLIC_SITE_URL 保持一致

验证

• 构建日志确认 Prisma Client 和 Next.js build 都已通过
• 部署后访问首页正常
• 登录注册流程正常
• 核心功能验证通过（参考"部署后验证"章节）