tyapi-server/docs/日志系统说明.md

📝 日志系统说明

概述

本项目使用增强的日志系统，支持按日分包和按大小分包，使用 lumberjack 进行日志轮转管理。

功能特性

✅ 按日分包

• 日志按日期自动分包存储
• 目录结构：logs/2024-01-01/app.log
• 便于按日期查找和管理日志

✅ 按大小分包

• 单个日志文件最大大小限制（默认100MB）
• 超过大小限制时自动创建新文件
• 文件命名：app.log, app.log.1, app.log.2 等

✅ 自动轮转

• 支持压缩旧日志文件
• 自动删除超过保留期限的日志
• 限制备份文件数量

✅ 生产环境持久化

• 日志目录挂载到宿主机 ./logs
• 容器重启后日志不丢失
• 便于日志收集和分析

配置说明

基础配置 (config.yaml)

logger:
    level: "info"           # 日志级别
    format: "console"       # 日志格式 (console/json)
    output: "stdout"        # 输出目标 (stdout/stderr/file)
    log_dir: "logs"         # 日志目录
    max_size: 100          # 单个文件最大大小(MB)
    max_backups: 3         # 最大备份文件数
    max_age: 7             # 最大保留天数
    compress: true         # 是否压缩
    use_color: true        # 是否使用彩色输出
    use_daily: false       # 是否按日分包

生产环境配置 (configs/env.production.yaml)

logger:
    level: warn            # 生产环境只记录警告及以上级别
    format: json           # JSON格式便于日志分析
    output: "file"         # 输出到文件
    log_dir: "/app/logs"   # 容器内日志目录
    max_size: 100         # 100MB
    max_backups: 5        # 5个备份文件
    max_age: 30           # 保留30天
    compress: true        # 启用压缩
    use_daily: true       # 启用按日分包

日志目录结构

按日分包模式

logs/
├── 2024-01-01/
│   ├── app.log          # 当前日志文件
│   ├── app.log.1        # 第一个备份文件
│   ├── app.log.2        # 第二个备份文件
│   └── app.log.3.gz     # 压缩的备份文件
├── 2024-01-02/
│   ├── app.log
│   └── app.log.1
└── 2024-01-03/
    └── app.log

传统模式

logs/
├── app.log              # 当前日志文件
├── app.log.1            # 第一个备份文件
├── app.log.2            # 第二个备份文件
└── app.log.3.gz         # 压缩的备份文件

日志级别

级别	说明	使用场景
debug	调试信息	开发环境详细调试
info	一般信息	业务流程关键节点
warn	警告信息	需要注意但不影响功能
error	错误信息	业务逻辑错误
fatal	致命错误	系统无法继续运行
panic	恐慌错误	程序崩溃

日志格式

JSON格式（生产环境）

{
  "timestamp": "2024-01-01T12:00:00Z",
  "level": "info",
  "message": "用户注册成功",
  "user_id": "12345",
  "phone": "138****8888",
  "request_id": "req-123456",
  "caller": "user_handler.go:45"
}

控制台格式（开发环境）

2024-01-01T12:00:00Z    INFO    用户注册成功    {"user_id": "12345", "phone": "138****8888"}

使用方法

1. 查看日志

# 查看实时日志
docker logs -f tyapi-app-prod

# 查看最近的日志
docker logs --tail 100 tyapi-app-prod

# 查看宿主机日志文件
tail -f logs/2024-01-01/app.log

# 查看错误日志
grep "ERROR" logs/2024-01-01/app.log

2. 日志管理

# 查看日志统计信息
./scripts/log-manager.sh stats

# 查看日志目录大小
./scripts/log-manager.sh size

# 列出所有日志文件
./scripts/log-manager.sh list

# 清理旧日志文件
./scripts/log-manager.sh clean

3. 日志分析

# 使用jq分析JSON日志
cat logs/2024-01-01/app.log | jq 'select(.level == "error")'

# 统计错误类型
cat logs/2024-01-01/app.log | jq -r '.level' | sort | uniq -c

# 查看特定用户的请求
cat logs/2024-01-01/app.log | jq 'select(.user_id == "12345")'

代码示例

基本日志记录

import "tyapi-server/internal/shared/logger"

// 获取日志器
log := logger.GetLogger()

// 记录不同级别的日志
log.Info("用户登录成功", logger.String("user_id", "12345"))
log.Warn("用户多次登录失败", logger.String("phone", "138****8888"))
log.Error("数据库连接失败", logger.Error(err))

带上下文的日志

// 从Gin上下文获取日志器
ctx := c.Request.Context()
log := logger.GetLogger().WithContext(ctx)

log.Info("处理用户请求",
    logger.String("action", "user_login"),
    logger.String("ip", c.ClientIP()),
)

结构化日志字段

log.Info("业务操作",
    logger.String("operation", "create_user"),
    logger.String("user_id", user.ID),
    logger.Int("age", user.Age),
    logger.Float64("score", 95.5),
    logger.Bool("is_active", true),
    logger.Error(err),
)

监控和告警

1. 日志监控

• 使用 ELK Stack (Elasticsearch + Logstash + Kibana)
• 或使用 Grafana + Loki
• 实时监控错误日志和性能指标

2. 告警配置

• 错误日志数量告警
• 日志文件大小告警
• 磁盘空间告警

3. 性能监控

# 监控日志写入性能
iostat -x 1

# 监控磁盘使用情况
df -h logs/

# 监控日志文件增长
watch -n 1 'ls -lh logs/$(date +%Y-%m-%d)/app.log'

故障排除

常见问题

1. 日志文件权限问题

   # 修复权限
   chmod -R 755 logs/
   chown -R $(whoami) logs/
   

2. 磁盘空间不足

   # 清理旧日志
   ./scripts/log-manager.sh clean
   
   # 检查磁盘使用情况
   df -h
   

3. 日志轮转失败

   # 检查lumberjack配置
   # 确保有足够的磁盘空间
   # 检查文件权限
   

性能优化

1. 异步日志写入

   • 使用缓冲写入减少I/O操作
   • 批量写入提高性能

2. 日志级别控制

   • 生产环境使用 warn 级别
   • 减少不必要的日志输出

3. 定期清理

   • 设置合理的保留期限
   • 定期清理旧日志文件

最佳实践

1. 日志内容

• ✅ 记录关键业务操作
• ✅ 包含足够的上下文信息
• ✅ 使用结构化的字段
• ❌ 避免记录敏感信息
• ❌ 避免过度详细的调试信息

2. 日志管理

• ✅ 定期清理旧日志
• ✅ 监控日志文件大小
• ✅ 设置合理的轮转策略
• ✅ 备份重要日志

3. 性能考虑

• ✅ 使用异步日志写入
• ✅ 合理设置日志级别
• ✅ 避免在循环中记录日志
• ✅ 使用结构化日志字段

相关文件

• internal/shared/logger/logger.go - 日志系统核心实现
• internal/config/config.go - 日志配置结构
• config.yaml - 基础日志配置
• configs/env.production.yaml - 生产环境日志配置
• docker-compose.prod.yml - Docker日志卷挂载配置
• scripts/log-manager.sh - 日志管理脚本