企业官网建设流程全解析

凌晨两点半，手机连着响了五六声，全是同一套监控告警：Agent Platform 的线上接口 P99 耗时从平时 300ms 一路飙到了 2.6 秒，错误率从 0.02% 跳到 7% 左右。我爬起来打开电脑，先是看到群里的消息已经炸了，紧接着一排红色告警刷下来，核心代理执行接口大面积超时，下游业务方已经开始反馈任务积压。这是 Agent Platform 上线以来最严重的一次线上超时故障，整个处理过程加上根因分析，前后花了将近六个小时。这篇文章把当时踩坑、定位、修复、复盘的全过程写下来，希望给做智能体平台、做 API 网关、做编排系统的朋友一些参考——尤其是那些自以为“上线了监控就万事大吉”的团队，真到故障来临时才知道，很多配置和预案都是虚的。

Agent Platform 这类系统的核心特点是：控制面复杂、执行链路长、依赖多。它不像普通 CRUD 接口那样只查一次库，一次 Agent 执行要经过配置中心拉取、工具注册表匹配、Schema 校验、多轮工具调用、结果拼接等好几个环节，任何一个环节耗时放大十几毫秒，放到高并发下都会变成雪崩的引子。这篇文章适合正在做 Agent/自动化平台研发、负责平台稳定性、或者对线上故障排查感兴趣的朋友，我会把整个故障的过程、排查思路、修复方案、复盘沉淀都拆开讲清楚，尽量做到你可以直接拿去对照自己的系统做体检。

1. 项目整体架构与故障场景还原

1.1 平台在系统中的定位和核心链路

先说清楚 Agent Platform 是什么。我们内部把它定义为“把 Agent 能力产品化的中间层”，它的上游是各个业务团队提交过来的任务请求，下游对接的是各类工具服务和模型服务。业务方不需要关心 Agent 是怎么组织的，只需要提交目标参数和上下文，平台负责完成代理执行、工具调用、结果汇聚、回传落地。

这个平台有几个核心模块：控制面负责 Agent 元数据管理、工具注册、编排配置下发；执行面负责接收任务、解析配置、按序调度工具调用；还有一层网关负责限流、鉴权和链路追踪。整体架构上，控制面和执行面虽然是分开部署的，但执行面每次跑一个 Agent 任务时，都会先从控制面的缓存里拉一次工具元数据，用来做 Schema 校验和参数适配。这个“每次拉取”的设计，恰好是后来超时故障的导火索之一。

1.2 故障当天的真实指标和现象

故障是在业务晚高峰开始的，大约晚上十点半，流量开始爬坡，我们收到了第一条耗时告警。告警规则是 P99 超过 800ms 持续 3 分钟触发，当时我看到后台监控面板里，代理执行接口的 P99 已经达到 1.6 秒，错误率开始抬头。十到十五分钟之后，耗时曲线几乎是垂直拉升，P99 突破 2.5 秒，同时执行面全部节点的活跃线程数逼近上限，Tomcat 线程池开始拒绝新请求，出现 Connection reset、Read timed out 等报错。

下游业务方很快就感受到了：所有依赖 Agent 执行的自动化流程明显变慢，有的任务直接失败，有的任务在队列里堆积了两三个小时才被执行。我们内部的监控大屏上，执行成功量骤降，积压数量以肉眼可见的速度在增长。更难受的是，重启单台机器只能缓解几十秒，新流量一进来，线程池马上又被占满，根本没有真正的恢复窗口。

1.3 故障爆发后的第一轮动作

凌晨的常规动作其实是固定的：先摘流量、再扩容、最后重启。但这次故障有个麻烦，摘流量会导致业务任务直接停滞，扩容出来的机器刚注册到服务发现，又被快速打满，问题并没有因为机器数量多了就缓解。这一现象本身就说明，瓶颈大概率不在 CPU 或内存，而在某个不可伸缩的资源上——比如线程池容量、某个外部依赖的连接数、又或者某些同步等待逻辑。

我们当时的做法是：先把告警拉群，让下游业务方知道平台异常、不要重试风暴；再留两台机器持续接流量用于现场抓取证据，其余节点执行摘流；同时打开全链路 trace 和 SQL 慢查询日志，准备从调用链往下钻。后面的事实证明，现场保留的这两台机器非常关键，因为它们保留了故障最真实的状态，让我们在五分钟内抓到了第一手线程栈。

