vitepress-template

Appearance

故障排除指南 ​

**本文档引用的文件** - [[bi-analysis/cmd/bi-analysis/main.go]](../file/bi-analysis/cmd/bi-analysis/main.go) - [[bi-analysis/configs/application-dev.yaml]](../file/bi-analysis/configs/application-dev.yaml) - [[bi-common/observability/logger/logger.go]](../file/bi-common/observability/logger/logger.go) - [[bi-common/registry/nacos/client.go]](../file/bi-common/registry/nacos/client.go) - [[bi-common/registry/nacos/discovery.go]](../file/bi-common/registry/nacos/discovery.go) - [[bi-common/registry/nacos/registry.go]](../file/bi-common/registry/nacos/registry.go) - [[bi-common/mq/kafkax/consumer.go]](../file/bi-common/mq/kafkax/consumer.go) - [[bi-common/mq/kafkax/config.go]](../file/bi-common/mq/kafkax/config.go) - [[bi-common/database/gormx/config.go]](../file/bi-common/database/gormx/config.go) - [[bi-basic/cmd/server/main.go]](../file/bi-basic/cmd/server/main.go) - [[bi-intra/charts/grafana/README.md]](../file/bi-intra/charts/grafana/readme.md) - [[mcp-server-starrocks/src/mcp_server_starrocks/db_client.py]](../file/mcp-server-starrocks/src/mcp-server-starrocks/db-client.py) - [[scripts/port-forward.sh]](../file/scripts/port-forward.sh) - [[_bmad/bmm/testarch/knowledge/log.md]](../file/bmad/bmm/testarch/knowledge/log.md) - [[_bmad/bmm/testarch/knowledge/error-handling.md]](../file/bmad/bmm/testarch/knowledge/error-handling.md)

目录 ​

  1. 简介
  2. 项目结构
  3. 核心组件
  4. 架构总览
  5. 详细组件分析
  6. 依赖关系分析
  7. 性能考量
  8. 故障排除指南
  9. 结论
  10. 附录

简介 ​

本指南面向BI分析平台的运维与开发人员，提供系统性的故障诊断方法与调试技巧。内容涵盖启动失败（依赖服务不可用、配置错误、端口冲突）、性能问题（慢查询、内存/CPU异常）、网络连接问题（服务发现、负载均衡、防火墙）、日志分析与错误解读、各服务模块特定故障模式与解决方案，以及应急响应流程与常用诊断命令。

项目结构 ​

BI分析平台由多语言、多模块构成，包含Go微服务、Python MCP服务、前端与可视化组件，并通过Nacos进行配置与服务治理，Kafka负责消息流，GORM/StarRocks负责数据访问，Grafana提供可观测性。

图表来源

章节来源

核心组件 ​

  • 应用启动与配置
    • Kratos应用通过Nacos配置源加载Bootstrap配置，初始化日志、雪花ID、服务注册与业务wireApp。
    • bi-basic同样采用Nacos配置源与统一日志初始化。
  • 服务注册与发现
    • Nacos客户端封装配置中心与服务发现能力；服务注册/注销与健康实例发现均基于SDK。
  • 消息队列
    • Kafka消费者支持健康检查、优雅关闭、单分区/消费者组模式、批量与超时配置。
  • 数据访问
    • GORM配置含连接池、慢查询阈值、TLS与DSN拼装，支持StarRocks优化。
  • 观测性
    • Grafana通过ARMS Prometheus采集指标，支持ACK集群内置与自定义ServiceMonitor。
  • 查询分析
    • Python MCP服务可收集StarRocks查询dump、profile与分析文本，辅助定位慢查询。

章节来源

架构总览 ​

下图展示启动阶段的关键交互：应用解析Nacos配置、初始化日志与注册、构建业务服务并启动。

图表来源

章节来源

详细组件分析 ​

启动与配置组件 ​

  • 配置加载
    • 通过Nacos配置源加载application-*.yaml，扫描为Bootstrap结构，随后初始化日志与雪花ID。
  • 日志初始化
    • 支持stdout/file/both输出、JSON/text格式、级别过滤、阿里云日志桥接与清理。
  • 服务注册
    • 将Nacos注册器注入Kratos，实现服务注册与注销、健康实例发现与订阅。

图表来源

章节来源

服务发现与注册 ​

  • 注册/注销
    • 解析Endpoint，提取主机与端口，按serviceName.scheme注册/注销。
  • 发现
    • 健康实例与全部实例发现，支持订阅回调。
  • 负载均衡
    • 选择一个健康实例作为目标。

图表来源

章节来源

Kafka消费者 ​

  • 健康检查
    • 通过Ping校验Broker连通性与可用Broker列表。
  • 运行模式
    • 支持单分区与消费者组模式；优雅关闭监听系统信号并等待处理完成。
  • 统计与延迟
    • 提供Lag、Stats等指标辅助定位积压。

图表来源

章节来源

数据库与慢查询定位 ​

  • DSN与TLS
    • 支持MySQL/StarRocks，自动拼装DSN，StarRocks优化建议与TLS参数。
  • 慢查询阈值
    • GORM日志级别与慢查询阈值可配置，便于识别慢SQL。
  • Python查询分析
    • 通过MCP服务收集query dump、profile与分析文本，辅助定位执行计划问题。

