change log

2025-07-28 15:21:37 +08:00
parent 610d0f5475
commit 560c81a8aa
7 changed files with 1351 additions and 12 deletions
--- a/docs/按级别分文件日志系统说明.md
+++ b/docs/按级别分文件日志系统说明.md
@@ -0,0 +1,344 @@
+# 📝 按级别分文件日志系统说明
+
+## 概述
+
+本系统支持按日志级别分文件存储，不同级别的日志写入不同的文件，便于日志管理和分析。
+
+## 功能特性
+
+### ✅ 按级别分文件
+- **Debug级别**: `debug.log` - 调试信息
+- **Info级别**: `info.log` - 一般信息
+- **Warn级别**: `warn.log` - 警告信息
+- **Error级别**: `error.log` - 错误信息
+- **Fatal级别**: `fatal.log` - 致命错误
+- **Panic级别**: `panic.log` - 恐慌错误
+
+### ✅ 独立配置
+- 每个级别可以独立配置文件大小、备份数量、保留天数
+- 支持不同级别的压缩策略
+- 灵活的轮转配置
+
+### ✅ 按日分包支持
+- 支持按日期分包：`logs/2024-01-01/error.log`
+- 传统模式：`logs/error.log`
+
+## 配置说明
+
+### 基础配置
+
+```yaml
+logger:
+    # 基础配置
+    level: info
+    format: json
+    output: "file"
+    log_dir: "/app/logs"
+    use_daily: true
+    
+    # 启用按级别分文件
+    enable_level_separation: true
+    
+    # 各级别配置
+    level_configs:
+        debug:
+            max_size: 50      # 50MB
+            max_backups: 3
+            max_age: 7        # 7天
+            compress: true
+        info:
+            max_size: 100     # 100MB
+            max_backups: 5
+            max_age: 30       # 30天
+            compress: true
+        warn:
+            max_size: 100     # 100MB
+            max_backups: 5
+            max_age: 30       # 30天
+            compress: true
+        error:
+            max_size: 200     # 200MB
+            max_backups: 10
+            max_age: 90       # 90天
+            compress: true
+        fatal:
+            max_size: 100     # 100MB
+            max_backups: 10
+            max_age: 365      # 1年
+            compress: true
+        panic:
+            max_size: 100     # 100MB
+            max_backups: 10
+            max_age: 365      # 1年
+            compress: true
+```
+
+## 日志目录结构
+
+### 按日分包模式
+```
+logs/
+├── 2024-01-01/
+│   ├── debug.log          # 调试日志
+│   ├── debug.log.1        # 调试日志备份
+│   ├── info.log           # 信息日志
+│   ├── info.log.1         # 信息日志备份
+│   ├── warn.log           # 警告日志
+│   ├── warn.log.1         # 警告日志备份
+│   ├── error.log          # 错误日志
+│   ├── error.log.1        # 错误日志备份
+│   ├── fatal.log          # 致命错误日志
+│   └── panic.log          # 恐慌错误日志
+├── 2024-01-02/
+│   ├── debug.log
+│   ├── info.log
+│   ├── warn.log
+│   ├── error.log
+│   ├── fatal.log
+│   └── panic.log
+```
+
+### 传统模式
+```
+logs/
+├── debug.log              # 调试日志
+├── debug.log.1            # 调试日志备份
+├── info.log               # 信息日志
+├── info.log.1             # 信息日志备份
+├── warn.log               # 警告日志
+├── warn.log.1             # 警告日志备份
+├── error.log              # 错误日志
+├── error.log.1            # 错误日志备份
+├── fatal.log              # 致命错误日志
+└── panic.log              # 恐慌错误日志
+```
+
+## 级别配置策略
+
+### 1. Debug级别
+- **用途**: 详细的调试信息
+- **保留策略**: 短期保留（7天）
+- **文件大小**: 较小（50MB）
+- **备份数量**: 较少（3个）
+
+### 2. Info级别
+- **用途**: 一般业务信息
+- **保留策略**: 中期保留（30天）
+- **文件大小**: 中等（100MB）
+- **备份数量**: 中等（5个）
+
+### 3. Warn级别
+- **用途**: 警告信息
+- **保留策略**: 中期保留（30天）
+- **文件大小**: 中等（100MB）
+- **备份数量**: 中等（5个）
+
+### 4. Error级别
+- **用途**: 错误信息
+- **保留策略**: 长期保留（90天）
+- **文件大小**: 较大（200MB）
+- **备份数量**: 较多（10个）
+
+### 5. Fatal级别
+- **用途**: 致命错误
+- **保留策略**: 永久保留（1年）
+- **文件大小**: 中等（100MB）
+- **备份数量**: 较多（10个）
+
+### 6. Panic级别
+- **用途**: 恐慌错误
+- **保留策略**: 永久保留（1年）
+- **文件大小**: 中等（100MB）
+- **备份数量**: 较多（10个）
+
+## 使用方法
+
+### 1. 基本使用
+
+```go
+import "tyapi-server/internal/shared/logger"
+
+// 获取日志器
+log := logger.GetLogger()
+
+// 不同级别的日志会自动写入对应文件
+log.Debug("调试信息", zap.String("component", "user_service"))
+log.Info("用户登录成功", zap.String("user_id", "12345"))
+log.Warn("用户多次登录失败", zap.String("phone", "138****8888"))
+log.Error("数据库连接失败", zap.Error(err))
+log.Fatal("系统无法启动", zap.Error(err))
+log.Panic("严重错误", zap.Error(err))
+```
+
+### 2. 带上下文的日志
+
+```go
+// 从Gin上下文获取日志器
+ctx := c.Request.Context()
+log := logger.GetLogger().WithContext(ctx)
+
+log.Info("处理用户请求",
+    zap.String("action", "user_login"),
+    zap.String("ip", c.ClientIP()),
+)
+```
+
+### 3. 结构化日志字段
+
+```go
+log.Info("业务操作",
+    zap.String("operation", "create_user"),
+    zap.String("user_id", user.ID),
+    zap.Int("age", user.Age),
+    zap.Float64("score", 95.5),
+    zap.Bool("is_active", true),
+    zap.Error(err),
+)
+```
+
+## 日志分析
+
+### 1. 查看特定级别日志
+
+```bash
+# 查看错误日志
+tail -f logs/2024-01-01/error.log
+
+# 查看警告日志
+tail -f logs/2024-01-01/warn.log
+
+# 查看信息日志
+tail -f logs/2024-01-01/info.log
+```
+
+### 2. 统计各级别日志数量
+
+```bash
+# 统计错误日志数量
+wc -l logs/2024-01-01/error.log
+
+# 统计警告日志数量
+wc -l logs/2024-01-01/warn.log
+
+# 统计信息日志数量
+wc -l logs/2024-01-01/info.log
+```
+
+### 3. 搜索特定内容
+
+```bash
+# 在错误日志中搜索特定错误
+grep "数据库连接失败" logs/2024-01-01/error.log
+
+# 在警告日志中搜索特定警告
+grep "用户多次登录失败" logs/2024-01-01/warn.log
+
+# 在信息日志中搜索特定操作
+grep "用户登录成功" logs/2024-01-01/info.log
+```
+
+### 4. 使用jq分析JSON日志
+
+```bash
+# 分析错误日志
+cat logs/2024-01-01/error.log | jq 'select(.level == "error")'
+
+# 统计错误类型
+cat logs/2024-01-01/error.log | jq -r '.message' | sort | uniq -c
+
+# 查看特定用户的错误
+cat logs/2024-01-01/error.log | jq 'select(.user_id == "12345")'
+```
+
+## 监控和告警
+
+### 1. 错误日志监控
+
+```bash
+# 监控错误日志增长
+watch -n 5 'wc -l logs/$(date +%Y-%m-%d)/error.log'
+
+# 监控错误日志大小
+watch -n 5 'ls -lh logs/$(date +%Y-%m-%d)/error.log'
+```
+
+### 2. 告警配置
+
+```bash
+# 检查错误日志是否超过阈值
+if [ $(wc -l < logs/$(date +%Y-%m-%d)/error.log) -gt 1000 ]; then
+    echo "错误日志数量过多，请检查系统状态"
+fi
+
+# 检查错误日志文件大小
+if [ $(stat -c%s logs/$(date +%Y-%m-%d)/error.log) -gt 104857600 ]; then
+    echo "错误日志文件过大，请检查系统状态"
+fi
+```
+
+## 性能优化
+
+### 1. 异步写入
+- 日志写入是异步的，不会阻塞业务逻辑
+- 使用缓冲写入减少I/O操作
+
+### 2. 级别过滤
+- 只记录配置的级别及以上级别的日志
+- 减少不必要的日志输出
+
+### 3. 文件轮转
+- 自动轮转避免单个文件过大
+- 压缩旧日志文件节省磁盘空间
+
+## 最佳实践
+
+### 1. 级别使用规范
+
+- **Debug**: 详细的调试信息（开发环境）
+- **Info**: 重要的业务信息（生产环境）
+- **Warn**: 需要关注但不影响主功能的问题
+- **Error**: 影响功能的错误信息
+- **Fatal**: 系统无法继续运行的错误
+- **Panic**: 程序崩溃的错误
+
+### 2. 日志内容规范
+
+- 记录关键业务操作
+- 包含足够的上下文信息
+- 使用结构化的字段
+- 避免记录敏感信息
+
+### 3. 文件管理规范
+
+- 定期清理旧日志文件
+- 监控日志文件大小
+- 设置合理的轮转策略
+- 备份重要日志
+
+## 故障排除
+
+### 1. 常见问题
+
+**问题**: 某个级别的日志文件没有创建
+**解决**: 检查该级别是否在配置中定义
+
+**问题**: 日志文件权限问题
+**解决**: 确保应用有写入日志目录的权限
+
+**问题**: 磁盘空间不足
+**解决**: 调整日志保留策略，减少保留天数
+
+### 2. 性能问题
+
+**问题**: 日志写入影响性能
+**解决**: 检查是否启用了异步写入
+
+**问题**: 日志文件过大
+**解决**: 调整文件大小限制和轮转策略
+
+## 相关文件
+
+- `internal/shared/logger/level_logger.go` - 按级别分文件日志器实现
+- `internal/config/config.go` - 日志配置结构
+- `configs/env.production.yaml` - 生产环境日志配置
+- `internal/container/container.go` - 依赖注入配置