WhaleTown End V2 部署

本文档覆盖 NestJS API、原生 WebSocket 服务和 React 管理端的单机部署。示例域名和目录与 deploy/nginx 中的模板一致，可按实际环境替换。

1. 环境要求

Node.js 20 或更高版本
pnpm 9
MySQL 8 和 Redis 7
PM2
Nginx
Python 3（仅皮肤生成功能需要）

生产目录默认为 /var/www/whale-town-end-v2。所有命令均在该目录执行。

2. 安装与配置

pnpm install --frozen-lockfile
cp .env.production.example .env
chmod 600 .env

编辑 .env 并至少完成以下配置：

为 JWT_SECRET 和 ADMIN_TOKEN_SECRET 设置独立的随机值。
完整设置 DB_HOST、DB_PORT、DB_USERNAME、DB_PASSWORD 和 DB_NAME，避免服务回退到内存存储。
完整设置 Redis 连接信息。
保持 REST API 使用 PORT=3000，聊天 WebSocket 使用 WEBSOCKET_PORT=3001。
使用 Zulip 时设置机器人凭据和至少 32 字节的 ZULIP_API_KEY_ENCRYPTION_KEY，并将 ZULIP_DEGRADED_MODE_ENABLED 设为 false。
不使用 Zulip 时可将 ZULIP_DEGRADED_MODE_ENABLED 设为 true 并留空 Zulip 凭据；此时 Zulip 集成和 API Key 加密存取功能不可用。

可分别生成随机密钥：

openssl rand -hex 32

不要把 .env、生成的密钥或数据库备份提交到 Git。

3. 构建

构建后端：

pnpm run build

配置并构建管理端：

cp client/.env.example client/.env.local
pnpm --filter whale-town-admin run build

确认 client/.env.local 中的 VITE_API_BASE_URL 指向实际后端 HTTPS 地址。该值在构建时写入管理端产物，修改后需要重新构建。

4. 启动服务

pm2 start ecosystem.config.js
pm2 save

服务使用仓库根目录作为工作目录，并从根目录的 .env 加载运行配置。查看状态和日志：

pm2 status
pm2 logs whale-town-end-v2

5. 配置 Nginx

安装后端和管理端模板：

sudo cp deploy/nginx/whaletownend-v2.conf.example /etc/nginx/conf.d/whaletownend-v2.conf
sudo cp deploy/nginx/whaletown-admin-v2.conf.example /etc/nginx/conf.d/whaletown-admin-v2.conf
sudo nginx -t
sudo systemctl reload nginx

后端模板将 REST API 转发到 3000，将 /game 转发到独立的聊天 WebSocket 端口 3001，并为 /location-broadcast 和 /ws/notice 保留 REST 端口上的 WebSocket Upgrade。上线前还需在 Nginx 或上游代理配置 TLS。

6. 验收

curl --fail https://whaletownend.xinghangee.icu/
curl --fail https://whaletownend.xinghangee.icu/health
curl --fail https://whaletownend.xinghangee.icu/api-docs

根接口应返回 version: 2.0.0，健康接口应返回 status: ok。还应分别验证以下 WebSocket 地址能够完成 101 Switching Protocols：

wss://whaletownend.xinghangee.icu/game
wss://whaletownend.xinghangee.icu/location-broadcast
wss://whaletownend.xinghangee.icu/ws/notice

最后使用管理端和游戏客户端完成登录、刷新令牌、世界聊天、位置同步和通知的冒烟测试。

7. 更新与回滚

更新前备份 .env 和数据库，然后执行：

git pull --ff-only
pnpm install --frozen-lockfile
pnpm run build
pnpm --filter whale-town-admin run build
pm2 reload whale-town-end-v2

出现问题时切回上一已验证提交，重新安装锁定依赖并构建，然后执行 pm2 reload whale-town-end-v2。数据库结构变更必须使用对应版本的迁移或备份恢复方案，不能只回滚应用代码。

3.5 KiB Raw Blame History Unescape Escape