日常运维最常遇到消费组“卡住”或“跑偏”，需用kafka-consumer-groups.sh先诊断状态（确保inactive），再通过--to-earliest、--to-latest、--to-datetime、--to-offset、--shift-by、--from-file六种方式精准重置Offset，并严格遵循dry-run预览、--execute执行、describe验证三步法。
Java Kafka 项目中，日常运维最常遇到的不是代码写错，而是消费组“卡住”或“跑偏”——比如延迟飙升、重复消费、漏消息。这时候靠改代码重启太慢，得用运维工具快速诊断+精准重置 Offset。核心原则是：先看清状态，再动手调整，且必须确保消费者组处于非活跃状态（inactive）。
一、用 kafka-consumer-groups.sh 快速诊断消费组状态
这是 Kafka 自带的命令行工具，无需额外依赖，适合所有环境。
-
查消费者组是否存在、是否活跃：
bin/kafka-consumer-groups.sh --bootstrap-server localhost:9092 --list | grep my-group
若输出中有该组名，再加--describe看详情；若无输出，说明组不存在或已彻底下线。 -
查实时消费进度与延迟：
bin/kafka-consumer-groups.sh --bootstrap-server localhost:9092 --group my-group --describe
关键看三列：CURRENT-OFFSET（当前消费到哪）、LOG-END-OFFSET（分区最新消息位置）、LAG（差多少条没消费）。LAG 持续增长，基本可判定消费停滞。 -
确认是否 inactive（重置前提！）：
如果--describe输出中STATE显示Stable或PreparingRebalance，说明消费者正在运行——必须先停掉所有该组的 Consumer 实例，等几秒再查，直到 STATE 变为Empty或直接查不到该组（表示已退出）。
二、六种常用 Offset 重置方式及适用场景
重置前务必明确目标：是要重放历史数据？跳过故障段？还是清空重来？选对策略比操作更重要。
-
--to-earliest：从最早消息开始重消费（如全量回溯验证逻辑）。
--reset-offsets --to-earliest --topic my-topic --execute -
--to-latest：跳过所有历史消息，只消费新进数据（如紧急上线后不想处理旧积压）。
--reset-offsets --to-latest --topic my-topic --execute -
--to-datetime：按时间点精准定位（如“重跑今天上午10点后的数据”）。注意时区用 UTC，格式严格：
--to-datetime 2026-07-28T10:00:00.000Z -
--to-offset：指定具体数字位移（需提前查好 partition 的合法 offset 范围，避免越界）。
--to-offset 12345 --topic my-topic --partition 0 -
--shift-by：相对移动（如“往前倒退100条”，用于小范围重试）。负数左移，正数右移。
--shift-by -100 --topic my-topic --all-topics -
--from-file：批量重置多 partition 不同 offset（适合复杂场景，需准备 CSV 文件，每行：
topic,partition,offset）。
三、安全操作三步法（防误操作）
重置 Offset 是高危操作，务必走完这三步：
立即学习“Java免费学习笔记（深入）”；
-
第一步：dry-run 预览 —— 加
--dry-run参数，不执行，只打印将要修改的结果。确认 topic、partition、新 offset 都符合预期再继续。 - 第二步：加 --execute 显式执行 —— 不加此参数命令不会生效，这是 Kafka 的安全保护机制，别省略。
-
第三步：重查验证 —— 执行后立刻再跑一次
--describe，核对 CURRENT-OFFSET 是否已更新，LAG 是否归零或符合预期。
四、Java 应用内辅助诊断技巧
如果无法直接连集群执行命令，可在应用中快速获取关键信息：
- 用
AdminClient.listConsumerGroups()查组是否存在； - 调用
AdminClient.describeConsumerGroup(groupId)获取状态（需 Kafka 2.4+）； - 通过
KafkaConsumer.position(TopicPartition)和endOffsets()计算实时 lag（仅适用于当前活跃 consumer）； - 日志里重点关注
NoOffsetForPartitionException或OffsetOutOfRangeException，它们直接暴露 auto.offset.reset 配置是否生效、消息是否已过期。
