WhaleTown End V2

WhaleTown V2 后端是基于 NestJS 的多人小镇服务，包含 REST API、WebSocket 实时通信和 React 管理端。

功能

• 账号注册、登录、令牌刷新、密码找回与资料管理。
• 世界聊天、私聊、玩家位置与外观实时同步。
• 商城、钱包、背包、房间家具和排行榜。
• 咖啡店陪伴助手、课程资源与 Zulip 集成。
• AI 小镇 NPC 日程、移动、交互与持久化运行时。
• 邀请码注册、管理员用户管理、邀请码管理和运行日志。
• 可选的服务端角色皮肤生成流程。

要求

• Node.js 20+
• pnpm 9.15.4
• MySQL 和 Redis（生产环境）
• Python 3（启用皮肤生成时）

运行

pnpm install --frozen-lockfile
cp .env.example .env
pnpm run db:migrate
pnpm run build
pnpm run start:prod

首次启用邀请码功能时必须先执行 pnpm run db:migrate。该命令使用 .env 中的 MySQL 配置创建邀请码表。

启动前至少需要在 .env 中设置随机的 JWT_SECRET 和 ADMIN_TOKEN_SECRET。启用 Zulip 时还必须设置 ZULIP_API_KEY_ENCRYPTION_KEY；若 ZULIP_DEGRADED_MODE_ENABLED=true，可以不配置 Zulip 凭据和加密密钥，但 Zulip 集成及 API Key 加密存取功能将不可用。生产环境请从 .env.production.example 开始配置，不要直接使用示例值。

API 默认监听 3000 端口，Swagger 地址为 /api-docs。

管理端

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

管理端默认以 /admin/ 为部署路径，并通过 client/.env.local 中的 VITE_API_BASE_URL 配置 API 地址。同域生产部署保持示例值 /api。

页面按路由懒加载，Vite 会在 client/dist/assets 中生成多个带哈希的 JS 文件。部署时应整体替换 client/dist，不要只上传 index.html 或单个 JS 文件。

验证

pnpm run build
pnpm --filter whale-town-admin run build
pnpm test
pnpm run test:world-npc

部署

生产部署、Nginx、PM2、验收和回滚步骤见 DEPLOYMENT.md。

安全

仓库不包含 .env、访问令牌、SSH 私钥、数据库文件、Redis 数据、日志或生成资产。敏感配置必须通过部署环境注入。