部署指南

基础设施要求

组件	要求	用途
服务器	Linux VM 或容器，Node.js 20+	应用托管
PostgreSQL	18 版本	主数据库
Redis	7+ 版本	队列、发布/订阅、缓存
Cloudflare R2	S3 兼容存储桶	文件存储（图片、上传）
Google Cloud	启用 Vertex AI API	AI 模型访问
Stripe	已配置 Webhook 的账户	支付处理
Resend	API 密钥	事务邮件

部署步骤

1. 安装依赖

pnpm install --frozen-lockfile

2. 生成 Prisma 客户端

npx prisma generate

3. 应用数据库 Schema

npx prisma db push

首次部署还需运行初始化数据：

npx prisma db seed

4. 构建

pnpm build

5. 使用 PM2 启动

pm2 start ecosystem.config.cjs --env production

这将启动全部四个进程：

进程	说明
mysticx-web	Next.js Web 服务（集群模式，使用所有 CPU）
mysticx-worker	塔罗解读 Worker
mysticx-insights-worker	指引/旅程生成 Worker
mysticx-telegram-bot	Telegram 机器人

自动化部署

项目包含 deploy.sh 脚本用于简化部署流程。

PM2 管理

# 查看所有进程
pm2 list

# 实时监控
pm2 monit

# 查看日志
pm2 logs
pm2 logs mysticx-web
pm2 logs mysticx-worker

# 重启进程
pm2 restart mysticx-web
pm2 restart mysticx-worker

# 零停机重载（仅集群模式）
pm2 reload mysticx-web

# 停止所有
pm2 stop all

# 保存进程列表用于重启后自动恢复
pm2 save
pm2 startup

日志

所有进程将日志写入 logs/ 目录：

文件	进程
logs/pm2-out.log	Web 服务标准输出
logs/pm2-error.log	Web 服务错误输出
logs/worker-out.log	塔罗 Worker 标准输出
logs/worker-error.log	塔罗 Worker 错误输出
logs/insights-worker-out.log	洞察 Worker 标准输出
logs/insights-worker-error.log	洞察 Worker 错误输出
logs/telegram-bot-out.log	Telegram 机器人标准输出
logs/telegram-bot-error.log	Telegram 机器人错误输出

Stripe Webhook 配置

将 Webhook 指向：https://your-domain.com/api/auth/stripe/webhook

订阅以下事件：

• checkout.session.completed
• invoice.payment_succeeded
• customer.subscription.updated
• customer.subscription.deleted

将 Webhook 签名密钥设置为 STRIPE_WEBHOOK_SECRET。

Cloudflare R2 设置

创建存储桶并配置：

• R2_ACCOUNT_ID — Cloudflare 账户 ID
• R2_ACCESS_KEY_ID — R2 API Token 访问密钥
• R2_SECRET_ACCESS_KEY — R2 API Token 密钥

用于：牌面皮肤图片、读者头像、用户头像上传、反馈截图。

Google Vertex AI 设置

1. 创建启用 Vertex AI API 的 GCP 项目
2. 创建具有 Vertex AI User 角色的服务账号
3. 下载 JSON 密钥文件
4. 将 GOOGLE_APPLICATION_CREDENTIALS 设置为密钥文件路径
5. 设置 GOOGLE_VERTEX_PROJECT 和 GOOGLE_VERTEX_LOCATION

环境变量清单

部署前确保所有必需环境变量已设置：

# 核心
DATABASE_URL=
BETTER_AUTH_SECRET=
BETTER_AUTH_URL=
NEXT_PUBLIC_APP_ENV=production

# 认证
GOOGLE_CLIENT_ID=
GOOGLE_CLIENT_SECRET=
RESEND_API_KEY=
EMAIL_FROM=

# AI
GOOGLE_APPLICATION_CREDENTIALS=
GOOGLE_VERTEX_PROJECT=
GOOGLE_VERTEX_LOCATION=

# 存储
R2_ACCOUNT_ID=
R2_ACCESS_KEY_ID=
R2_SECRET_ACCESS_KEY=

# 支付
STRIPE_SECRET_KEY=
STRIPE_WEBHOOK_SECRET=

# Redis（如非本地）
REDIS_HOST=
REDIS_PORT=

# Telegram（可选）
TELEGRAM_BOT_TOKEN=
INTERNAL_API_KEY=

健康检查

部署后验证：

1. Web 服务：访问站点，检查页面是否正常加载
2. 认证：测试登录和注册流程
3. 解读：提交一次测试解读并验证流式输出是否正常
4. Worker：检查 PM2 日志中的 Worker 启动消息
5. Stripe：在测试模式下测试结账流程
6. Telegram：向机器人发送 /start（如已启用）

扩展

• Web 服务以 PM2 集群模式运行，可跨 CPU 核心水平扩展
• Worker 设计为单实例（BullMQ 处理任务锁定）
• 如需更高吞吐量，塔罗 Worker 可利用 BullMQ 内置并发能力扩展为多实例
• PostgreSQL 连接池由 Prisma 的 @prisma/adapter-pg 管理