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

docs: 重构文档结构和组织

Browse Source 
- 重新组织docs目录结构，按功能模块分类
- 新增deployment和development目录
- 更新API文档结构
- 添加客户端README文档
- 移除过时的文档文件
This commit is contained in:
moyin
2025-12-24 18:04:14 +08:00
parent 032c97a1fc
commit 85d488a508
20 changed files with 2416 additions and 1763 deletions
Download Patch File Download Diff File Expand all files Collapse all files

186
docs/systems/admin-dashboard/README.md
View File

@@ -1,186 +0,0 @@
# 管理员后台（Admin Dashboard）
本模块提供 Whale Town 的管理员后台能力，包含：
- 管理员登录（role=9）
- 用户列表管理
- 用户密码重置
- 运行日志查看（读取 logs/ 下最新日志）
> 说明：本项目用户系统原本的 `access_token` 为演示用 Base64 令牌。为了不影响现有用户端流程，管理员后台使用单独的签名 Token（HMAC-SHA256）做鉴权。
---
## 1. 管理员账号设计
### 1.1 角色约定
用户表 `users.role`：
- `1`：普通用户
- `9`：管理员（可访问后台）
### 1.2 启动引导创建管理员（可选）
通过环境变量启用启动引导：在服务启动时，如果不存在指定用户名的用户，则自动创建一个管理员账户（role=9）。
在 `.env` 中配置：
- `ADMIN_BOOTSTRAP_ENABLED=true`
- `ADMIN_USERNAME=admin`
- `ADMIN_PASSWORD=Admin123456`（需满足密码强度：至少8位，包含字母和数字）
- `ADMIN_NICKNAME=管理员`（可选）
注意：
- 建议仅在首次部署/开发环境开启，引导创建成功后可关闭。
- 生产环境务必设置强随机密码与强随机 `ADMIN_TOKEN_SECRET`。
---
## 2. 管理员鉴权 Token
### 2.1 配置项
- `ADMIN_TOKEN_SECRET`：签名密钥（至少16字符；生产环境建议≥32并随机）
- `ADMIN_TOKEN_TTL_SECONDS`：Token 有效期（秒），默认 `28800`（8小时）
### 2.2 使用方式
管理员登录成功后返回 `access_token`，后续请求在 Header 中携带：
- `Authorization: Bearer <access_token>`
---
## 3. 后端接口
### 3.1 管理员登录
- `POST /admin/auth/login`
请求：
```json
{
"identifier": "admin",
"password": "Admin123456"
}
```
响应（成功）：
```json
{
"success": true,
"data": {
"admin": { "id": "1", "username": "admin", "nickname": "管理员", "role": 9 },
"access_token": "...",
"expires_at": 1766102400000
},
"message": "管理员登录成功"
}
```
### 3.2 用户列表
- `GET /admin/users?limit=100&offset=0`
- 需要管理员 Token
### 3.3 用户详情
- `GET /admin/users/:id`
- 需要管理员 Token
### 3.4 重置用户密码
- `POST /admin/users/:id/reset-password`
- 需要管理员 Token
请求：
```json
{
"new_password": "NewPass1234"
}
```
### 3.5 运行日志（tail）
- `GET /admin/logs/runtime?lines=200`
- 需要管理员 Token
说明：
- 开发环境默认读取 `logs/dev.log`
- 生产环境默认读取 `logs/app.log`
- `lines` 默认 200，最大 2000
### 3.6 下载全部运行日志（archive）
- `GET /admin/logs/archive`
- 需要管理员 Token
说明：
- 返回一个 `tar.gz` 文件（浏览器会触发下载）
- 内容为整个 `logs/` 目录（例如开发环境的 `dev.log`，生产环境的 `app.log/access.log/error.log` 等）
---
## 4. 前端后台（Ant Design）
前端工程位于 `client/`，使用 Vite + React + Ant Design。
### 4.1 安装依赖
在项目根目录执行：
```bash
pnpm install
```
### 4.2 启动后端
```bash
pnpm run dev
```
### 4.3 启动前端后台
```bash
pnpm -C client dev
```
默认访问：
- 前端：`http://localhost:5173`
- 后端：`http://localhost:3000`
- Swagger：`http://localhost:3000/api-docs`
页面说明：
- 用户管理：`/users`
- 运行日志：`/logs`
在“运行日志”页面可点击“下载日志压缩包”获取整个 `logs/` 目录的打包文件。
### 4.4 前端配置
- 复制 `client/.env.example` 为 `client/.env.local`
- 可通过 `VITE_API_BASE_URL` 指向后端地址
---
## 5. 代码位置
- 后端：
- `src/core/admin_core/`：管理员核心逻辑
- `src/core/guards/admin.guard.ts`：管理员接口鉴权
- `src/business/admin/`：管理员HTTP API
- `src/dto/admin*.ts`：管理员请求/响应 DTO
- 前端：
- `client/src/pages/LoginPage.tsx`：管理员登录页
- `client/src/pages/UsersPage.tsx`：用户管理页（列表+重置密码）
- `client/src/pages/LogsPage.tsx`：运行日志页

