Bunship运维
环境变量与配置
Bunship Web + API 运行所需的环境变量清单。
本页是当前仓库 必需环境变量 的权威清单。
代码参考：
- web schema：
apps/ship/src/env.ts - auth runtime：
packages/auth/src/server.ts,packages/auth-clerk/src/server.ts - api runtime：
apps/ship-api/src/server.ts与apps/ship-api/src/index.ts
最小必需（Web + API）
缺失这些变量会导致启动/构建失败，或影响认证/支付/存储等核心流程。
| 变量 | 是否必需 | 使用方 | 说明 |
|---|---|---|---|
NEXT_PUBLIC_AUTH_PROVIDER | 是（默认 better-auth） | web, api | better-auth 或 clerk |
DATABASE_URL | 是 | web, api, auth | Postgres 连接串 |
NEXT_PUBLIC_SITE_URL | 是 | web, api, auth | 站点地址，支持逗号分隔多域名 |
NEXT_PUBLIC_SERVER_URL | 是 | web, api, auth | API 地址 |
NEXT_PUBLIC_API_PREFIX | 否（默认 /api/v1） | web, api, auth | API 前缀 |
ADMIN_EMAIL_LIST | 是 | web, auth | 管理员邮箱列表（逗号分隔） |
EMAIL_FROM | 是 | auth | 邮件发件人（验证码/重置密码/OTP） |
RESEND_API_KEY | 是 | web/auth | 邮件服务密钥 |
S3_ENDPOINT | 是 | web, api | 存储服务地址 |
S3_REGION | 是 | web, api | 存储区域 |
S3_ACCESS_KEY | 是 | web, api | 存储访问密钥 |
S3_SECRET_KEY | 是 | web, api | 存储访问密钥密文 |
S3_BUCKET | 是 | web, api | Bucket 名称 |
NEXT_PUBLIC_S3_URL_BASE | 是 | web, api | 公网对象地址前缀 |
STRIPE_SECRET_KEY | 是 | web, api | Stripe API Key |
STRIPE_WEBHOOK_SECRET | 是 | web, api | Stripe Webhook 签名密钥 |
S_GITHUB_PERSONAL_ACCESS_TOKEN | 是 | web, api | 管理端/功能页用的 GitHub API Token |
CLOUDFLARE_ACCOUNT_ID | 是（web schema） | web | 当前环境校验要求 |
Better Auth 专用（当 NEXT_PUBLIC_AUTH_PROVIDER=better-auth）
| 变量 | 是否必需 | 使用方 | 说明 |
|---|---|---|---|
BETTER_AUTH_SECRET | 是 | auth/api | Better Auth 签名密钥 |
BETTER_AUTH_URL | 是 | auth/api | Auth 基础地址 |
AUTH_SECRET | 是 | web/auth | Web 环境校验必需 |
OAUTH_GITHUB_CLIENT_ID | 是（开启 GitHub OAuth 时） | web/auth | GitHub OAuth |
OAUTH_GITHUB_CLIENT_SECRET | 是（开启 GitHub OAuth 时） | web/auth | GitHub OAuth |
OAUTH_GOOGLE_CLIENT_ID | 建议 | auth | Google OAuth 服务端 Client ID |
OAUTH_GOOGLE_CLIENT_SECRET | 建议 | auth | Google OAuth 服务端 Secret |
NEXT_PUBLIC_OAUTH_GOOGLE_CLIENT_ID | 是（开启 Google OAuth 时） | web | Google One Tap / Sign-In UI |
Clerk 专用（当 NEXT_PUBLIC_AUTH_PROVIDER=clerk）
| 变量 | 是否必需 | 使用方 | 说明 |
|---|---|---|---|
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY | 是 | web | Clerk 公钥 |
CLERK_SECRET_KEY | 是 | api/auth | Clerk 服务端密钥 |
CLERK_WEBHOOK_SECRET | 是 | api | /api/v1/webhook/clerk 使用 |
API 运行与部署变量
| 变量 | 是否必需 | 说明 |
|---|---|---|
PORT | 否（默认 9001） | API 监听端口 |
APP_ENV | 建议 | development / production 等环境标识 |
NODE_ENV | 建议 | Node 运行环境 |
JWT_SECRET | 建议 | API JWT 签名密钥（虽有 fallback，不建议用于生产） |
JWT_EXPIRATION | 否（默认 7d） | API JWT 有效期 |
GIT_COMMIT_SHA | 否 | 日志构建信息 |
BUILD_TIME | 否 | 日志构建信息 |
CROSS_SUB_DOMAIN | 可选 | 跨子域 Cookie 域名 |
可选功能变量
| 变量 | 功能 |
|---|---|
UPSTASH_REDIS_REST_URL, UPSTASH_REDIS_REST_TOKEN | KV/Redis 功能 |
NEXT_PUBLIC_GA_ID, NEXT_PUBLIC_UMAMI_DATA_ID | 分析统计 |
NEXT_PUBLIC_APP_VERSION, VERCEL_GIT_COMMIT_SHA | UI 版本展示 |
BETTER_UPLOAD_PROVIDER, AWS_FORCE_PATH_STYLE | 上传提供方行为 |
OPENAI_API_KEY, OPENAI_API_BASE | 管理端 AI 命令/协作 |
REPLICATE_API_TOKEN | Replicate 服务 |
KIE_API_KEY, KIE_API_BASE_URL | KIE 服务 |
FAL_API_KEY | FAL 服务 |
本地 .env 示例（Better Auth）
NEXT_PUBLIC_AUTH_PROVIDER=better-auth
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/bunship
BETTER_AUTH_SECRET=replace-with-long-random-secret
BETTER_AUTH_URL=http://localhost:3001
AUTH_SECRET=replace-with-long-random-secret
NEXT_PUBLIC_SITE_URL=http://localhost:3000
NEXT_PUBLIC_SERVER_URL=http://localhost:3001
NEXT_PUBLIC_API_PREFIX=/api/v1
ADMIN_EMAIL_LIST=admin@example.com
EMAIL_FROM=Bunship <noreply@example.com>
RESEND_API_KEY=re_xxx
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
S3_ENDPOINT=https://s3.example.com
S3_REGION=auto
S3_ACCESS_KEY=xxx
S3_SECRET_KEY=xxx
S3_BUCKET=bunship
NEXT_PUBLIC_S3_URL_BASE=https://cdn.example.com
STRIPE_SECRET_KEY=sk_test_xxx
STRIPE_WEBHOOK_SECRET=whsec_xxx
S_GITHUB_PERSONAL_ACCESS_TOKEN=ghp_xxx
CLOUDFLARE_ACCOUNT_ID=xxx本地 .env 示例（Clerk）
NEXT_PUBLIC_AUTH_PROVIDER=clerk
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/bunship
NEXT_PUBLIC_SITE_URL=http://localhost:3000
NEXT_PUBLIC_SERVER_URL=http://localhost:3001
NEXT_PUBLIC_API_PREFIX=/api/v1
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_xxx
CLERK_SECRET_KEY=sk_test_xxx
CLERK_WEBHOOK_SECRET=whsec_xxx
ADMIN_EMAIL_LIST=admin@example.com
EMAIL_FROM=Bunship <noreply@example.com>
RESEND_API_KEY=re_xxx
S3_ENDPOINT=https://s3.example.com
S3_REGION=auto
S3_ACCESS_KEY=xxx
S3_SECRET_KEY=xxx
S3_BUCKET=bunship
NEXT_PUBLIC_S3_URL_BASE=https://cdn.example.com
STRIPE_SECRET_KEY=sk_test_xxx
STRIPE_WEBHOOK_SECRET=whsec_xxx
S_GITHUB_PERSONAL_ACCESS_TOKEN=ghp_xxx
CLOUDFLARE_ACCOUNT_ID=xxx