docs/v1.0/server/guides/logging.md

日志管理指南

概述

项目使用按服务拆分的日志系统，便于问题排查和服务监控。

日志文件结构

server/logs/
├── app.log                # FastAPI 应用日志（API 请求、业务逻辑）
├── celery_ai.log          # AI Worker 日志（图片、视频、配音生成）
├── celery_export.log      # Export Worker 日志（项目导出、视频渲染）
├── celery_beat.log        # Beat 调度器日志（定时任务）
├── error.log              # 所有 ERROR 级别日志（统一收集）
├── app_size.log           # 按大小轮转日志（最大 100MB）
└── *.log.2026-XX-XX       # 历史日志（按日期轮转，保留 30 天）

日志级别

级别	用途	示例
DEBUG	详细调试信息	SQL 查询、函数调用
INFO	常规操作信息	任务启动、完成状态
WARNING	警告信息	重试操作、性能问题
ERROR	错误信息	异常、失败操作
CRITICAL	严重错误	服务崩溃、数据丢失

常用命令

查看日志

# 实时查看 FastAPI 应用日志
tail -f logs/app.log

# 实时查看 AI Worker 日志
tail -f logs/celery_ai.log

# 实时查看 Export Worker 日志
tail -f logs/celery_export.log

# 实时查看 Beat 调度器日志
tail -f logs/celery_beat.log

# 查看所有错误日志
tail -f logs/error.log

搜索日志

# 搜索 AI 任务错误
grep ERROR logs/celery_ai.log

