tyapi-server/docs/日志系统配置示例.md

# 📝 日志系统配置示例

## 概述

新的日志系统完全基于配置文件，所有配置都在 `config.yaml` 中设置，容器代码保持简洁。

## 🎯 完整配置示例

```yaml
# 🚀 日志系统配置 - 基于 Zap 官方推荐
logger:
    # 基础配置
    level: "info"                    # 日志级别: debug, info, warn, error, fatal, panic
    format: "json"                   # 输出格式: json, console
    output: "file"                   # 输出方式: stdout, stderr, file
    log_dir: "logs"                  # 日志目录
    use_daily: true                  # 是否按日分包
    use_color: false                 # 是否使用彩色输出（仅console格式有效）
    
    # 文件配置
    max_size: 100                    # 单个文件最大大小(MB)
    max_backups: 5                   # 最大备份文件数
    max_age: 30                      # 最大保留天数
    compress: true                    # 是否压缩
    
    # 高级功能
    enable_level_separation: true    # 是否启用按级别分文件
    enable_request_logging: true     # 是否启用请求日志
    enable_performance_log: 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
```

## 🔧 环境特定配置

### 开发环境配置

```yaml
# 开发环境 - 详细日志，控制台输出
logger:
    level: "debug"
    format: "console"
    output: "stdout"
    use_daily: false
    use_color: true
    enable_level_separation: false
    development: true
```

### 生产环境配置

```yaml
# 生产环境 - 精简日志，文件输出
logger:
    level: "warn"
    format: "json"
    output: "file"
    log_dir: "/app/logs"
    use_daily: true
    use_color: false
    enable_level_separation: true
    development: false
    
    # 生产环境文件配置
    max_size: 200
    max_backups: 10
    max_age: 90
    compress: true
    
    # 生产环境级别配置
    level_configs:
        warn:
            max_size: 200
            max_backups: 10
            max_age: 90
            compress: true
        error:
            max_size: 500
            max_backups: 20
            max_age: 180
            compress: true
        fatal:
            max_size: 100
            max_backups: 10
            max_age: 365
            compress: true
```

## 📊 配置字段说明

### 基础配置字段

| 字段 | 类型 | 说明 | 默认值 |
|------|------|------|--------|
| `level` | string | 日志级别 | "info" |
| `format` | string | 输出格式 | "json" |
| `output` | string | 输出方式 | "stdout" |
| `log_dir` | string | 日志目录 | "logs" |
| `use_daily` | bool | 是否按日分包 | false |
| `use_color` | bool | 是否使用彩色输出 | false |

### 文件配置字段

| 字段 | 类型 | 说明 | 默认值 |
|------|------|------|--------|
| `max_size` | int | 单个文件最大大小(MB) | 100 |
| `max_backups` | int | 最大备份文件数 | 5 |
| `max_age` | int | 最大保留天数 | 30 |
| `compress` | bool | 是否压缩 | true |

### 高级功能字段

| 字段 | 类型 | 说明 | 默认值 |
|------|------|------|--------|
| `enable_level_separation` | bool | 是否启用按级别分文件 | false |
| `enable_request_logging` | bool | 是否启用请求日志 | false |
| `enable_performance_log` | bool | 是否启用性能日志 | false |

### 级别配置字段

| 字段 | 类型 | 说明 | 默认值 |
|------|------|------|--------|
| `max_size` | int | 单个文件最大大小(MB) | 无 |
| `max_backups` | int | 最大备份文件数 | 无 |
| `max_age` | int | 最大保留天数 | 无 |
| `compress` | bool | 是否压缩 | 无 |

## 🚀 配置最佳实践

### 1. 按环境配置

```yaml
# 开发环境
logger:
    level: "debug"
    format: "console"
    output: "stdout"
    use_color: true
    enable_level_separation: false

# 测试环境
logger:
    level: "info"
    format: "json"
    output: "file"
    use_daily: true
    enable_level_separation: true

# 生产环境
logger:
    level: "warn"
    format: "json"
    output: "file"
    use_daily: true
    enable_level_separation: true
    max_size: 200
    max_backups: 10
    max_age: 90
```

### 2. 按级别配置

```yaml
logger:
    enable_level_separation: true
    level_configs:
        # 调试日志 - 小文件，短期保留
        debug:
            max_size: 50
            max_backups: 3
            max_age: 7
            compress: true
        
        # 信息日志 - 中等文件，中期保留
        info:
            max_size: 100
            max_backups: 5
            max_age: 30
            compress: true
        
        # 警告日志 - 中等文件，中期保留
        warn:
            max_size: 100
            max_backups: 5
            max_age: 30
            compress: true
        
        # 错误日志 - 大文件，长期保留
        error:
            max_size: 200
            max_backups: 10
            max_age: 90
            compress: true
        
        # 致命错误 - 中等文件，长期保留
        fatal:
            max_size: 100
            max_backups: 10
            max_age: 365
            compress: true
```

### 3. 性能优化配置

```yaml
logger:
    # 生产环境性能优化
    level: "warn"                    # 只记录警告及以上级别
    format: "json"                   # JSON格式便于日志分析
    output: "file"                   # 文件输出避免控制台性能影响
    use_daily: true                  # 按日分包便于管理
    enable_level_separation: true    # 按级别分文件便于分析
    
    # 文件轮转优化
    max_size: 200                    # 较大的文件大小减少轮转频率
    max_backups: 10                  # 适中的备份数量
    max_age: 90                      # 90天保留期平衡存储和分析需求
    compress: true                    # 启用压缩节省存储空间
```

## 🔍 配置验证

### 1. 必需字段

以下字段是必需的，如果未设置将使用默认值：

- `level`: 日志级别
- `format`: 输出格式
- `output`: 输出方式

### 2. 可选字段

以下字段是可选的，如果未设置将使用系统默认值：

- `log_dir`: 日志目录
- `use_daily`: 是否按日分包
- `use_color`: 是否使用彩色输出
- `max_size`: 文件大小限制
- `max_backups`: 备份文件数量
- `max_age`: 文件保留天数
- `compress`: 是否压缩

### 3. 条件字段

以下字段在特定条件下是必需的：

- 当 `output: "file"` 时，建议设置 `log_dir`
- 当 `enable_level_separation: true` 时，建议设置 `level_configs`
- 当 `format: "console"` 时，`use_color` 才有效

## 📝 配置迁移指南

### 从旧配置迁移

如果您之前使用的是旧版本的日志配置，可以按照以下方式迁移：

#### 旧配置
```yaml
# 旧版本配置
logging:
    level: "info"
    file: "logs/app.log"
    max_size: 100
    max_backups: 3
```

#### 新配置
```yaml
# 新版本配置
logger:
    level: "info"
    output: "file"
    log_dir: "logs"
    max_size: 100
    max_backups: 3
    format: "json"
    use_daily: false
```

## 🎉 总结

新的日志系统配置完全基于 `config.yaml` 文件，具有以下特点：

1. **配置集中**: 所有日志配置都在一个地方管理
2. **环境友好**: 支持不同环境的配置
3. **灵活性强**: 支持按级别分文件、按日分包等高级功能
4. **性能优化**: 基于 Zap 官方最佳实践
5. **易于维护**: 配置结构清晰，易于理解和修改

通过合理的配置，您可以获得高性能、结构化的日志系统，满足开发、测试和生产环境的各种需求！