docs/v1.0/server/changelogs/2026-02-14-logging-separation.md

Changelog: 日志系统按服务拆分

日期: 2026-02-14
类型: 功能增强
影响范围: 后端日志系统
状态: ✅ 已完成

---

变更概述

将统一的 app.log 拆分为按服务区分的独立日志文件，便于生产环境问题排查和服务监控。

变更详情

修改文件

1. server/app/core/logging.py
   • ✅ 新增 get_log_filename() 函数：根据进程类型自动识别日志文件名
   • ✅ 修改 setup_logging() 函数：使用动态日志文件名
   • ✅ 更新日志初始化信息：显示当前使用的日志文件

新增文档

2. docs/server/guides/logging.md
   • ✅ 日志文件结构说明
   • ✅ 常用命令参考
   • ✅ 问题排查场景
   • ✅ 最佳实践指南

日志文件变化

变更前

logs/
├── app.log          # 所有服务混合
├── error.log        # 错误日志
└── app_size.log     # 按大小轮转

变更后

logs/
├── app.log              # FastAPI 应用日志
├── celery_ai.log        # AI Worker 日志（新增）
├── celery_export.log    # Export Worker 日志（新增）
├── celery_beat.log      # Beat 调度器日志（新增）
├── error.log            # 错误日志（保持）
└── app_size.log         # 按大小轮转（保持）

日志文件自动识别逻辑

def get_log_filename() -> str:
    """根据进程命令行参数自动识别日志文件名"""
    
    # Celery Beat 调度器
    if 'beat' in sys.argv:
        return 'celery_beat.log'
    
    # Celery AI Worker (队列: ai)
    if '-Q ai' in sys.argv:
        return 'celery_ai.log'
    
    # Celery Export Worker (队列: export)
    if '-Q export' in sys.argv:
        return 'celery_export.log'
    
    # 默认 FastAPI 应用
    return 'app.log'

使用示例

实时监控各服务

# FastAPI 应用
tail -f logs/app.log

# AI 任务处理
tail -f logs/celery_ai.log

# 导出任务处理
tail -f logs/celery_export.log

# 定时任务调度
tail -f logs/celery_beat.log

# 所有错误
tail -f logs/error.log

问题排查

# AI 图片生成失败
grep ERROR logs/celery_ai.log | tail -20

# 导出任务超时
grep "timeout\|TimeoutError" logs/celery_export.log

# API 请求错误
grep "500\|502\|503\|504" logs/app.log

向后兼容性

• ✅ 历史日志（app.log.2026-XX-XX）保持不变
• ✅ 错误日志（error.log）继续收集所有 ERROR 级别日志
• ✅ 日志轮转策略保持一致（每日午夜，保留 30 天）
• ✅ 日志格式完全兼容

测试验证

验证步骤

# 1. 重启容器
docker compose restart

# 2. 等待 5 秒
sleep 5

# 3. 检查日志文件
ls -lh logs/ | grep -E "celery|app.log"

# 4. 验证日志内容
cat logs/celery_ai.log
cat logs/celery_export.log
cat logs/celery_beat.log
cat logs/app.log

验证结果

✅ celery_ai.log - 已创建，包含 AI Worker 初始化日志
✅ celery_export.log - 已创建，包含 Export Worker 初始化日志
✅ celery_beat.log - 已创建，包含 Beat 调度器初始化日志
✅ app.log - 保持原有功能，仅包含 FastAPI 应用日志
✅ error.log - 继续收集所有服务的错误日志

优势

问题排查

• 🔍 快速定位：直接查看对应服务的日志文件
• 📊 独立分析：不同服务日志互不干扰
• 🎯 精准搜索：减少无关日志干扰

运维监控

• 📈 独立监控：可针对特定服务设置告警规则
• 🔔 精准告警：AI 任务失败不会被其他日志淹没
• 📉 性能分析：单独分析 AI/Export 任务耗时

日志管理

• 💾 存储优化：可针对不同服务设置不同保留策略
• 🗂️ 分类清晰：便于日志归档和备份
• 🔄 轮转灵活：AI 日志可设置更短保留期（日志量大）

注意事项

1. 磁盘空间

• ⚠️ 日志文件数量增加（4 个主日志 + 历史日志）
• ⚠️ 总体积不变（只是拆分），但需要预留足够空间
• 💡 建议定期清理 7 天前的历史日志

2. 日志采集

如果使用日志采集工具（如 Filebeat、Fluentd），需要更新配置：

# 旧配置
paths:
  - /app/logs/app.log

# 新配置
paths:
  - /app/logs/app.log
  - /app/logs/celery_ai.log
  - /app/logs/celery_export.log
  - /app/logs/celery_beat.log

3. 日志聚合

使用 ELK/Loki 等日志聚合工具时，建议添加 service 标签：

# Filebeat 配置示例
- type: log
  paths:
    - /app/logs/celery_ai.log
  fields:
    service: celery-ai
    
- type: log
  paths:
    - /app/logs/celery_export.log
  fields:
    service: celery-export

回滚方案

如果需要回滚到统一日志：

# 修改 app/core/logging.py
def get_log_filename() -> str:
    """所有服务使用统一日志文件"""
    return 'app.log'

然后重启容器：

docker compose restart

后续优化建议

短期（1-2 周）

• 观察日志文件大小增长情况
• 根据实际使用调整保留策略
• 添加日志监控告警规则

中期（1-2 月）

• 接入日志聚合工具（ELK/Loki）
• 实施自动化日志备份
• 建立日志分析 Dashboard

长期（3-6 月）

• 实现日志脱敏自动化
• 建立日志审计机制
• 优化日志查询性能

相关文档

• 日志管理指南
• 基础设施和部署
• 日志规范

负责人

• 实施: Claude AI Assistant
• 审核: 待定
• 部署: 2026-02-14

---

变更状态: ✅ 已完成并验证