ANGJustinl/whale-town-end
1
0
Fork 0
forked from datawhale/whale-town-end
Code Pull Requests Activity

docs：更新README、贡献者文档和部署指南

Browse Source 
- 更新README.md：添加管理员后台系统介绍，更新测试统计为154个用例
- 更新CONTRIBUTORS.md：补充jianuo的管理员后台开发贡献，更新项目里程碑
- 更新DEPLOYMENT.md：完善前后端分离部署方案，添加管理员后台配置说明
- 反映最新管理员后台功能的部署要求和配置变更
This commit is contained in:
moyin
2025-12-22 15:13:04 +08:00
parent 2fb46967c7
commit d80d2c5cb8
3 changed files with 294 additions and 64 deletions
Download Patch File Download Diff File Expand all files Collapse all files

20
CONTRIBUTORS.md
View File

@@ -39,18 +39,22 @@
**jianuo** - 核心开发者 **jianuo** - 核心开发者
- Gitea: [@jianuo](https://gitea.xinghangee.icu/jianuo) - Gitea: [@jianuo](https://gitea.xinghangee.icu/jianuo)
- Email: 32106500027@e.gzhu.edu.cn - Email: 32106500027@e.gzhu.edu.cn
- 提交数: **3 commits** - 提交数: **6 commits**
- 主要贡献： - 主要贡献：
- 🐳 Docker部署问题修复 - 🎛️ **管理员后台系统** - 完整的前后端管理界面开发
- 📖 项目文档错误修复 - 📊 **日志管理功能** - 运行时日志查看与下载系统
- 🔧 部署配置优化 - 🔐 **管理员认证系统** - 独立Token认证与权限控制
- 🧪 **单元测试完善** - 管理员功能测试用例编写
- ⚙️ **TypeScript配置优化** - Node16模块解析配置
- 🐳 **Docker部署优化** - 容器化部署问题修复
- 📖 **技术栈文档更新** - 项目技术栈说明完善
## 贡献统计 ## 贡献统计
| 贡献者 | 提交数 | 主要领域 | 贡献占比 | | 贡献者 | 提交数 | 主要领域 | 贡献占比 |
|--------|--------|----------|----------| |--------|--------|----------|----------|
| moyin | 66 | 架构设计、核心功能、文档、测试 | 93% | | moyin | 66 | 架构设计、核心功能、文档、测试 | 88% |
| jianuo | 3 | 部署、文档 | 4% | | jianuo | 6 | 管理员后台、日志系统、部署优化 | 8% |
| angjustinl | 2 | 功能优化、测试、重构 | 3% | | angjustinl | 2 | 功能优化、测试、重构 | 3% |
## 项目里程碑 ## 项目里程碑
@@ -64,6 +68,10 @@
- **12月18日**: angjustinl重构邮箱验证流程，引入内存用户服务 - **12月18日**: angjustinl重构邮箱验证流程，引入内存用户服务
- **12月18日**: jianuo修复Docker部署问题 - **12月18日**: jianuo修复Docker部署问题
- **12月18日**: 完成测试用例修复和优化 - **12月18日**: 完成测试用例修复和优化
- **12月19日**: jianuo开发管理员后台系统
- **12月20日**: jianuo完善日志管理功能
- **12月21日**: jianuo添加管理员后台单元测试
- **12月22日**: 管理员后台功能合并到主分支
## 如何成为贡献者 ## 如何成为贡献者

298
DEPLOYMENT.md
View File

@@ -1,14 +1,20 @@
# 部署指南 # 🚀 Whale Town 部署指南
本文档详细说明如何部署 Pixel Game Server 到生产环境。 本文档详细说明如何部署 Whale Town 像素游戏后端服务到生产环境。
## 前置要求 ## 📋 前置要求
- Node.js 18+ ### 基础环境
- pnpm 包管理器 - **Node.js** 18+ (推荐 20.x LTS)
- MySQL 8.0+ - **pnpm** 包管理器
- PM2 进程管理器（推荐） - **MySQL** 8.0+
- Nginx（可选，用于反向代理） - **Redis** 6.0+ (可选，支持文件存储模式)
- **PM2** 进程管理器（推荐）
- **Nginx** 反向代理（推荐）
### 新增要求 (管理员后台)
- **Web服务器** (Nginx/Apache) - 用于前端管理界面
- **SSL证书** (推荐) - 保护管理后台安全
## 部署步骤 ## 部署步骤
@@ -84,11 +90,21 @@ EXIT;
### 5. 安装依赖和构建 ### 5. 安装依赖和构建
```bash ```bash
# 安装依赖 # 安装后端依赖
pnpm install --frozen-lockfile pnpm install --frozen-lockfile
# 构建项目 # 安装前端依赖 (新增)
cd client
pnpm install --frozen-lockfile
cd ..
# 构建后端
pnpm run build pnpm run build
# 构建前端管理界面 (新增)
cd client
pnpm run build
cd ..
``` ```
### 6. 启动服务 ### 6. 启动服务
@@ -105,20 +121,19 @@ pm2 startup
# 按照提示执行显示的命令 # 按照提示执行显示的命令
``` ```
### 7. 配置 Nginx（可选） ### 7. 配置 Nginx
创建 Nginx 配置文件： #### 方案一: 分离部署 (推荐)
创建后端API配置：
```bash ```bash
sudo nano /etc/nginx/sites-available/whale-town-end sudo nano /etc/nginx/sites-available/whale-town-api
``` ```
添加以下内容：
```nginx ```nginx
server { server {
listen 80; listen 80;
server_name your-domain.com; server_name api.whaletown.com;
location / { location / {
proxy_pass http://localhost:3000; proxy_pass http://localhost:3000;
@@ -131,30 +146,132 @@ server {
proxy_set_header X-Forwarded-Proto $scheme; proxy_set_header X-Forwarded-Proto $scheme;
proxy_cache_bypass $http_upgrade; proxy_cache_bypass $http_upgrade;
} }
}
```
location /webhook { 创建前端管理界面配置：
proxy_pass http://localhost:9000; ```bash
proxy_http_version 1.1; sudo nano /etc/nginx/sites-available/whale-town-admin
```
```nginx
server {
listen 80;
server_name admin.whaletown.com;
root /var/www/whale-town-end/client/dist;
index index.html;
# SPA路由支持
location / {
try_files $uri $uri/ /index.html;
}
# API代理
location /api/ {
proxy_pass http://api.whaletown.com/;
proxy_set_header Host $host; proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme; }
# 静态资源缓存
location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg)$ {
expires 1y;
add_header Cache-Control "public, immutable";
} }
} }
``` ```
启用站点： #### 方案二: 单域名部署
创建统一配置：
```bash ```bash
sudo ln -s /etc/nginx/sites-available/whale-town-end /etc/nginx/sites-enabled/ sudo nano /etc/nginx/sites-available/whale-town-unified
```
```nginx
server {
listen 80;
server_name whaletown.com;
# API接口
location /api/ {
proxy_pass http://localhost:3000/;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
}
# 管理后台
location /admin/ {
alias /var/www/whale-town-end/client/dist/;
try_files $uri $uri/ /admin/index.html;
}
# 主站点 (可选)
location / {
proxy_pass http://localhost:3000;
}
}
```
启用配置：
```bash
# 启用站点
sudo ln -s /etc/nginx/sites-available/whale-town-* /etc/nginx/sites-enabled/
# 测试配置
sudo nginx -t sudo nginx -t
# 重载配置
sudo systemctl reload nginx sudo systemctl reload nginx
``` ```
## Gitea Webhook 配置 ## 🔒 SSL证书配置 (推荐)
### 使用 Let's Encrypt
```bash
# 安装 Certbot
sudo apt install certbot python3-certbot-nginx
# 为API域名申请证书
sudo certbot --nginx -d api.whaletown.com
# 为管理后台申请证书
sudo certbot --nginx -d admin.whaletown.com
# 设置自动续期
sudo crontab -e
# 添加: 0 12 * * * /usr/bin/certbot renew --quiet
```
## 🎛️ 管理员后台配置
### 环境变量配置
在 `.env.production` 中添加：
```bash
# 管理员Token配置 (必须)
ADMIN_TOKEN_SECRET=your_super_strong_random_secret_at_least_32_chars
ADMIN_TOKEN_TTL_SECONDS=28800
# 首次部署启用管理员引导
ADMIN_BOOTSTRAP_ENABLED=true
ADMIN_USERNAME=admin
ADMIN_PASSWORD=YourStrongPassword123!
ADMIN_NICKNAME=系统管理员
# CORS配置 (如果前后端分离)
CORS_ORIGIN=https://admin.whaletown.com
```
### 访问管理后台
- **地址**: https://admin.whaletown.com
- **默认账号**: admin / YourStrongPassword123!
**⚠️ 重要**: 首次登录后立即修改密码并关闭引导功能 (`ADMIN_BOOTSTRAP_ENABLED=false`)
## 📡 Gitea Webhook 配置
1. 在 Gitea 仓库中进入 **Settings** → **Webhooks** 1. 在 Gitea 仓库中进入 **Settings** → **Webhooks**
2. 点击 **Add Webhook** → **Gitea**
3. 配置： 3. 配置：
- **Target URL**: `http://your-server.com:9000/webhook` 或 `http://your-domain.com/webhook` - **Target URL**: `http://your-server.com:9000/webhook` 或 `http://your-domain.com/webhook`
- **HTTP Method**: `POST` - **HTTP Method**: `POST`
@@ -163,54 +280,139 @@ sudo systemctl reload nginx
- **Trigger On**: 选择 `Push events` - **Trigger On**: 选择 `Push events`
- **Branch filter**: `main` - **Branch filter**: `main`
## 验证部署 ## ✅ 验证部署
### 基础服务检查
```bash ```bash
# 检查服务状态 # 检查PM2服务状态
pm2 status pm2 status
# 查看日志 # 检查后端API
pm2 logs whale-town-end
pm2 logs webhook-handler
# 测试 API
curl http://localhost:3000/ curl http://localhost:3000/
curl http://localhost:3000/api-docs curl http://localhost:3000/api-docs
# 检查前端管理界面
curl -I https://admin.whaletown.com
``` ```
## 常用命令 ### 管理员后台测试
```bash ```bash
# 重启服务 # 测试管理员登录API
curl -X POST https://api.whaletown.com/admin/auth/login \
-H "Content-Type: application/json" \
-d '{"identifier":"admin","password":"YourStrongPassword123!"}'
# 访问管理界面
# 浏览器打开: https://admin.whaletown.com
```
### 功能验证清单
- [ ] 后端API服务正常响应
- [ ] API文档可访问
- [ ] 前端管理界面加载正常
- [ ] 管理员登录功能正常
- [ ] 用户管理功能正常
- [ ] 日志查看功能正常
- [ ] SSL证书配置正确
## 🔧 常用命令
### 服务管理
```bash
# 重启后端服务
pm2 restart whale-town-end pm2 restart whale-town-end
# 查看日志 # 重启前端服务 (如果使用PM2托管)
pm2 restart whale-town-admin
# 查看服务日志
pm2 logs whale-town-end --lines 100 pm2 logs whale-town-end --lines 100
pm2 logs whale-town-admin --lines 100
# 手动部署 # 手动部署
bash deploy.sh bash deploy.sh
```
# 更新代码（不重启） ### 更新部署
```bash
# 更新后端
git pull origin main git pull origin main
pnpm install pnpm install
pnpm run build pnpm run build
pm2 reload whale-town-end pm2 reload whale-town-end
# 更新前端管理界面
cd client
git pull origin main
pnpm install
pnpm run build
sudo systemctl reload nginx
cd ..
``` ```
## 故障排除 ### 日志管理
```bash
# 查看应用日志
tail -f logs/app.log
### 服务无法启动 # 查看管理员操作日志
- 检查环境变量配置 tail -f logs/admin.log
- 检查数据库连接
- 查看 PM2 日志
### Webhook 不工作 # 查看Nginx日志
- 检查防火墙设置 sudo tail -f /var/log/nginx/access.log
- 验证 webhook URL 可访问性 sudo tail -f /var/log/nginx/error.log
- 检查 Gitea webhook 日志 ```
- 验证签名密钥是否一致
### 数据库连接失败 ## 🚨 故障排除
- 检查 MySQL 服务状态
### 后端服务问题
**服务无法启动**
- 检查环境变量配置 (`cat .env.production`)
- 检查数据库连接 (`mysql -u pixel_game -p`)
- 查看PM2日志 (`pm2 logs whale-town-end`)
- 检查端口占用 (`netstat -tlnp | grep 3000`)
**管理员登录失败**
- 验证 `ADMIN_TOKEN_SECRET` 配置
- 检查管理员账号是否创建
- 查看后端错误日志
- 确认密码复杂度要求
### 前端管理界面问题
**界面无法访问**
- 检查前端构建是否成功 (`ls -la client/dist/`)
- 验证Nginx配置 (`sudo nginx -t`)
- 检查域名解析
- 查看Nginx错误日志
**API请求失败**
- 检查CORS配置
- 验证API代理设置
- 确认后端服务状态
- 检查防火墙规则
### 数据库连接问题
**连接失败**
- 检查MySQL服务状态 (`sudo systemctl status mysql`)
- 验证数据库用户权限 - 验证数据库用户权限
- 检查网络连接 - 检查网络连接
- 确认数据库配置
### SSL证书问题
**证书验证失败**
- 检查证书有效期 (`sudo certbot certificates`)
- 验证域名解析
- 重新申请证书 (`sudo certbot --nginx -d your-domain.com`)
### 性能问题
**响应缓慢**
- 检查系统资源使用 (`htop`, `df -h`)
- 优化数据库查询
- 配置Redis缓存
- 启用Nginx压缩
### 日志文件过大
**磁盘空间不足**
- 配置日志轮转 (`sudo nano /etc/logrotate.d/whale-town`)
- 清理旧日志文件
- 监控磁盘使用情况