图表来源

章节来源

依赖关系分析 ​

  • 配置与日志
    • 应用通过Nacos配置源加载Bootstrap，再初始化日志与雪花ID。
  • 服务治理
    • Nacos提供配置中心与服务发现，消费者与注册器均依赖其SDK。
  • 数据与消息
    • 数据访问依赖GORM配置；消息消费依赖Kafka消费者封装。
  • 可观测性
    • Grafana通过ARMS Prometheus采集指标，支持ACK内置与自定义ServiceMonitor。

图表来源

章节来源

性能考量 ​

  • 指标采集
    • Grafana通过ARMS Prometheus采集节点、容器与业务指标，支持自定义ServiceMonitor。
  • 数据库
    • GORM慢查询阈值与日志级别可调；StarRocks连接池优化建议启用。
  • 消息队列
    • 消费者组模式提升扩展性；合理设置批大小、超时与隔离级别。
  • Python查询分析
    • 使用MCP服务收集profile与analyze结果，定位热点SQL与执行瓶颈。

章节来源

故障排除指南 ​

启动失败排查 ​

  • 依赖服务不可用
    • Nacos配置中心不可达：检查Nacos地址、端口、命名空间与DataId；确认网络连通与鉴权。
    • Kafka不可达：使用消费者Ping检查Broker连通性。
    • StarRocks不可达：检查DSN、TLS与网络策略。
  • 配置错误
    • application-*.yaml缺失或字段不合法：核对nacos.server、client.group、config.data_ids。
    • 日志配置非法：检查日志级别、输出方式与文件路径。
  • 端口冲突
    • 通过端口转发脚本进行连通性验证，避免端口占用导致启动失败。

章节来源

性能问题定位 ​

  • 慢查询
    • 开启GORM慢查询日志，结合阈值定位热点SQL；必要时启用StarRocks优化参数。
    • 使用MCP服务收集query dump与profile，分析执行计划。
  • 内存/CPU过载
    • 通过Grafana查看Pod/节点指标，结合业务指标判断是否为热点接口或批处理峰值。
    • 调整Kafka消费者批大小、超时与并发，缓解瞬时压力。
  • 连接池问题
    • 检查数据库连接池参数（最大打开/空闲连接、生命周期），避免连接泄漏或抖动。

章节来源

网络连接问题 ​

  • 服务发现失败
    • 使用DiscoverService/SelectOneHealthyInstance确认健康实例是否存在；检查Group与Cluster配置。
  • 负载均衡异常
    • 核对消费者组模式与分区分配；关注重平衡与心跳间隔。
  • 防火墙/网络策略
    • 使用Ping与端口转发脚本验证连通性；检查入站/出站策略与安全组。

章节来源

日志分析与错误解读 ​

  • 日志配置
    • 使用本地与阿里云日志桥接，确保错误与关键路径均有落盘与上报。
  • 敏感信息保护
    • 避免直接记录敏感字段；必要时仅输出摘要或预览。
  • 错误上下文
    • 记录请求上下文（endpoint、method、status、用户ID等），便于复现与追踪。

章节来源

各服务模块特定故障模式与解决方案 ​

  • Nacos配置中心
    • 现象：无法拉取配置或注册失败。
    • 排查：校验地址、端口、命名空间、DataId与鉴权；检查SDK日志。
  • Kafka消费者
    • 现象：无消息消费、积压严重。
    • 排查：确认消费者组、分区分配、批大小与超时；使用Lag/Stats观察延迟。
  • 数据库
    • 现象：连接失败、慢查询增多。
    • 排查：检查DSN/TLS、连接池参数与慢查询阈值；必要时启用StarRocks优化。
  • Grafana/指标
    • 现象：面板无数据或延迟高。
    • 排查：确认ServiceMonitor配置、Job标签与采集周期。

章节来源

应急响应流程与紧急修复 ​

  • 快速止损
    • 降级非关键链路、临时关闭热点接口、限流与熔断。
  • 修复步骤
    • 依据日志与指标定位根因；回滚最近变更；修复配置或代码；验证后恢复。
  • 回归验证
    • 通过端到端测试与关键指标回归，确保问题彻底解决。

[本节为通用流程说明，不直接分析具体文件]

常用诊断命令与工具 ​

  • 端口连通性
    • 使用端口转发脚本进行连通性验证。
  • Nacos
    • 检查配置发布/删除/监听状态；确认命名空间与DataId。
  • Kafka
    • 消费者Ping、Stats/Lag查看、单分区/消费者组模式切换。
  • 数据库
    • 检查DSN/TLS参数与连接池；开启慢查询日志。
  • Grafana
    • 校验ServiceMonitor与Job标签，确认采集与存储。

章节来源

结论 ​

本指南提供了从启动、网络、性能到日志与应急响应的完整排障路径。建议在日常运维中结合Grafana指标、Kafka消费者Stats与GORM慢查询日志，形成“配置—注册—消息—数据—观测”的闭环，快速定位并解决问题。

附录 ​