# 故障排除

<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)