Bunship部署说明
面向 TurboRepo 的可复制部署手册（Vercel / Cloudflare）。
部署模型
Bunship 是 TurboRepo monorepo。线上只部署一个站点（apps/ship），同时承载：
- 营销页
- 业务页
- 管理后台
- 文档路由与文档搜索接口
/api/v1/*API 路由
无需单独部署 docs 项目。
1. 前置环境变量（先复制）
先生成密钥：
openssl rand -base64 32生产环境最小可用变量（可直接粘贴再替换）：
# 认证与站点地址
BETTER_AUTH_SECRET="replace-with-long-random-secret"
AUTH_SECRET="replace-with-long-random-secret"
BETTER_AUTH_URL="https://你的域名"
NEXT_PUBLIC_SITE_URL="https://你的域名"
NEXT_PUBLIC_SERVER_URL="https://你的域名"
NEXT_PUBLIC_API_PREFIX="/api/v1"
ADMIN_EMAIL_LIST="admin@你的域名"
EMAIL_FROM="Bunship <noreply@你的域名>"
# OAuth
OAUTH_GITHUB_CLIENT_ID="xxx"
OAUTH_GITHUB_CLIENT_SECRET="xxx"
OAUTH_GOOGLE_CLIENT_ID="xxx"
OAUTH_GOOGLE_CLIENT_SECRET="xxx"
NEXT_PUBLIC_OAUTH_GOOGLE_CLIENT_ID="xxx"
# 数据库与邮件
DATABASE_URL="postgresql://..."
RESEND_API_KEY="re_xxx"
# Stripe
STRIPE_SECRET_KEY="sk_live_xxx"
STRIPE_WEBHOOK_SECRET="whsec_xxx"
# 存储（S3 / R2）
S3_ENDPOINT="https://<account>.r2.cloudflarestorage.com"
S3_REGION="auto"
S3_ACCESS_KEY="xxx"
S3_SECRET_KEY="xxx"
S3_BUCKET="your-bucket"
NEXT_PUBLIC_S3_URL_BASE="https://cdn.你的域名"
# 当前模板校验还会要求
S_GITHUB_PERSONAL_ACCESS_TOKEN="ghp_xxx"
CLOUDFLARE_ACCOUNT_ID="xxx"若使用 Better Auth，请设置 AUTH_SECRET 与 BETTER_AUTH_SECRET（可复用同一个强随机值）。若使用 Clerk，请配置 NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY、CLERK_SECRET_KEY 和 CLERK_WEBHOOK_SECRET。
相关配置文档：
- Better Auth: https://www.better-auth.com/docs/introduction
- Clerk: https://clerk.com/docs
- GitHub OAuth App: https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/creating-an-oauth-app
- Google OAuth: https://developers.google.com/identity/protocols/oauth2
- Stripe Key/Webhook: https://docs.stripe.com/keys、https://docs.stripe.com/webhooks
- Resend: https://resend.com/docs
- 仓库完整变量清单：/zh/docs/operations/env-config
2. Vercel 部署（TurboRepo）
由于这是 TurboRepo，有两种可用配置。
方案 A（推荐）：Turbo Root 模式
把 Vercel 的 Root Directory 设为仓库根目录。
| Vercel 配置项 | 值 |
|---|---|
| Framework Preset | Next.js |
| Root Directory | .（仓库根目录） |
| Install Command | bun install |
| Build Command | bunx turbo run build --filter=@bunship-ai/ship... |
| Output Directory | 留空（Next.js 默认） |
推荐原因：更符合 monorepo 依赖图，Turbo 缓存和依赖构建更稳定。
方案 B：App Root 模式
如果继续用 Root Directory = apps/ship，则：
| Vercel 配置项 | 值 |
|---|---|
| Framework Preset | Next.js |
| Root Directory | apps/ship |
| Include files outside root directory in Build Step | Enabled |
| Install Command | bun install |
| Build Command | bun run build |
| Output Directory | 留空（Next.js 默认） |
App Root 模式下，务必保持 “Include files outside root directory in Build Step = Enabled”，否则工作区包可能无法解析。
部署完成后，在 Stripe 后台配置 Webhook：
https://你的域名/api/v1/webhook/stripe
参考链接：
- Vercel Monorepo: https://vercel.com/docs/monorepos
- Vercel Build 设置: https://vercel.com/docs/builds/configure-a-build
- Turbo Filter: https://turbo.build/repo/docs/crafting-your-repository/running-tasks#using-filters
3. Cloudflare 部署（OpenNext）
仓库已内置 OpenNext Cloudflare 配置（apps/ship/open-next.config.ts、apps/ship/wrangler.jsonc）。
从仓库根目录执行：
bun install
cd apps/ship
bunx wrangler login
bun run deploybun run deploy 会执行：
opennextjs-cloudflare buildopennextjs-cloudflare deploy
参考链接：
- OpenNext Cloudflare: https://opennext.js.org/cloudflare
- Wrangler 配置: https://developers.cloudflare.com/workers/wrangler/configuration/
- Secrets 与变量: https://developers.cloudflare.com/workers/configuration/secrets/
Cloudflare 运行时建议显式设置 VERCEL_ENV=production，与模板内部生产分支行为保持一致。
4. 一键部署清单（照单执行）
Vercel
- 导入仓库
- 按上文选择方案 A 或 B 填写构建设置
- 填入前置环境变量
- 点击 Deploy
- 配置 Stripe Webhook
- 执行下方冒烟检查
Cloudflare
- 创建/选择 Workers 项目
- 填入环境变量与 Secrets
- 执行
bun install - 执行
cd apps/ship && bun run deploy - 绑定自定义域名
- 执行下方冒烟检查
5. 上线后冒烟验证
-
/:locale/docs -
/:locale/signin -
/:locale/subscription -
/:locale/admin -
/api/v1/health（如你当前环境已开放） -
/api/docs/search