vitepress-template

Appearance

故障排除 ​

**本文引用的文件** - [[bi-common/observability/logger/README.md]](file/bi-common/observability/logger/readme.md) - [[bi-common/database/gormx/README.md]](file/bi-common/database/gormx/readme.md) - [[bi-common/database/gormx/config.go]](file/bi-common/database/gormx/config.go) - [[bi-common/registry/nacos/README.md]](file/bi-common/registry/nacos/readme.md) - [[bi-common/registry/nacos/config.go]](file/bi-common/registry/nacos/config.go) - [[bi-intra/charts/kafka/README.md]](file/bi-intra/charts/kafka/readme.md) - [[bi-intra/charts/grafana/deploy.sh]](file/bi-intra/charts/grafana/deploy.sh) - [[mcp-server-starrocks/src/mcp_server_starrocks/connection_health_checker.py]](file/mcp-server-starrocks/src/mcp-server-starrocks/connection-health-checker.py) - [[mcp-server-starrocks/tests/test_db_client.py]](file/mcp-server-starrocks/tests/test-db-client.py) - [[bi-chat/bi_chat/src/agents/general_agent.py]](file/bi-chat/bi-chat/src/agents/general-agent.py) - [[bi-chat/bi_chat/src/workflow/execution_engine.py]](file/bi-chat/bi-chat/src/workflow/execution-engine.py)

目录 ​

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

简介 ​

本故障排除文档面向BI分析平台的运维与开发人员，聚焦于启动失败、连接超时、性能问题、网络与数据库诊断、AI智能体系统调试与工具调用异常处理，以及应急响应与升级机制。文档提供系统化的排查步骤、日志分析技巧、关键指标解读与监控工具使用建议，帮助快速定位并解决问题。

项目结构 ​

本平台采用多模块分层架构，包含：

  • 通用基础设施：日志、数据库、配置中心（Nacos）、消息队列（Kafka）、监控（Grafana）等
  • 业务服务：分析服务、API网关、聊天与智能体系统
  • AI智能体：多Agent协作、工具调用、任务编排与反思

[本图为概念性结构示意，不直接映射具体源码文件，故不附“图表来源”]

核心组件 ​

  • 日志组件：统一日志格式、级别过滤、多输出（stdout/文件/SLS）、请求日志中间件、链路追踪
  • 数据库组件：GORM封装、连接池、StarRocks优化、TLS加密、事务支持
  • 配置中心：Nacos SDK v2，配置优先级、Kratos集成、服务发现
  • 消息队列：Kafka Helm Chart，Combined Mode，健康检查与故障排查
  • 监控：Grafana Helm部署脚本与仪表板
  • AI智能体：多Agent工具调用、DAG执行、反思与异常处理

章节来源

  • file://bi-common/observability/logger/README.md#L1-L489
  • file://bi-common/database/gormx/README.md#L1-L608
  • file://bi-common/database/gormx/config.go#L1-L227
  • file://bi-common/registry/nacos/README.md#L1-L759
  • file://bi-common/registry/nacos/config.go#L1-L223
  • file://bi-intra/charts/kafka/README.md#L1-L291
  • file://bi-intra/charts/grafana/deploy.sh#L57-L107

架构总览 ​

图表来源

详细组件分析 ​

日志组件（故障排查重点） ​

  • 日志级别与格式：开发/生产不同配置；JSON格式便于分析；建议生产环境info/warn
  • 敏感信息脱敏：避免记录密码、Token、身份证等
  • 请求日志中间件：自动记录kind、operation、request_id、code、reason、duration_ms
  • 多输出与降级：stdout、文件、阿里云SLS；云端失败不影响本地
  • 告警配置：错误率、P95延迟、日志量异常

图表来源

章节来源

  • file://bi-common/observability/logger/README.md#L342-L407

数据库组件（连接与性能） ​

  • 连接池：MaxOpenConns、MaxIdleConns、ConnMaxLifetime、ConnMaxIdleTime
  • StarRocks优化：自动MaxIdleConns=MaxOpenConns，禁用空闲回收
  • TLS加密：系统默认CA、自定义CA、双向认证(mTLS)、SNI
  • 健康检查：Ping接口；Stats连接池状态
  • 慢查询：日志级别与慢查询阈值配置

图表来源

章节来源

  • file://bi-common/database/gormx/README.md#L531-L572
  • file://bi-common/database/gormx/config.go#L184-L227

配置中心（Nacos）与服务发现 ​

  • 零配置启动、环境变量优先级、Kratos集成
  • 多配置文件合并、DataID自动推断(go.mod)
  • 服务注册/发现、Kratos Registry集成
  • 常见问题：鉴权失败、DataID不匹配、命名空间/分组错误

图表来源

章节来源

  • file://bi-common/registry/nacos/README.md#L313-L392
  • file://bi-common/registry/nacos/config.go#L191-L223

消息队列（Kafka）与监控 ​

  • Combined Mode：broker+controller在同一Pod
  • 监听器：CONTROLLER(9093)、PLAINTEXT(19092)、PLAINTEXT_HOST(9092)
  • 故障排查：DNS解析NXDOMAIN、Liveness探针失败、镜像拉取失败
  • 部署验证：查看集群、创建topic、describe topic

图表来源

章节来源

  • file://bi-intra/charts/kafka/README.md#L396-L404
  • file://bi-intra/charts/kafka/README.md#L256-L291

监控（Grafana）部署与检查 ​

  • Helm部署脚本：创建Secret、检查Helm与Chart、等待安装完成
  • 部署后检查：Pod状态、Service、ServiceMonitor、日志