265
docs/systems/email-verification/README.md
View File

@@ -1,265 +0,0 @@
# 邮箱验证系统
## 概述
邮箱验证系统提供完整的邮箱验证功能，包括验证码生成、发送、验证和管理。
## 功能特性
- 📧 邮箱验证码发送
- 🔐 验证码安全验证
- ⏰ 验证码过期管理
- 🚫 防刷机制（频率限制）
- 📊 验证统计和监控
## 系统架构
```
邮箱验证系统
├── 验证码服务 (VerificationService)
│ ├── 验证码生成
│ ├── 验证码验证
│ └── 防刷机制
├── 邮件服务 (EmailService)
│ ├── 验证码邮件发送
│ ├── 欢迎邮件发送
│ └── 邮件模板管理
└── Redis缓存
├── 验证码存储
├── 冷却时间管理
└── 发送频率限制
```
## 核心组件
### 1. 验证码服务 (VerificationService)
负责验证码的生成、验证和管理：
- **验证码生成**：6位数字验证码
- **验证码验证**：支持多次尝试限制
- **过期管理**：5分钟有效期
- **防刷机制**：60秒冷却时间，每小时最多5次
### 2. 邮件服务 (EmailService)
负责邮件的发送和模板管理：
- **验证码邮件**：发送验证码到用户邮箱
- **欢迎邮件**：用户注册成功后发送
- **模板支持**：支持HTML邮件模板
### 3. Redis缓存
负责数据的临时存储：
- **验证码存储**：`verification_code:${type}:${identifier}`
- **冷却时间**：`verification_cooldown:${type}:${identifier}`
- **发送频率**：`verification_hourly:${type}:${identifier}:${date}:${hour}`
## 使用流程
### 注册流程中的邮箱验证
1. **发送验证码**
```typescript
POST /auth/send-email-verification
{
"email": "user@example.com"
}
```
2. **用户注册**
```typescript
POST /auth/register
{
"username": "testuser",
"password": "password123",
"nickname": "测试用户",
"email": "user@example.com",
"email_verification_code": "123456"
}
```
### 独立邮箱验证
1. **验证邮箱**
```typescript
POST /auth/verify-email
{
"email": "user@example.com",
"verification_code": "123456"
}
```
## 配置说明
### 环境变量
```bash
# 邮件服务配置
SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_USER=your-email@example.com
SMTP_PASS=your-password
SMTP_FROM=noreply@example.com
# Redis配置
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=
```
### 验证码配置
```typescript
// 验证码长度
CODE_LENGTH = 6
// 验证码过期时间（秒）
CODE_EXPIRE_TIME = 300 // 5分钟
// 最大验证尝试次数
MAX_ATTEMPTS = 3
// 发送冷却时间（秒）
RATE_LIMIT_TIME = 60 // 1分钟
// 每小时最大发送次数
MAX_SENDS_PER_HOUR = 5
```
## API接口
### 发送邮箱验证码
- **接口**：`POST /auth/send-email-verification`
- **描述**：向指定邮箱发送验证码
- **参数**：
```typescript
{
email: string; // 邮箱地址
}
```
### 验证邮箱验证码
- **接口**：`POST /auth/verify-email`
- **描述**：使用验证码验证邮箱
- **参数**：
```typescript
{
email: string; // 邮箱地址
verification_code: string; // 6位数字验证码
}
```
### 重新发送验证码
- **接口**：`POST /auth/resend-email-verification`
- **描述**：重新向指定邮箱发送验证码
- **参数**：
```typescript
{
email: string; // 邮箱地址
}
```
## 错误处理
### 常见错误码
- `VERIFICATION_CODE_NOT_FOUND`：验证码不存在或已过期
- `VERIFICATION_CODE_INVALID`：验证码错误
- `TOO_MANY_ATTEMPTS`：验证尝试次数过多
- `RATE_LIMIT_EXCEEDED`：发送频率过高
- `EMAIL_SEND_FAILED`：邮件发送失败
### 错误响应格式
```typescript
{
success: false,
message: "错误描述",
error_code: "ERROR_CODE"
}
```
## 监控和日志
### 关键指标
- 验证码发送成功率
- 验证码验证成功率
- 邮件发送延迟
- Redis连接状态
### 日志记录
- 验证码生成和验证日志
- 邮件发送状态日志
- 错误和异常日志
- 性能监控日志
## 安全考虑
### 防刷机制
1. **发送频率限制**：每个邮箱60秒内只能发送一次
2. **每小时限制**：每个邮箱每小时最多发送5次
3. **验证尝试限制**：每个验证码最多尝试3次
### 数据安全
1. **验证码加密存储**：Redis中的验证码经过加密
2. **过期自动清理**：验证码5分钟后自动过期
3. **日志脱敏**：日志中不记录完整验证码
## 部署指南
详细的部署说明请参考：[deployment-guide.md](./deployment-guide.md)
## 测试
### 单元测试
```bash
# 运行验证服务测试
npm test -- verification.service.spec.ts
# 运行邮件服务测试
npm test -- email.service.spec.ts
```
### 集成测试
```bash
# 运行邮箱验证集成测试
npm run test:e2e -- email-verification
```
## 故障排除
### 常见问题
1. **验证码收不到**
- 检查SMTP配置
- 检查邮箱是否在垃圾邮件中
- 检查网络连接
2. **验证码验证失败**
- 检查验证码是否过期
- 检查验证码输入是否正确
- 检查Redis连接状态
3. **发送频率限制**
- 等待冷却时间结束
- 检查是否达到每小时限制
## 更新日志
- **v1.0.0** (2025-12-17)
- 初始版本发布
- 支持基本的邮箱验证功能
- 集成Redis缓存
- 添加防刷机制

