# 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         # 按大小轮转（保持）
```

## 日志文件自动识别逻辑

```python
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'
```

## 使用示例

### 实时监控各服务

```bash
# 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
```

### 问题排查

```bash
# 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 天）
- ✅ 日志格式完全兼容

## 测试验证

### 验证步骤

```bash
# 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），需要更新配置：

```yaml
# 旧配置
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` 标签：

```yaml
# 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
```

## 回滚方案

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

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

然后重启容器：

```bash
docker compose restart
```

## 后续优化建议

### 短期（1-2 周）

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

### 中期（1-2 月）

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

### 长期（3-6 月）

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

## 相关文档

- [日志管理指南](../guides/logging.md)
- [基础设施和部署](../../../.claude/skills/jointo-tech-stack/references/infrastructure.md)
- [日志规范](../../../.claude/skills/jointo-tech-stack/references/logging.md)

## 负责人

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

---

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