Spring Cloud Alibaba 微服务线上故障应急排查手册

告警触发
  │
  ├─ 第 1 分钟：确认告警真实性
  │    └─ 查看监控大盘，确认指标是否真实异常（排除监控自身故障）
  │
  ├─ 第 2-3 分钟：判断影响范围
  │    └─ 通过全链路追踪确认异常服务节点、错误率、RT 飙升曲线
  │
  ├─ 第 4-5 分钟：止血决策
  │    ├─ 单节点故障 → 摘除流量（Nacos 下线实例 / Gateway 路由屏蔽）
  │    ├─ 依赖故障 → 降级开关（Sentinel 熔断 / 配置中心动态降级）
  │    ├─ 全量异常 → 版本回滚
  │    └─ 容量不足 → 弹性扩容
  │
  ├─ 第 6-10 分钟：根因定位
  │    └─ 根据异常组件类型，进入对应章节的专项排查流程
  │
  └─ 10 分钟后：根因修复 + 复盘准备

# 查看所有 Java 进程，确认目标服务 PID
jps -lvm

# 查看 JVM 堆内存概况（新生代/老年代/元空间各区域使用情况）
jmap -heap <pid>

# Dump 堆内存用于离线分析内存泄漏（生产环境注意文件体积，建议加 live 参数只 dump 存活对象）
jmap -dump:live,format=b,file=/tmp/heap_$(date +%s).hprof <pid>

# 查看线程堆栈，排查死锁、线程阻塞、线程池耗尽
jstack <pid>
jstack -l <pid>   # -l 额外打印锁信息，排查死锁时必加

# GC 统计，每 1 秒采样 1 次，共 10 次，观察 Full GC 频率和耗时
jstat -gcutil <pid> 1000 10

# 查看进程内各线程 CPU 占用，定位高 CPU 线程
top -H -p <pid>

# 将高 CPU 线程 ID（十进制）转为十六进制，用于在 jstack 输出中定位对应线程
printf "%x\n" <tid>

# 启动 Arthas，选择目标进程
java -jar arthas-boot.jar

# 实时数据面板：线程、内存、GC、运行时环境一览
dashboard

# 查看 JVM 详细信息（类加载器、GC、编译器、运行参数）
jvm

# 查看各内存区域使用情况
memory

# 查看所有线程状态
thread

# 查看最忙的 3 个线程（CPU 占用最高的 3 个）
thread -n 3

# 查看指定线程的堆栈
thread <thread-id>

# 检测死锁（查找阻塞其他线程的线程）
thread -b

# 方法执行监控：统计 10 秒内的调用次数、成功率和平均 RT
monitor com.example.order.service.OrderService createOrder -c 10

# 方法内部调用路径及耗时：逐层展示方法内部各子调用的耗时，定位慢调用根源
trace com.example.order.service.OrderService createOrder

# 方法执行数据观测：查看入参、返回值、抛出的异常
watch com.example.order.service.OrderService createOrder "{params, returnObj, throwExp}" -x 2

# 方法调用栈：查看谁在调用这个方法，定位异常调用来源
stack com.example.order.service.OrderService createOrder

# 时空隧道：记录每次方法调用，可事后回放查看入参和返回值
tt -t com.example.order.service.OrderService createOrder

# 查看已加载的类信息（来源 jar 包、类加载器）
sc -d com.example.order.service.OrderService

# 反编译已加载的类，确认线上运行代码与预期一致
jad com.example.order.service.OrderService

# 临时热更新代码（验证修复方案，不可作为正式发布手段）
redefine /tmp/OrderService.class

# 在线修改日志级别（故障排查时临时开启 DEBUG，无需重启）
logger --name com.example.order --level DEBUG

# 查看和修改 JVM 系统属性
sysprop
sysprop spring.profiles.active

# 查看环境变量
sysenv

# Dump 堆内存到文件
heapdump /tmp/heap.hprof

# 生成火焰图（async-profiler 集成），用于 CPU 性能分析
profiler start
# 采集 30 秒后停止并生成 HTML 报告
profiler stop --format html

# 按时间范围过滤日志（排查特定时段的异常）
grep "2026-07-15 10:[0-5]" /opt/app/logs/app.log | grep -i "error\|exception"

# 统计错误类型分布（快速定位最高频异常）
grep "Exception" /opt/app/logs/app.log | awk -F: '{print $1}' | sort | uniq -c | sort -rn | head -20

# 通过 traceId 追踪全链路日志
grep "traceId=a1b2c3d4" /opt/app/logs/app.log

# 统计某接口在指定时段的 P99 响应时间
grep "/api/order/create" access.log | awk '{print $NF}' | sort -n | awk 'BEGIN{c=0} {a[c++]=$1} END{print a[int(c*0.99)]}'

