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

📝 日志系统配置示例

概述

新的日志系统完全基于配置文件，所有配置都在 config.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

🔧 环境特定配置

开发环境配置

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

生产环境配置

# 生产环境 - 精简日志，文件输出
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. 按环境配置

# 开发环境
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. 按级别配置

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. 性能优化配置

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 才有效

📝 配置迁移指南

从旧配置迁移

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

旧配置

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

新配置

# 新版本配置
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. 易于维护: 配置结构清晰，易于理解和修改

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