316
docs/systems/email-verification/deployment-guide.md
View File

@@ -1,316 +0,0 @@
# 邮箱验证功能部署指南
## 概述
本指南详细说明如何部署和配置邮箱验证功能，包括Redis缓存、邮件服务配置等。
## 1. 安装依赖
```bash
# 安装新增的依赖包
pnpm install ioredis nodemailer
# 安装类型定义
pnpm install -D @types/nodemailer
```
## 2. Redis 服务配置
### 2.1 安装 Redis
#### Ubuntu/Debian
```bash
sudo apt update
sudo apt install redis-server
sudo systemctl start redis-server
sudo systemctl enable redis-server
```
#### CentOS/RHEL
```bash
sudo yum install redis
sudo systemctl start redis
sudo systemctl enable redis
```
#### Docker 方式
```bash
docker run -d --name redis -p 6379:6379 redis:7-alpine
```
### 2.2 Redis 配置验证
```bash
# 测试 Redis 连接
redis-cli ping
# 应该返回 PONG
```
## 3. 邮件服务配置
### 3.1 Gmail 配置示例
1. **启用两步验证**：
- 登录 Google 账户
- 进入"安全性"设置
- 启用"两步验证"
2. **生成应用专用密码**：
- 在"安全性"设置中找到"应用专用密码"
- 生成新的应用密码
- 记录生成的16位密码
3. **环境变量配置**：
```env
EMAIL_HOST=smtp.gmail.com
EMAIL_PORT=587
EMAIL_SECURE=false
EMAIL_USER=your-email@gmail.com
EMAIL_PASS=your-16-digit-app-password
EMAIL_FROM="Whale Town Game" <noreply@gmail.com>
```
### 3.2 其他邮件服务商配置
#### 163邮箱
```env
EMAIL_HOST=smtp.163.com
EMAIL_PORT=587
EMAIL_SECURE=false
EMAIL_USER=your-email@163.com
EMAIL_PASS=your-authorization-code
```
#### QQ邮箱
```env
EMAIL_HOST=smtp.qq.com
EMAIL_PORT=587
EMAIL_SECURE=false
EMAIL_USER=your-email@qq.com
EMAIL_PASS=your-authorization-code
```
#### 阿里云邮件推送
```env
EMAIL_HOST=smtpdm.aliyun.com
EMAIL_PORT=587
EMAIL_SECURE=false
EMAIL_USER=your-smtp-username
EMAIL_PASS=your-smtp-password
```
## 4. 环境变量配置
### 4.1 创建环境配置文件
```bash
# 复制环境变量模板
cp .env.production.example .env
# 编辑环境变量
nano .env
```
### 4.2 完整的环境变量配置
```env
# 数据库配置
DB_HOST=localhost
DB_PORT=3306
DB_USERNAME=pixel_game
DB_PASSWORD=your_db_password
DB_NAME=pixel_game_db
# 应用配置
NODE_ENV=production
PORT=3000
# JWT 配置
JWT_SECRET=your_jwt_secret_key_here_at_least_32_characters
JWT_EXPIRES_IN=7d
# Redis 配置
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=
REDIS_DB=0
# 邮件服务配置
EMAIL_HOST=smtp.gmail.com
EMAIL_PORT=587
EMAIL_SECURE=false
EMAIL_USER=your-email@gmail.com
EMAIL_PASS=your-app-password
EMAIL_FROM="Whale Town Game" <noreply@whaletown.com>
```
## 5. 数据库迁移
由于添加了新的字段，需要更新数据库结构：
```sql
-- 添加邮箱验证状态字段
ALTER TABLE users ADD COLUMN email_verified BOOLEAN NOT NULL DEFAULT FALSE COMMENT '邮箱是否已验证';
-- 为已有用户设置默认值
UPDATE users SET email_verified = FALSE WHERE email_verified IS NULL;
-- 如果是OAuth用户且有邮箱，可以设为已验证
UPDATE users SET email_verified = TRUE WHERE github_id IS NOT NULL AND email IS NOT NULL;
```
## 6. 启动和测试
### 6.1 启动应用
```bash
# 安装依赖
pnpm install
# 构建应用
pnpm run build
# 启动应用
pnpm run start:prod
```
### 6.2 功能测试
#### 测试邮箱验证码发送
```bash
curl -X POST http://localhost:3000/auth/send-email-verification \
-H "Content-Type: application/json" \
-d '{"email":"test@example.com"}'
```
#### 测试邮箱验证
```bash
curl -X POST http://localhost:3000/auth/verify-email \
-H "Content-Type: application/json" \
-d '{"email":"test@example.com","verification_code":"123456"}'
```
#### 测试密码重置
```bash
curl -X POST http://localhost:3000/auth/forgot-password \
-H "Content-Type: application/json" \
-d '{"identifier":"test@example.com"}'
```
## 7. 监控和日志
### 7.1 查看应用日志
```bash
# PM2 日志
pm2 logs pixel-game-server
# 或者查看文件日志
tail -f logs/dev.log
```
### 7.2 Redis 监控
```bash
# 查看 Redis 信息
redis-cli info
# 监控 Redis 命令
redis-cli monitor
# 查看验证码相关的键
redis-cli keys "verification_*"
```
### 7.3 邮件发送监控
应用会记录邮件发送的日志，包括：
- 发送成功/失败状态
- 收件人信息
- 发送时间
- 错误信息（如果有）
## 8. 故障排除
### 8.1 Redis 连接问题
**问题**：Redis连接失败
```
Redis连接错误: Error: connect ECONNREFUSED 127.0.0.1:6379
```
**解决方案**：
1. 检查Redis服务状态：`sudo systemctl status redis`
2. 启动Redis服务：`sudo systemctl start redis`
3. 检查防火墙设置
4. 验证Redis配置文件
### 8.2 邮件发送问题
**问题**：邮件发送失败
```
邮件发送失败: Error: Invalid login: 535-5.7.8 Username and Password not accepted
```
**解决方案**：
1. 检查邮箱用户名和密码
2. 确认已启用应用专用密码（Gmail）
3. 检查邮件服务商的SMTP设置
4. 验证网络连接
### 8.3 验证码问题
**问题**：验证码验证失败
**解决方案**：
1. 检查Redis中是否存在验证码：`redis-cli get verification_code:email_verification:test@example.com`
2. 检查验证码是否过期
3. 验证验证码格式（6位数字）
4. 检查应用日志
## 9. 安全建议
### 9.1 邮件服务安全
1. **使用应用专用密码**：不要使用主密码
2. **启用TLS/SSL**：确保邮件传输加密
3. **限制发送频率**：防止邮件轰炸
4. **监控发送量**：避免被标记为垃圾邮件
### 9.2 Redis 安全
1. **设置密码**：`requirepass your_redis_password`
2. **绑定IP**：`bind 127.0.0.1`
3. **禁用危险命令**：`rename-command FLUSHDB ""`
4. **定期备份**：设置Redis数据备份
### 9.3 验证码安全
1. **设置过期时间**：默认5分钟
2. **限制尝试次数**：最多3次
3. **防刷机制**：60秒冷却时间
4. **记录日志**：监控异常行为
## 10. 性能优化
### 10.1 Redis 优化
```redis
# Redis 配置优化
maxmemory 256mb
maxmemory-policy allkeys-lru
save 900 1
save 300 10
save 60 10000
```
### 10.2 邮件发送优化
1. **连接池**：复用SMTP连接
2. **异步发送**：不阻塞主流程
3. **队列机制**：处理大量邮件
4. **失败重试**：自动重试机制
---
*部署完成后，建议进行完整的功能测试，确保所有邮箱验证功能正常工作。*