# Nacos 2.x 需要开放的三个端口
# 8848  — HTTP API 主端口
# 9848  — 客户端 gRPC 端口（主端口 + 1000）
# 9849  — 服务端 gRPC raft 端口（主端口 + 1001）
telnet <nacos-ip> 8848
telnet <nacos-ip> 9848
telnet <nacos-ip> 9849

# 确认防火墙是否放行
firewall-cmd --list-ports

# 查看注册相关日志
grep -i "register\|failed\|exception" /opt/app/logs/nacos/naming.log

# 典型报错及含义：
# "failed to register"          — 注册请求失败，检查网络或鉴权
# "invalid token"               — 鉴权 token 失效，需重新生成
# "metadata too long"            — 实例元数据超过 512 字节限制
# "Connection refused"           — Nacos 服务端不可达

# 错误写法（使用名称）
spring:
  cloud:
    nacos:
      discovery:
        namespace: production    # 错误！Nacos 不认名称

# 正确写法（使用 Namespace ID）
spring:
  cloud:
    nacos:
      discovery:
        namespace: a1b2c3d4-e5f6-7890-abcd-ef1234567890  # 在 Nacos 控制台 → 命名空间 列表中获取

# 查看消费端缓存的服务实例
# 通过 Arthas 查看客户端缓存
java -jar arthas-boot.jar
ognl '@com.alibaba.nacos.client.naming.core.HostReactor@serviceInfoMap' -x 2

# 查看 Nacos 客户端推送日志
grep "push\|notify" /opt/app/logs/nacos/naming.log

# 查看消费端与 Nacos 的连接状态
netstat -anp | grep 9848 | grep ESTABLISHED

# 方案一：关闭推空保护（需评估风险，注册中心故障时可能导致全部实例被清空）
spring:
  cloud:
    nacos:
      discovery:
        # Nacos 客户端 2.x 默认开启推空保护
        naming-load-cache-at-start: false

# 方案二：重启消费端进程，强制重新拉取服务列表
# （生产环境慎用，仅在其他方法无效时执行）

# 方案三：通过 Nacos API 手动触发实例下线
curl -X PUT "http://<nacos-ip>:8848/nacos/v1/ns/instance?serviceName=payment-service&ip=<instance-ip>&port=8080&enabled=false"

# 通过 API 直接查询配置内容，确认应用读取的是这份配置
curl "http://<nacos-ip>:8848/nacos/v1/cs/configs?dataId=order-service-prod.yml&group=ORDER_GROUP&tenant=<namespace-id>"

# 查看配置刷新日志
grep "config\|refresh\|listener" /opt/app/logs/nacos/config.log

# 如果日志中没有 "refresh" 记录，说明客户端未收到推送
# 检查长连接是否正常
netstat -anp | grep 9848 | grep ESTABLISHED

# 对比集群各节点同一份配置的 MD5，确认是否一致
for ip in 192.168.1.10 192.168.1.11 192.168.1.12; do
  echo -n "$ip: "
  curl -s "http://$ip:8848/nacos/v1/cs/configs?dataId=order-service-prod.yml&group=ORDER_GROUP&tenant=<namespace-id>" | md5sum
done

# 查看集群各节点状态
for ip in 192.168.1.10 192.168.1.11 192.168.1.12; do
  echo -n "$ip: "
  curl -s "http://$ip:8848/nacos/v1/ns/operator/metrics" | jq '.leader'
done

# 查看集群日志，搜索选举和脑裂相关关键字
grep -i "election\|leader\|term\|unavailable" /opt/nacos/logs/cluster-alert.log

# 检查 Raft 日志
grep -i "raft\|vote\|term" /opt/nacos/logs/protocol-raft.log

# 1. 停止异常节点（脱离集群独立运行的节点）
ssh <abnormal-ip> "sh /opt/nacos/bin/shutdown.sh"

# 2. 等待 15 秒确保 Raft 选举完成（观察 leader 日志确认新 leader 产生）
sleep 15 && grep "leader" /opt/nacos/logs/protocol-raft.log | tail -5

# 3. 清理异常节点数据后重新加入集群
# 删除 data 目录下的 protocol/raft 快照（谨慎操作）
rm -rf /opt/nacos/data/protocol/raft/

# 4. 启动节点重新加入集群
ssh <abnormal-ip> "sh /opt/nacos/bin/startup.sh"

# 5. 如果脑裂严重无法自动恢复，强制重置集群状态（最后手段，需评估数据丢失风险）
curl -X POST "http://<leader-ip>:8848/nacos/v1/ns/operator/resetCluster"

# 检查应用启动参数是否配置了 Dashboard 地址
ps -ef | grep java | grep -- '-Dcsp.sentinel.dashboard.server'

# 预期输出包含：
# -Dcsp.sentinel.dashboard.server=<dashboard-ip>:8080
# -Dproject.name=order-service

