企业官网建设流程全解析

一、引言

告警出现时，人们第一反应是打开日志平台搜关键词，切到APM看监控曲线，再去链路追踪系统找trace详情。在三个平台间来回切换后，却发现只是上游GC抖动导致的瞬间超时，且一分钟后就自愈了。这类告警排查通常需10 - 30分钟，主要耗时在于频繁登录不同平台、拼凑分散的数据。同时，排查效率高度依赖个人经验，新人面对告警往往不知先看什么。于是，我们开发了Troubleshooter，它利用LLM Agent自动完成告警的数据采集、根因分析和处置建议生成。上线后，中位数排查耗时从20分钟左右降到4.4分钟，覆盖了11个服务和10 + 种告警类型。本文将详细介绍其技术方案。

二、架构设计

整体采用分层设计，核心原则是告警接入与排查执行解耦，即接入层只负责接收和持久化，排查由独立的调度器异步触发。Agent框架选用Spring AI Alibaba而非自建ReAct循环，主要是因其省事，该框架已内置推理循环、工具拦截器、模型拦截器，可直接使用。

三、核心流程

完整排查链路有其特定流程，核心步骤如下：告警接入，接收告警数据并生成唯一事件ID；指纹生成，提取5维度特征（服务名、告警类型、错误模式、指标名、错误摘要），生成32位MD5指纹；知识匹配，在知识库中检索相似记录，匹配成功则直接复用历史结论；AI排查，由Supervisor Agent编排排查，执行ReAct推理循环；结论验收，由独立的Validation Agent检查根因明确性和处置建议完整性；报告推送，生成Markdown格式报告，推送到飞书群组；知识沉淀，运维确认后的结论存入知识库。

四、AI排查引擎：ReAct Agent实战

这是整个系统最核心的部分，我们使用了Spring AI Alibaba的ReactAgent，它实现了经典的ReAct推理循环：LLM思考 → 选择工具 → 执行工具 → 观察结果 → 继续思考 → ... → 输出结论。

SupervisorAgent：不是简单地调Prompt

很多人认为「AI排查」就是构造一个Prompt丢给大模型，但实际上LLM无法凭空知晓服务当前QPS、错误日志内容、调用链超时环节等信息，它需要工具。SupervisorAgent有其核心设计，包含四个@Tool方法，分别用于查询并分析应用日志、查询服务监控指标、通过traceId查询分布式调用链详情、无traceId时通过接口路径查询错误日志并提取traceId。其执行排查的核心方法包括动态构建instruction、构建ReAct Agent以及进行验收循环，最多进行2次LLM内容重试。

四个排查工具的设计哲学

工具一：queryLogs——日志查询与分析。日志是排查的第一入口，它通过WebSocket连接日志平台，按优先级分批查询，查询优先级为：traceId > exceptionName > endpoint > keywords。每批结果都会经过LLM异步分析，最后汇总所有批次的结论，同时还有日志去重（LogDeduplicator），防止同一请求的多条日志重复占据分析窗口。

工具二：queryMetrics——监控指标查询。支持10个维度的指标查询，LLM可根据告警类型自主决定查询哪些维度。MetricService接口为不同环境（csprd/oa/pre/t1）提供了可插拔的实现，因为APM查询参数中环境代码不同，生产环境用csprd - proxy，测试环境用t1 - proxy。

工具三：queryTrace——分布式链路追踪。当告警带有traceId时，此工具直接查询APM获取Span树，渲染为格式化文本后交给LLM分析，能识别出哪个下游依赖变慢、哪个环节抛出了异常。

工具四：queryEndpointErrors——接口错误排查。当没有traceId但有明确的接口路径时，这个工具会查询该接口的错误日志，通过正则提取所有traceId，再逐个分析。有个重要的防护逻辑，当endpoint为根路径 "/" 时，拒绝执行，因为匹配所有请求的查询不具备排查意义。

动态策略组装

