Appearance
故障排除与FAQ
**本文引用的文件** - [bootstrap.yml](file://lemes-cloud/lemes-gateway/src/main/resources/bootstrap.yml) - [LemesErrorWebExceptionHandler.java](file://lemes-cloud/lemes-gateway/src/main/java/com/lenovo/lemes/gateway/handler/LemesErrorWebExceptionHandler.java) - [GlobalFallbackException.java](file://lemes-cloud/lemes-framework/lemes-framework-core/src/main/java/com/lenovo/lemes/framework/core/exception/GlobalFallbackException.java) - [ResultData.java](file://lemes-cloud/lemes-framework/lemes-framework-core/src/main/java/com/lenovo/lemes/framework/core/util/ResultData.java) - [LenovoLogUtil.java](file://lemes-cloud/lemes-framework/lemes-framework-core/src/main/java/com/lenovo/lemes/framework/core/util/compliance/LenovoLogUtil.java) - [FrameworkController.java](file://lemes-cloud/lemes-framework/lemes-framework-datasource/src/main/java/com/lenovo/lemes/datasource/api/FrameworkController.java) - [DynamicDbName.java](file://lemes-cloud/lemes-framework/lemes-framework-datasource/src/main/java/com/lenovo/lemes/datasource/constants/DynamicDbName.java) - [OpenApiController.java](file://lemes-cloud/lemes-framework/lemes-framework-datasource/src/main/java/com/lenovo/lemes/datasource/api/OpenApiController.java) - [docker-compose.yml](file://lemes-cloud/src/devops/docker-compose/docker-compose.yml) - [settings.js](file://dm/lemes-web/src/settings.js) - [axios.js](file://dm/lemes-web/src/components/verifition/utils/axios.js) - [index.js](file://app/devicemate-app/config/index.js) - [upgrade.js](file://app/devicemate-app/utils/upgrade/upgrade.js) - [upgrade-config.js](file://app/devicemate-app/utils/upgrade/upgrade-config.js) - [messages_en_US.properties](file://lemes-job-devicemate/lemes-job-devicemate-executor/src/main/resources/messages_en_US.properties) - [IotServiceImpl.java](file://lemes-cloud/lemes-business-devicemate/lemes-service-dm-common/lemes-service-dm-common-server/src/main/java/com/lenovo/lemes/service/dm/common/service/impl/IotServiceImpl.java) - [DeviceMttrServiceImpl.java](file://lemes-job-devicemate/lemes-job-devicemate-executor/src/main/java/com/lenovo/lemes/job/devicemate/executor/service/device/impl/DeviceMttrServiceImpl.java) - [ClientServiceImpl.java](file://lemes-cloud/lemes-service-common/lemes-service-common-server/src/main/java/com/lenovo/lemes/service/common/server/service/impl/ClientServiceImpl.java) - [LemesLoadBalancer.java](file://lemes-cloud/lemes-framework/lemes-framework-core/src/main/java/com/lenovo/lemes/framework/core/config/LemesLoadBalancer.java)目录
简介
本文件面向DeviceMate项目的运维与开发人员，提供系统启动失败、数据库连接问题、服务调用异常等典型故障的诊断与修复方法；解释日志分析技巧、性能问题定位与系统监控指标解读；并给出版本升级注意事项、兼容性问题与迁移指南，帮助快速定位与解决问题。
项目结构
DeviceMate由前端应用、后端微服务网关与多个业务子服务组成，采用Spring Cloud/Nacos注册发现与配置中心、动态数据源切换、统一异常与响应封装、以及Kubernetes/Docker容器化部署方案。
图示来源
章节来源
核心组件
- 网关与异常处理：统一异常返回、错误响应体、跨服务调用失败兜底。
- 动态数据源：支持多数据源切换与查询，避免敏感信息泄露。
- 日志合规：统一API调用日志格式，便于审计与问题追踪。
- 前端请求与升级：统一超时、拦截器与升级流程提示。
- 容器编排：通过Compose/K8s管理服务生命周期与端口映射。
章节来源
- LemesErrorWebExceptionHandler.java:1-63
- ResultData.java:1-115
- FrameworkController.java:1-49
- LenovoLogUtil.java:24-129
- axios.js:1-30
- upgrade.js:62-94
架构总览
下图展示从客户端到网关、再到各业务服务与数据源的整体调用链路与异常处理路径。
图示来源
详细组件分析
网关异常处理与统一响应
- 统一异常处理：对非2xx响应进行捕获，构造标准错误响应体。
- 返回体规范：基于统一结果封装类，确保前后端一致的错误字段。
- 兜底异常：自定义全局异常用于兜底场景。
图示来源
章节来源
动态数据源与安全
- 多数据源枚举：集中定义可用数据源名称，避免硬编码。
- 列表接口：返回数据源名称与主从标识，不直接暴露连接串。
- 表查询接口：在指定数据源上下文中查询表清单，避免泄露敏感信息。
图示来源
章节来源
前端请求与升级机制
- 请求拦截：统一超时、请求头、响应拦截与错误透传。
- 升级流程：下载进度提示、错误弹窗与失败回退。
图示来源
章节来源
作业执行与性能指标
- 设备MTTR统计：对同一设备的停机时间进行聚合与比率计算，注意空值保护与除零风险。
- 服务负载均衡：实例选择与无可用实例告警，保障流量分发健康。
图示来源
章节来源
依赖关系分析
- 网关依赖异常处理与统一响应封装，保证对外一致性。
- 业务服务依赖动态数据源框架，实现多库查询与安全控制。
- 前端依赖axios拦截器与升级模块，提升用户体验与稳定性。
图示来源
- LemesErrorWebExceptionHandler.java:34-62
- ResultData.java:45-79
- FrameworkController.java:22-48
- axios.js:1-30
- upgrade.js:62-94
章节来源
- LemesErrorWebExceptionHandler.java:1-63
- ResultData.java:1-115
- FrameworkController.java:1-49
- axios.js:1-30
- upgrade.js:62-94
性能考量
- 超时与重试：前端请求默认较长超时，建议结合业务场景调整；后端服务间调用需考虑熔断与降级策略。
- 日志开销：合规日志包含延迟与错误信息，生产环境需关注日志级别与落盘性能。
- 负载均衡：实例不可用时的告警与实例选择逻辑，有助于快速发现服务异常。
- 数据源查询：批量查询与连接池参数需根据并发与数据量调优。
章节来源
故障排除指南
系统启动失败
- 现象
- 网关无法启动或端口占用。
- 服务注册失败或Nacos连接异常。
- 日志路径或权限问题导致启动失败。
- 诊断步骤
- 检查网关端口与优雅停机配置。
- 校验Nacos用户名/密码/命名空间/组配置。
- 确认日志目录存在且具备写权限。
- 修复建议
- 修改端口或释放冲突进程。
- 使用正确的Nacos凭据与网络可达性。
- 创建日志目录并赋予写权限。
章节来源
数据库连接问题
- 现象
- 查询接口报错或返回空数据。
- 动态数据源切换失败。
- 诊断步骤
- 通过数据源列表接口确认可用数据源名称。
- 在指定数据源上下文查询表清单，验证连接。
- 检查数据源枚举与实际配置是否一致。
- 修复建议
- 在业务层正确设置数据源上下文。
- 核对连接串与驱动配置，避免明文泄露。
章节来源
服务调用异常
- 现象
- 跨服务调用返回非成功状态或空数据。
- 业务聚合逻辑出现空指针或除零。
- 诊断步骤
- 检查上游服务返回的统一结果封装字段。
- 关注聚合服务对空值与集合判空的处理。
- 修复建议
- 在调用方增加健壮性校验与默认值处理。
- 对可能为null的数值进行保护性判断。
章节来源
网关异常与统一响应
- 现象
- 非2xx响应未被正确格式化。
- 自定义异常未按预期返回。
- 诊断步骤
- 查看异常处理器对响应是否已提交。
- 确认异常类型分支与错误码映射。
- 修复建议
- 避免重复提交响应；确保统一错误体序列化成功。
章节来源
前端请求与升级问题
- 现象
- 请求超时或无响应。
- 升级下载进度异常或失败。
- 诊断步骤
- 检查基础URL与超时配置。
- 观察升级模块事件回调与提示文案。
- 修复建议
- 调整超时阈值与重试策略。
- 优化升级提示与失败回退逻辑。
章节来源
日志分析与合规
- 现象
- API调用延迟过高或错误频繁。
- 缺少错误信息导致定位困难。
- 诊断步骤
- 使用统一日志工具记录目标URL、方法、状态码、延迟与错误信息。
- 结合CMDB字段进行关联分析。
- 修复建议
- 在高延迟或错误场景补充错误信息字段。
- 控制日志级别与采样率以平衡可观测性与性能。
章节来源
版本升级注意事项与兼容性
- 注意事项
- 前端升级模块需确保下载事件回调与提示文案一致。
- 升级配置项影响弹窗样式与行为，需与UI约定保持一致。
- 兼容性
- 基础密钥配置需与后端一致，避免鉴权失败。
- 迁移指南
- 升级前备份当前配置与日志。
- 升级后验证网关连通性与服务注册状态。
章节来源
结论
通过统一异常处理、动态数据源与合规日志体系，DeviceMate在可观测性与稳定性方面具备良好基础。针对启动、数据库、服务调用、前端请求与升级等常见问题，建议优先检查配置与依赖、强化空值与边界条件处理，并结合日志与监控指标进行定位与优化。
附录
常见错误码与提示
- 作业执行器国际化提示包含连接超时等错误描述，便于定位上游服务问题。
章节来源
前端错误日志与设置
- 生产环境默认开启错误日志组件，便于捕获前端异常。
章节来源