# 检查客户端与 Dashboard 的心跳连接
grep "dashboard" /opt/app/logs/sentinel/sentinel-record.log

// 情况一：Spring MVC 接口，Sentinel 默认资源名是 URL 路径
// Dashboard 中应配置资源名为：/api/order/create

// 情况二：使用 @SentinelResource 注解，资源名是注解的 value
@SentinelResource(value = "createOrder", blockHandler = "createOrderBlockHandler")
public OrderResult createOrder(OrderRequest request) { ... }
// Dashboard 中应配置资源名为：createOrder（不是 URL 路径）

// 情况三：自定义资源名
try (Entry entry = SphU.entry("customResourceName")) {
    // 业务逻辑
} catch (BlockException e) {
    // 限流处理
}

<!-- 确保只引入 spring-cloud-starter-alibaba-sentinel，它会传递依赖正确的 sentinel-core 版本 -->
<dependency>
    <groupId>com.alibaba.cloud</groupId>
    <artifactId>spring-cloud-starter-alibaba-sentinel</artifactId>
</dependency>
<!-- 不要手动指定 sentinel-core 版本，避免版本冲突 -->

# 通过 Dashboard 查看实时监控
# 菜单：簇点链路 → 选择资源 → 查看实时监控
# 关注：通过 QPS、拒绝 QPS、平均 RT、异常数

# 查看 sentinel-record.log 中的熔断事件记录
grep "DegradeException\|FlowException" /opt/app/logs/sentinel/sentinel-record.log | tail -20

# 典型日志：
# DegradeException: max rt exceeds threshold  — RT 熔断触发
# FlowException: qps exceeds threshold        — QPS 限流触发

# 观察方法入参、返回值和异常
watch com.example.order.service.OrderService createOrder "{params, returnObj, throwExp}" -x 2

# 如果发现大量 BusinessException（业务异常），应调整熔断策略
# 方案：改用异常数熔断并排除业务异常，或提高异常比例阈值

// 常见误配场景：
// 问题：依赖服务超时，但配置了"异常比例"熔断
// 超时异常是系统级异常，但比例可能达不到阈值，导致熔断不及时
// 解决：超时场景应配置"慢调用比例（RT）"熔断

// Sentinel 熔断策略选择指南：
// 慢调用比例（RT）  → 适用于下游响应慢的场景
// 异常比例          → 适用于下游偶发报错的场景
// 异常数            → 适用于需要严格保护、异常数超阈值立即熔断的场景

// 方案一：自定义异常忽略，排除业务异常不计入熔断统计
@SentinelResource(value = "createOrder", 
    blockHandler = "createOrderBlockHandler",
    exceptionsToIgnore = {BusinessException.class, ParamValidException.class})
public OrderResult createOrder(OrderRequest request) { ... }

// 方案二：调整熔断规则，提高阈值或增加最小请求数
// 在 Dashboard 中修改规则：
// - 异常比例阈值：50% → 80%
// - 最小请求数：5 → 20
// - 统计时长：1000ms → 2000ms

# 1. 确认 Dashboard 地址配置正确
ps -ef | grep java | grep 'csp.sentinel.dashboard.server'
# 输出应包含：-Dcsp.sentinel.dashboard.server=<ip>:8080

# 2. 确认应用名配置正确
ps -ef | grep java | grep 'project.name'
# 输出应包含：-Dproject.name=order-service

# 3. 确认 Dashboard 端口可达
telnet <dashboard-ip> 8080

# 4. 查看客户端传输日志，确认心跳是否正常发送
grep "dashboard\|transport\|connect" /opt/app/logs/sentinel/sentinel-record.log

# 5. 确认 Sentinel 传输端口未被占用
# Sentinel 客户端默认使用 8719 端口与 Dashboard 通信，如被占用会自动递增
netstat -tlnp | grep 8719

# 如果传输端口被占用，手动指定端口
java -Dcsp.sentinel.transport.port=8720 -jar app.jar

# 如果 Dashboard 地址配错，修改后重启应用
# 确保配置在 application.yml 中也正确

spring:
  cloud:
    sentinel:
      transport:
        dashboard: <dashboard-ip>:8080
        port: 8719  # 客户端与 Dashboard 通信端口
      eager: true   # 立即初始化，不再等首次请求

# 确认 Seata Starter 依赖
grep "seata-spring-boot-starter" pom.xml

# 确认 Seata Server 版本与 Client 版本一致
# 查看应用加载的 Seata 版本
java -jar arthas-boot.jar
sc -d io.seata.spring.annotation.GlobalTransactional
# 查看 classloader 中的 seata 版本

<!-- 确保 Seata 版本与 Server 端一致 -->
<dependency>
    <groupId>io.seata</groupId>
    <artifactId>seata-spring-boot-starter</artifactId>
    <version>1.7.0</version>  <!-- 与 Seata Server 版本一致 -->
