Spring Cloud 生产故障排查实战

微服务架构下故障是常态，难的是快速定位。本文整理 Spring Cloud 生产环境中五类高频故障：配置刷新失效、服务调用超时、负载均衡失效、Nacos 节点变更踩坑、线程池耗尽。每一类都按"现象 → 根因 → 排查 → 修复 → 预防"展开，给出可直接落地的排查路径。

一、配置刷新失效

现象

配置中心改了值，服务没生效：
  ├─ 页面已保存，服务日志无 RefreshScope 刷新记录
  ├─ 只改了 Nacos，未走 Bus 广播，其他服务不感知
  └─ 配置类里个别字段生效、个别字段不生效

根因分析

配置刷新的前置条件（缺一不可）：
  ├─ spring-cloud-starter-bootstrap 与 config 依赖就位
  ├─ 配置类要标注 @RefreshScope
  ├─ 数据源来源是 Environment 中的配置属性
  └─ 触发方式有效（Nacos 长轮询 / Bus 消息）

常见失效原因：

失效原因清单：
  ├─ 类没加 @RefreshScope → 改动不生效
  ├─ 配置被 @Value 注入到普通 Bean（未代理）→ 不刷新
  ├─ Bus 目标服务未订阅（rabbit 队列绑定错）→ 广播收不到
  ├─ 配置文件优先级问题 → 本地配置覆盖远程配置
  └─ 缓存数据未失效（本地缓存、静态字段）→ 值变了但取的是旧缓存

排查步骤

排查路径：
  1. 确认依赖：spring-cloud-starter-alibaba-nacos-config 版本与 Spring Cloud 兼容
  2. 看服务日志：是否有 "RefreshScope" 或 "Received remote config" 记录
  3. 用 Actuator 验证：/actuator/refresh 手动触发一次
  4. 检查配置类：@RefreshScope 是否在类上、字段是否通过属性注入
  5. 对比优先级：spring.config.import 与 bootstrap.yml 的加载顺序

# 排查要点：确认远程配置确实被加载
management:
  endpoints:
    web:
      exposure:
        include: refresh, env, health

修复与预防

修复：
  ├─ 需要动态刷新的类统一加 @RefreshScope
  ├─ 敏感配置（数据源、连接池）建议重启而非热刷新
  └─ Bus 场景确认 rabbit 交换机/队列绑定关系

预防：
  ├─ 配置类约束：只有标注 @RefreshScope 的属性允许变更
  ├─ 变更走审批 + 灰度（先改一台验证）
  └─ 刷新后自动校验：关键配置变更后触发健康检查

二、服务调用超时

现象

服务间调用变慢或超时：
  ├─ Feign 调用偶尔报 Read timed out
  ├─ 某个接口整体响应变慢（P95 上涨）
  ├─ 网关转发超时，客户端收到 504
  └─ 熔断频繁触发，大量请求走降级

根因分析

超时链路分层（每层都有超时配置）：
  ├─ 网关层：Gateway HTTP Client 响应超时
  ├─ Feign 层：connectTimeout / readTimeout
  ├─ 连接池层：连接获取等待超时
  ├─ 服务端：Tomcat/线程池排队
  └─ 数据库层：慢 SQL / 连接池耗尽

典型根因：
  ├─ Feign 超时配置过小（默认读超时可能不足 2 秒）
  ├─ 上游服务慢（慢 SQL、锁等待、线程池排队）
  ├─ 连接池耗尽（maxConnections 过小）
  ├─ 级联超时：A 调 B 调 C，每层超时叠加
  └─ 网络抖动 / 实例资源不足（CPU 飙高）

排查步骤

排查路径：
  1. 确认超时发生在哪一层：
     ├─ 看调用链（SkyWalking）：哪一段耗时最大
     └─ 分步压测：网关 → 服务 → 数据库
  2. 检查慢 SQL：慢查询日志、执行计划
  3. 检查线程池：活跃线程数、排队任务数
  4. 检查资源：CPU、内存、GC 停顿
  5. 抓包 / 网络指标：丢包、重传

关键指标：
  ├─ 调用耗时分布：P50 / P95 / P99
  ├─ 数据库慢 SQL 次数
  ├─ 线程池活跃线程 / 队列长度
  └─ 熔断器打开次数与降级比例

修复与预防

