forked from xiangwang25/whale-town-end-v2
65 lines
2.2 KiB
Markdown
65 lines
2.2 KiB
Markdown
# WhaleTown End V2
|
||
|
||
WhaleTown V2 后端是基于 NestJS 的多人小镇服务，包含 REST API、WebSocket 实时通信和 React 管理端。
|
||
|
||
## 功能
|
||
|
||
- 账号注册、登录、令牌刷新、密码找回与资料管理。
|
||
- 世界聊天、私聊、玩家位置与外观实时同步。
|
||
- 商城、钱包、背包、房间家具和排行榜。
|
||
- 咖啡店陪伴助手、课程资源与 Zulip 集成。
|
||
- AI 小镇 NPC 日程、移动、交互与持久化运行时。
|
||
- 邀请码注册、管理员用户管理、邀请码管理和运行日志。
|
||
- 可选的服务端角色皮肤生成流程。
|
||
|
||
## 要求
|
||
|
||
- Node.js 20+
|
||
- pnpm 9.15.4
|
||
- MySQL 和 Redis（生产环境）
|
||
- Python 3（启用皮肤生成时）
|
||
|
||
## 运行
|
||
|
||
```bash
|
||
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`。
|
||
|
||
## 管理端
|
||
|
||
```bash
|
||
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 文件。
|
||
|
||
## 验证
|
||
|
||
```bash
|
||
pnpm run build
|
||
pnpm --filter whale-town-admin run build
|
||
pnpm test
|
||
pnpm run test:world-npc
|
||
```
|
||
|
||
## 部署
|
||
|
||
生产部署、Nginx、PM2、验收和回滚步骤见 [DEPLOYMENT.md](DEPLOYMENT.md)。
|
||
|
||
## 安全
|
||
|
||
仓库不包含 `.env`、访问令牌、SSH 私钥、数据库文件、Redis 数据、日志或生成资产。敏感配置必须通过部署环境注入。
|