</dependency>

# 在 account-service 中通过 Arthas 查看 XID
java -jar arthas-boot.jar
ognl '@io.seata.core.context.RootContext.getXID()'
# 如果返回 null，说明 XID 未传递到该服务

// 确保 Feign 拦截器配置正确，传递 XID
// Seata 自动配置了 SeataFeignClient 拦截器，但需确认未被覆盖
// 检查是否手动注册了 Feign.Builder 导致拦截器丢失

// application.yml 确认配置
seata:
  enabled: true
  application-id: ${spring.application.name}
  tx-service-group: my_tx_group
  service:
    vgroup-mapping:
      my_tx_group: default  # 对应 Seata Server 的 cluster 名称

-- 检查业务库是否有 undo_log 表
SHOW TABLES LIKE 'undo_log';

-- 如果不存在，执行以下建表语句（每个参与全局事务的数据库都要建）
CREATE TABLE `undo_log` (
  `branch_id`     BIGINT       NOT NULL COMMENT 'branch transaction id',
  `xid`           VARCHAR(128) NOT NULL COMMENT 'global transaction id',
  `context`       VARCHAR(128) NOT NULL COMMENT 'undo_log context,such as serialization',
  `rollback_info` LONGBLOB     NOT NULL COMMENT 'rollback info',
  `log_status`    INT          NOT NULL COMMENT '0:normal status,1:defense status',
  `log_created`   DATETIME(6)  NOT NULL COMMENT 'create datetime',
  `log_modified`   DATETIME(6)  NOT NULL COMMENT 'modify datetime',
  UNIQUE KEY `ux_undo_log` (`xid`, `branch_id`)
) ENGINE = InnoDB COMMENT ='AT transaction mode undo table';

// 错误写法：默认只回滚 RuntimeException
@GlobalTransactional
public void createOrder() {
    orderService.create();    // 如果这里抛出 IOException（受检异常），不会回滚
    stockService.deduct();    // 扣减库存
    accountService.deduct();  // 扣减余额
}

// 正确写法：显式指定回滚的异常类型
@GlobalTransactional(rollbackFor = Exception.class)
public void createOrder() {
    orderService.create();
    stockService.deduct();
    accountService.deduct();
}

-- 第一步：查看未完成的全局事务（status != 0 表示未完成）
SELECT xid, status, gmt_create, gmt_modified, timeout
FROM global_table
WHERE status != 0
ORDER BY gmt_create DESC
LIMIT 20;

-- 第二步：查看锁持有情况，找出长时间持有未释放的锁
SELECT * FROM lock_table
WHERE gmt_create < DATE_SUB(NOW(), INTERVAL 5 MINUTE);

-- 第三步：通过 xid 查看分支事务状态
SELECT * FROM branch_table
WHERE xid = '<xid-from-step-1>';

-- 第四步：查看某个资源（表）被哪些事务锁定
SELECT * FROM lock_table
WHERE resource_id = 'stock_table'
ORDER BY gmt_create;

## file.conf 调整锁等待参数
client {
  ## 获取全局锁重试间隔（毫秒），默认 10
  lock.retryInterval = 30
  ## 获取全局锁最大重试次数，默认 30
  lock.retryTimes = 60
  ## 全局事务超时时间（毫秒），默认 60000
  tm.defaultGlobalTransactionTimeout = 120000
}

-- 清理残留的僵尸全局事务（手动修复，谨慎操作）
-- 1. 先确认事务确实已超时且不会恢复
SELECT xid, gmt_create FROM global_table WHERE status = 1 AND gmt_create < DATE_SUB(NOW(), INTERVAL 1 HOUR);
-- 2. 删除残留的全局事务记录
DELETE FROM global_table WHERE status = 1 AND gmt_create < DATE_SUB(NOW(), INTERVAL 1 HOUR);
-- 3. 清理对应的锁记录
DELETE FROM lock_table WHERE xid NOT IN (SELECT xid FROM global_table);
-- 4. 清理分支事务记录
DELETE FROM branch_table WHERE xid NOT IN (SELECT xid FROM global_table);

// 架构层面优化：高并发热点数据场景，从 AT 模式改为 TCC 模式
// TCC 不依赖全局锁，Try 阶段预留资源，Confirm/Cancel 阶段直接操作
@LocalTCC
public interface StockTccAction {
    @TwoPhaseBusinessAction(name = "deductStock", commitMethod = "confirm", rollbackMethod = "cancel")
    boolean tryDeduct(BusinessActionContext context, @BusinessActionContextParameter String sku, @BusinessActionContextParameter Integer count);

    boolean confirm(BusinessActionContext context);
    boolean cancel(BusinessActionContext context);
}

-- 检查 undo_log 表中的残留记录
SELECT * FROM undo_log;
-- 如果有残留记录，说明回滚未成功执行