2. 排查实录：从报警到揪出真正的元凶

2.1 先看全局，再逐步缩小范围

排查超时问题，我个人的经验是：不要一上来就怀疑代码，先看全局监控，用排除法把范围快速缩小。当天我们把排查路径分成三个分支并行推进：第一路查数据库慢查询和连接池状态，第二路查下游工具服务和模型服务的响应耗时，第三路查本应用 CPU、GC、线程池、网络 IO 这些基础指标。

数据库那一侧最先被排除。慢查询日志里没有任何长时间运行的 SQL，连接池活跃连接数也远低于上限，说明不是存储层的问题。下游服务的耗时曲线当时维持在正常水位，甚至没有明显的波动，也排除了一个大的嫌疑对象。真正异常的指标集中在应用本机：CPU 使用率在 30% 到 45% 之间，不算高；内存和 GC 也正常；但 Tomcat 线程池的 active 线程数长期接近 max 值，同时等待队列每秒都在增长。

这个组合非常典型：CPU 不高、线程却一直忙、任务排队严重，意味着大量线程并没有真正在做计算，而是阻塞在某个 IO 等待或者锁等待上。通常排查这类问题，抓线程栈是最高效的手段。

2.2 用线程栈和 Arthas 锁定耗时热点

当时我们连续抓了三次线程栈，间隔三秒，每次都有大量类似这样的栈顶：

"http-nio-8080-exec-72" #72 daemon prio=5 os_prio=0 cpu=12.30ms elapsed=325.14s tid=0x00007f123c0b2800 nid=0x2c1 waiting on condition [0x00007f120b2f5000] java.lang.Thread.State: RUNNABLE at com.fasterxml.jackson.databind.ObjectMapper.readValue(ObjectMapper.java:1133) at com.xxx.agent.core.metadata.ToolSchemaParser.parseJsonString(ToolSchemaParser.java:47) at com.xxx.agent.core.metadata.ToolSchemaParser.resolveToolSchema(ToolSchemaParser.java:89) at com.xxx.agent.core.execution.ToolRouter.matchTools(ToolRouter.java:62)

看到ObjectMapper.readValue大量出现时，第一反应是 JSON 解析很耗时。但让人困惑的是，JSON 解析正常的耗时是在毫秒级，怎么也不至于把线程堵这么久。于是我们直接用 Arthas 做了线上 trace，定位到具体方法的耗时分布：

# arthas 命令：追踪指定方法的调用耗时 trace com.xxx.agent.core.metadata.ToolSchemaParser resolveToolSchema '#cost > 200'

trace 结果非常直白：单个resolveToolSchema调用内部，耗时主要花在一次jsonNode.toString()和一次objectMapper.readValue()上，单次解析的峰值耗时超过 1.2 秒，平均耗时也在 800ms 左右。而且每一次 Agent 执行，这个方法至少要被调用三次：工具匹配阶段一次、参数解析阶段一次、结果校验阶段一次。

这类集中式的耗时点，一旦并发量上来，就会直接把线程池打满，后面的请求全得排队。排查到这里，方向已经很明确了，剩下的就是搞清楚为什么一个看似正常的 JSON 解析会突然变得这么慢。

2.3 压测复现并算清线程池的账

为了验证结论，我们当场对线上环境做了一个小规模压测：从工具镜像仓库拉取同一份真实工具元数据，用并发线程反复执行resolveToolSchema的完整调用链。压测结果和线上表现基本吻合：单次解析耗时会因为元数据内容长度的增加而显著上升，当工具描述文件膨胀到几十 KB 时，解析耗时的增速远超线性。

这里有一个关键计算，当时给我们敲响了警钟。执行面的 Tomcat 线程池配置是max-threads=200，高峰期单机每秒请求量约 120 到 150 个。如果每个请求的完整执行链路平均耗时是 1.8 秒，那单台机器同一时刻占用的线程数就是 QPS 乘以平均耗时，也就是120 * 1.8 ≈ 216。这个数字已经超过 200，线程池必然排队。如果平均耗时拉到 2.5 秒，占用的线程数就是 300 以上，大量请求直接超时失败。

