16 KiB
16 KiB
故障处理
**本文引用的文件** - [GlobalExceptionHandler.java](file://fms-api/src/main/java/cn/g3soft/fmsapi/exception/GlobalExceptionHandler.java) - [application.yaml](file://fms-api/src/main/resources/application.yaml) - [http.js](file://fms-vue/src/services/http.js) - [FpsMonitor.vue](file://fms-vue/src/components/FpsMonitor.vue) - [OrgDatabaseConfigLoader.java](file://fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgDatabaseConfigLoader.java) - [OrgDatabaseConfig.java](file://fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgDatabaseConfig.java) - [README.md](file://fms-api/config/dbconfigs/README.md) - [LogRebuild.java](file://.tmp-fkcheck/LogRebuild.java) - [OrgDataSourceFactoryTests.java](file://fms-api/src/test/java/cn/g3soft/fmsapi/database/OrgDataSourceFactoryTests.java)目录
简介
本指南面向FMS系统的运维与研发人员，聚焦于常见故障的类型识别、定位方法、恢复流程与预防机制。内容覆盖前后端错误日志分析、数据库连接异常、网络问题、内存与CPU瓶颈诊断，以及服务重启、数据回滚、熔断降级与健康检查等实践建议。
项目结构
FMS系统由前端Vue应用与后端Spring Boot API组成：
- 前端负责请求拦截、统一错误提示、登录态处理与运行时性能监控（FPS）。
- 后端提供全局异常处理、多机构数据库配置加载、连接池参数配置与结构化日志表设计。
graph TB
FE["前端 Vue<br/>请求拦截/错误提示/FPS监控"] --> API["后端 Spring Boot API<br/>全局异常/接口响应"]
API --> DB["SQL Server<br/>多机构数据库"]
API --> LOG["日志表 s_log_technical / s_log_login / s_log_audit"]
图表来源
章节来源
核心组件
- 前端HTTP拦截器：统一注入鉴权头、解析服务端返回码、处理超时与网络异常、对认证失败进行会话清理与跳转登录。
- 后端全局异常处理器：捕获业务异常、保存对象异常、数据库访问异常与未处理异常，记录系统异常并返回统一错误响应。
- 多机构数据库配置加载：按机构ID读取properties文件，校验URL协议为SQL Server，抛出非法路径或认证错误。
- 连接池与服务器配置：定义端口、上下文路径、数据库连接池参数（初始大小、最大活跃数、等待时间、空闲检测等）。
- 日志表结构：技术日志、登录日志、审计日志包含trace_id、request_id、错误码、异常文本、上下文等字段，便于追踪与分析。
章节来源
- http.js:40-104
- GlobalExceptionHandler.java:15-84
- OrgDatabaseConfigLoader.java:31-57
- application.yaml:1-34
- LogRebuild.java:25-96
架构总览
前后端通过REST交互，前端在请求层集中处理鉴权与错误提示；后端以全局异常处理器统一收敛异常，并通过数据库连接池访问多机构SQL Server。日志写入结构化表，支持按trace_id与级别检索。
sequenceDiagram
participant U as "用户浏览器"
participant FE as "前端 http.js"
participant API as "后端 GlobalExceptionHandler"
participant DB as "SQL Server"
participant LOG as "日志表"
U->>FE : 发起API请求
FE->>FE : 注入Authorization头
FE->>API : HTTP请求
API->>DB : 执行数据库操作
DB-->>API : 结果或异常
API->>LOG : 记录技术/登录/审计日志
API-->>FE : 统一响应(成功/业务/系统异常)
FE-->>U : 展示结果或错误提示
图表来源
详细组件分析
前端错误处理与性能监控
- 请求拦截：自动附加Bearer Token，超时默认15秒。
- 响应拦截：将无code的响应包装为标准结构；根据返回码判断是否认证失败并跳转登录；对网络异常与5xx错误弹出全局消息提示。
- 性能监控：内置FPS监控组件，使用requestAnimationFrame采样，统计当前帧率、平均值与历史柱状图，支持重置与拖拽。
flowchart TD
Start(["请求开始"]) --> Inject["注入Authorization头"]
Inject --> Send["发送HTTP请求"]
Send --> Resp{"响应成功?"}
Resp -- 否 --> NetErr["网络异常/超时"]
NetErr --> Toast["显示全局错误提示"]
Toast --> End(["结束"])
Resp -- 是 --> CheckCode{"返回码=0?"}
CheckCode -- 否 --> AuthCheck{"是否认证错误?"}
AuthCheck -- 是 --> Logout["清理会话并跳转登录"]
AuthCheck -- 否 --> BizErr["构造业务错误并抛出"]
CheckCode -- 是 --> Success["透传数据"]
Success --> End
Logout --> End
BizErr --> End
图表来源
章节来源
后端全局异常处理
- 分类处理：认证异常、业务异常、保存对象异常、数据库异常与通用异常。
- 日志记录：对所有系统异常记录method、uri与堆栈信息。
- 统一响应：返回标准错误码与消息，避免暴露内部细节。
classDiagram
class GlobalExceptionHandler {
+handleAuthenticationException()
+handleBusinessException()
+handleSaveObjectException()
+handleDatabaseException()
+handleException()
-logSystemException()
-systemErrorResponse()
}
图表来源
章节来源
多机构数据库配置与连接策略
- 配置文件：每个机构一个properties文件，命名规范为{ORG_ID}.properties，仅允许字母、数字、下划线与连字符。
- 安全校验：路径规范化后限制在配置目录内；缺失文件或非法路径抛出认证异常。
- 驱动与协议：强制要求URL以jdbc:sqlserver:开头。
- 连接池行为：测试用例表明获取连接失败时不重试、快速失败并断开后续尝试，避免雪崩。
flowchart TD
A["加载机构配置"] --> B["规范化组织ID与路径"]
B --> C{"路径合法且文件存在?"}
C -- 否 --> E["抛出认证异常"]
C -- 是 --> D["读取properties并校验URL协议"]
D --> F{"是否为SQL Server URL?"}
F -- 否 --> G["抛出非法协议异常"]
F -- 是 --> H["创建数据源(连接池)"]
图表来源
章节来源
- OrgDatabaseConfigLoader.java:31-57
- OrgDatabaseConfig.java:1-10
- README.md:1-28
- OrgDataSourceFactoryTests.java:11-29
依赖关系分析
- 前端依赖axios进行HTTP通信，统一封装post方法与拦截器逻辑。
- 后端依赖Spring MVC与Druid连接池，通过application.yaml配置服务与连接池参数。
- 日志模块通过SQL脚本创建结构化表，支撑技术日志、登录日志与审计日志的持久化与索引查询。
graph LR
Axios["axios(http.js)"] --> API["Spring MVC(GlobalExceptionHandler)"]
API --> Druid["Druid连接池(application.yaml)"]
API --> SQL["SQL Server(LogRebuild.java)"]
图表来源
章节来源
性能注意事项
- 前端渲染性能：使用FPS监控组件观察帧率变化，结合历史柱状图定位卡顿时段；合理设置采样间隔与历史长度，避免过度响应式更新。
- 后端接口响应：关注数据库连接池参数（最大活跃数、等待时间），在高并发场景下避免连接耗尽导致请求排队。
- 数据库查询优化：利用日志表中的trace_id与级别索引，结合业务模块代码定位慢查询与异常热点。
[本节为通用指导，无需特定文件引用]
故障排查指南
网络连接问题
- 现象：前端报“网络异常”或“请求超时”，后端可能不可达或返回5xx。
- 排查步骤：
- 检查前端超时配置与baseURL是否正确。
- 确认后端服务端口与上下文路径配置。
- 查看后端全局异常处理器是否记录了系统异常与方法URI。
- 若为认证错误（401/40101），前端会清理会话并跳转登录页。
章节来源
数据库连接异常
- 现象：接口报错“系统异常”，或连接池无法获取连接。
- 排查步骤：
- 核对机构配置文件是否存在且路径合法，URL必须为SQL Server协议。
- 检查连接池参数（initial-size、max-active、max-wait）是否合理。
- 验证连接失败时的快速失败策略，避免重试风暴。
- 通过日志表检索trace_id与错误码，定位具体数据库节点与SQL。
章节来源
- OrgDatabaseConfigLoader.java:31-57
- application.yaml:14-26
- OrgDataSourceFactoryTests.java:11-29
- LogRebuild.java:52-75
内存溢出（OOM）
- 现象：服务频繁重启、GC频繁、堆内存占用过高。
- 排查步骤：
- 收集JVM堆转储与GC日志，分析大对象与泄漏点。
- 检查数据库连接池是否过大导致连接泄露。
- 审查前端是否一次性加载超大资源导致页面崩溃。
- 结合日志表中的trace_id关联前后端调用链，定位触发点。
[本节为通用指导，无需特定文件引用]
CPU占用过高
- 现象：接口响应变慢、线程阻塞、CPU持续高位。
- 排查步骤：
- 使用线程dump分析热点线程与锁竞争。
- 检查数据库慢查询与全表扫描。
- 评估前端重渲染与大数据量列表导致的计算开销。
- 通过日志表按模块与级别筛选异常与耗时记录。
[本节为通用指导，无需特定文件引用]
错误日志分析方法
- 前端JavaScript错误：
- 关注http.js的响应拦截器抛出的错误结构与提示。
- 使用浏览器控制台与网络面板查看请求与响应。
- 后端异常堆栈：
- 通过GlobalExceptionHandler记录的method与uri定位接口。
- 结合日志表s_log_technical的exception_text与context_text深入分析。
- 业务逻辑错误：
- 依据业务异常与保存对象异常的table、action、index字段缩小范围。
章节来源
性能瓶颈识别与优化方案
- 前端渲染性能优化：
- 使用FpsMonitor.vue观察帧率波动，减少不必要的重渲染。
- 合理分页与虚拟滚动，降低DOM压力。
- 后端接口响应优化：
- 调整连接池参数，避免连接耗尽。
- 引入缓存与异步处理，降低同步阻塞。
- 数据库查询优化：
- 基于日志表trace_id与级别索引定位慢查询。
- 优化SQL与索引，减少全表扫描。
章节来源
系统恢复流程
- 服务重启策略：
- 先停止流量入口，再优雅关闭服务，确保事务一致性。
- 重启后验证健康检查与基础接口可用性。
- 数据回滚操作：
- 基于迁移脚本与备份进行回滚，优先回滚最近变更。
- 回滚后校验关键表结构与数据完整性。
- 紧急修复方案：
- 临时放宽连接池限制或降级非核心功能。
- 通过日志表快速定位问题根因并实施热修复。
[本节为通用指导，无需特定文件引用]
故障预防机制
- 健康检查：
- 实现轻量级健康检查接口，验证数据库连通性与自身可达性。
- 自动重试：
- 对幂等接口配置有限重试与退避策略，避免雪崩。
- 熔断降级：
- 对依赖服务启用熔断器，失败时快速返回降级响应。
- 监控告警：
- 基于日志表与指标采集建立阈值告警，及时发现问题。
[本节为通用指导，无需特定文件引用]
应急预案与灾难恢复计划
- 预案分级：
- 定义P0-P3事件等级，明确响应时限与升级路径。
- 恢复目标：
- RTO（恢复时间目标）与RPO（恢复点目标）设定与演练。
- 演练与复盘：
- 定期开展故障演练，完善SOP与知识库。
- 复盘根因，落实改进措施与回归测试。
[本节为通用指导，无需特定文件引用]
结论
FMS系统在前后端均具备完善的错误处理与日志能力。通过统一的异常处理、结构化日志表与连接池配置，可高效定位网络、数据库与性能问题。建议结合健康检查、重试与熔断机制提升系统韧性，并制定标准化的恢复流程与应急预案，保障业务连续性。
附录
- 常用命令与配置参考：
- 启动Legacy SQL Server开发环境时指定TLS安全属性。
- 检查连接池参数与服务器上下文路径。
章节来源