-- 检查 log_status 字段
-- log_status = 0：正常状态
-- log_status = 1：防御状态（已被标记删除但未实际删除）

-- 查看 Seata Server 日志中的回滚失败记录

# 查看 Seata Server 回滚日志
grep "rollback\|undo\|BranchRollback" /opt/seata/logs/seata-server.log | tail -20

# 常见报错：
# "BranchRollbackFailed: undo_log not found"    — undo_log 已被删除，无法回滚
# "undo_log dirty data"                          — undo_log 数据被篡改或损坏
# "lock_table row_key length insufficient"       — lock_table 中字段长度不足，锁记录插入静默失败

-- 1. 确认 lock_table 字段长度足够（row_key 和 xid 字段）
ALTER TABLE lock_table MODIFY row_key VARCHAR(255) NOT NULL;
ALTER TABLE lock_table MODIFY xid VARCHAR(128) NOT NULL;

-- 2. 手动清理残留的 undo_log 记录（确认事务已结束且数据状态正确后执行）
DELETE FROM undo_log WHERE log_created < DATE_SUB(NOW(), INTERVAL 1 DAY);

-- 3. 手动补偿数据（如果回滚失败导致数据不一致，需根据 undo_log 中的 rollback_info 手动恢复）
-- rollback_info 是序列化后的前后镜像数据，需反序列化后对比恢复

消费端发起调用
    │
    ▼
① 注册中心层 — Provider 是否注册成功？Consumer 是否订阅成功？
    │
    ▼
② 消费端路由层 — 路由规则是否过滤了所有 Provider？
    │
    ▼
③ 网络 TCP 层 — 消费端与 Provider 的网络是否通畅？
    │
    ▼
④ Provider 线程池层 — Provider 线程池是否已满？处理是否超时？

# 如果使用 Nacos 作为注册中心
curl "http://<nacos-ip>:8848/nacos/v1/ns/instance/list?serviceName=providers:com.example.UserService:1.0.0"

# 如果使用 ZooKeeper 作为注册中心
zkCli.sh -server 127.0.0.1:2181
# 查看所有 Provider
ls /dubbo/com.example.UserService/providers
# 查看 Provider 注册详情（URL 参数）
get /dubbo/com.example.UserService/providers/dubbo%3A%2F%2F192.168.1.10%3A20880%2Fcom.example.UserService...
# 查看所有 Consumer
ls /dubbo/com.example.UserService/consumers
# 查看路由规则（排查是否被规则过滤）
ls /dubbo/com.example.UserService/routers

# 通过 Dubbo QoS（端口 22222）查看消费端缓存的服务列表
telnet 127.0.0.1 22222
# 列出所有服务
ls
# 查看特定服务的 Provider 列表
ls com.example.UserService

// Provider 端配置
@DubboService(group = "production", version = "1.0.0")
public class UserServiceImpl implements UserService { ... }

// Consumer 端配置必须完全匹配
@DubboReference(group = "production", version = "1.0.0")
private UserService userService;
// 常见错误：
// 1. Consumer 没配 group，Provider 配了 group
// 2. Consumer 的 version 与 Provider 不一致
// 3. Consumer 引入的接口包名与 Provider 不同（如 com.example.api.UserService vs com.example.UserService）

dubbo:
  # 确认序列化方式一致
  protocol:
    serialization: hessian2  # 明确指定，避免版本默认值不一致

# 线程池耗尽的典型日志
grep "EXHAUSTED\|Thread pool" /opt/app/logs/dubbo/dubbo.log | tail -10

# 典型日志格式：
# Thread pool is EXHAUSTED! Thread Name: DubboServerHandler-192.168.1.10:20880,
# Pool Size: 200 (active: 200, core: 200, max: 200, largest: 200), Task: 45678

# 统计 DubboServerHandler 线程数量
jstack <pid> | grep 'DubboServerHandler' | wc -l

# 查看线程状态分布
jstack <pid> | grep 'DubboServerHandler' | awk '{print $2}' | sort | uniq -c | sort -rn

# 查看各线程的堆栈，定位阻塞原因
jstack <pid> | grep -A 20 'DubboServerHandler' | head -80

# 常见阻塞原因：
# - java.net.SocketInputStream.socketRead0    → 等待数据库或 HTTP 响应
# - java.util.concurrent.locks.ReentrantLock  → 等待获取业务锁
# - sun.misc.Unsafe.park                       → 等待异步任务完成

telnet 127.0.0.1 22222
# 查看线程池和连接池状态
status -s

dubbo:
  protocol:
    # 方案一：调大线程池（临时缓解）
    threads: 500         # 线程池大小，默认 200
    threadpool: fixed     # 固定线程池（默认），也可用 cached

    # 方案二：启用线程池告警和拒绝策略
    # 当线程池使用率超过阈值时告警

