forked from datawhale/whale-town-end
e58cc57769
- 将日志系统文档移动到 docs/systems/logger/detailed-specification.md - 将邮箱验证部署指南移动到 docs/systems/email-verification/deployment-guide.md - 创建邮箱验证系统完整文档 docs/systems/email-verification/README.md - 按功能模块组织文档，提高可维护性
363 lines
9.0 KiB
Markdown
363 lines
9.0 KiB
Markdown
# 日志系统详细说明
|
||
|
||
## 📋 概述
|
||
|
||
本项目的日志系统基于 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 帮你自动生成符合规范的日志代码！** |