不同服务、不同告警类型的排查思路差异很大，比如OOM告警要关注GC指标和堆内存，接口超时要关注QPS突变和下游依赖延迟。我们设计了策略匹配机制，按(service_name, alert_type)从数据库精确匹配排查策略，未匹配时使用内置兜底策略。运维人员可通过前端页在线编辑策略内容，无需改代码。

工具超时隔离

外部系统（日志平台、APM）不一定稳定，每个工具调用通过ToolExecutor包装，用独立线程池 + Future.get(timeout)实现超时控制。

AI权限安全保证

超时时返回降级消息，如「指标查询超时，继续使用已有信息进行排查」，LLM会基于已有证据继续推进，不会因单个工具超时导致整个排查流程中断。

五、幻觉控制与结论质量保障

LLM输出不稳定是落地过程中最大的风险点，我们从四个维度构建了幻觉控制体系。规则格式校验（零LLM调用），第一轮检查直接检查5个必要章节是否存在，以及指标表格格式是否规范，这一步完全不调用LLM，毫秒级完成。独立验收Agent进行内容质量审查，检查项包括结论是否明确、核心判定是否合理、根因是否有工具证据、建议是否可执行。多轮交叉验证要求不同工具的返回结果必须相互印证才能形成结论，如queryLogs与queryTrace交叉、queryLogs与queryMetrics交叉、时间线一致性校验。重试机制规定格式问题不消耗重试配额，内容问题最多重试2次，验收Agent异常时宽容通过。

六、排查过程可观测性

排查过程不能是一个黑盒，我们需要让运维人员看到AI每一步在做什么。

文件系统日志

每次排查在文件系统中创建独立目录（按事件ID），LoggerInterceptor和ToolInterceptor记录了所有LLM输入/输出和工具调用/返回。

内存进度追踪

EventProgressTracker在内存中维护每个事件的实时状态（当前阶段、当前策略描述），前端通过3秒轮询获取进度更新。

七、真实排查案例：效率网关超时

下面以一次生产环境网关超时告警为例，完整展示Troubleshooter的排查过程。告警信息包括服务名、告警类型、错误信息、严重级别、环境、接口路径、TraceID、告警时间等。AI排查过程中，SupervisorAgent在4分钟内完成了3次工具调用 + 1轮验收修正，逐步逼近根因。第1次验收未通过，要求补全缺失的必填字段；第2次验收通过，LLM补充了结构化字段，紧急程度为「观察」，置信度为「高」。AI最终排查结论明确了本次告警的根因、影响范围和处置建议。效果对比显示，整个排查过程从告警接入到输出结论耗时约4分钟（工具调用总计88s + LLM推理 + 验收），若人工排查，保守估计需10 - 20分钟。

八、技术难点与踩过的坑

环境统一映射

告警信息中的环境标识五花八门，日志平台和APM平台的环境代码也不同。我们通过EnvironmentProperties集中管理了5套环境的别名映射，支持精确匹配 + 包含匹配，且在tool方法中直接使用告警事件中的环境字段，不让LLM自行映射，避免LLM "翻译" 环境名时出错。

LLM调用Round - Robin多Key

LLM网关有频率限制，单个API Key在高频调用下会被限流。我们实现了RoundRobinChatModel，支持配置多个API Key，按事件ID哈希取模固定分配，同一个排查过程中的所有LLM调用使用同一个Key，避免上下文切换。

九、效果与数据

系统上线后，我们统计了从2026 - 04 - 21至2026 - 05 - 14的运行数据，包括运行概况、排查性能、效率对比等。结论质量方面，验收首次通过率约60%，验收二次通过率约38%，验收耗尽兜底率约2%。

十、后续迭代方向

当前版本还有一些设计上的取舍，按优先级规划如下：多Agent并行排查，日志查询和指标查询可以并行执行；指纹知识库，实现秒级匹配已知问题；跨服务关联分析，识别级联故障；自动处置能力，从"排查 + 建议"升级到"排查 + 自动修复"；向量语义检索，实现语义级相似问题检索。Troubleshooter不是要替代运维人员，而是把机械操作交给AI，让运维人员专注于需要判断力和创造力的决策。