修复：
  ├─ 按链路合理设置超时（内部调用可放宽，网关对外收紧）
  ├─ 优化慢 SQL：加索引、改查询、分批处理
  ├─ 扩大连接池并设置等待超时
  └─ 超时兜底：Feign 降级返回，避免级联阻塞

预防：
  ├─ 全链路超时规范：每层超时 < 上层超时（留出缓冲）
  ├─ 依赖服务设置熔断与降级
  └─ 超时监控告警：P95 超阈值即告警

# Feign 超时配置示例
feign:
  client:
    config:
      default:
        connectTimeout: 2000
        readTimeout: 5000

三、负载均衡失效

现象

负载均衡表现异常：
  ├─ 请求总是打到同一台实例（其他实例闲置）
  ├─ 新扩容的实例迟迟收不到流量
  ├─ 下线实例仍被调用（报连接拒绝）
  └─ 权重配置不生效

根因分析

负载均衡失效的原因：
  ├─ 服务发现缓存未更新：实例列表缓存在本地，未感知变更
  ├─ Nacos 心跳 / 健康检查异常：实例被标记不健康但未剔除
  ├─ LoadBalancer 缓存：实例缓存刷新周期过长
  ├─ 路由策略固定（如一直选第一台）
  └─ 多注册中心 / 命名空间不一致：查不到新实例

排查步骤

排查路径：
  1. 查看 Nacos 控制台：实例列表是否完整、健康状态
  2. 检查服务日志：拉取实例列表的日志频率
  3. 确认命名空间与分组：服务是否注册在同一个 namespace
  4. 检查 LoadBalancer 缓存刷新配置
  5. 直连测试：直接访问新实例 IP 是否可用

重点检查项：
  ├─ Nacos 控制台实例健康数 vs 实际实例数
  ├─ 心跳间隔：beatInterval（默认 5 秒）
  ├─ 剔除时间：服务端对失联实例的驱逐周期
  └─ 客户端缓存：ServiceInstanceListSupplier 的刷新周期

修复与预防

修复：
  ├─ 确认实例健康检查通过（健康端点返回 UP）
  ├─ 调整 LoadBalancer 实例缓存刷新周期
  ├─ 修正命名空间 / 分组配置
  └─ 必要时手动下线异常实例（Nacos 控制台）

预防：
  ├─ 扩容后观察实例列表是否即时出现
  ├─ 缩容走优雅下线：先摘流量再停服务
  └─ 上线自动化校验：新实例健康检查通过后才加入

四、Nacos 节点变更踩坑

现象

Nacos 集群变更引发连锁问题：
  ├─ 重启某个 Nacos 节点后，部分服务注册失败
  ├─ 客户端偶发 "no available server"
  ├─ 配置拉取失败，服务启动用了旧配置
  └─ 服务列表抖动：实例忽多忽少

根因分析

Nacos 节点变更的常见坑：
  ├─ 节点下线未摘流量：客户端仍把请求打到该节点
  ├─ 集群节点数配置不一致：addresses 列表不完整
  ├─ CP/AP 切换：临时实例（AP）与持久实例（CP）行为不同
  ├─ 配置中心未开启持久化：重启丢配置
  └─ 客户端缓存过期策略：重试不充分

Raft 场景（持久实例）：
  ├─ Leader 变更期间写入失败
  ├─ 客户端未重试 → 注册失败
  └─ 需要等待 Leader 选举完成（秒级）

Distro 场景（临时实例）：
  ├─ 节点间数据同步有延迟
  ├─ 变更后反熵收敛需要时间
  └─ 客户端可能读到旧数据

排查步骤

排查路径：
  1. 确认 Nacos 集群节点状态：/nacos/actuator 健康
  2. 检查客户端配置的 server-addr 是否包含全部节点
  3. 看客户端日志：连接失败重试日志、注册失败日志
  4. 确认配置持久化：MySQL 存储是否正常
  5. 检查网络：节点间 8848/9848 端口连通性

关键检查项：
  ├─ 集群 node 数是否与预期一致
  ├─ 是否有节点处于 DOWN 状态
  ├─ 客户端重试策略（failfast / 重连间隔）
  └─ 配置变更后的推送是否成功（客户端 MD5 是否更新）

修复与预防

