提交文件

2026-02-28 15:16:15 +08:00
parent 1a4e50e0a4
commit 44f250f58e
159 changed files with 61268 additions and 0 deletions
--- a/.qoder/repowiki/zh/content/故障排除.md
+++ b/.qoder/repowiki/zh/content/故障排除.md
@@ -0,0 +1,477 @@
+# 故障排除
+
+<cite>
+**本文引用的文件**
+- [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/core/logging_config.py](file://backend/app/core/logging_config.py)
+- [backend/requirements.txt](file://backend/requirements.txt)
+- [backend/.env.example](file://backend/.env.example)
+- [backend/app/api/v1/__init__.py](file://backend/app/api/v1/__init__.py)
+- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py)
+- [backend/app/services/staff_service.py](file://backend/app/services/staff_service.py)
+- [backend/app/models/models.py](file://backend/app/models/models.py)
+- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py)
+- [docs/backend.md](file://docs/backend.md)
+- [frontend/src/api/request.js](file://frontend/src/api/request.js)
+- [frontend/vite.config.js](file://frontend/vite.config.js)
+- [frontend/package.json](file://frontend/package.json)
+</cite>
+
+## 目录
+1. [简介](#简介)
+2. [项目结构](#项目结构)
+3. [核心组件](#核心组件)
+4. [架构总览](#架构总览)
+5. [详细组件分析](#详细组件分析)
+6. [依赖关系分析](#依赖关系分析)
+7. [性能考虑](#性能考虑)
+8. [故障排除指南](#故障排除指南)
+9. [结论](#结论)
+10. [附录](#附录)
+
+## 简介
+本指南面向运维与开发人员，聚焦“医院绩效系统”的启动失败、数据库连接问题、API 接口错误、前端加载异常、日志分析、性能瓶颈定位、内存泄漏检测、网络连接问题、权限配置错误以及数据不一致等常见问题，提供系统化的诊断方法、错误代码含义与解决方案，并给出调试工具使用、开发与生产环境故障策略。
+
+## 项目结构
+系统采用前后端分离架构：
+- 后端：FastAPI + SQLAlchemy 2.0 + PostgreSQL，支持异步 IO，提供 REST API。
+- 前端：Vue 3 + Element Plus + Axios，通过 Vite 开发服务器运行，代理转发到后端。
+
+```mermaid
+graph TB
+subgraph "前端"
+FE_Vite["Vite 开发服务器<br/>端口 5173"]
+FE_Axios["Axios 实例<br/>baseURL: /api/v1"]
+end
+subgraph "后端"
+BE_Uvicorn["Uvicorn 服务器<br/>端口 8000"]
+BE_FastAPI["FastAPI 应用"]
+BE_Router["API 路由聚合"]
+BE_DB["SQLAlchemy 异步引擎<br/>PostgreSQL"]
+end
+FE_Vite --> FE_Axios
+FE_Axios --> BE_Uvicorn
+BE_Uvicorn --> BE_FastAPI
+BE_FastAPI --> BE_Router
+BE_Router --> BE_DB
+```
+
+图表来源
+- [frontend/vite.config.js](file://frontend/vite.config.js#L12-L20)
+- [frontend/src/api/request.js](file://frontend/src/api/request.js#L7-L12)
+- [backend/app/main.py](file://backend/app/main.py#L19-L51)
+- [backend/app/core/database.py](file://backend/app/core/database.py#L10-L20)
+
+章节来源
+- [docs/backend.md](file://docs/backend.md#L16-L58)
+- [frontend/vite.config.js](file://frontend/vite.config.js#L12-L20)
+- [backend/app/main.py](file://backend/app/main.py#L19-L51)
+
+## 核心组件
+- 应用入口与异常处理：负责创建 FastAPI 实例、注册路由、CORS、健康检查与全局异常处理。
+- 配置中心：集中管理应用名、版本、API 前缀、数据库连接、JWT、跨域、分页等配置。
+- 数据库层：异步引擎与会话工厂，提供依赖注入式数据库会话。
+- 日志系统：按日切分的滚动日志，区分普通日志与错误日志，统一输出格式。
+- 安全模块：OAuth2 密码流、JWT 编解码、用户校验与权限判定。
+- 前端请求封装：Axios 实例、请求/响应拦截器、错误提示与自动登出。
+
+章节来源
+- [backend/app/main.py](file://backend/app/main.py#L15-L77)
+- [backend/app/core/config.py](file://backend/app/core/config.py#L9-L46)
+- [backend/app/core/database.py](file://backend/app/core/database.py#L9-L39)
+- [backend/app/core/logging_config.py](file://backend/app/core/logging_config.py#L17-L64)
+- [backend/app/core/security.py](file://backend/app/core/security.py#L20-L110)
+- [frontend/src/api/request.js](file://frontend/src/api/request.js#L14-L63)
+
+## 架构总览
+系统启动与请求处理的关键流程如下：
+
+```mermaid
+sequenceDiagram
+participant Dev as "开发者/运维"
+participant FE as "前端浏览器"
+participant Vite as "Vite 代理"
+participant Uvicorn as "Uvicorn"
+participant FastAPI as "FastAPI 应用"
+participant Router as "API 路由"
+participant DB as "数据库"
+Dev->>Uvicorn : 启动后端服务
+Dev->>FE : 启动前端开发服务器
+FE->>Vite : 访问 /api/v1/*
+Vite->>Uvicorn : 代理转发
+Uvicorn->>FastAPI : 路由匹配
+FastAPI->>Router : 调用对应处理器
+Router->>DB : 异步查询/写入
+DB-->>Router : 返回结果
+Router-->>FastAPI : 标准响应
+FastAPI-->>Uvicorn : HTTP 响应
+Uvicorn-->>Vite : HTTP 响应
+Vite-->>FE : 前端渲染
+```
+
+图表来源
+- [backend/app/main.py](file://backend/app/main.py#L54-L77)
+- [backend/app/api/v1/__init__.py](file://backend/app/api/v1/__init__.py#L1-L17)
+- [backend/app/core/database.py](file://backend/app/core/database.py#L28-L39)
+- [frontend/vite.config.js](file://frontend/vite.config.js#L14-L19)
+- [frontend/src/api/request.js](file://frontend/src/api/request.js#L7-L12)
+
+## 详细组件分析
+
+### 后端异常与健康检查
+- 健康检查端点：用于快速判断后端是否存活。
+- 异常处理：对 HTTP 异常、请求验证异常与全局异常进行记录与透传，便于定位问题。
+
+```mermaid
+flowchart TD
+Start(["请求进入"]) --> Match["路由匹配"]
+Match --> Handler["业务处理器"]
+Handler --> Ok{"处理成功？"}
+Ok --> |是| Resp["返回 2xx/业务响应"]
+Ok --> |否| Err["抛出异常"]
+Err --> Log["记录日志"]
+Log --> Raise["向上抛出"]
+Raise --> ClientErr["客户端错误码返回"]
+Resp --> End(["结束"])
+ClientErr --> End
+```
+
+图表来源
+- [backend/app/main.py](file://backend/app/main.py#L58-L77)
+
+章节来源
+- [backend/app/main.py](file://backend/app/main.py#L54-L77)
+
+### 数据库连接与事务
+- 异步引擎与会话工厂：支持高并发与长连接复用。
+- 依赖注入式会话：自动提交、回滚与关闭，避免资源泄露。
+- 连接池参数：可通过配置调整池大小与溢出上限。
+
+```mermaid
+classDiagram
+class AsyncEngine {
+create_async_engine(url, echo)
+}
+class AsyncSessionMaker {
+async_sessionmaker(engine, class_, expire_on_commit)
+}
+class AsyncSession {
+__enter__()
+__exit__()
+commit()
+rollback()
+close()
+}
+AsyncEngine <.. AsyncSessionMaker : "创建"
+AsyncSessionMaker --> AsyncSession : "工厂创建"
+```
+
+图表来源
+- [backend/app/core/database.py](file://backend/app/core/database.py#L10-L20)
+- [backend/app/core/database.py](file://backend/app/core/database.py#L28-L39)
+
+章节来源
+- [backend/app/core/database.py](file://backend/app/core/database.py#L9-L39)
+- [backend/app/core/config.py](file://backend/app/core/config.py#L18-L22)
+
+### 安全与认证
+- OAuth2 密码流：统一登录入口，返回 JWT。
+- 用户校验：从令牌解析用户 ID，查询数据库并校验状态与角色。
+- 权限判定：管理员、经理等角色访问控制。
+
+```mermaid
+sequenceDiagram
+participant Client as "客户端"
+participant Auth as "认证路由"
+participant DB as "数据库"
+participant JWT as "JWT 工具"
+Client->>Auth : POST /api/v1/auth/login
+Auth->>DB : 查询用户
+DB-->>Auth : 用户对象
+Auth->>JWT : 生成访问令牌
+JWT-->>Auth : access_token
+Auth-->>Client : Token 响应
+```
+
+图表来源
+- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py#L17-L37)
+- [backend/app/core/security.py](file://backend/app/core/security.py#L55-L82)
+
+章节来源
+- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py#L17-L37)
+- [backend/app/core/security.py](file://backend/app/core/security.py#L55-L110)
+
+### 前端请求拦截与错误处理
+- Axios 实例：统一 base URL、超时与头部。
+- 请求拦截：自动附加 Bearer Token。
+- 响应拦截：统一错误码处理、HTTP 状态码映射、网络错误提示与自动登出。
+
+```mermaid
+flowchart TD
+Req["发起请求"] --> Interceptor["请求拦截器<br/>附加 Token"]
+Interceptor --> Send["发送到后端"]
+Send --> Resp{"响应成功？"}
+Resp --> |是| Parse["解析业务响应"]
+Resp --> |否| Handle["响应拦截器处理"]
+Handle --> Status{"HTTP 状态码"}
+Status --> |401| Logout["清除 Token 并跳转登录"]
+Status --> |403/404/500| Msg["提示错误信息"]
+Status --> |其他| NetErr["网络错误提示"]
+Parse --> Done["返回数据"]
+Logout --> Done
+Msg --> Done
+NetErr --> Done
+```
+
+图表来源
+- [frontend/src/api/request.js](file://frontend/src/api/request.js#L14-L63)
+
+章节来源
+- [frontend/src/api/request.js](file://frontend/src/api/request.js#L14-L63)
+- [frontend/vite.config.js](file://frontend/vite.config.js#L14-L19)
+
+## 依赖关系分析
+- 后端依赖：FastAPI、SQLAlchemy 2.0、asyncpg、Alembic、Pydantic、Pydantic Settings、Passlib、Uvicorn 等。
+- 前端依赖：Vue 3、Vue Router、Pinia、Axios、Element Plus、ECharts、Day.js 等。
+- 开发与运行：后端通过 Uvicorn 运行，前端通过 Vite 开发服务器运行并通过代理转发到后端。
+
+```mermaid
+graph TB
+subgraph "后端依赖"
+F["FastAPI"]
+S["SQLAlchemy 2.0"]
+A["asyncpg"]
+Al["Alembic"]
+P["Pydantic/Settings"]
+Pa["Passlib"]
+U["Uvicorn"]
+end
+subgraph "前端依赖"
+V["Vue 3"]
+VR["Vue Router"]
+Pi["Pinia"]
+Ax["Axios"]
+EP["Element Plus"]
+E["ECharts"]
+D["Day.js"]
+end
+F --> S --> A
+F --> U
+P --> F
+Pa --> F
+Al --> S
+V --> VR --> Ax
+V --> Pi
+V --> EP
+V --> E
+V --> D
+```
+
+图表来源
+- [backend/requirements.txt](file://backend/requirements.txt#L1-L17)
+- [frontend/package.json](file://frontend/package.json#L11-L25)
+
+章节来源
+- [backend/requirements.txt](file://backend/requirements.txt#L1-L17)
+- [frontend/package.json](file://frontend/package.json#L11-L25)
+
+## 性能考虑
+- 数据库连接池：合理设置池大小与溢出上限，避免连接争用与超时。
+- 异步查询：优先使用异步 ORM 查询，减少阻塞。
+- 分页与索引：接口分页参数限制与数据库索引优化，降低查询成本。
+- 日志级别：生产环境建议提升日志级别，减少磁盘 IO。
+- 前端缓存与懒加载：减少重复请求与首屏压力。
+
+[本节为通用指导，无需列出章节来源]
+
+## 故障排除指南
+
+### 一、系统启动失败
+常见症状
+- 后端启动报错（端口占用、依赖缺失、配置错误）
+- 前端无法访问或 404
+
+排查步骤
+1. 检查后端端口与依赖
+   - 确认端口未被占用；查看依赖安装是否完整。
+   - 参考后端启动命令与依赖清单。
+2. 检查环境变量与配置
+   - 确认 .env 或环境变量中数据库连接字符串、密钥等配置正确。
+3. 检查前端代理
+   - 确认 Vite 代理指向正确的后端地址与端口。
+4. 查看日志
+   - 后端日志目录与文件命名按日期切分，结合错误日志定位。
+
+章节来源
+- [docs/backend.md](file://docs/backend.md#L454-L475)
+- [backend/.env.example](file://backend/.env.example#L3-L10)
+- [frontend/vite.config.js](file://frontend/vite.config.js#L12-L20)
+- [backend/app/core/logging_config.py](file://backend/app/core/logging_config.py#L17-L20)
+
+### 二、数据库连接问题
+常见症状
+- 启动时报数据库连接失败
+- 接口出现超时或连接池耗尽
+
+排查步骤
+1. 检查数据库服务状态与可达性
+   - 确认 PostgreSQL 正常运行且监听端口开放。
+2. 校验连接字符串
+   - 对照示例文件中的连接串，确保主机、端口、数据库名、用户名与密码正确。
+3. 调整连接池参数
+   - 根据并发与资源情况调整池大小与溢出上限。
+4. 查看数据库层日志
+   - 结合后端日志定位具体 SQL 与异常。
+
+章节来源
+- [backend/.env.example](file://backend/.env.example#L4)
+- [backend/app/core/config.py](file://backend/app/core/config.py#L18-L22)
+- [backend/app/core/database.py](file://backend/app/core/database.py#L10-L20)
+
+### 三、API 接口错误
+常见症状
+- 400 参数校验失败
+- 401 未认证/令牌过期
+- 403 权限不足
+- 404 资源不存在
+- 500 服务器内部错误
+
+排查步骤
+1. 参数校验
+   - 检查请求体字段类型、长度与枚举值是否符合 Pydantic 模式定义。
+2. 认证与权限
+   - 确认携带有效 Bearer Token；检查用户状态与角色。
+3. 路由与处理器
+   - 确认路由前缀与路径正确；查看处理器是否抛出预期异常。
+4. 日志分析
+   - 使用异常处理器记录的上下文信息定位问题。
+
+章节来源
+- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py#L17-L37)
+- [backend/app/core/security.py](file://backend/app/core/security.py#L55-L110)
+- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L315-L345)
+- [backend/app/main.py](file://backend/app/main.py#L58-L77)
+
+### 四、前端加载异常
+常见症状
+- 页面空白、静态资源 404
+- 登录后页面不跳转或白屏
+
+排查步骤
+1. 检查代理配置
+   - 确认 Vite 代理将 /api 前缀转发到后端地址。
+2. 检查请求拦截器
+   - 确认本地存储中存在有效 Token；检查响应拦截器对 401 的处理。
+3. 浏览器网络面板
+   - 观察 /api/v1/* 请求状态码与响应内容。
+4. 控制台错误
+   - 查看前端打包产物与运行时错误。
+
+章节来源
+- [frontend/vite.config.js](file://frontend/vite.config.js#L14-L19)
+- [frontend/src/api/request.js](file://frontend/src/api/request.js#L14-L63)
+
+### 五、日志分析方法
+- 日志位置与命名：按日期切分的日志文件，区分普通与错误日志。
+- 日志格式：包含时间、模块名、级别与消息。
+- 分析要点：关注异常堆栈、请求 URL、状态码与业务错误信息。
+
+章节来源
+- [backend/app/core/logging_config.py](file://backend/app/core/logging_config.py#L17-L59)
+
+### 六、性能瓶颈定位
+- 数据库层面
+  - 检查慢查询与索引缺失；优化分页与联表查询。
+- 应用层面
+  - 使用异步查询减少阻塞；限制分页大小；开启连接池调优。
+- 前端层面
+  - 减少不必要的请求与重渲染；启用懒加载与缓存。
+
+章节来源
+- [backend/app/core/config.py](file://backend/app/core/config.py#L31-L33)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L82-L85)
+
+### 七、内存泄漏检测
+- 后端
+  - 确保每个请求生命周期内的数据库会话正确关闭与回滚。
+  - 避免在全局持有大对象或长生命周期缓存。
+- 前端
+  - 清理事件监听器与定时器；避免循环引用；及时释放大数组与图片对象。
+
+章节来源
+- [backend/app/core/database.py](file://backend/app/core/database.py#L28-L39)
+
+### 八、网络连接问题
+- 后端
+  - 检查 CORS 配置与允许的来源列表。
+- 前端
+  - 确认代理与跨域头设置；检查浏览器同源策略与证书问题。
+
+章节来源
+- [backend/app/core/config.py](file://backend/app/core/config.py#L28-L29)
+- [frontend/vite.config.js](file://frontend/vite.config.js#L14-L19)
+
+### 九、权限配置错误
+- 用户状态
+  - 确保用户处于启用状态；检查角色字段与权限映射。
+- JWT 配置
+  - 确认密钥与算法配置；检查令牌有效期与签发方。
+
+章节来源
+- [backend/app/core/security.py](file://backend/app/core/security.py#L55-L110)
+- [backend/app/core/config.py](file://backend/app/core/config.py#L23-L26)
+
+### 十、数据不一致
+- 事务边界
+  - 确保业务操作在单个事务中完成；必要时使用悲观/乐观锁。
+- 并发控制
+  - 使用唯一约束与幂等设计；避免竞态条件。
+- 数据模型
+  - 检查外键与约束；确保枚举值与默认值一致。
+
+章节来源
+- [backend/app/models/models.py](file://backend/app/models/models.py#L14-L146)
+
+### 十一、调试工具使用
+- 后端
+  - 使用 Uvicorn 开发模式热重载；利用 OpenAPI 文档与 ReDoc 进行接口调试。
+- 前端
+  - 使用 Vue DevTools 与浏览器开发者工具；借助 Axios Mock 或后端联调。
+
+章节来源
+- [docs/backend.md](file://docs/backend.md#L454-L475)
+- [frontend/package.json](file://frontend/package.json#L6-L10)
+
+### 十二、开发环境与生产环境差异
+- 开发环境
+  - DEBUG 开启；日志级别较低；CORS 来源宽松。
+- 生产环境
+  - 关闭 DEBUG；严格 CORS；使用强密钥；启用 HTTPS；监控与告警。
+
+章节来源
+- [backend/app/core/config.py](file://backend/app/core/config.py#L15)
+- [backend/.env.example](file://backend/.env.example#L9-L10)
+
+## 结论
+通过明确的启动流程、完善的异常与日志机制、严格的权限与配置管理，以及前后端协同的代理与拦截器，系统具备良好的可观测性与可维护性。遇到问题时，建议遵循“先日志、再配置、后接口”的顺序，结合本文提供的图示与步骤，快速定位并解决问题。
+
+## 附录
+- 常用端点与职责
+  - 健康检查：/health
+  - 认证：/api/v1/auth/login、/api/v1/auth/register、/api/v1/auth/me
+  - 员工管理：/api/v1/staff
+  - 科室管理：/api/v1/departments
+  - 指标管理：/api/v1/indicators
+  - 考核管理：/api/v1/assessments
+  - 工资管理：/api/v1/salary
+  - 统计报表：/api/v1/stats
+  - 财务核算：/api/v1/finance
+  - 绩效计划：/api/v1/performance_plans
+  - 菜单管理：/api/v1/menus
+  - 指标模板：/api/v1/templates
+
+章节来源
+- [backend/app/main.py](file://backend/app/main.py#L54-L56)
+- [backend/app/api/v1/__init__.py](file://backend/app/api/v1/__init__.py#L1-L17)