Files

2026-02-28 15:16:15 +08:00

17 KiB

Raw Permalink Blame History

故障排除

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

简介

本指南面向运维与开发人员，聚焦“医院绩效系统”的启动失败、数据库连接问题、API 接口错误、前端加载异常、日志分析、性能瓶颈定位、内存泄漏检测、网络连接问题、权限配置错误以及数据不一致等常见问题，提供系统化的诊断方法、错误代码含义与解决方案，并给出调试工具使用、开发与生产环境故障策略。

项目结构

系统采用前后端分离架构：

后端：FastAPI + SQLAlchemy 2.0 + PostgreSQL，支持异步 IO，提供 REST API。
前端：Vue 3 + Element Plus + Axios，通过 Vite 开发服务器运行，代理转发到后端。

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

图表来源

章节来源

核心组件

应用入口与异常处理：负责创建 FastAPI 实例、注册路由、CORS、健康检查与全局异常处理。
配置中心：集中管理应用名、版本、API 前缀、数据库连接、JWT、跨域、分页等配置。
数据库层：异步引擎与会话工厂，提供依赖注入式数据库会话。
日志系统：按日切分的滚动日志，区分普通日志与错误日志，统一输出格式。
安全模块：OAuth2 密码流、JWT 编解码、用户校验与权限判定。
前端请求封装：Axios 实例、请求/响应拦截器、错误提示与自动登出。

章节来源

架构总览

系统启动与请求处理的关键流程如下：

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 : 前端渲染

图表来源

详细组件分析

后端异常与健康检查

健康检查端点：用于快速判断后端是否存活。
异常处理：对 HTTP 异常、请求验证异常与全局异常进行记录与透传，便于定位问题。

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

章节来源

backend/app/main.py

数据库连接与事务

异步引擎与会话工厂：支持高并发与长连接复用。
依赖注入式会话：自动提交、回滚与关闭，避免资源泄露。
连接池参数：可通过配置调整池大小与溢出上限。

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 : "工厂创建"

图表来源

章节来源

安全与认证

OAuth2 密码流：统一登录入口，返回 JWT。
用户校验：从令牌解析用户 ID，查询数据库并校验状态与角色。
权限判定：管理员、经理等角色访问控制。

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 响应

图表来源

章节来源

前端请求拦截与错误处理

Axios 实例：统一 base URL、超时与头部。
请求拦截：自动附加 Bearer Token。
响应拦截：统一错误码处理、HTTP 状态码映射、网络错误提示与自动登出。

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

章节来源

依赖关系分析

后端依赖：FastAPI、SQLAlchemy 2.0、asyncpg、Alembic、Pydantic、Pydantic Settings、Passlib、Uvicorn 等。
前端依赖：Vue 3、Vue Router、Pinia、Axios、Element Plus、ECharts、Day.js 等。
开发与运行：后端通过 Uvicorn 运行，前端通过 Vite 开发服务器运行并通过代理转发到后端。

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

图表来源

章节来源

性能考虑

数据库连接池：合理设置池大小与溢出上限，避免连接争用与超时。
异步查询：优先使用异步 ORM 查询，减少阻塞。
分页与索引：接口分页参数限制与数据库索引优化，降低查询成本。
日志级别：生产环境建议提升日志级别，减少磁盘 IO。
前端缓存与懒加载：减少重复请求与首屏压力。

[本节为通用指导，无需列出章节来源]

故障排除指南

一、系统启动失败

常见症状

后端启动报错（端口占用、依赖缺失、配置错误）
前端无法访问或 404

排查步骤

检查后端端口与依赖
- 确认端口未被占用；查看依赖安装是否完整。
- 参考后端启动命令与依赖清单。
检查环境变量与配置
- 确认 .env 或环境变量中数据库连接字符串、密钥等配置正确。
检查前端代理
- 确认 Vite 代理指向正确的后端地址与端口。
查看日志
- 后端日志目录与文件命名按日期切分，结合错误日志定位。

章节来源

二、数据库连接问题

常见症状

启动时报数据库连接失败
接口出现超时或连接池耗尽

排查步骤

检查数据库服务状态与可达性
- 确认 PostgreSQL 正常运行且监听端口开放。
校验连接字符串
- 对照示例文件中的连接串，确保主机、端口、数据库名、用户名与密码正确。
调整连接池参数
- 根据并发与资源情况调整池大小与溢出上限。
查看数据库层日志
- 结合后端日志定位具体 SQL 与异常。