这也是为什么故障发生后不管怎么扩容都没有用的原因：单次请求时长太长，系统的吞吐上限被严重压低，加再多机器也只是延缓问题爆发，并不能根治。要想真正恢复，必须把单次请求耗时降下来，把流量高峰的占用线程数压到安全水位以下。

3. 根因拆解：JSON 解析为什么会成为放大器

3.1 真实的耗时账单和数据结构问题

找到具体的慢方法之后，我们把它内部的耗时拆成了三个部分：字符串读取、Jackson 解析、后续节点遍历。这里的核心问题在于平台里存的“工具元数据”不是纯 JSON，它内嵌了大量用于描述参数结构的 JSON 字符串字段。换句话说，最外层的 JSON 里，有多个字段的值本身就是一大段 JSON 文本，后端在解析时，需要先把外层的 JSON 反序列化成 JsonNode，再取出内嵌字段，再次反序列化成独立的 JsonNode，最后做递归遍历和类型映射。

双层嵌套已经够折腾了，更麻烦的是单个 Agent 的工具注册表在某些场景下会非常大。压测时我们抽了一份真实数据，单个工具描述文件超过 50KB，包含近千个字段和几十层嵌套结构。每次执行 Agent 都要对这份 Schema 做多次完整解析，算下来单个请求在 JSON 解析上付出的 CPU 和 IO 成本会非常可观。

市面上主流的 JSON 解析库，包括 Jackson、Gson、Fastjson，在处理小对象时效率都很高，但面对这类几十 KB、深度嵌套、含内嵌 JSON 字符串的结构时，解析路径会变长，分配出去的临时对象增多，GC 压力也跟着上来，耗时很容易从几百微秒膨胀到几百毫秒甚至秒级。

3.2 线程池耗尽引发的连锁反应

JSON 解析本身的慢只是起点，真正的问题是它把执行面的线程池堵死之后，引发了一系列连锁反应。

第一个反应是下游 RPC 超时重试风暴。业务方的任务是同步调用 Agent 平台的，平台超时之后，业务方按照自己的重试策略进行重试，重试的新请求又会堆积到平台方的线程池等待队列里，进一步加剧线程被占用的局面。我们在线程栈里看到了大量同一调用链的重复请求记录，说明重试放大效应非常明显。

第二个反应是缓存击穿。平台有一个本地缓存，缓存键是工具元数据的版本号，正常情况下绝大多数请求能命中。但故障发生时，由于业务方拿到了部分失败错误码，很多请求直接触发强制刷新逻辑，本地缓存形同虚设，所有的解析压力全部打在原始数据读取和解析上，形成了缓存击穿式的恶性循环。

第三个反应是健康检查探活失败。由于线程池被占满，部分健康检查请求无法及时处理，注册中心开始摘除节点。被摘除节点上面的存量连接被强制断开，客户端感知后重新发起连接和重试，进一步放大了流量。从这里也能看出来，一个底层慢方法，经过线程池、重试、缓存失效这些机制的多级放大，最后表现在用户那里就是轰轰烈烈的大面积超时。

3.3 为什么这么大的隐患之前没被发现

这个问题的回答很扎心：日常流量低的时候，单次解析的绝对耗时并不高，只有几十毫秒，系统完全能扛得住。我们的压测环境用的数据是精简版，工具描述文件很小，没有覆盖到生产环境数据膨胀的场景。而真正触发爆发的，是某个业务团队在故障前两周接入了一批数量庞大、结构复杂的工具定义，单个 Schema 体积增加了近二十倍，再加上晚高峰流量叠加，隐患直接变成了事故。

这也暴露了稳定性建设上的两个核心缺失：一是没有针对接口性能做常态化的容量评估，尤其是没有跟着业务数据增长趋势做回归压测；二是监控指标只盯了 CPU、内存、接口耗时这种宏观层面，没有细化到线程池活跃度、具体方法耗时这类微观指标。等到宏观指标异常时，系统早就已经在崩溃边缘了。

4. 修复落地：缓存、裁剪与降级三板斧

4.1 第一板斧：给元数据解析加二级缓存

