监控与日志 - 邮轮穿舱件管理系统后台

概述

本文档详细分析邮轮穿舱件管理系统后台的监控指标、日志分析和性能追踪方法，特别关注errors.log的使用和系统日志架构。该系统采用FastAPI框架构建，具有完整的日志记录、异常处理和性能监控机制。

系统日志架构

日志系统组件关系

flowchart TD
    A[HTTP请求] --> B[GlobalExceptionMiddleware]
    B --> C[路由处理]
    C --> D[业务逻辑]
    D --> E[数据库操作]
    
    B --> F[异常捕获]
    F --> G[日志记录]
    E --> H[访问日志]
    
    G --> I[控制台输出]
    G --> J[文件日志]
    H --> K[数据库存储]
    
    I --> L[实时监控]
    J --> M[日志文件]
    K --> N[审计分析]
    
    style G fill:#bbf
    style H fill:#bbf
    style J fill:#f9f

核心日志组件

系统采用三层日志记录架构：

应用日志 - 使用Loguru库记录运行时信息
访问日志 - 存储在数据库中的操作审计记录
错误日志 - 专门的错误跟踪文件

日志配置分析

Loguru日志配置

系统使用Loguru作为主要日志记录工具，配置位于 [app/core/loggers.py](git_repository_url/app/core/loggers.py)：

# 日志格式配置
LOG_FORMAT = (
    "<green>{time:YYYY-MM-DD HH:mm:ss}</green> | "
    "<level>{level: <8}</level> | "
    "<cyan>{name}</cyan>:<cyan>{function}</cyan>:<cyan>{line}</cyan> - "
    "<level>{message}</level>"
)

# 文件日志配置
_logger.add(
    str(LOG_DIR / "fastapi_{time:YYYY-MM-DD}.log"),
    rotation="00:00",  # 每天0点轮转
    retention="7 days",  # 保留7天
    compression="zip",  # 压缩存储
    level="DEBUG" if debug else "INFO",
    format=LOG_FORMAT,
    encoding="utf-8",
    enqueue=True,  # 线程安全
)

关键特性

时间轮转：每天生成新的日志文件
自动压缩：旧日志文件自动压缩为zip格式
多级日志：支持DEBUG/INFO/WARNING/ERROR等级别
线程安全：支持多线程环境下的安全日志记录

errors.log分析

错误日志结构

根据现有的 [errors.log](git_repository_url/errors.log) 文件分析，系统记录了以下类型的错误：

2025-11-08 19:21:57,755 - codewiki.doc_manage.detail_content_gen - session=- | conversation=- | request=- | user=- - ERROR - [/usr/local/lib/python3.12/site-packages/codewiki/doc_manage/detail_content_gen.py:106]
生成文档内容时出错: 1 validation error for DocumentFileItem
content
  Input should be a valid string [type=string_type, input_value=None, input_type=NoneType]

错误模式识别

从错误日志中识别出以下模式：

Pydantic验证错误 - 数据验证失败
外部依赖错误 - 第三方库调用异常
时间戳记录 - 精确到毫秒的错误发生时间
堆栈跟踪 - 完整的错误调用链信息

异常处理机制

全局异常处理

系统实现了完整的异常处理架构，位于 [app/core/middleware.py](git_repository_url/app/core/middleware.py)：

sequenceDiagram
    participant Client
    participant Middleware
    participant Router
    participant Service
    participant Database
    
    Client->>Middleware: HTTP请求
    Middleware->>Router: 转发请求
    Router->>Service: 业务处理
    Service->>Database: 数据操作
    
    alt 发生异常
        Database-->>Service: 数据库异常
        Service-->>Router: 服务异常
        Router-->>Middleware: 路由异常
        Middleware->>Middleware: 记录错误日志
        Middleware->>Client: 返回错误响应
    else 正常流程
        Database-->>Service: 返回数据
        Service-->>Router: 返回结果
        Router-->>Middleware: 返回响应
        Middleware->>Client: 返回成功响应
    end

异常分类处理

# 异常类型映射
异常类型 -> HTTP状态码 -> 响应格式
ValueError -> 400 -> {"error": "Bad Request", ...}
PermissionError -> 403 -> {"error": "Forbidden", ...}  
FileNotFoundError -> 404 -> {"error": "Not Found", ...}
其他异常 -> 500 -> {"error": "Internal Server Error", ...}