章节来源

  • file://bi-intra/charts/grafana/deploy.sh#L57-L107

AI智能体系统（调试与工具调用） ​

  • GeneralAgent：工具注册（计算、百科、汇率、联网搜索），工具调用循环，异常处理
  • DAG执行器：任务依赖满足检测、并行执行、错误上报与回退
  • 反思器：评估结果满足度，反馈缺失部分，避免死循环

图表来源

章节来源

  • file://bi-chat/bi_chat/src/agents/general_agent.py#L1-L279
  • file://bi-chat/bi_chat/src/workflow/execution_engine.py#L1-L287

依赖关系分析 ​

图表来源

性能考量 ​

  • 日志性能：生产环境info级别、JSON格式、异步写入；高流量服务考虑采样
  • 数据库性能：合理设置连接池参数；StarRocks优化减少连接抖动；慢查询阈值
  • 网络与Kafka：探针参数调优、Headless Service Ready行为、镜像拉取优化
  • 监控与告警：错误率、P95延迟、日志量异常阈值

[本节为通用指导，不直接分析具体文件，故不附“章节来源”]

故障排除指南 ​

启动失败 ​

  • 检查依赖服务：数据库、Nacos、Kafka是否就绪
  • 查看容器日志：Grafana部署后检查Pod日志与Service状态
  • 环境变量与配置：确认日志、数据库、Nacos配置正确
  • 配置优先级：环境变量 > 函数选项 > 配置文件 > 默认值

章节来源

  • file://bi-intra/charts/grafana/deploy.sh#L57-L107
  • file://bi-common/registry/nacos/README.md#L313-L392

连接超时 ​

  • 数据库连接：检查DSN、TLS配置、连接池参数；使用Ping与Stats诊断
  • Nacos连接：确认鉴权、DataID、命名空间/分组；查看客户端日志级别
  • Kafka连接：检查DNS解析、Service与Endpoints、端口连通性

章节来源

  • file://bi-common/database/gormx/README.md#L565-L572
  • file://bi-common/database/gormx/config.go#L184-L227
  • file://bi-common/registry/nacos/README.md#L332-L360
  • file://bi-intra/charts/kafka/README.md#L256-L291

性能问题 ​

  • 日志分析：使用request_id关联请求链路；关注错误率与P95延迟
  • 数据库优化：调整连接池与慢查询阈值；StarRocks优化策略
  • 监控告警：在Grafana中设置错误率与延迟阈值告警

章节来源

  • file://bi-common/observability/logger/README.md#L401-L407
  • file://bi-common/database/gormx/README.md#L531-L547

网络问题排查 ​

  • DNS与Service：确认Headless Service解析；必要时开启publishNotReadyAddresses
  • 探针与健康：调整Liveness初始延迟与失败阈值
  • 镜像拉取：配置私有仓库认证

章节来源

  • file://bi-intra/charts/kafka/README.md#L396-L404

数据库连接问题诊断 ​

  • 连接健康检查：定期执行show databases；记录错误信息
  • 连接参数解析：URL解析测试覆盖多种场景（IP、端口、特殊字符）
  • 连接池状态：使用Stats查看InUse/Idle/WaitCount

图表来源

章节来源

  • file://mcp-server-starrocks/src/mcp_server_starrocks/connection_health_checker.py#L15-L153
  • file://mcp-server-starrocks/tests/test_db_client.py#L776-L811

AI智能体系统调试与工具调用异常处理 ​

  • 工具调用循环：捕获工具执行异常，记录错误并继续流程
  • DAG执行：检测死锁/无进展，强制并行执行剩余任务；错误上报
  • 反思器：评估结果满足度，反馈缺失部分；失败时默认满足防止死循环

章节来源

  • file://bi-chat/bi_chat/src/agents/general_agent.py#L164-L263
  • file://bi-chat/bi_chat/src/workflow/execution_engine.py#L55-L110
  • file://bi-chat/bi_chat/src/workflow/execution_engine.py#L185-L194
  • file://bi-chat/bi_chat/src/workflow/execution_engine.py#L282-L286

应急响应流程与问题升级机制 ​

  • 一级响应：快速定位日志与错误码，确认是否为瞬时异常
  • 二级响应：涉及数据库/网络/配置中心的跨组件问题，组织跨团队协同
  • 三级响应：影响范围广、SLA告警，启动应急预案并升级至技术负责人

[本节为通用流程建议，不直接分析具体文件，故不附“章节来源”]

结论 ​

通过统一的日志、完善的数据库与配置中心、健壮的消息队列与监控体系，以及可编排的AI智能体系统，BI分析平台具备较强的可观测性与可维护性。遵循本文提供的系统化排查步骤与最佳实践，可显著缩短故障定位与恢复时间，保障业务连续性。

附录 ​

  • 常用命令与检查清单
    • Grafana部署：检查Helm、Chart、Values；查看Pod/Service/ServiceMonitor/日志
    • Kafka：查看Pod事件、StatefulSet、Service/Endpoints；DNS解析与端口连通性；创建/描述topic
    • 数据库：Ping与Stats；DSN/TLS配置；连接池参数
    • Nacos：鉴权、DataID、命名空间/分组；配置合并优先级

章节来源

  • file://bi-intra/charts/grafana/deploy.sh#L57-L107
  • file://bi-intra/charts/kafka/README.md#L256-L291
  • file://bi-common/database/gormx/README.md#L565-L572
  • file://bi-common/registry/nacos/README.md#L313-L392