修复：
  ├─ 客户端 server-addr 配置全量节点
  ├─ 节点变更（升级/下线）安排在低峰期
  ├─ 下线前先确认客户端已不感知该节点（摘除再停）
  └─ 配置中心开启 MySQL 持久化

预防：
  ├─ Nacos 节点变更演练：定期做节点重启测试
  ├─ 客户端连接参数调优：重试、超时
  └─ 监控：注册失败率、配置拉取失败率、服务列表抖动

五、线程池耗尽

现象

线程池耗尽的表现：
  ├─ 接口响应缓慢，排队时间飙升
  ├─ 日志大量 "Thread pool is EXHAUSTED"
  ├─ Tomcat 线程耗尽：新请求全部排队/拒绝
  ├─ 业务线程池（Feign/异步）拒绝任务
  └─ 服务整体假死，健康检查变慢

根因分析

线程池耗尽的根因：
  ├─ 下游阻塞：调用第三方/数据库慢，线程被占用不释放
  ├─ 任务堆积：突发流量 > 处理能力
  ├─ 线程池配置过小：核心线程与最大线程不匹配
  ├─ 线程泄漏：任务里持有线程（线程 sleep、无限等待）
  ├─ 锁竞争：数据库行锁、分布式锁长时间持有
  └─ 阻塞调用链：同步等待导致线程不归还

Tomcat 线程池（默认 200）耗尽链：
  请求进入 → 排队（acceptCount 默认 100）
  → 线程池满 → 新连接被拒绝（Connection reset）
  → 客户端重试 → 更多连接 → 雪崩

排查步骤

排查路径：
  1. 看线程 dump（jstack）：大多数线程卡在哪个方法
     ├─ java.net.SocketInputStream → 下游超时
     ├─ Object.wait / LockSupport.park → 锁等待
     └─ Thread.sleep → 代码问题
  2. 看线程池指标：active / queued / rejected
  3. 检查下游：数据库连接池、第三方调用耗时
  4. 检查 CPU / GC：是否频繁 Full GC

线程 dump 分析重点：
  ├─ 统计阻塞线程数分布
  ├─ 找到共性调用栈（卡在同一个下游）
  └─ 确认是否有线程异常（runnable 但长期不结束）

修复与预防

修复：
  ├─ 临时：扩容实例、重启恢复
  ├─ 治本：修掉阻塞源（慢 SQL / 第三方超时）
  ├─ 设置下游调用超时 + 线程池拒绝策略兜底
  └─ 线程池参数调优：核心/最大/队列、空闲回收

预防：
  ├─ 线程池监控：活跃线程数、排队数、拒绝数告警
  ├─ 隔离：核心链路与旁路任务分线程池
  ├─ 压测验证线程池容量
  └─ 异步化改造：不阻塞的调用走消息/异步

六、通用排查方法论

故障定位四步法

四步定位：
  1. 界定范围：哪个服务、哪个接口、多少比例受影响
  2. 收集现场：日志（TraceId）、指标、线程 dump、GC 日志
  3. 分层定位：入口 → 网关 → 服务 → 数据库 → 依赖
  4. 验证假设：小流量复现，确认根因

常用排查工具

工具清单：
  ├─ 链路追踪：SkyWalking / Zipkin（定位耗时分层）
  ├─ 指标：Prometheus + Grafana（耗时、成功率、资源）
  ├─ 日志：按 TraceId 聚合（ELK / Loki）
  ├─ JVM：jstack（线程）、jmap（堆）、Arthas（在线诊断）
  └─ 压测：JMeter / Gatling（复现并发问题）

故障预防清单

预防清单：
  ├─ 全链路超时规范（每层超时递减）
  ├─ 熔断降级兜底（依赖不可用不拖垮主链路）
  ├─ 线程池与连接池监控告警
  ├─ 配置变更灰度 + 可回滚
  ├─ 容量评估与压测（大促前必做）
  └─ 故障演练（Nacos 节点重启、实例宕机、依赖故障）

总结

生产故障排查的核心是"快定位、准根因、稳恢复"。五类高频故障有共同规律：超时与阻塞是线程池耗尽的源头，缓存与优先级是配置不生效的原因，实例健康与缓存刷新是负载均衡失效的关键，节点变更需要重试与持久化兜底。把监控指标、链路追踪、日志三支柱打通，配合分层定位法，大多数故障都能在分钟级定位到具体环节。