# 故障处理

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

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

## 简介
本指南面向FMS系统的运维与研发人员，聚焦于常见故障的类型识别、定位方法、恢复流程与预防机制。内容覆盖前后端错误日志分析、数据库连接异常、网络问题、内存与CPU瓶颈诊断，以及服务重启、数据回滚、熔断降级与健康检查等实践建议。

## 项目结构
FMS系统由前端Vue应用与后端Spring Boot API组成：
- 前端负责请求拦截、统一错误提示、登录态处理与运行时性能监控（FPS）。
- 后端提供全局异常处理、多机构数据库配置加载、连接池参数配置与结构化日志表设计。

```mermaid
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.js:40-104](file://fms-vue/src/services/http.js#L40-L104)
- [GlobalExceptionHandler.java:15-84](file://fms-api/src/main/java/cn/g3soft/fmsapi/exception/GlobalExceptionHandler.java#L15-L84)
- [application.yaml:1-34](file://fms-api/src/main/resources/application.yaml#L1-L34)
- [LogRebuild.java:25-96](file://.tmp-fkcheck/LogRebuild.java#L25-L96)

**章节来源**
- [http.js:1-111](file://fms-vue/src/services/http.js#L1-L111)
- [application.yaml:1-34](file://fms-api/src/main/resources/application.yaml#L1-L34)

## 核心组件
- 前端HTTP拦截器：统一注入鉴权头、解析服务端返回码、处理超时与网络异常、对认证失败进行会话清理与跳转登录。
- 后端全局异常处理器：捕获业务异常、保存对象异常、数据库访问异常与未处理异常，记录系统异常并返回统一错误响应。
- 多机构数据库配置加载：按机构ID读取properties文件，校验URL协议为SQL Server，抛出非法路径或认证错误。
- 连接池与服务器配置：定义端口、上下文路径、数据库连接池参数（初始大小、最大活跃数、等待时间、空闲检测等）。
- 日志表结构：技术日志、登录日志、审计日志包含trace_id、request_id、错误码、异常文本、上下文等字段，便于追踪与分析。

**章节来源**
- [http.js:40-104](file://fms-vue/src/services/http.js#L40-L104)
- [GlobalExceptionHandler.java:15-84](file://fms-api/src/main/java/cn/g3soft/fmsapi/exception/GlobalExceptionHandler.java#L15-L84)
- [OrgDatabaseConfigLoader.java:31-57](file://fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgDatabaseConfigLoader.java#L31-L57)
- [application.yaml:1-34](file://fms-api/src/main/resources/application.yaml#L1-L34)
- [LogRebuild.java:25-96](file://.tmp-fkcheck/LogRebuild.java#L25-L96)

## 架构总览
前后端通过REST交互，前端在请求层集中处理鉴权与错误提示；后端以全局异常处理器统一收敛异常，并通过数据库连接池访问多机构SQL Server。日志写入结构化表，支持按trace_id与级别检索。

```mermaid
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 : 展示结果或错误提示
```

**图表来源**
- [http.js:40-104](file://fms-vue/src/services/http.js#L40-L104)
- [GlobalExceptionHandler.java:15-84](file://fms-api/src/main/java/cn/g3soft/fmsapi/exception/GlobalExceptionHandler.java#L15-L84)
- [LogRebuild.java:25-96](file://.tmp-fkcheck/LogRebuild.java#L25-L96)

## 详细组件分析

### 前端错误处理与性能监控
- 请求拦截：自动附加Bearer Token，超时默认15秒。
- 响应拦截：将无code的响应包装为标准结构；根据返回码判断是否认证失败并跳转登录；对网络异常与5xx错误弹出全局消息提示。
- 性能监控：内置FPS监控组件，使用requestAnimationFrame采样，统计当前帧率、平均值与历史柱状图，支持重置与拖拽。

```mermaid
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
```

**图表来源**
- [http.js:40-104](file://fms-vue/src/services/http.js#L40-L104)

**章节来源**
- [http.js:1-111](file://fms-vue/src/services/http.js#L1-L111)
- [FpsMonitor.vue:1-290](file://fms-vue/src/components/FpsMonitor.vue#L1-L290)

### 后端全局异常处理
- 分类处理：认证异常、业务异常、保存对象异常、数据库异常与通用异常。
- 日志记录：对所有系统异常记录method、uri与堆栈信息。
- 统一响应：返回标准错误码与消息，避免暴露内部细节。

```mermaid
classDiagram
class GlobalExceptionHandler {
+handleAuthenticationException()
+handleBusinessException()
+handleSaveObjectException()
+handleDatabaseException()
+handleException()
-logSystemException()
-systemErrorResponse()
}
```

**图表来源**
- [GlobalExceptionHandler.java:15-84](file://fms-api/src/main/java/cn/g3soft/fmsapi/exception/GlobalExceptionHandler.java#L15-L84)

**章节来源**
- [GlobalExceptionHandler.java:15-84](file://fms-api/src/main/java/cn/g3soft/fmsapi/exception/GlobalExceptionHandler.java#L15-L84)

### 多机构数据库配置与连接策略
- 配置文件：每个机构一个properties文件，命名规范为{ORG_ID}.properties，仅允许字母、数字、下划线与连字符。
- 安全校验：路径规范化后限制在配置目录内；缺失文件或非法路径抛出认证异常。
- 驱动与协议：强制要求URL以jdbc:sqlserver:开头。
- 连接池行为：测试用例表明获取连接失败时不重试、快速失败并断开后续尝试，避免雪崩。

```mermaid
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](file://fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgDatabaseConfigLoader.java#L31-L57)
- [OrgDataSourceFactoryTests.java:11-29](file://fms-api/src/test/java/cn/g3soft/fmsapi/database/OrgDataSourceFactoryTests.java#L11-L29)

**章节来源**
- [OrgDatabaseConfigLoader.java:31-57](file://fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgDatabaseConfigLoader.java#L31-L57)
- [OrgDatabaseConfig.java:1-10](file://fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgDatabaseConfig.java#L1-L10)
- [README.md:1-28](file://fms-api/config/dbconfigs/README.md#L1-L28)
- [OrgDataSourceFactoryTests.java:11-29](file://fms-api/src/test/java/cn/g3soft/fmsapi/database/OrgDataSourceFactoryTests.java#L11-L29)

## 依赖关系分析
- 前端依赖axios进行HTTP通信，统一封装post方法与拦截器逻辑。
- 后端依赖Spring MVC与Druid连接池，通过application.yaml配置服务与连接池参数。
- 日志模块通过SQL脚本创建结构化表，支撑技术日志、登录日志与审计日志的持久化与索引查询。

```mermaid
graph LR
Axios["axios(http.js)"] --> API["Spring MVC(GlobalExceptionHandler)"]
API --> Druid["Druid连接池(application.yaml)"]
API --> SQL["SQL Server(LogRebuild.java)"]
```

**图表来源**
- [http.js:1-111](file://fms-vue/src/services/http.js#L1-L111)
- [application.yaml:1-34](file://fms-api/src/main/resources/application.yaml#L1-L34)
- [LogRebuild.java:25-96](file://.tmp-fkcheck/LogRebuild.java#L25-L96)

**章节来源**
- [http.js:1-111](file://fms-vue/src/services/http.js#L1-L111)
- [application.yaml:1-34](file://fms-api/src/main/resources/application.yaml#L1-L34)
- [LogRebuild.java:25-96](file://.tmp-fkcheck/LogRebuild.java#L25-L96)

## 性能注意事项
- 前端渲染性能：使用FPS监控组件观察帧率变化，结合历史柱状图定位卡顿时段；合理设置采样间隔与历史长度，避免过度响应式更新。
- 后端接口响应：关注数据库连接池参数（最大活跃数、等待时间），在高并发场景下避免连接耗尽导致请求排队。
- 数据库查询优化：利用日志表中的trace_id与级别索引，结合业务模块代码定位慢查询与异常热点。

[本节为通用指导，无需特定文件引用]

## 故障排查指南

### 网络连接问题
- 现象：前端报“网络异常”或“请求超时”，后端可能不可达或返回5xx。
- 排查步骤：
  - 检查前端超时配置与baseURL是否正确。
  - 确认后端服务端口与上下文路径配置。
  - 查看后端全局异常处理器是否记录了系统异常与方法URI。
  - 若为认证错误（401/40101），前端会清理会话并跳转登录页。

**章节来源**
- [http.js:40-104](file://fms-vue/src/services/http.js#L40-L104)
- [application.yaml:1-4](file://fms-api/src/main/resources/application.yaml#L1-L4)
- [GlobalExceptionHandler.java:57-84](file://fms-api/src/main/java/cn/g3soft/fmsapi/exception/GlobalExceptionHandler.java#L57-L84)

### 数据库连接异常
- 现象：接口报错“系统异常”，或连接池无法获取连接。
- 排查步骤：
  - 核对机构配置文件是否存在且路径合法，URL必须为SQL Server协议。
  - 检查连接池参数（initial-size、max-active、max-wait）是否合理。
  - 验证连接失败时的快速失败策略，避免重试风暴。
  - 通过日志表检索trace_id与错误码，定位具体数据库节点与SQL。

**章节来源**
- [OrgDatabaseConfigLoader.java:31-57](file://fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgDatabaseConfigLoader.java#L31-L57)
- [application.yaml:14-26](file://fms-api/src/main/resources/application.yaml#L14-L26)
- [OrgDataSourceFactoryTests.java:11-29](file://fms-api/src/test/java/cn/g3soft/fmsapi/database/OrgDataSourceFactoryTests.java#L11-L29)
- [LogRebuild.java:52-75](file://.tmp-fkcheck/LogRebuild.java#L52-L75)

### 内存溢出（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字段缩小范围。

**章节来源**
- [http.js:49-104](file://fms-vue/src/services/http.js#L49-L104)
- [GlobalExceptionHandler.java:20-64](file://fms-api/src/main/java/cn/g3soft/fmsapi/exception/GlobalExceptionHandler.java#L20-L64)
- [LogRebuild.java:52-75](file://.tmp-fkcheck/LogRebuild.java#L52-L75)

### 性能瓶颈识别与优化方案
- 前端渲染性能优化：
  - 使用FpsMonitor.vue观察帧率波动，减少不必要的重渲染。
  - 合理分页与虚拟滚动，降低DOM压力。
- 后端接口响应优化：
  - 调整连接池参数，避免连接耗尽。
  - 引入缓存与异步处理，降低同步阻塞。
- 数据库查询优化：
  - 基于日志表trace_id与级别索引定位慢查询。
  - 优化SQL与索引，减少全表扫描。

**章节来源**
- [FpsMonitor.vue:1-290](file://fms-vue/src/components/FpsMonitor.vue#L1-L290)
- [application.yaml:14-26](file://fms-api/src/main/resources/application.yaml#L14-L26)
- [LogRebuild.java:52-75](file://.tmp-fkcheck/LogRebuild.java#L52-L75)

### 系统恢复流程
- 服务重启策略：
  - 先停止流量入口，再优雅关闭服务，确保事务一致性。
  - 重启后验证健康检查与基础接口可用性。
- 数据回滚操作：
  - 基于迁移脚本与备份进行回滚，优先回滚最近变更。
  - 回滚后校验关键表结构与数据完整性。
- 紧急修复方案：
  - 临时放宽连接池限制或降级非核心功能。
  - 通过日志表快速定位问题根因并实施热修复。

[本节为通用指导，无需特定文件引用]

### 故障预防机制
- 健康检查：
  - 实现轻量级健康检查接口，验证数据库连通性与自身可达性。
- 自动重试：
  - 对幂等接口配置有限重试与退避策略，避免雪崩。
- 熔断降级：
  - 对依赖服务启用熔断器，失败时快速返回降级响应。
- 监控告警：
  - 基于日志表与指标采集建立阈值告警，及时发现问题。

[本节为通用指导，无需特定文件引用]

### 应急预案与灾难恢复计划
- 预案分级：
  - 定义P0-P3事件等级，明确响应时限与升级路径。
- 恢复目标：
  - RTO（恢复时间目标）与RPO（恢复点目标）设定与演练。
- 演练与复盘：
  - 定期开展故障演练，完善SOP与知识库。
  - 复盘根因，落实改进措施与回归测试。

[本节为通用指导，无需特定文件引用]

## 结论
FMS系统在前后端均具备完善的错误处理与日志能力。通过统一的异常处理、结构化日志表与连接池配置，可高效定位网络、数据库与性能问题。建议结合健康检查、重试与熔断机制提升系统韧性，并制定标准化的恢复流程与应急预案，保障业务连续性。

## 附录
- 常用命令与配置参考：
  - 启动Legacy SQL Server开发环境时指定TLS安全属性。
  - 检查连接池参数与服务器上下文路径。

**章节来源**
- [README.md:18-28](file://fms-api/config/dbconfigs/README.md#L18-L28)
- [application.yaml:1-34](file://fms-api/src/main/resources/application.yaml#L1-L34)