chenqi/hospital_performance
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
0395f31d24e6601c652dfbe2a6826cf8de2037be
hospital_performance/.qoder/repowiki/zh/content/部署运维/系统监控.md
chenqi 44f250f58e 提交文件
2026-02-28 15:16:15 +08:00

16 KiB
Raw Blame History

系统监控

**本文引用的文件** - [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)

目录

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

简介

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

项目结构

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

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

图表来源

章节来源

核心组件

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

章节来源

架构总览

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

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["控制台处理器"]

图表来源

详细组件分析

日志配置与轮转策略

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

图表来源

章节来源

异常处理与错误日志收集

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

图表来源

章节来源

性能日志与统计分析入口

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

图表来源

章节来源

数据库连接与查询性能

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

图表来源

章节来源

健康检查与前端连通性

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

图表来源

章节来源

依赖关系分析

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

图表来源

章节来源

性能考虑

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

故障排查指南

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

章节来源

结论

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

附录

日志级别与格式标准化建议

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

章节来源

告警机制与通知渠道

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

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

监控仪表板与可视化

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

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