38
README.md
View File

@@ -12,11 +12,12 @@
Whale Town 是一个功能完整的像素游戏后端服务，提供： Whale Town 是一个功能完整的像素游戏后端服务，提供：
- 🔐 **完整用户认证系统** - 支持邮箱验证、密码重置、第三方登录 - 🔐 **完整用户认证系统** - 支持邮箱验证、密码重置、第三方登录
- 🎛️ **管理员后台系统** - React + Ant Design，用户管理、日志监控、权限控制
- 📧 **智能邮件服务** - 支持测试模式和生产模式自动切换 - 📧 **智能邮件服务** - 支持测试模式和生产模式自动切换
- 🗄️ **灵活存储方案** - Redis文件存储 + 内存数据库，支持无依赖测试 - 🗄️ **灵活存储方案** - Redis文件存储 + 内存数据库，支持无依赖测试
- 🚀 **高性能架构** - 基于NestJS，支持WebSocket实时通信 - 🚀 **高性能架构** - 基于NestJS，支持WebSocket实时通信
- 📚 **完整API文档** - Swagger UI + OpenAPI规范 - 📚 **完整API文档** - Swagger UI + OpenAPI规范
- 🧪 **全面测试覆盖** - 单元测试 + API功能测试 - 🧪 **全面测试覆盖** - 154个单元测试用例全部通过
--- ---
@@ -46,22 +47,34 @@ pnpm run dev
🎉 **服务启动成功！** 访问 http://localhost:3000 🎉 **服务启动成功！** 访问 http://localhost:3000
### 🧑‍💻 管理员后台（Ant Design） ### 🧑‍💻 管理员后台系统
项目包含一个最小可用的管理员后台（管理员登录 / 用户管理 / 重置密码），文档见： 项目包含一个功能完整的管理员后台系统，基于 React + Ant Design 构建：
- [docs/systems/admin-dashboard/README.md](docs/systems/admin-dashboard/README.md) **🎛️ 核心功能：**
- 管理员身份认证（独立Token系统）
- 用户列表管理与搜索
- 用户密码重置功能
- 运行时日志查看与下载
- 响应式界面设计
启动方式： **📚 详细文档：** [docs/systems/admin-dashboard/README.md](docs/systems/admin-dashboard/README.md)
**🚀 快速启动：**
```bash ```bash
# 1. 安装依赖
pnpm install pnpm install
# 后端 # 2. 启动后端服务
pnpm run dev pnpm run dev
# 前端后台 # 3. 启动前端管理界面
pnpm -C client dev pnpm -C client dev
# 4. 访问管理后台
# 地址: http://localhost:5173
# 账号: admin / Admin123456
``` ```
### 🧪 快速测试 ### 🧪 快速测试
@@ -238,6 +251,13 @@ pnpm -C client dev
- **第三方登录** - GitHub OAuth支持 - **第三方登录** - GitHub OAuth支持
- **权限控制** - 基于角色的访问控制 - **权限控制** - 基于角色的访问控制
### 🎛️ 管理员后台系统
- **独立认证** - 专用Token系统，与用户系统隔离
- **用户管理** - 用户列表、搜索、密码重置
- **日志监控** - 实时日志查看、历史日志下载
- **权限控制** - 管理员角色验证（role=9）
- **现代界面** - React + Ant Design响应式设计
### 📧 智能邮件服务 ### 📧 智能邮件服务
- **测试模式** - 控制台输出，无需SMTP服务器 - **测试模式** - 控制台输出，无需SMTP服务器
- **生产模式** - 支持主流邮件服务商 - **生产模式** - 支持主流邮件服务商
@@ -304,8 +324,8 @@ pnpm run test:cov
### 📈 测试覆盖率 ### 📈 测试覆盖率
- **单元测试**: 114个测试用例 ✅ - **单元测试**: 154个测试用例 ✅
- **功能测试**: 用户认证、邮件验证、数据存储 ✅ - **功能测试**: 用户认证、邮件验证、数据存储、管理员后台 ✅
- **集成测试**: 完整业务流程 ✅ - **集成测试**: 完整业务流程 ✅
--- ---