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

- 更新README.md：添加管理员后台系统介绍，更新测试统计为154个用例 - 更新CONTRIBUTORS.md：补充jianuo的管理员后台开发贡献，更新项目里程碑 - 更新DEPLOYMENT.md：完善前后端分离部署方案，添加管理员后台配置说明 - 反映最新管理员后台功能的部署要求和配置变更
2025-12-22 15:13:04 +08:00
parent 2fb46967c7
commit d80d2c5cb8
3 changed files with 294 additions and 64 deletions
--- a/CONTRIBUTORS.md
+++ b/CONTRIBUTORS.md
@@ -39,18 +39,22 @@
 **jianuo** - 核心开发者
 - Gitea: [@jianuo](https://gitea.xinghangee.icu/jianuo)
 - Email: 32106500027@e.gzhu.edu.cn
- 提交数: **3 commits**
+- 提交数: **6 commits**
 - 主要贡献：
-  - 🐳 Docker部署问题修复
-  - 📖 项目文档错误修复
-  - 🔧 部署配置优化
+  - 🎛️ **管理员后台系统** - 完整的前后端管理界面开发
+  - 📊 **日志管理功能** - 运行时日志查看与下载系统
+  - 🔐 **管理员认证系统** - 独立Token认证与权限控制
+  - 🧪 **单元测试完善** - 管理员功能测试用例编写
+  - ⚙️ **TypeScript配置优化** - Node16模块解析配置
+  - 🐳 **Docker部署优化** - 容器化部署问题修复
+  - 📖 **技术栈文档更新** - 项目技术栈说明完善

 ## 贡献统计

 | 贡献者 | 提交数 | 主要领域 | 贡献占比 |
 |--------|--------|----------|----------|
-| moyin | 66 | 架构设计、核心功能、文档、测试 | 93% |
-| jianuo | 3 | 部署、文档 | 4% |
+| moyin | 66 | 架构设计、核心功能、文档、测试 | 88% |
+| jianuo | 6 | 管理员后台、日志系统、部署优化 | 8% |
 | angjustinl | 2 | 功能优化、测试、重构 | 3% |

 ## 项目里程碑
@@ -64,6 +68,10 @@
 - **12月18日**: angjustinl重构邮箱验证流程，引入内存用户服务
 - **12月18日**: jianuo修复Docker部署问题
 - **12月18日**: 完成测试用例修复和优化
+- **12月19日**: jianuo开发管理员后台系统
+- **12月20日**: jianuo完善日志管理功能
+- **12月21日**: jianuo添加管理员后台单元测试
+- **12月22日**: 管理员后台功能合并到主分支

 ## 如何成为贡献者

--- a/DEPLOYMENT.md
+++ b/DEPLOYMENT.md
@@ -1,14 +1,20 @@
-# 部署指南
+# 🚀 Whale Town 部署指南

-本文档详细说明如何部署 Pixel Game Server 到生产环境。
+本文档详细说明如何部署 Whale Town 像素游戏后端服务到生产环境。

-## 前置要求
+## 📋 前置要求

- Node.js 18+
- pnpm 包管理器
- MySQL 8.0+
- PM2 进程管理器（推荐）
- Nginx（可选，用于反向代理）
+### 基础环境
+- **Node.js** 18+ (推荐 20.x LTS)
+- **pnpm** 包管理器
+- **MySQL** 8.0+
+- **Redis** 6.0+ (可选，支持文件存储模式)
+- **PM2** 进程管理器（推荐）
+- **Nginx** 反向代理（推荐）
+
+### 新增要求 (管理员后台)
+- **Web服务器** (Nginx/Apache) - 用于前端管理界面
+- **SSL证书** (推荐) - 保护管理后台安全

 ## 部署步骤

@@ -84,11 +90,21 @@ EXIT;
 ### 5. 安装依赖和构建

 ```bash
-# 安装依赖
+# 安装后端依赖
 pnpm install --frozen-lockfile

-# 构建项目
+# 安装前端依赖 (新增)
+cd client
+pnpm install --frozen-lockfile
+cd ..
+
+# 构建后端
 pnpm run build
+
+# 构建前端管理界面 (新增)
+cd client
+pnpm run build
+cd ..
 ```

 ### 6. 启动服务
@@ -105,20 +121,19 @@ pm2 startup
 # 按照提示执行显示的命令
 ```

-### 7. 配置 Nginx（可选）
+### 7. 配置 Nginx

-创建 Nginx 配置文件：
+#### 方案一: 分离部署 (推荐)

+创建后端API配置：
 ```bash
-sudo nano /etc/nginx/sites-available/whale-town-end
+sudo nano /etc/nginx/sites-available/whale-town-api
 ```

-添加以下内容：
-
 ```nginx
 server {
    listen 80;
-    server_name your-domain.com;
+    server_name api.whaletown.com;

    location / {
        proxy_pass http://localhost:3000;
@@ -131,30 +146,132 @@ server {
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_cache_bypass $http_upgrade;
    }
+}
+```

-    location /webhook {
-        proxy_pass http://localhost:9000;
-        proxy_http_version 1.1;
+创建前端管理界面配置：
+```bash
+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 X-Real-IP $remote_addr;
        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
-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 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**
-2. 点击 **Add Webhook** → **Gitea**
 3. 配置：
   - **Target URL**: `http://your-server.com:9000/webhook` 或 `http://your-domain.com/webhook`
   - **HTTP Method**: `POST`
@@ -163,54 +280,139 @@ sudo systemctl reload nginx
   - **Trigger On**: 选择 `Push events`
   - **Branch filter**: `main`

-## 验证部署
+## ✅ 验证部署

+### 基础服务检查
 ```bash
-# 检查服务状态
+# 检查PM2服务状态
 pm2 status

-# 查看日志
-pm2 logs whale-town-end
-pm2 logs webhook-handler
-
-# 测试 API
+# 检查后端API
 curl http://localhost:3000/
 curl http://localhost:3000/api-docs
+
+# 检查前端管理界面
+curl -I https://admin.whaletown.com
 ```

-## 常用命令
-
+### 管理员后台测试
 ```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托管)
+pm2 restart whale-town-admin
+
+# 查看服务日志
 pm2 logs whale-town-end --lines 100
+pm2 logs whale-town-admin --lines 100

 # 手动部署
 bash deploy.sh
+```

-# 更新代码（不重启）
+### 更新部署
+```bash
+# 更新后端
 git pull origin main
 pnpm install
 pnpm run build
 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

-### 服务无法启动
- 检查环境变量配置
- 检查数据库连接
- 查看 PM2 日志
+# 查看管理员操作日志
+tail -f logs/admin.log

-### Webhook 不工作
- 检查防火墙设置
- 验证 webhook URL 可访问性
- 检查 Gitea webhook 日志
- 验证签名密钥是否一致
+# 查看Nginx日志
+sudo tail -f /var/log/nginx/access.log
+sudo tail -f /var/log/nginx/error.log
+```

-### 数据库连接失败
- 检查 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`)
+- 清理旧日志文件
+- 监控磁盘使用情况
--- a/README.md
+++ b/README.md
@@ -12,11 +12,12 @@
 Whale Town 是一个功能完整的像素游戏后端服务，提供：

 - 🔐 **完整用户认证系统** - 支持邮箱验证、密码重置、第三方登录
+- 🎛️ **管理员后台系统** - React + Ant Design，用户管理、日志监控、权限控制
 - 📧 **智能邮件服务** - 支持测试模式和生产模式自动切换
 - 🗄️ **灵活存储方案** - Redis文件存储 + 内存数据库，支持无依赖测试
 - 🚀 **高性能架构** - 基于NestJS，支持WebSocket实时通信
 - 📚 **完整API文档** - Swagger UI + OpenAPI规范
- 🧪 **全面测试覆盖** - 单元测试 + API功能测试
+- 🧪 **全面测试覆盖** - 154个单元测试用例全部通过

 ---

@@ -46,22 +47,34 @@ pnpm run dev

 🎉 **服务启动成功！** 访问 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
+# 1. 安装依赖
 pnpm install

-# 后端
+# 2. 启动后端服务
 pnpm run dev

-# 前端后台
+# 3. 启动前端管理界面
 pnpm -C client dev
+
+# 4. 访问管理后台
+# 地址: http://localhost:5173
+# 账号: admin / Admin123456
 ```

 ### 🧪 快速测试
@@ -238,6 +251,13 @@ pnpm -C client dev
 - **第三方登录** - GitHub OAuth支持
 - **权限控制** - 基于角色的访问控制

+### 🎛️ 管理员后台系统
+- **独立认证** - 专用Token系统，与用户系统隔离
+- **用户管理** - 用户列表、搜索、密码重置
+- **日志监控** - 实时日志查看、历史日志下载
+- **权限控制** - 管理员角色验证（role=9）
+- **现代界面** - React + Ant Design响应式设计
+
 ### 📧 智能邮件服务
 - **测试模式** - 控制台输出，无需SMTP服务器
 - **生产模式** - 支持主流邮件服务商
@@ -304,8 +324,8 @@ pnpm run test:cov

 ### 📈 测试覆盖率

- **单元测试**: 114个测试用例 ✅
- **功能测试**: 用户认证、邮件验证、数据存储 ✅
+- **单元测试**: 154个测试用例 ✅
+- **功能测试**: 用户认证、邮件验证、数据存储、管理员后台 ✅
 - **集成测试**: 完整业务流程 ✅

 ---