tyapi-server/docs/按级别分文件日志系统说明.md

# 📝 按级别分文件日志系统说明

## 概述

本系统支持按日志级别分文件存储，不同级别的日志写入不同的文件，便于日志管理和分析。

## 功能特性

### ✅ 按级别分文件
- **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` - 依赖注入配置