// 方案三：根治 — 找到慢调用的根因并修复
// 1. 数据库慢查询：加索引、优化 SQL、引入缓存
// 2. 外部 HTTP 调用超时：设置合理超时时间、增加重试、引入熔断
// 3. 同步转异步：将耗时的非核心逻辑异步化

// 方案四：关键接口隔离线程池，避免互相影响
// Dubbo 3.x 支持为不同服务配置独立的线程池
@DubboService(executor = "orderServiceExecutor")
public class OrderServiceImpl implements OrderService { ... }

// 配置自定义线程池
@Configuration
public class DubboThreadPoolConfig {
    @Bean("orderServiceExecutor")
    public ExecutorService orderServiceExecutor() {
        return new ThreadPoolExecutor(
            50, 100, 60, TimeUnit.SECONDS,
            new LinkedBlockingQueue<>(1000),
            new ThreadFactoryBuilder().setNameFormat("order-service-%d").build()
        );
    }
}

# 文案一：请求还没发出去（消费端线程池排队超时）
# 日志特征：Waiting server-side execution timeout
# 含义：消费端的请求在本地线程池排队等待发送，排队时间超过了超时阈值
# 根因：消费端线程池满，或消费端 GC 导致 STW

# 文案二：请求已发出但等不回响应
# 日志特征：Waiting server-side response timeout
# 含义：请求已发送到 Provider，但在超时时间内未收到响应
# 根因：Provider 处理慢、网络延迟高、Provider GC 停顿

# 查看 Provider 日志中该次调用的耗时
grep "execute service.*cost.*ms" /opt/app/logs/dubbo/dubbo.log | tail -10
# 典型日志：[DUBBO] [Dubbo-Provider] execute service xxx cost 3001ms,
#           this invocation almost (maybe already) timeout. Timeout: 1000ms

# 追踪方法内部各子调用的耗时
trace com.example.user.service.UserServiceImpl getUserInfo
# 输出示例：
# ├─[0.01ms] com.example.user.mapper.UserMapper.selectById()
# ├─[800ms] com.example.user.service.AccountService.getBalance()  ← 罪魁祸首
# └─[0.02ms] com.example.user.converter.UserConverter.convert()

dubbo:
  provider:
    timeout: 3000    # Provider 默认超时 3 秒
    retries: 1       # 默认重试 1 次（仅对查询类幂等操作有效）
  consumer:
    timeout: 5000    # Consumer 默认超时 5 秒
    # 针对特定服务单独配置
    check: false      # 启动时不检查 Provider 是否可用

  # 针对写操作配置不重试（避免重复扣款等副作用）
  # 在 @DubboReference 上单独指定

// 写操作必须配置 retries=0，避免重复执行
@DubboReference(timeout = 5000, retries = 0)
private OrderService orderService;

// 查询操作可以配置重试
@DubboReference(timeout = 2000, retries = 2)
private UserService userService;

# 典型日志
grep "Serializable\|SerializeException" /opt/app/logs/dubbo/dubbo.log | tail -5

// 1. 确保传输的数据对象实现了 Serializable 接口
public class UserDTO implements Serializable {
    private static final long serialVersionUID = 1L;
    private Long id;
    private String name;
    // ...
}

// 2. Dubbo 3.x 默认使用 fastjson2 序列化，对无参构造器和 getter/setter 有要求
// 如果报 "no default constructor"，添加无参构造器
public class UserDTO implements Serializable {
    public UserDTO() {}  // 无参构造器
}

// 3. 如果存在循环引用，使用 fastjson2 的 @JSONField(serialize = false) 排除

# 查看消费组消费进度（最关键命令）
sh mqadmin consumerProgress -n <nameserver-addr> -g order-consumer-group

# 输出示例：
# #Topic      #Broker Name  #QID  #Broker Offset  #Consumer Offset  #Diff
# order-topic broker-a      0     1523456          1423456           100000  ← 积压 10 万
# order-topic broker-a      1     1523456          1453456           70000
# Consume TPS: 0    ← 消费 TPS 为 0，消费者完全停止

# 关键指标：
# Consume TPS = 0     → 消费者完全停止，检查消费者进程是否存活
# Consume TPS 很低    → 消费者处理慢，检查消费逻辑或扩容
# Diff (TOTAL) 持续增长 → 消费速度跟不上生产速度

# 检查消费者进程
ps -ef | grep rocketmq

# 查看消费者日志
grep "exception\|error\|reconsume" /opt/app/logs/rocketmq/consumer.log | tail -20

# 常见阻塞原因：
# "MessageExt object is null"     → 消息已过期被清理（超过 fileReservedTime）
# "IllegalStateException"         → 消费逻辑抛出未捕获异常，线程池停止
# "too many times"               → 消息重试次数耗尽，进入死信队列

# 通过 Arthas 查看消费者线程池状态
java -jar arthas-boot.jar
thread | grep ConsumeMessageThread