80
docs/systems/logger/README.md
View File

@@ -1,80 +0,0 @@
# 日志系统
## 概述
项目集成了完整的日志系统，基于 Pino 高性能日志库，提供结构化日志记录、自动敏感信息过滤和多级别日志控制。
## 功能特性
- 🚀 高性能日志记录
- 🔒 自动敏感信息过滤
- 🎯 多级别日志控制
- 🔍 请求上下文绑定
- 📊 结构化日志输出
## 使用示例
### 基础用法
```typescript
import { AppLoggerService } from './core/utils/logger/logger.service';
@Injectable()
export class UserService {
constructor(private readonly logger: AppLoggerService) {}
async createUser(userData: CreateUserDto) {
this.logger.info('开始创建用户', {
operation: 'createUser',
email: userData.email,
timestamp: new Date().toISOString()
});
try {
const user = await this.userRepository.save(userData);
this.logger.info('用户创建成功', {
operation: 'createUser',
userId: user.id,
email: userData.email
});
return user;
} catch (error) {
this.logger.error('用户创建失败', {
operation: 'createUser',
email: userData.email,
error: error.message
}, error.stack);
throw error;
}
}
}
```
## 日志级别
- `error`: 错误信息
- `warn`: 警告信息
- `info`: 一般信息
- `debug`: 调试信息
## 配置
日志配置位于 `src/core/utils/logger/logger.config.ts`，支持：
- 日志级别设置
- 输出格式配置
- 敏感信息过滤规则
- 文件输出配置
## 敏感信息过滤
系统自动过滤以下敏感信息：
- 密码字段
- 令牌信息
- 个人身份信息
- 支付相关信息
详细使用方法请参考：[后端开发规范指南 - 日志系统使用指南](../../backend_development_guide.md#四日志系统使用指南)

363
docs/systems/logger/detailed-specification.md
View File

@@ -1,363 +0,0 @@
# 日志系统详细说明
## 📋 概述
本项目的日志系统基于 Pino 高性能日志库构建，提供完整的日志记录、管理和分析功能。
---
## 🗂️ 日志文件结构
### 开发环境 (`NODE_ENV=development`)
```
logs/
└── dev.log # 开发环境综合日志（所有级别）
```
**输出方式：**
- 🖥️ **控制台**：彩色美化输出，便于开发调试
- 📁 **文件**：保存到 `logs/dev.log`，便于问题追踪
### 生产环境 (`NODE_ENV=production`)
```
logs/
├── app.log # 应用综合日志（info及以上级别）
├── error.log # 错误日志（error和fatal级别）
├── access.log # HTTP访问日志（请求响应记录）
├── app.log.gz # 压缩的历史日志文件
├── error.log.gz # 压缩的历史错误日志
└── access.log.gz # 压缩的历史访问日志
```
**输出方式：**
- 📁 **文件**：分类保存到不同的日志文件
- 🖥️ **控制台**：仅输出 warn 及以上级别（用于容器日志收集）
---
## 📊 日志级别和用途
| 级别 | 数值 | 用途 | 保存位置 | 示例场景 |
|------|------|------|----------|----------|
| **TRACE** | 10 | 极细粒度调试 | dev.log | 循环内变量状态 |
| **DEBUG** | 20 | 开发调试信息 | dev.log | 方法调用参数 |
| **INFO** | 30 | 重要业务操作 | app.log, dev.log | 用户登录成功 |
| **WARN** | 40 | 警告信息 | app.log, dev.log, 控制台 | 参数验证失败 |
| **ERROR** | 50 | 错误信息 | error.log, app.log, 控制台 | 数据库连接失败 |
| **FATAL** | 60 | 致命错误 | error.log, app.log, 控制台 | 系统不可用 |
---
## 🔄 日志轮转和管理
### 自动轮转策略
| 文件类型 | 轮转频率 | 文件大小限制 | 保留时间 | 压缩策略 |
|----------|----------|--------------|----------|----------|
| **app.log** | 每日 | 10MB | 7天 | 7天后压缩 |
| **error.log** | 每日 | 10MB | 30天 | 7天后压缩 |
| **access.log** | 每日 | 50MB | 14天 | 7天后压缩 |
| **dev.log** | 手动 | 无限制 | 无限制 | 不压缩 |
### 定时任务
| 任务 | 执行时间 | 功能 |
|------|----------|------|
| **日志清理** | 每天 02:00 | 删除过期日志文件 |
| **日志压缩** | 每周日 03:00 | 压缩7天前的日志文件 |
| **健康监控** | 每小时 | 监控日志系统状态 |
| **统计报告** | 每天 09:00 | 输出日志统计信息 |
---
## 🚀 如何使用日志系统
### 基本使用
```typescript
import { Injectable } from '@nestjs/common';
import { AppLoggerService } from '../core/utils/logger/logger.service';
@Injectable()
export class UserService {
constructor(private readonly logger: AppLoggerService) {}
async createUser(userData: CreateUserDto) {
// 记录操作开始
this.logger.info('开始创建用户', {
operation: 'createUser',
email: userData.email,
timestamp: new Date().toISOString()
});
try {
const user = await this.userRepository.save(userData);
// 记录成功操作
this.logger.info('用户创建成功', {
operation: 'createUser',
userId: user.id,
email: userData.email,
duration: Date.now() - startTime
});
return user;
} catch (error) {
// 记录错误
this.logger.error('用户创建失败', {
operation: 'createUser',
email: userData.email,
error: error.message
}, error.stack);
throw error;
}
}
}
```
### 请求上下文绑定
```typescript
@Controller('users')
export class UserController {
constructor(private readonly logger: AppLoggerService) {}
@Get(':id')
async getUser(@Param('id') id: string, @Req() req: Request) {
// 绑定请求上下文
const requestLogger = this.logger.bindRequest(req, 'UserController');
requestLogger.info('开始获取用户信息', { userId: id });
try {
const user = await this.userService.findById(id);
requestLogger.info('用户信息获取成功', { userId: id });
return user;
} catch (error) {
requestLogger.error('用户信息获取失败', error.stack, {
userId: id,
reason: error.message
});
throw error;
}
}
}
```
---
## 🔍 日志格式详解
### 开发环境日志格式
```
🕐 2024-12-13 14:30:25 📝 INFO pixel-game-server [UserService] 用户创建成功
operation: "createUser"
userId: "user_123"
email: "user@example.com"
duration: 45
```
### 生产环境日志格式 (JSON)
```json
{
"level": 30,
"time": 1702456225000,
"pid": 12345,
"hostname": "server-01",
"app": "pixel-game-server",
"version": "1.0.0",
"msg": "用户创建成功",
"operation": "createUser",
"userId": "user_123",
"email": "user@example.com",
"duration": 45,
"reqId": "req_1702456225_abc123"
}
```
### HTTP 请求日志格式
```json
{
"level": 30,
"time": 1702456225000,
"req": {
"id": "req_1702456225_abc123",
"method": "POST",
"url": "/api/users",
"headers": {
"host": "localhost:3000",
"user-agent": "Mozilla/5.0...",
"content-type": "application/json"
},
"ip": "127.0.0.1"
},
"res": {
"statusCode": 201,
"responseTime": 45
},
"msg": "POST /api/users completed in 45ms"
}
```
---
## 🛠️ 问题排查指南
### 1. 如何查找特定用户的操作日志？
```bash
# 在日志文件中搜索特定用户ID
grep "userId.*user_123" logs/app.log
# 搜索特定操作
grep "operation.*createUser" logs/app.log
# 搜索特定时间段的日志
grep "2024-12-13 14:" logs/app.log
```
### 2. 如何查找错误日志？
```bash
# 查看所有错误日志
cat logs/error.log
# 查看最近的错误
tail -f logs/error.log
# 搜索特定错误
grep "数据库连接失败" logs/error.log
```
### 3. 如何分析性能问题？
```bash
# 查找响应时间超过1000ms的请求
grep "responseTime.*[0-9][0-9][0-9][0-9]" logs/access.log
# 查找特定接口的性能数据
grep "POST /api/users" logs/access.log | grep responseTime
```
### 4. 如何监控系统健康状态？
```bash
# 查看日志统计信息
grep "日志系统健康状态报告" logs/app.log
# 查看日志清理记录
grep "日志清理任务完成" logs/app.log
# 查看压缩记录
grep "日志压缩任务完成" logs/app.log
```
---
## 📈 日志分析和监控
### 日志统计信息
系统会自动收集以下统计信息：
- **文件数量**：当前日志文件总数
- **总大小**：所有日志文件占用的磁盘空间
- **错误日志数量**：错误级别日志文件数量
- **最旧/最新文件**：日志文件的时间范围
- **平均文件大小**：单个日志文件的平均大小
### 健康监控告警
系统会在以下情况发出警告：
- 📊 **磁盘空间告警**：日志文件总大小超过阈值
- ⚠️ **错误日志告警**：错误日志数量异常增长
- 🔧 **清理失败告警**：日志清理任务执行失败
- 💾 **压缩失败告警**：日志压缩任务执行失败
---
## ⚙️ 配置说明
### 环境变量配置
```bash
# 应用名称
APP_NAME=pixel-game-server
# 环境标识
NODE_ENV=development
# 日志级别
LOG_LEVEL=debug
# 日志目录
LOG_DIR=./logs
# 日志保留天数
LOG_MAX_FILES=7d
# 单个日志文件最大大小
LOG_MAX_SIZE=10m
```
### 高级配置选项
如需自定义日志配置，可以修改 `src/core/utils/logger/logger.config.ts`：
```typescript
// 自定义日志轮转策略
{
target: 'pino-roll',
options: {
file: path.join(logDir, 'app.log'),
frequency: 'daily', // 轮转频率：daily, hourly, weekly
size: '10m', // 文件大小限制
limit: {
count: 7, // 保留文件数量
},
},
}
```
---
## 🚨 注意事项
### 安全考虑
1. **敏感信息过滤**：系统自动过滤密码、token等敏感字段
2. **访问控制**：确保日志文件只有授权用户可以访问
3. **传输加密**：生产环境建议使用加密传输日志
### 性能考虑
1. **异步写入**：Pino 使用异步写入，不会阻塞主线程
2. **日志级别**：生产环境建议使用 info 及以上级别
3. **文件轮转**：及时清理和压缩日志文件，避免占用过多磁盘空间
### 运维建议
1. **监控磁盘空间**：定期检查日志目录的磁盘使用情况
2. **备份重要日志**：对于重要的错误日志，建议定期备份
3. **日志分析**：可以集成 ELK Stack 等日志分析工具
4. **告警设置**：配置日志监控告警，及时发现系统问题
---
## 🔗 相关文档
- [后端开发规范 - 日志系统使用指南](./backend_development_guide.md#四日志系统使用指南)
- [AI 辅助开发规范指南](./AI辅助开发规范指南.md)
- [Pino 官方文档](https://getpino.io/)
- [NestJS Pino 集成文档](https://github.com/iamolegga/nestjs-pino)
---
**💡 提示：使用 [AI 辅助开发指南](./AI辅助开发规范指南.md) 可以让 AI 帮你自动生成符合规范的日志代码！**

334
docs/systems/user-auth/README.md
View File

@@ -1,334 +0,0 @@
# 用户认证系统
## 概述
用户认证系统提供完整的用户注册、登录、密码管理功能，支持传统用户名密码登录和第三方OAuth登录。
## 功能特性
- 🔐 多种登录方式：用户名/邮箱/手机号登录
- 📝 用户注册和信息管理
- 🐙 GitHub OAuth 第三方登录
- 🔄 密码重置和修改
- 🛡️ bcrypt 密码加密
- 🎯 基于角色的权限控制
## 架构设计
### 分层结构
```
src/
├── business/login/ # 业务逻辑层
│ ├── login.controller.ts # HTTP 控制器
│ ├── login.service.ts # 业务服务
│ ├── login.dto.ts # 数据传输对象
│ ├── login.service.spec.ts # 业务服务测试
│ └── login.module.ts # 业务模块
├── core/
│ ├── login_core/ # 核心功能层
│ │ ├── login_core.service.ts # 核心认证逻辑
│ │ ├── login_core.service.spec.ts # 核心服务测试
│ │ └── login_core.module.ts # 核心模块
│ └── db/users/ # 数据访问层
│ ├── users.entity.ts # 用户实体
│ ├── users.service.ts # 用户数据服务
│ └── users.dto.ts # 用户 DTO
```
### 职责分离
#### 1. 业务逻辑层 (Business Layer)
- **位置**: `src/business/login/`
- **职责**:
- 处理HTTP请求和响应
- 数据格式化和验证
- 业务流程控制
- 错误处理和日志记录
#### 2. 核心功能层 (Core Layer)
- **位置**: `src/core/login_core/`
- **职责**:
- 认证核心算法实现
- 密码加密和验证
- 用户查找和匹配
- 令牌生成和验证
#### 3. 数据访问层 (Data Access Layer)
- **位置**: `src/core/db/users/`
- **职责**:
- 数据库操作封装
- 实体关系映射
- 数据完整性保证
- 查询优化
## API 接口
### 用户注册
```bash
POST /auth/register
Content-Type: application/json
{
"username": "testuser",
"password": "password123",
"nickname": "测试用户",
"email": "test@example.com",
"phone": "+8613800138000"
}
```
**响应**:
```json
{
"success": true,
"data": {
"user": {
"id": "1",
"username": "testuser",
"nickname": "测试用户",
"email": "test@example.com",
"phone": "+8613800138000",
"avatar_url": null,
"role": 1,
"created_at": "2025-12-17T10:00:00.000Z"
},
"access_token": "eyJ1c2VySWQiOiIxIiwidXNlcm5hbWUiOiJ0ZXN0dXNlciJ9...",
"is_new_user": true,
"message": "注册成功"
},
"message": "注册成功"
}
```
### 用户登录
```bash
POST /auth/login
Content-Type: application/json
{
"identifier": "testuser", # 支持用户名/邮箱/手机号
"password": "password123"
}
```
### GitHub OAuth登录
```bash
POST /auth/github
Content-Type: application/json
{
"github_id": "12345678",
"username": "githubuser",
"nickname": "GitHub用户",
"email": "github@example.com",
"avatar_url": "https://avatars.githubusercontent.com/u/12345678"
}
```
### 密码重置
```bash
# 1. 发送验证码
POST /auth/forgot-password
{
"identifier": "test@example.com"
}
# 2. 重置密码
POST /auth/reset-password
{
"identifier": "test@example.com",
"verification_code": "123456",
"new_password": "newpassword123"
}
```
### 修改密码
```bash
PUT /auth/change-password
{
"user_id": "1",
"old_password": "password123",
"new_password": "newpassword123"
}
```
## 数据模型
### 用户实体 (Users Entity)
```typescript
{
id: bigint, // 主键ID
username: string, // 用户名（唯一）
email?: string, // 邮箱（唯一，可选）
phone?: string, // 手机号（唯一，可选）
password_hash?: string, // 密码哈希（OAuth用户为空）
nickname: string, // 显示昵称
github_id?: string, // GitHub ID（唯一，可选）
avatar_url?: string, // 头像URL
role: number, // 用户角色（1-普通，9-管理员）
created_at: Date, // 创建时间
updated_at: Date // 更新时间
}
```
### 数据库设计特点
1. **唯一性约束**: username, email, phone, github_id
2. **索引优化**: 主键、唯一索引、角色索引
3. **字符集支持**: utf8mb4，支持emoji
4. **数据类型**: BIGINT主键，VARCHAR字段，DATETIME时间戳
## 安全机制
### 1. 密码安全
- **加密算法**: bcrypt (saltRounds=12)
- **强度验证**: 最少8位，包含字母和数字
- **存储安全**: 只存储哈希值，不存储明文
### 2. 数据验证
- **输入验证**: class-validator装饰器
- **SQL注入防护**: TypeORM参数化查询
- **XSS防护**: 数据转义和验证
### 3. 访问控制
- **令牌机制**: 基于用户信息的访问令牌
- **角色权限**: 基于角色的访问控制（RBAC）
- **会话管理**: 令牌生成和验证
### 4. 错误处理
- **统一异常**: NestJS异常过滤器
- **日志记录**: 操作日志和错误日志
- **信息脱敏**: 敏感信息自动脱敏
## 测试覆盖
### 单元测试
- 核心服务测试：`src/core/login_core/login_core.service.spec.ts`
- 业务服务测试：`src/business/login/login.service.spec.ts`
### 集成测试
- 端到端测试：`test/business/login.e2e-spec.ts`
### 测试用例
- 用户注册和登录流程
- GitHub OAuth认证
- 密码重置和修改
- 数据验证和错误处理
- 安全性测试
## 使用示例
### JavaScript/TypeScript
```javascript
// 用户注册
const registerResponse = await fetch('/auth/register', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
},
body: JSON.stringify({
username: 'testuser',
password: 'password123',
nickname: '测试用户',
email: 'test@example.com'
})
});
const registerData = await registerResponse.json();
console.log(registerData);
// 用户登录
const loginResponse = await fetch('/auth/login', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
},
body: JSON.stringify({
identifier: 'testuser',
password: 'password123'
})
});
const loginData = await loginResponse.json();
console.log(loginData);
```
### curl 命令
```bash
# 用户注册
curl -X POST http://localhost:3000/auth/register \
-H "Content-Type: application/json" \
-d '{
"username": "testuser",
"password": "password123",
"nickname": "测试用户",
"email": "test@example.com"
}'
# 用户登录
curl -X POST http://localhost:3000/auth/login \
-H "Content-Type: application/json" \
-d '{
"identifier": "testuser",
"password": "password123"
}'
```
## 错误处理
### 常见错误代码
- `LOGIN_FAILED`: 登录失败
- `REGISTER_FAILED`: 注册失败
- `GITHUB_OAUTH_FAILED`: GitHub登录失败
- `SEND_CODE_FAILED`: 发送验证码失败
- `RESET_PASSWORD_FAILED`: 密码重置失败
- `CHANGE_PASSWORD_FAILED`: 密码修改失败
### 错误响应格式
```json
{
"success": false,
"message": "错误描述",
"error_code": "ERROR_CODE"
}
```
## 扩展功能
### 计划中的功能
1. **JWT令牌管理**
- 访问令牌和刷新令牌
- 令牌黑名单机制
- 自动刷新功能
2. **多因子认证**
- 短信验证码
- 邮箱验证码
- TOTP应用支持
3. **社交登录扩展**
- 微信登录
- QQ登录
- 微博登录
4. **安全增强**
- 登录失败次数限制
- IP白名单/黑名单
- 设备指纹识别
5. **用户管理**
- 用户状态管理（激活/禁用）
- 用户角色权限细化
- 用户行为日志记录