whale-town-end/docs/systems/logger/detailed-specification.md

日志系统详细说明

📋 概述

本项目的日志系统基于 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	输出日志统计信息

---

🚀 如何使用日志系统

基本使用

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;
    }
  }
}

请求上下文绑定

@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)

{
  "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 请求日志格式

{
  "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. 如何查找特定用户的操作日志？

# 在日志文件中搜索特定用户ID
grep "userId.*user_123" logs/app.log

# 搜索特定操作
grep "operation.*createUser" logs/app.log

# 搜索特定时间段的日志
grep "2024-12-13 14:" logs/app.log

2. 如何查找错误日志？

# 查看所有错误日志
cat logs/error.log

# 查看最近的错误
tail -f logs/error.log

# 搜索特定错误
grep "数据库连接失败" logs/error.log

3. 如何分析性能问题？

# 查找响应时间超过1000ms的请求
grep "responseTime.*[0-9][0-9][0-9][0-9]" logs/access.log

# 查找特定接口的性能数据
grep "POST /api/users" logs/access.log | grep responseTime

4. 如何监控系统健康状态？

# 查看日志统计信息
grep "日志系统健康状态报告" logs/app.log

# 查看日志清理记录
grep "日志清理任务完成" logs/app.log

# 查看压缩记录
grep "日志压缩任务完成" logs/app.log

---

📈 日志分析和监控

日志统计信息

系统会自动收集以下统计信息：

• 文件数量：当前日志文件总数
• 总大小：所有日志文件占用的磁盘空间
• 错误日志数量：错误级别日志文件数量
• 最旧/最新文件：日志文件的时间范围
• 平均文件大小：单个日志文件的平均大小

健康监控告警

系统会在以下情况发出警告：

• 📊 磁盘空间告警：日志文件总大小超过阈值
• ⚠️ 错误日志告警：错误日志数量异常增长
• 🔧 清理失败告警：日志清理任务执行失败
• 💾 压缩失败告警：日志压缩任务执行失败

---

⚙️ 配置说明

环境变量配置

# 应用名称
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：

// 自定义日志轮转策略
{
  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. 告警设置：配置日志监控告警，及时发现系统问题

---

🔗 相关文档

• 后端开发规范 - 日志系统使用指南
• AI 辅助开发规范指南
• Pino 官方文档
• NestJS Pino 集成文档

---

💡 提示：使用 AI 辅助开发指南 可以让 AI 帮你自动生成符合规范的日志代码！