Kafka 生产检查清单

适用 Kafka 3.9 / 4.0；4.0 只支持 KRaft，3.9 是最后一个支持 ZooKeeper 的版本。默认值标注版本，版本差异以官方文档为准。 只列不做会丢数据、会不可用、会查不出故障的动作；机制解释见本目录各篇正文。

上线前

• [ ] Topic 级可靠性三件套落实：replication.factor=3、min.insync.replicas=2（Broker 默认 1）、unclean.leader.election.enable=false（3.9/4.0）。建完用 kafka-configs.sh --describe --all --entity-type topics --entity-name <topic> 核对生效值，只看 Broker 默认不算。
• [ ] Producer 投递语义显式确认：acks=all（3.0 起默认）、enable.idempotence=true（3.0 起默认）、delivery.timeout.ms=120000（3.9/4.0）。有客户端覆盖成 acks=1 或关闭幂等时，记录原因和影响面；事务消费端另配 isolation.level=read_committed。
• [ ] 分区数和 key 路由一次定好：分区只能增不能减；扩分区会改变同 key 的落点，依赖同 key 有序的业务要在扩容前评估。replication.factor 不能超过 Broker 数。
• [ ] 容量按分区副本总量估算：log.retention.hours=168、log.retention.bytes=-1（3.9/4.0，默认不按大小限制）、log.segment.bytes=1073741824。-1 表示磁盘会一直涨；数据盘单独挂载，建议使用率到 70% 启动扩容评估、85% 前完成处置。
• [ ] 消费组起点和发布预算已确认：auto.offset.reset=latest（3.9/4.0），需要存量数据的组改 earliest 或 none；max.poll.records=500 × 单条处理耗时 < max.poll.interval.ms=300000；session.timeout.ms=45000、heartbeat.interval.ms=3000（3.0 起）；位点保留 offsets.retention.minutes=10080。滚动发布用 group.instance.id，并保证同一 ID 同一时刻只有一个实例。
• [ ] KRaft 迁移路径验证过：3.9 → 4.0 不是滚动重启；按 KIP-866 走 bridge，备份元数据，在测试环境完成一次迁移和回滚。4.0 不支持 ZooKeeper。

运行中

• [ ] 副本冗余持续可见：kafka-topics.sh --describe 看 Isr 是否等于 Replicas；JMX kafka.server:type=ReplicaManager,name=UnderReplicatedPartitions 持续大于 0 就告警。
• [ ] lag 看趋势不看快照：kafka-consumer-groups.sh --describe --group <group> 看 LAG 斜率，--members --verbose 看分区归属；单分区高先查 key 倾斜，全分区高先查消费者数量和下游。
• [ ] 磁盘增长和保留配置对齐：kafka-log-dirs.sh --describe --topic-list <topic> 看 size/offsetLag/isFuture，df -h 看数据盘；再 kafka-configs.sh --describe --all 确认 Topic 实际生效的 retention.ms/retention.bytes。
• [ ] 重平衡频率有基线：消费者日志统计 PreparingRebalance/CompletingRebalance；成员 ID 频繁变化、分区归属反复漂移时，先查 max.poll.interval.ms、GC 和网络，再考虑分配策略。

故障时

• [ ] ISR 收缩 / NotEnoughReplicasException → --describe 看 Isr、JMX UnderReplicatedPartitions、Broker 日志搜 Shrinking ISR → 单个 Follower 掉队查磁盘/GC/网络，所有 Follower 同时掉队查 Leader 写入压力和 replica.fetch.max.bytes=1048576；不要先调大 replica.lag.time.max.ms，也不要开 unclean 选举。
• [ ] rebalance 风暴 → 日志搜 PreparingRebalance、member has left、Attempt to heartbeat failed，--members --verbose 看成员是否反复进出 → 单批处理超过 max.poll.interval.ms=300000 是首要原因；先减小 max.poll.records 或把处理异步化，不要靠重启消费者恢复。
• [ ] lag 持续增长 → --describe 看 LAG 斜率、CONSUMER-ID 是否为空 → 全分区涨先把消费者扩到分区数（不能超过），仍不够再评估扩分区；不要用 --reset-offsets --to-latest 消 lag，那会跳过未消费数据。
• [ ] 磁盘写满 / 分区 offline → kafka-log-dirs.sh 看 size、isFuture，df -h，Broker 日志搜 No space left on device → 先降 retention.ms/retention.bytes 等清理线程整段删除，或迁分区/扩盘；不要手工 rm 活跃的 .log/.index。
• [ ] OffsetOutOfRangeException / 位点越界 → kafka-get-offsets.sh --time -2（earliest）和 --time -1（latest），再 --describe 对已提交位点 → 位点小于 earliest 是数据已被保留期删除，大于 LEO 是重置到未来或 Topic 重建；先停消费者，--dry-run 后 --execute，--to-earliest 会重放、--to-latest 会跳过。