# 方案一：调高消费线程数和批量拉取数（最直接，无需重启）
# 通过 Nacos 动态修改配置
spring:
  rocketmq:
    consumer:
      consume-thread-min: 50       # 最小消费线程数，默认 20
      consume-thread-max: 200      # 最大消费线程数，默认 64
      consume-message-batch-max-size: 16  # 一次拉取 16 条消息，默认 1 条（吞吐量翻 16 倍）

# 方案二：增加 Topic 队列数（决定最大并发度，消费者实例数不能超过队列数）
sh mqadmin updateTopic -n <nameserver-addr> -t order-topic -r 16 -w 16
# r=readQueueNums, w=writeQueueNums

# 方案三：水平扩容消费者实例
# 注意：消费者实例数 ≤ 队列数，超过队列数的实例不会分配到队列
# 例如 16 个队列最多 16 个消费者实例并发

# 方案四：积压严重时的紧急处理 — 临时跳过积压消息（慎用，会丢失未处理的消息）
# 1. 停止当前消费者
# 2. 创建一个临时的消费者组，快速消费积压消息并跳过处理
#    （仅将消息标记为已消费，不执行业务逻辑）
# 3. 重置位点到最新位置
sh mqadmin resetOffsetByTime -n <nameserver-addr> -t order-topic -g order-consumer-group -s now
# -s now 表示重置到最新位点

# 方案五：重置位点从某个时间点开始消费（积压消息中大部分已过期无用时）
sh mqadmin resetOffsetByTime -n <nameserver-addr> -t order-topic -g order-consumer-group -s 20260715120000
# -s 格式：yyyyMMddHHmmss，从该时间点开始消费

# 查看消费失败日志
grep "CONSUME_FAILED\|reconsume\|exception" /opt/app/logs/rocketmq/consumer.log | tail -20

# 查看重试队列中的消息
sh mqadmin queryMsgByKey -n <nameserver-addr> -t "%RETRY%order-consumer-group" -k <msgKey>

# 查看死信队列（重试 16 次后进入）
sh mqadmin queryMsgByKey -n <nameserver-addr> -t "%DLQ%order-consumer-group" -k <msgKey>

// 常见消费失败原因及修复

// 原因一：消费逻辑抛出未捕获异常
@RocketMQMessageListener(topic = "order-topic", consumerGroup = "order-consumer-group")
public class OrderConsumer implements RocketMQListener<String> {
    @Override
    public void onMessage(String message) {
        // 错误：未捕获异常，异常会触发重试
        OrderDTO order = JSON.parseObject(message, OrderDTO.class);
        orderService.process(order);  // 如果这里抛异常，消息会重试

        // 正确：捕获异常并分类处理
        try {
            OrderDTO order = JSON.parseObject(message, OrderDTO.class);
            orderService.process(order);
        } catch ( BusinessException e) {
            // 业务异常：记录日志，返回消费成功（不重试）
            // 消息进入人工处理队列
            log.error("业务异常，消息不再重试: {}", message, e);
            return;  // 正常返回，不抛异常，消费成功
        } catch (Exception e) {
            // 系统异常：抛出异常触发重试
            throw e;
        }
    }
}

// 原因二：消息体反序列化失败（生产者与消费者实体类不一致）
// 修复：统一实体类版本，或使用 JSON 格式传输并配置宽容解析

// 原因三：数据库唯一键冲突（消息重复消费）
// 修复：消费端实现幂等性

@Override
public void onMessage(MessageExt message) {
    String msgId = message.getMsgId();
    String msgKey = message.getKeys();  // 业务唯一标识（如订单号）

    // 1. 先查询是否已消费（Redis 或数据库）
    String consumeKey = "mq:consumed:" + msgKey;
    if (Boolean.TRUE.equals(redisTemplate.hasKey(consumeKey))) {
        log.info("消息已消费，跳过: msgKey={}", msgKey);
        return;  // 已消费，直接返回成功
    }

    // 2. 执行消费逻辑
    try {
        OrderDTO order = JSON.parseObject(new String(message.getBody()), OrderDTO.class);
        orderService.process(order);

        // 3. 标记已消费（设置过期时间，避免 Redis key 无限增长）
        redisTemplate.opsForValue().set(consumeKey, "1", 24, TimeUnit.HOURS);
    } catch (Exception e) {
        // 系统异常才重试，业务异常直接消费成功
        if (e instanceof BusinessException) {
            redisTemplate.opsForValue().set(consumeKey, "error", 24, TimeUnit.HOURS);
            return;
        }
        throw e;  // 触发重试
    }
}

# 第一步：确认生产者发送状态
grep "SEND_OK\|SEND_FAIL\|FLUSH_DISK_TIMEOUT" /opt/app/logs/rocketmq/producer.log | tail -20

