# 系统监控

<cite>
**本文引用的文件**   
- [backend/app/core/logging_config.py](file://backend/app/core/logging_config.py)
- [backend/app/main.py](file://backend/app/main.py)
- [backend/app/core/config.py](file://backend/app/core/config.py)
- [backend/app/core/database.py](file://backend/app/core/database.py)
- [backend/app/api/v1/stats.py](file://backend/app/api/v1/stats.py)
- [backend/app/services/stats_service.py](file://backend/app/services/stats_service.py)
- [backend/app/models/models.py](file://backend/app/models/models.py)
- [backend/requirements.txt](file://backend/requirements.txt)
- [backend/.env.example](file://backend/.env.example)
- [test_frontend_connection.py](file://test_frontend_connection.py)
- [ALL_ISSUES_FIXED.md](file://ALL_ISSUES_FIXED.md)
</cite>

## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能考虑](#性能考虑)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录](#附录)

## 简介
本指南面向“系统监控与日志管理”，围绕应用日志配置、错误日志收集、性能日志分析、日志轮转策略、日志级别与格式标准化，以及系统资源与应用性能监控（API响应时间、数据库查询性能、并发处理能力）、告警机制与通知渠道、监控仪表板搭建与可视化展示进行系统化说明。结合仓库现有代码，给出可落地的实践建议与最佳实践。

## 项目结构
后端采用 FastAPI + SQLAlchemy 2.0 异步架构，日志配置集中于核心模块，主程序负责异常处理与健康检查，统计服务与 API 提供了性能与报表相关的能力入口。前端通过健康检查脚本与测试报告验证系统连通性。

```mermaid
graph TB
subgraph "后端"
MAIN["app/main.py"]
CFG["app/core/config.py"]
LOG["app/core/logging_config.py"]
DB["app/core/database.py"]
STATS_API["app/api/v1/stats.py"]
STATS_SVC["app/services/stats_service.py"]
MODELS["app/models/models.py"]
end
subgraph "外部"
REQ["requirements.txt"]
ENV[".env.example"]
TEST["test_frontend_connection.py"]
end
MAIN --> LOG
MAIN --> CFG
MAIN --> STATS_API
STATS_API --> STATS_SVC
STATS_SVC --> DB
DB --> MODELS
REQ --> MAIN
ENV --> CFG
TEST --> MAIN
```

图表来源
- [backend/app/main.py](file://backend/app/main.py#L1-L92)
- [backend/app/core/logging_config.py](file://backend/app/core/logging_config.py#L1-L65)
- [backend/app/core/config.py](file://backend/app/core/config.py#L1-L47)
- [backend/app/core/database.py](file://backend/app/core/database.py#L1-L39)
- [backend/app/api/v1/stats.py](file://backend/app/api/v1/stats.py#L1-L242)
- [backend/app/services/stats_service.py](file://backend/app/services/stats_service.py#L1-L300)
- [backend/app/models/models.py](file://backend/app/models/models.py#L1-L438)
- [backend/requirements.txt](file://backend/requirements.txt#L1-L17)
- [backend/.env.example](file://backend/.env.example#L1-L11)
- [test_frontend_connection.py](file://test_frontend_connection.py#L1-L36)

章节来源
- [backend/app/main.py](file://backend/app/main.py#L1-L92)
- [backend/app/core/logging_config.py](file://backend/app/core/logging_config.py#L1-L65)
- [backend/app/core/config.py](file://backend/app/core/config.py#L1-L47)
- [backend/app/core/database.py](file://backend/app/core/database.py#L1-L39)
- [backend/app/api/v1/stats.py](file://backend/app/api/v1/stats.py#L1-L242)
- [backend/app/services/stats_service.py](file://backend/app/services/stats_service.py#L1-L300)
- [backend/app/models/models.py](file://backend/app/models/models.py#L1-L438)
- [backend/requirements.txt](file://backend/requirements.txt#L1-L17)
- [backend/.env.example](file://backend/.env.example#L1-L11)
- [test_frontend_connection.py](file://test_frontend_connection.py#L1-L36)

## 核心组件
- 日志配置模块：定义日志目录、格式、级别与处理器（控制台、应用日志文件、错误日志文件），并提供子日志器获取方法。
- 主应用：注册异常处理器、CORS 中间件、路由；提供健康检查端点；统一记录 HTTP、校验与全局异常。
- 配置模块：集中管理应用名称、版本、调试开关、数据库连接池大小、JWT、跨域、分页等配置。
- 数据库模块：创建异步引擎与会话工厂，支持调试模式下的 SQL 输出。
- 统计 API 与服务：提供 BSC 维度、部门统计、趋势、排名、完成度等统计接口与服务实现，便于性能与业务指标分析。
- 模型层：定义科室、员工、指标、考核、明细、工资、计划、菜单、模板等实体与索引，支撑统计分析与查询性能。

章节来源
- [backend/app/core/logging_config.py](file://backend/app/core/logging_config.py#L1-L65)
- [backend/app/main.py](file://backend/app/main.py#L1-L92)
- [backend/app/core/config.py](file://backend/app/core/config.py#L1-L47)
- [backend/app/core/database.py](file://backend/app/core/database.py#L1-L39)
- [backend/app/api/v1/stats.py](file://backend/app/api/v1/stats.py#L1-L242)
- [backend/app/services/stats_service.py](file://backend/app/services/stats_service.py#L1-L300)
- [backend/app/models/models.py](file://backend/app/models/models.py#L1-L438)

## 架构总览
下图展示了日志、异常处理、数据库访问与统计分析之间的交互关系，体现监控与日志在系统中的位置与职责边界。

```mermaid
graph TB
CLIENT["客户端/前端"] --> API["FastAPI 应用"]
API --> EXC["异常处理器<br/>HTTP/校验/全局异常"]
API --> LOG["日志记录器"]
API --> ROUTER["路由注册"]
ROUTER --> STATS_API["统计 API 层"]
STATS_API --> STATS_SVC["统计服务层"]
STATS_SVC --> DB["异步数据库引擎/会话"]
DB --> MODELS["ORM 模型"]
LOG --> HANDLER_APP["应用日志文件处理器"]
LOG --> HANDLER_ERR["错误日志文件处理器"]
LOG --> HANDLER_CONSOLE["控制台处理器"]
```

图表来源
- [backend/app/main.py](file://backend/app/main.py#L54-L76)
- [backend/app/core/logging_config.py](file://backend/app/core/logging_config.py#L33-L59)
- [backend/app/api/v1/stats.py](file://backend/app/api/v1/stats.py#L17-L33)
- [backend/app/services/stats_service.py](file://backend/app/services/stats_service.py#L19-L72)
- [backend/app/core/database.py](file://backend/app/core/database.py#L9-L20)
- [backend/app/models/models.py](file://backend/app/models/models.py#L149-L202)

## 详细组件分析

### 日志配置与轮转策略
- 日志目录与文件命名：自动创建 logs 目录，按日期生成应用日志与错误日志文件，避免多进程写冲突。
- 日志格式：统一包含时间戳、记录器名称、级别与消息体，便于检索与聚合。
- 处理器与级别：
  - 控制台处理器：INFO 级别及以上输出至 stdout。
  - 应用日志文件处理器：DEBUG 级别，10MB 分割，保留 7 份备份。
  - 错误日志文件处理器：ERROR 级别，独立文件，10MB 分割，保留 7 份备份。
- 子日志器：通过 get_logger(name) 获取子记录器，便于模块化日志隔离与追踪。

```mermaid
flowchart TD
Start(["应用启动"]) --> InitLogger["初始化日志记录器<br/>设置级别与格式"]
InitLogger --> AddConsole["添加控制台处理器<br/>级别: INFO"]
InitLogger --> AddAppFile["添加应用日志文件处理器<br/>级别: DEBUG<br/>大小: 10MB<br/>备份数: 7"]
InitLogger --> AddErrFile["添加错误日志文件处理器<br/>级别: ERROR<br/>大小: 10MB<br/>备份数: 7"]
AddConsole --> Ready["日志系统就绪"]
AddAppFile --> Ready
AddErrFile --> Ready
```

图表来源
- [backend/app/core/logging_config.py](file://backend/app/core/logging_config.py#L26-L59)

章节来源
- [backend/app/core/logging_config.py](file://backend/app/core/logging_config.py#L1-L65)

### 异常处理与错误日志收集
- HTTP 异常：记录请求方法、URL、状态码与详情，便于定位接口错误。
- 请求校验异常：记录校验错误上下文，辅助前端参数修正。
- 全局异常：记录异常堆栈，便于定位未捕获异常。
- 健康检查：提供 /health 端点，便于运维快速判断服务可用性。

```mermaid
sequenceDiagram
participant C as "客户端"
participant A as "FastAPI 应用"
participant L as "日志记录器"
C->>A : 发起请求
A->>A : 路由匹配与业务处理
alt HTTP 异常
A->>L : 记录警告日志
A-->>C : 返回 HTTP 错误
else 校验异常
A->>L : 记录错误日志
A-->>C : 返回校验错误
else 其他异常
A->>L : 记录错误日志(含堆栈)
A-->>C : 返回服务器错误
end
```

图表来源
- [backend/app/main.py](file://backend/app/main.py#L58-L76)

章节来源
- [backend/app/main.py](file://backend/app/main.py#L1-L92)

### 性能日志与统计分析入口
- 统计 API：提供 BSC 维度、部门统计、趋势、排名、完成度等接口，作为性能与业务分析的数据源。
- 统计服务：封装复杂查询与聚合逻辑，支持按年月、科室等维度过滤与排序。
- 数据模型：定义考核、明细、指标、部门、员工等实体，配合索引提升查询效率。

```mermaid
sequenceDiagram
participant FE as "前端"
participant API as "统计 API"
participant SVC as "统计服务"
participant DB as "数据库引擎/会话"
participant M as "ORM 模型"
FE->>API : GET /stats/...
API->>SVC : 调用统计方法(传入过滤条件)
SVC->>DB : 执行异步查询(聚合/分组/排序)
DB->>M : 映射为模型对象
SVC-->>API : 返回聚合结果
API-->>FE : 返回 JSON 响应
```

图表来源
- [backend/app/api/v1/stats.py](file://backend/app/api/v1/stats.py#L17-L33)
- [backend/app/services/stats_service.py](file://backend/app/services/stats_service.py#L19-L72)
- [backend/app/core/database.py](file://backend/app/core/database.py#L28-L39)
- [backend/app/models/models.py](file://backend/app/models/models.py#L149-L202)

章节来源
- [backend/app/api/v1/stats.py](file://backend/app/api/v1/stats.py#L1-L242)
- [backend/app/services/stats_service.py](file://backend/app/services/stats_service.py#L1-L300)
- [backend/app/models/models.py](file://backend/app/models/models.py#L1-L438)

### 数据库连接与查询性能
- 异步引擎：基于 SQLAlchemy 2.0 的异步引擎，支持 echo 开关用于调试期 SQL 输出。
- 会话工厂：配置过载与池大小，结合业务并发需求调整。
- 索引与约束：模型层定义了多处索引与约束，有助于统计查询的性能与数据完整性。

```mermaid
classDiagram
class DatabaseConfig {
+DATABASE_URL
+DATABASE_POOL_SIZE
+DATABASE_MAX_OVERFLOW
+DEBUG
}
class Engine {
+create_async_engine(url, echo)
}
class SessionMaker {
+async_session_maker()
}
class Base {
<<declarative_base>>
}
DatabaseConfig --> Engine : "提供连接参数"
Engine --> SessionMaker : "创建会话工厂"
SessionMaker --> Base : "会话绑定模型"
```

图表来源
- [backend/app/core/config.py](file://backend/app/core/config.py#L18-L26)
- [backend/app/core/database.py](file://backend/app/core/database.py#L9-L20)
- [backend/app/models/models.py](file://backend/app/models/models.py#L62-L85)

章节来源
- [backend/app/core/config.py](file://backend/app/core/config.py#L1-L47)
- [backend/app/core/database.py](file://backend/app/core/database.py#L1-L39)
- [backend/app/models/models.py](file://backend/app/models/models.py#L1-L438)

### 健康检查与前端连通性
- 健康检查：/health 返回服务状态与版本，便于容器编排与负载均衡探活。
- 前端连通性测试：脚本对后端健康端点与前端端口进行探测，辅助快速定位网络或服务问题。

```mermaid
sequenceDiagram
participant T as "测试脚本"
participant BE as "后端 /health"
participant FE as "前端"
T->>BE : GET /health
BE-->>T : 200 健康状态
T->>FE : GET 前端首页
FE-->>T : 200 页面
T-->>T : 输出连通性结论
```

图表来源
- [backend/app/main.py](file://backend/app/main.py#L54-L56)
- [test_frontend_connection.py](file://test_frontend_connection.py#L15-L35)

章节来源
- [backend/app/main.py](file://backend/app/main.py#L1-L92)
- [test_frontend_connection.py](file://test_frontend_connection.py#L1-L36)

## 依赖关系分析
- 运行时依赖：FastAPI、Uvicorn、SQLAlchemy 2.x、asyncpg/aiosqlite、Alembic、Pydantic、Pydantic-Settings、Passlib、python-dotenv、HTTPX、PyTest 等。
- 环境变量：数据库 URL、JWT 密钥、调试开关等通过 .env.example 提供示例。

```mermaid
graph LR
FASTAPI["FastAPI"] --> UVICORN["Uvicorn"]
FASTAPI --> SQLA["SQLAlchemy 2.x"]
SQLA --> ASYNC["异步引擎/会话"]
SQLA --> MODELS["ORM 模型"]
ALEMBIC["Alembic"] --> DB["数据库迁移"]
PYDANTIC["Pydantic/Settings"] --> CONFIG["应用配置"]
PASSLIB["Passlib"] --> AUTH["认证/加密"]
DOTENV["python-dotenv"] --> CONFIG
```

图表来源
- [backend/requirements.txt](file://backend/requirements.txt#L1-L17)
- [backend/.env.example](file://backend/.env.example#L1-L11)
- [backend/app/core/config.py](file://backend/app/core/config.py#L35-L46)

章节来源
- [backend/requirements.txt](file://backend/requirements.txt#L1-L17)
- [backend/.env.example](file://backend/.env.example#L1-L11)
- [backend/app/core/config.py](file://backend/app/core/config.py#L1-L47)

## 性能考虑
- 日志轮转：当前配置为 10MB 分割、7 份备份，建议结合磁盘容量与日志量评估，必要时降低单文件大小或增加备份数。
- 日志级别：生产环境建议将控制台级别提升至 WARNING 或 ERROR，减少 INFO 级噪声；仅在调试阶段开启 DEBUG。
- 数据库连接池：根据并发与数据库承载能力调整池大小与最大溢出数，避免连接争用。
- 查询优化：利用模型层索引（如考核状态、周期、部门等）与分页，避免一次性加载大量数据。
- API 响应时间：可通过中间件或装饰器埋点统计请求耗时，结合日志与指标系统进行趋势分析。

## 故障排查指南
- 健康检查失败：确认后端服务已启动且监听端口正确，查看日志文件定位异常。
- 前端无法访问：使用测试脚本检查前端端口可达性，核对 CORS 配置。
- 统计接口返回空数据：当前部分统计接口返回模拟数据或需填充真实数据，参考测试报告中的接口调用示例。
- 数据库连接问题：核对 .env 中 DATABASE_URL 与数据库服务状态，确认驱动（asyncpg/aiosqlite）安装正确。

章节来源
- [test_frontend_connection.py](file://test_frontend_connection.py#L1-L36)
- [ALL_ISSUES_FIXED.md](file://ALL_ISSUES_FIXED.md#L94-L169)
- [backend/.env.example](file://backend/.env.example#L3-L10)

## 结论
本项目已具备完善的日志配置与异常处理基础，统计 API 与服务提供了性能与业务分析的入口。建议在生产环境中进一步完善日志级别与轮转策略、引入数据库慢查询与连接池监控、扩展告警与通知机制，并基于统计接口搭建可视化仪表板，实现持续可观测与趋势分析。

## 附录

### 日志级别与格式标准化建议
- 级别划分：DEBUG/INFO/WARNING/ERROR/CRITICAL，生产环境默认 WARNING，调试时临时提升。
- 格式字段：时间戳、记录器名称、线程/协程 ID、级别、模块路径、行号、消息体、异常堆栈（如有）。
- 文件命名：按日期切分，错误日志独立文件，便于检索与归档。

章节来源
- [backend/app/core/logging_config.py](file://backend/app/core/logging_config.py#L22-L24)
- [backend/app/core/logging_config.py](file://backend/app/core/logging_config.py#L33-L59)

### 告警机制与通知渠道
- 告警维度：HTTP 错误率、异常频次、数据库连接池耗尽、慢查询阈值、队列积压、磁盘/内存/CPU 阈值。
- 阈值设置：结合历史峰值与 SLA 设定，建议采用滚动窗口与自适应阈值。
- 通知渠道：邮件、企业微信/钉钉机器人、IM 通道，区分严重与一般告警等级。

[本节为概念性内容，无需文件来源]

### 监控仪表板与可视化
- 数据源：统计 API（BSC 维度、部门统计、趋势、排名、完成度）与系统指标（CPU/内存/磁盘/网络）。
- 可视化组件：折线图（趋势）、柱状图（排名）、仪表盘（关键指标）、热力图（部门得分分布）。
- 实现建议：前端图表库 + 后端定时抓取/推送，或接入 Prometheus/Grafana（扩展）。

[本节为概念性内容，无需文件来源]