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

docs：重新组织系统文档结构

Browse Source 
- 将日志系统文档移动到 docs/systems/logger/detailed-specification.md
- 将邮箱验证部署指南移动到 docs/systems/email-verification/deployment-guide.md
- 创建邮箱验证系统完整文档 docs/systems/email-verification/README.md
- 按功能模块组织文档，提高可维护性
This commit is contained in:
moyin
2025-12-17 20:20:00 +08:00
parent 0065357fa5
commit e58cc57769
3 changed files with 581 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -0,0 +1,363 @@
# 日志系统详细说明
## 📋 概述
本项目的日志系统基于 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 帮你自动生成符合规范的日志代码！**