定位到根因之后，修复方案其实已经比较清晰了：核心目标是把“每次执行都重复解析”改成“尽量不解析”。我们做了一个本地缓存加分布式缓存的两级方案。一级是 Caffeine 本地缓存，设置最大容量和过期时间，最近访问最频繁的工具 Schema 常驻内存；二级是 Redis 缓存，存放序列化后的解析结果对象，当本地缓存 miss 时再查询 Redis。

缓存更新策略用的是版本号加定时刷新：配置中心里的工具元数据一旦变更，版本号会变化，平台后台线程每 30 秒拉一次最新版本，如果版本号不同，就重新解析并更新两级缓存，同时保留旧版本缓存一段时间，直到新版本预热成功后再切换。处理后的核心代码如下：

public ToolSchema getToolSchema(String toolName) { // 一级本地缓存 ToolSchema schema = localCache.getIfPresent(toolName); if (schema != null) { return schema; } // 二级分布式缓存：解析结果的序列化产物 String cacheKey = "agent:schema:" + toolName; String cached = redisTemplate.opsForValue().get(cacheKey); if (cached != null) { // 反序列化一次即可，成本远低于完整 JSON 解析 schema = objectMapper.readValue(cached, ToolSchema.class); localCache.put(toolName, schema); return schema; } // 两级都 miss 才走完整解析，并加分布式锁防止缓存击穿 schema = loadAndParseSchema(toolName); localCache.put(toolName, schema); redisTemplate.opsForValue().set(cacheKey, objectMapper.writeValueAsString(schema), 30, TimeUnit.MINUTES); return schema; }

这个方案最直接的效果是，大部分请求走到第一级缓存就返回了，连 Redis 都不需要访问。本地缓存命中的情况下，getToolSchema的耗时从平均 800ms 降到了不到 1ms，这个差距肉眼可见。

4.2 第二板斧：统一 ObjectMapper 并给序列化瘦身

除了缓存，我们还做了一轮 JSON 解析本身的重构，目标是降低每次解析的成本。

第一件事，确认全局使用单例 ObjectMapper。排查代码时发现，个别工具调用链路上还在用new ObjectMapper()创建新实例。ObjectMapper 的构建成本不低，每次创建都会重新注册模块、初始化序列化器缓存，在高并发场景下非常浪费。改成 Spring 容器里注入的全局单例后，这部分开销彻底消失。

第二件事，在兼容业务需要的前提下，关闭了 Jackson 的一些默认特性。比如FAIL_ON_UNKNOWN_PROPERTIES在某些历史配置中是开启的，遇到未知字段会尝试做类型解析然后抛异常，既浪费 CPU 又增加了不必要的分支判断。我们的依赖方协议已经比较统一，直接关闭这个特性，改为忽略未知字段，能减少不少解析时间。

第三件事，针对工具元数据做了存储格式优化。原有的双倍嵌套 JSON 字符串结构，本身就是历史包袱，兼容老协议不能直接改格式，但我们可以在写入缓存时换一种紧凑的序列化方式。比如使用 Jackson 默认的数据绑定直接生成二进制格式，或者只缓存解析后的对象映射，不再存储原始内嵌文本。这样既能保持下游兼容，又能把运行时解析的复杂度降下来。

调整后的统一配置大致是这样的：

@Bean public ObjectMapper objectMapper() { ObjectMapper mapper = new ObjectMapper(); // 统一使用单例，避免重复创建 mapper.configure(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES, false); mapper.configure(DeserializationFeature.USE_BIG_DECIMAL_FOR_FLOATS, false); mapper.setSerializationInclusion(JsonInclude.Include.NON_NULL); // 注册 JavaTimeModule 处理时间类型，同时复用序列化器缓存 mapper.registerModule(new JavaTimeModule()); mapper.disable(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS); return mapper; }

4.3 第三板斧：预加载、限流与 RPC 兜底

缓存解决的是稳态问题，而不能应对特别极端的突发流量。所以我们又加了三道防护。

第一道是启动预加载。Agent Platform 每次启动时，会从配置中心拉取当前生效的工具元数据版本列表，在服务正式注册到服务中心之前，就把高频工具 Schema 预先解析好并写入本地缓存。这样新的执行节点一上线，不会因为冷缓存而被大量请求打穿。

第二道是接口限流和排队策略。我们在网关层对代理执行接口配置了基于令牌桶的限流，超过阈值的请求直接返回明确的错误码，让业务方走自己的重试或降级策略，而不是在平台侧无限排队等待。同时将同步等待的 RPC 调用统一设置超时时间，快速失败，避免把连接池和线程池一起拖死。

第三道是面开关。平台内置了降级配置，如果出现了极端故障，可以通过配置中心一键切到降级模式。降级模式下不再动态解析工具元数据，而是使用最近一次成功缓存和精简执行路径，保证核心链路可用，牺牲部分高级功能换整体稳定。这个开关在后续的大促保障中成了保命符，多次在流量异常时发挥作用。

4.4 灰度发布与最终收益验证

修复代码合入后，我们没有直接全量发布，而是分了三批灰度：第一批先发布两台低流量节点，观察内存占用、解析耗时、线程池活跃度；第二批发布剩下的一半节点；第三批处理完其余节点。每一批之间间隔二十分钟左右，方便收集监控数据。

收益非常直观。发布完成之后，代理执行接口的 P99 从故障时的 2.6 秒降到了 380ms，TP999 从 5 秒以上降到 1.2 秒左右，错误率回到 0.05% 以下。线程池活跃数从峰值 190 降到 60 左右，而且 GC 频率也显著下降，因为不再有大量解析产生的临时对象。容量测试时，即使把单机 QPS 打到之前的 1.5 倍，线程池也还有一半以上的余量。

5. 故障复盘沉淀：从一次救火到体系化防护

5.1 监控体系补课：线程池与分位数才是保命指标

这次故障最深刻的教训之一是监控视角太粗。过去我们只看 CPU、内存、平均耗时、错误率这些宽口径指标，但这类指标在故障初期往往不会立刻出现剧烈变化。真正能提前暴露问题的，是线程池活跃线程数、等待队列长度、方法级耗时这些偏底层的指标。

故障后我们做了三件事。第一，执行面和网关的所有线程池都接入监控平台，配置水位告警，比如活跃线程数超过 max 的 70% 持续 1 分钟就触发；等待队列长度超过 100 就告警。第二，核心接口统一上报 P99、TP999，并按照分钟粒度观察，不再只看平均值。第三，对 Agent Platform 内部的工具匹配、参数解析、RPC 调用等关键方法都做了自定义埋点，任何一个方法耗时异常都会被 trace 体系第一时间捕获。

这套体系在故障后第二周就起作用了。某个下游模型服务因为推理队列膨胀导致响应变慢，P99 耗时开始抬头，线程池水位同步爬升，监控提前了十五分钟发出告警，我们在业务受到影响之前就做了扩容和降级，避免了一次潜在故障。

5.2 容量评估与回归压测应该跟着数据走

故障的诱因是工具元数据体积膨胀，这本质上是一个容量规划问题。团队过去做压测用的数据样本太理想化，没有模拟线上真实的数据分布，导致性能隐患长期没有被发现。现在我们把压测数据的更新纳入到版本发布的流程里：每次有新工具接入或元数据格式调整，都要把生产环境的数据抽样脱敏后加入压测样本集，跑一次全链路性能回归。

比如这次故障过后，我们专门做了一个“Schema 体积与解析耗时基线”的检查项，当某个版本的解析耗时期望值相比基线上升超过 30% 时，平台会阻塞发布流程，要求相关负责人给出优化方案后才能放行。虽然看起来增加了流程负担，但相比一次线上故障的代价，这点成本完全可以接受。

另外一个值得推广的经验是，容量评估要把“最差情况”纳入考量。以线程池为例，稳定运行时看平均并发就够了，但故障逃生时，必须按照 P99 耗时的 QPS 模型去估算线程需求，同时留出至少 1 倍余量。我们内部现在有一个人人都会算的口诀：线程需求 = 峰值请求速率 × 预计耗时 P99。当这个数字超过线程池 max 的 70%，就必须做方案。

5.3 应急预案成为可演练的流程而不是文档

故障前我们的应急预案其实写得并不差，有告警、有值班、有重启和扩容步骤。但这次真正执行时才发现，很多步骤缺乏明确的前置判断条件，人到了现场要先花很长的时间去做判断，延误了故障恢复的窗口。

所以现在应急预案的定义方式做了大改，把“如果看到什么指标，就执行什么操作”变成最简单的规则卡片。比如：线程池活跃数超过 90% 持续 3 分钟，先执行摘流并启用降级开关；P99 超过 1000ms 且下游调用耗时正常，直接拉取线程栈并开启缓存预加载；错误率超过 2% 且重试量异常，先做限流并通知业务方停止重试等。

同时每季度组织一次线上故障演练，专门挑流量低峰期对灰度节点注入真实故障，验证应急规则的有效性。这个做法带来的好处是，真正再出故障时，大家心理压力小了很多，因为都知道流程接下来会发生什么，也知道每个操作会带来什么效果。

6. 线上排查的工具体系与常见问题速查

6.1 排查超时问题的常用工具组合

这次排查里，我们用到的一整套工具体系值得梳理出来：

• 监控大盘：第一时间看全局指标，确定范围，区分是存储、下游还是本应用的问题。
• 链路追踪系统：全链路 trace 可以快速定位调用链中的慢节点，比手工翻日志高效得多。
• Arthas：线上定位方法级耗时的利器，trace、watch、stack 三个命令基本覆盖了最常见场景。
• jstack：抓线程栈看线程状态分布，尤其适合判断线程是处于 RUNNABLE 但卡 IO、还是 WAITING 等锁、又或者是 BLOCKED 状态。
• 压测平台：复现问题、验证修复，也可以用来做容量预估。

几个命令随手记一下：

# 抓取线程栈，连续三次间隔 2 秒，观察栈顶分布 jstack <pid> > thread_stack_1.txt sleep 2 jstack <pid> > thread_stack_2.txt sleep 2 jstack <pid> > thread_stack_3.txt # arthas 定位耗时方法，只输出耗时超过 200ms 的调用 trace com.xxx.agent.core.metadata.ToolSchemaParser resolveToolSchema '#cost > 200' # arthas 查看线程池状态 vmtool --action getInstances --className java.util.concurrent.ThreadPoolExecutor --limit 10

6.2 常见症状、根因与应对对照表

经过这次故障和之后多次线上问题处理，我整理了一个速查表，基本覆盖了 Agent 平台类服务比较常见的超时问题形态：

这张表看着简单，但每一条都对应着实打实的故障现场。平时可以打印出来贴工位上，遇到线上告警的时候先按表格里的方向定位，能省下大量靠猜来排查的时间。

6.3 排查时容易忽略的两个细节

第一个细节是线程栈要抓多次看趋势，单独一次线程栈的参考价值有限。JVM 线程状态是瞬时快照，偶发的一次 WAITING 可能只是正常的任务间隙，所以至少要连续抓三到五次，间隔两三秒，统计哪些栈顶反复出现，那些反复出现的才是真正可疑的占线程大户。

第二个细节是压测的时候一定要用真实数据。我们这次故障的一个重大教训就是压测样本太干净，真实环境里会存在大字段、深嵌套、内嵌 JSON 字符串这类畸形结构。做性能回归的时候，从生产抽取一份真实的数据脱敏，保留字段长度、嵌套深度和类型分布的统计特征，才能在故障发生前暴露隐患。

7. 写在最后：这次故障给我留下的几个实在体会

整个过程复盘下来，我印象最深的一点是：线上故障从来不是一个单一的技术问题，而是设计、监控、容量、流程多方面隐患同时达到临界点后的集中爆发。我们这次的问题表面上是一个 JSON 解析耗时过长，但背后是缓存策略不完善、线程池容量规划缺失、监控指标过粗、压测数据失真、应急预案不可操作等一连串长期积压的问题。

从实际操作中的体会来说，我建议负责平台类系统的开发者，上线前至少回答这三个问题：你的线程池在水位多高时会告警，你是否做过基于 P99 耗时的容量估算，你的核心接口在流量翻倍时靠什么兜底。如果这三个问题回答不上来，那你的系统大概率也埋着类似的地雷。

最后再分享一个小技巧，故障恢复之后一定要留住现场，包括线程栈文件、JFR 文件、流量日志、trace 日志，最好归档保存至少三个月。这些现场数据不仅能用于复盘，更重要的是它们可以用来验证修复方案的准确性和覆盖率。很多团队故障处理完就把现场删了，等下次故障重现时，才发现上一次的结论其实并不完整。留好现场，就是给未来的自己留一双看清问题的眼睛。