访问日志系统

数据模型设计

访问日志数据模型位于 [app/models/access_log.py](git_repository_url/app/models/access_log.py)：

erDiagram
    ACCESS_LOG {
        int log_id PK
        string action_type
        string action_title
        string action_description
        string related_users
        string related_tickets
        string related_workpieces
        int created_by
        int updated_by
        datetime created_at
        datetime updated_at
    }

服务层实现

访问日志服务提供完整的CRUD操作，位于 [app/service/access_log_service.py](git_repository_url/app/service/access_log_service.py#L7-L45)：

async def service_create_access_log(
    action_type: str,
    action_title: str,
    action_description: str = "",
    related_users: str = "",
    related_tickets: str = "",
    related_workpieces: str = "",
    created_by: int = -1
) -> AccessLog:
    """创建访问日志记录"""

API接口

系统提供完整的访问日志REST API，位于 [app/routers/log_router.py](git_repository_url/app/routers/log_router.py)：

端点	方法	描述	参数
`/log/detail/{log_id}`	GET	获取日志详情	log_id
`/log/all`	GET	获取所有日志	skip, limit
`/log/type/{action_type}`	GET	按类型筛选	action_type, skip, limit
`/log/user/{user_id}`	GET	按用户筛选	user_id, skip, limit
`/log/search`	GET	关键词搜索	keyword, skip, limit
`/log/{log_id}`	DELETE	删除日志	log_id

性能监控指标

关键性能指标

响应时间监控
- API端点平均响应时间
- 数据库查询执行时间
- 外部服务调用延迟
吞吐量指标
- 请求/秒处理能力
- 并发连接数统计
- 错误率监控
资源使用率
- CPU和内存使用情况
- 数据库连接池状态
- 磁盘I/O性能

监控数据流

flowchart LR
    A[应用层] --> B[中间件]
    B --> C[性能计数器]
    C --> D[指标收集]
    D --> E[监控仪表盘]
    D --> F[告警系统]
    
    style C fill:#9f9
    style E fill:#bbf

错误分析与追踪

错误分类体系

错误类别	示例	处理策略	监控重点
验证错误	Pydantic验证失败	返回400错误	输入数据质量
权限错误	无访问权限	返回403错误	权限配置
资源错误	文件不存在	返回404错误	资源管理
系统错误	数据库连接失败	返回500错误	系统健康度

错误追踪流程

错误检测 - 通过异常中间件捕获
日志记录 - 记录到文件和控制台
分类处理 - 根据异常类型返回相应HTTP状态码
监控告警 - 集成到监控系统进行实时告警

最佳实践建议

日志管理优化

结构化日志：建议采用JSON格式便于解析
日志分级：合理设置不同环境的日志级别
日志聚合：考虑使用ELK栈进行集中管理
敏感信息：避免在日志中记录敏感数据

监控改进建议

自定义指标：添加业务特定的性能指标
分布式追踪：集成OpenTelemetry进行全链路追踪
健康检查：实现应用健康检查端点
性能基线：建立性能基准进行对比分析

索引

邮轮穿舱件管理系统后台建立了完善的日志和监控体系，具有以下特点：

多层日志架构：应用日志、访问日志、错误日志分离
全面异常处理：全局异常捕获和分类处理机制
性能监控基础：具备基本的性能指标收集能力
可扩展设计：支持后续监控系统的集成

通过持续优化错误追踪和性能监控，可以进一步提升系统的可靠性和可维护性。

参考文件

app/core/loggers.py - 日志配置核心文件
app/core/middleware.py - 全局异常处理中间件
app/models/access_log.py - 访问日志数据模型
app/service/access_log_service.py - 访问日志服务层
app/routers/log_router.py - 日志相关API接口
errors.log - 错误日志文件示例
app/main.py - 主应用异常处理配置

概述​

系统日志架构​

日志系统组件关系​

核心日志组件​

日志配置分析​

Loguru日志配置​

关键特性​

errors.log分析​

错误日志结构​

错误模式识别​

异常处理机制​

全局异常处理​

异常分类处理​

访问日志系统​

数据模型设计​

服务层实现​

API接口​

性能监控指标​

关键性能指标​

监控数据流​

错误分析与追踪​

错误分类体系​

错误追踪流程​

最佳实践建议​

日志管理优化​

监控改进建议​

索引​

参考文件​

概述