章节来源

三、API 接口错误

常见症状

400 参数校验失败
401 未认证/令牌过期
403 权限不足
404 资源不存在
500 服务器内部错误

排查步骤

参数校验
- 检查请求体字段类型、长度与枚举值是否符合 Pydantic 模式定义。
认证与权限
- 确认携带有效 Bearer Token；检查用户状态与角色。
路由与处理器
- 确认路由前缀与路径正确；查看处理器是否抛出预期异常。
日志分析
- 使用异常处理器记录的上下文信息定位问题。

章节来源

四、前端加载异常

常见症状

页面空白、静态资源 404
登录后页面不跳转或白屏

排查步骤

检查代理配置
- 确认 Vite 代理将 /api 前缀转发到后端地址。
检查请求拦截器
- 确认本地存储中存在有效 Token；检查响应拦截器对 401 的处理。
浏览器网络面板
- 观察 /api/v1/* 请求状态码与响应内容。
控制台错误
- 查看前端打包产物与运行时错误。

章节来源

五、日志分析方法

日志位置与命名：按日期切分的日志文件，区分普通与错误日志。
日志格式：包含时间、模块名、级别与消息。
分析要点：关注异常堆栈、请求 URL、状态码与业务错误信息。

章节来源

backend/app/core/logging_config.py

六、性能瓶颈定位

数据库层面
- 检查慢查询与索引缺失；优化分页与联表查询。
应用层面
- 使用异步查询减少阻塞；限制分页大小；开启连接池调优。
前端层面
- 减少不必要的请求与重渲染；启用懒加载与缓存。

章节来源

七、内存泄漏检测

后端
- 确保每个请求生命周期内的数据库会话正确关闭与回滚。
- 避免在全局持有大对象或长生命周期缓存。
前端
- 清理事件监听器与定时器；避免循环引用；及时释放大数组与图片对象。

章节来源

backend/app/core/database.py

八、网络连接问题

后端
- 检查 CORS 配置与允许的来源列表。
前端
- 确认代理与跨域头设置；检查浏览器同源策略与证书问题。

章节来源

九、权限配置错误

用户状态
- 确保用户处于启用状态；检查角色字段与权限映射。
JWT 配置
- 确认密钥与算法配置；检查令牌有效期与签发方。

章节来源

十、数据不一致

事务边界
- 确保业务操作在单个事务中完成；必要时使用悲观/乐观锁。
并发控制
- 使用唯一约束与幂等设计；避免竞态条件。
数据模型
- 检查外键与约束；确保枚举值与默认值一致。

章节来源

backend/app/models/models.py

十一、调试工具使用

后端
- 使用 Uvicorn 开发模式热重载；利用 OpenAPI 文档与 ReDoc 进行接口调试。
前端
- 使用 Vue DevTools 与浏览器开发者工具；借助 Axios Mock 或后端联调。

章节来源

十二、开发环境与生产环境差异

开发环境
- DEBUG 开启；日志级别较低；CORS 来源宽松。
生产环境
- 关闭 DEBUG；严格 CORS；使用强密钥；启用 HTTPS；监控与告警。

章节来源

结论

通过明确的启动流程、完善的异常与日志机制、严格的权限与配置管理，以及前后端协同的代理与拦截器，系统具备良好的可观测性与可维护性。遇到问题时，建议遵循“先日志、再配置、后接口”的顺序，结合本文提供的图示与步骤，快速定位并解决问题。

附录

常用端点与职责
- 健康检查：/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

章节来源

17 KiB Raw Permalink Blame History Unescape Escape

故障排除

目录

简介

项目结构

核心组件

架构总览

详细组件分析

后端异常与健康检查

数据库连接与事务

安全与认证

前端请求拦截与错误处理

依赖关系分析

性能考虑

故障排除指南

一、系统启动失败

二、数据库连接问题

三、API 接口错误

四、前端加载异常

五、日志分析方法

六、性能瓶颈定位

七、内存泄漏检测

八、网络连接问题

九、权限配置错误

十、数据不一致

十一、调试工具使用

十二、开发环境与生产环境差异

结论

附录

17 KiB

Raw Permalink Blame History