# 搜索特定任务 ID
grep "task_id=abc123" logs/*.log

# 搜索用户相关日志
grep "user_id=019c5a0b" logs/app.log

# 搜索最近 1 小时的错误
grep "$(date -u +%Y-%m-%d\ %H)" logs/error.log

日志分析

# 统计 API 请求数量
grep "GET\|POST\|PUT\|DELETE" logs/app.log | wc -l

# 统计错误数量
grep -c ERROR logs/error.log

# 查看最频繁的错误
grep ERROR logs/error.log | sort | uniq -c | sort -rn | head -10

# 分析 AI 任务耗时
grep "completed in" logs/celery_ai.log

日志清理

# 删除 30 天前的历史日志
find logs/ -name "*.log.2026-*" -mtime +30 -delete

# 压缩历史日志
tar czf logs_archive_$(date +%Y%m%d).tar.gz logs/*.log.2026-*

# 清空当前日志（保留文件）
> logs/app.log
> logs/celery_ai.log
> logs/celery_export.log
> logs/celery_beat.log

日志轮转配置

按时间轮转（默认）

• 轮转周期：每天午夜（00:00）
• 备份数量：30 天
• 命名格式：app.log.2026-02-14

按大小轮转

• 最大文件大小：100 MB
• 备份数量：5 个
• 文件名：app_size.log

容器内日志查看

# 查看 FastAPI 应用日志
docker exec jointo-server-app tail -f /app/logs/app.log

# 查看 Celery AI Worker 日志
docker exec jointo-server-celery-ai tail -f /app/logs/celery_ai.log

# 查看 Celery Export Worker 日志
docker exec jointo-server-celery-export tail -f /app/logs/celery_export.log

# 查看容器标准输出（包含启动日志）
docker logs -f jointo-server-app
docker logs -f jointo-server-celery-ai
docker logs -f jointo-server-celery-export
docker logs -f jointo-server-celery-beat

问题排查场景

场景 1：AI 图片生成失败

# 1. 查看 AI Worker 日志
tail -f logs/celery_ai.log

# 2. 搜索错误信息
grep ERROR logs/celery_ai.log | tail -20

# 3. 查找特定任务
grep "generate_image_task" logs/celery_ai.log

# 4. 查看 API 触发日志
grep "generate_image" logs/app.log

场景 2：导出任务超时

# 1. 查看 Export Worker 日志
tail -f logs/celery_export.log

# 2. 查找超时任务
grep "timeout\|TimeoutError" logs/celery_export.log

# 3. 检查队列积压
docker exec jointo-server-rabbitmq rabbitmqctl list_queues

# 4. 查看 Worker 状态
docker logs jointo-server-celery-export

场景 3：定时任务未执行

# 1. 查看 Beat 调度器日志
tail -f logs/celery_beat.log

# 2. 搜索任务调度记录
grep "Scheduler" logs/celery_beat.log

# 3. 检查 Beat 容器状态
docker ps | grep beat
docker logs jointo-server-celery-beat

场景 4：API 请求异常

# 1. 查看 FastAPI 应用日志
tail -f logs/app.log

# 2. 搜索特定 API 路径
grep "/api/v1/storyboard" logs/app.log

# 3. 查找 5xx 错误
grep "500\|502\|503\|504" logs/app.log

# 4. 查看详细错误信息
grep ERROR logs/error.log | tail -20

日志监控告警（生产环境）

推荐工具

• ELK Stack：Elasticsearch + Logstash + Kibana
• Loki + Grafana：轻量级日志聚合
• 云服务：阿里云 SLS、AWS CloudWatch

告警规则建议

# 错误率告警
- 条件：ERROR 日志超过 100 条/小时
- 级别：警告

# AI 任务失败率告警
- 条件：celery_ai.log 中 ERROR 超过 10 条/小时
- 级别：严重

# 导出任务超时告警
- 条件：celery_export.log 中 timeout 出现
- 级别：警告

# 磁盘空间告警
- 条件：logs 目录超过 10GB
- 级别：警告

日志格式说明

标准日志格式

时间戳 | 级别 | 模块:函数:行号 | request_id=xxx | user_id=xxx | 消息内容

示例

2026-02-14 03:21:14 | INFO | app.tasks.ai_tasks:generate_image_task:45 | request_id=abc123 | user_id=019c5a0b | 图片生成任务启动

字段说明

• 时间戳：YYYY-MM-DD HH:MM:SS 格式
• 级别：DEBUG/INFO/WARNING/ERROR/CRITICAL
• 模块：app.tasks.ai_tasks
• 函数：generate_image_task
• 行号：45
• request_id：请求追踪 ID（跨服务追踪）
• user_id：用户 ID（业务追踪）
• 消息内容：实际日志信息

最佳实践

1. 日志级别使用

# ✅ 正确
logger.info("任务启动: task_id=%s", task_id)
logger.error("任务失败: %s", error, exc_info=True)

# ❌ 错误
logger.info("任务失败")  # 应该使用 ERROR
logger.debug("用户登录成功")  # 应该使用 INFO

2. 敏感信息处理

# ✅ 正确：脱敏处理
logger.info("用户登录: phone=%s", phone[-4:])

# ❌ 错误：泄露敏感信息
logger.info("用户密码: %s", password)
logger.info("API Key: %s", api_key)

3. 异常日志记录

# ✅ 正确：包含堆栈信息
try:
    do_something()
except Exception as e:
    logger.error("操作失败", exc_info=True)

# ❌ 错误：丢失堆栈信息
except Exception as e:
    logger.error(f"操作失败: {e}")

4. 结构化日志

# ✅ 正确：使用占位符
logger.info("任务完成: task_id=%s, duration=%dms", task_id, duration)

# ❌ 错误：字符串拼接
logger.info(f"任务完成: task_id={task_id}, duration={duration}ms")

日志备份策略

本地备份

#!/bin/bash
# 每天备份日志

BACKUP_DIR="/backup/logs"
DATE=$(date +%Y%m%d)

# 压缩当天日志
tar czf "${BACKUP_DIR}/logs_${DATE}.tar.gz" logs/*.log

# 删除 7 天前的备份
find "${BACKUP_DIR}" -name "logs_*.tar.gz" -mtime +7 -delete

远程备份

# 上传到 S3（阿里云 OSS）
ossutil cp logs_20260214.tar.gz oss://your-bucket/logs/

# 上传到 NAS
rsync -avz logs/ user@nas:/backup/logs/

常见问题

Q1: 日志文件过大导致磁盘满

解决方案：

# 1. 检查磁盘使用
df -h

# 2. 查找大文件
du -sh logs/* | sort -rh | head -10

# 3. 清理历史日志
find logs/ -name "*.log.2026-*" -mtime +7 -delete

# 4. 调整日志级别（临时）
# 在 .env 中设置：LOG_LEVEL=WARNING

Q2: 找不到特定日志

排查步骤：

# 1. 确认日志文件存在
ls -lh logs/

# 2. 检查容器挂载
docker inspect jointo-server-app | grep -A 10 Mounts

# 3. 查看容器内日志
docker exec jointo-server-app ls -lh /app/logs/

# 4. 检查日志配置
docker exec jointo-server-app env | grep LOG

Q3: 日志时区不一致

说明：

• 容器内使用 UTC 时区
• 宿主机使用本地时区
• 建议统一使用 UTC，便于分布式系统日志关联

查看时区：

# 容器内
docker exec jointo-server-app date

# 宿主机
date

相关文档

• 基础设施和部署
• 日志规范
• 后端开发规范