# 第二步：通过 msgId 在 Broker 端查询消息是否存在
sh mqadmin queryMsgById -n <nameserver-addr> -i <msgId>

# 第三步：查看消息轨迹（需开启消息轨迹功能）
sh mqadmin queryMsgTrace -n <nameserver-addr> -i <msgId>

# 生产者端配置
rocketmq:
  producer:
    # 同步发送（确保 Broker 收到后才返回）
    send-message-timeout: 3000
    # 发送失败重试次数
    retry-times-when-send-failed: 3
    # 异步发送失败重试次数
    retry-times-when-send-async-failed: 3

# Broker 端配置（broker.conf）
# 同步刷盘（确保消息写入磁盘后才返回）
flushDiskType=SYNC_FLUSH
# 主从同步复制（确保消息复制到从节点）
brokerRole=SYNC_MASTER
# 消息保存时间（默认 72 小时，生产建议 168 小时=7 天）
fileReservedTime=168

<!-- 必须！Gateway 默认不包含 LoadBalancer 依赖 -->
<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-loadbalancer</artifactId>
</dependency>

spring:
  cloud:
    gateway:
      routes:
        - id: order-service
          uri: lb://order-service    # 必须用 lb:// 前缀，不能用 http://
          predicates:
            - Path=/api/order/**
          filters:
            - StripPrefix=1

# 通过 Nacos API 查看服务实例
curl "http://<nacos-ip>:8848/nacos/v1/ns/instance/list?serviceName=order-service"
# 检查返回的 instances 数组：
# - healthy: true（健康检查通过）
# - enabled: true（实例已启用）
# - weight > 0（权重不为 0，权重为 0 不会被调用）

# 查看 Gateway 进程线程状态
jstack <gateway-pid> | grep 'reactor\|http\|netty' | awk '{print $2}' | sort | uniq -c | sort -rn

# 查看是否有大量线程处于 WAITING 状态
jstack <gateway-pid> | grep -c "WAITING"

spring:
  cloud:
    gateway:
      # 调整网关连接池配置（防止连接池耗尽）
      httpclient:
        connect-timeout: 3000        # 连接超时 3 秒
        response-timeout: 30s        # 响应超时 30 秒
        pool:
          max-connections: 500       # 最大连接数，默认 500
          acquire-timeout: 5000     # 获取连接超时 5 秒
          type: elastic              # 弹性连接池（推荐）

# 测试 TLS 握手
openssl s_client -connect <order-service-ip>:443 -servername order-service
# 如果输出 "verify error:num=10:certificate has expired"，证书已过期

# 确认 Gateway 和下游服务的 HTTP 版本一致
curl -v --http2 http://<order-service-ip>:8080/health
curl -v --http1.1 http://<order-service-ip>:8080/health

# 错误：服务名含下划线
spring:
  application:
    name: order_service    # Nacos 可能无法正确处理

# 正确：使用连字符
spring:
  application:
    name: order-service    # 推荐使用连字符命名

# 查看 Gateway 日志中的异常
grep "ERROR\|Exception\|GlobalFilter" /opt/gateway/logs/gateway.log | tail -20

# 开启 Gateway 调试日志
# 通过 Arthas 动态修改日志级别
logger --name org.springframework.cloud.gateway --level DEBUG

# 第一步：确认是否 GC 导致 STW
jstat -gcutil <gateway-pid> 1000 5
# 如果 Full GC 频繁或耗时 > 500ms，说明堆内存不足

# 第二步：查看 Netty 事件循环线程是否被阻塞
# Gateway 基于 WebFlux，事件循环线程不应执行阻塞操作
jstack <gateway-pid> | grep 'reactor-http' -A 20
# 如果线程堆栈中包含 SocketInputStream.socketRead0，说明在执行阻塞 IO

# 第三步：通过 Arthas 追踪网关请求处理耗时
trace org.springframework.web.reactive.DispatcherHandler handle

# JVM 调优（网关是 IO 密集型，建议使用 G1GC）
java -Xms2g -Xmx4g -XX:+UseG1GC -XX:MaxGCPauseMillis=100 -jar gateway.jar

// 确保网关中不执行阻塞操作
// 错误：在过滤器中同步调用数据库
@Component
public class BadFilter implements GlobalFilter {
    @Override
    public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) {
        // 错误！同步阻塞调用
        String result = restTemplate.getForObject("http://config-service/config", String.class);
        return chain.filter(exchange);
    }
}

// 正确：使用响应式编程
@Component
public class GoodFilter implements GlobalFilter {
    private final WebClient webClient;

    @Override
    public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) {
        return webClient.get()
            .uri("http://config-service/config")
            .retrieve()
            .bodyToMono(String.class)
            .flatMap(config -> {
                exchange.getRequest().mutate().header("X-Config", config).build();
                return chain.filter(exchange);
            });
    }
}