From f980e40fb0c146a1dc0a0c70d972f14bd09010fe Mon Sep 17 00:00:00 2001 From: moyin <244344649@qq.com> Date: Sat, 13 Dec 2025 16:44:28 +0800 Subject: [PATCH] =?UTF-8?q?docs=EF=BC=9A=E6=96=B0=E5=A2=9E=E6=97=A5?= =?UTF-8?q?=E5=BF=97=E7=B3=BB=E7=BB=9F=E8=AF=A6=E7=BB=86=E4=BD=BF=E7=94=A8?= =?UTF-8?q?=E8=AF=B4=E6=98=8E?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 提供完整的日志文件结构和格式说明 - 包含开发和生产环境的配置差异 - 添加问题排查和日志分析指南 - 提供实用的使用示例和最佳实践 - 说明定时任务和健康监控功能 --- docs/日志系统详细说明.md | 363 +++++++++++++++++++++++++++++++ 1 file changed, 363 insertions(+) create mode 100644 docs/日志系统详细说明.md diff --git a/docs/日志系统详细说明.md b/docs/日志系统详细说明.md new file mode 100644 index 0000000..1e100bb --- /dev/null +++ b/docs/日志系统详细说明.md @@ -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 帮你自动生成符合规范的日志代码！** \ No newline at end of file