生命周期管理与故障排查
Kafka 备份、变更和恢复要区分配置、ZooKeeper 元数据与消息日志。运行中的 Broker 数据目录不能通过普通文件复制后直接覆盖恢复；消息级 RPO 需要跨集群复制或经验证的灾备方案。
1. 日常巡检
# 检查副本不足与不可用分区；两条命令均无输出才是预期状态。
/opt/kafka/bin/kafka-topics.sh --describe --under-replicated-partitions \
--bootstrap-server kafka-1.example.internal:9092
/opt/kafka/bin/kafka-topics.sh --describe --unavailable-partitions \
--bootstrap-server kafka-1.example.internal:9092
# 检查三个 ZooKeeper 节点；预期一个 leader、两个 follower。
for host in zk-1 zk-2 zk-3; do
echo "== ${host} ==" # 输出节点名，便于审计巡检结果。
echo stat | nc -w 3 "${host}" 2181 | rg 'Mode: (leader|follower)'
done
2. 变更、备份与升级
- Broker 静态配置通过滚动重启生效，一次只处理一个 Broker，并等待 ISR 恢复。
- Topic 动态配置通过
kafka-configs.sh变更，记录变更前值、目标值、影响与回滚。 - 备份 Kafka/ZooKeeper 配置、Broker ID、Topic 配置、ACL 与 ZooKeeper 快照；关键消息需要单独设计异地复制。
- ZooKeeper 模式升级前完成版本兼容核对、预发演练和回滚评审；不要向现有
server.properties临时混入 KRaft 参数。
# 导出 Topic 元数据与动态配置，输出应存放在受控备份位置并限制访问权限。
/opt/kafka/bin/kafka-topics.sh --describe \
--bootstrap-server kafka-1.example.internal:9092 > kafka-topics-$(date +%F).txt
/opt/kafka/bin/kafka-configs.sh --describe \
--bootstrap-server kafka-1.example.internal:9092 \
--entity-type topics > kafka-topic-configs-$(date +%F).txt
3. 高频故障
| 现象 | 检查路径 | 避免操作 |
|---|---|---|
| 客户端连接失败 | DNS、advertised.listeners、TLS/SASL、ACL、负载均衡 | 不要将 advertised.listeners 改为 localhost |
| 生产超时或拒绝写入 | ISR、min.insync.replicas、磁盘、网络、Producer acks | 不要永久降低最小 ISR |
| 消费 Lag 增长 | 分区热点、下游依赖、重平衡、处理耗时 | 不要盲目扩容超过分区数的消费者 |
| Controller 频繁变化 | ZooKeeper 会话、法定人数、网络与 GC | 不要删除 ZooKeeper 数据目录 |
故障恢复后必须复查 ISR、生产失败率、Consumer Lag 和 ZooKeeper 角色，并记录故障期间被拒绝写入或延迟的业务范围。
4. 升级与迁移检查表
- 已确认 Kafka 3.x、JDK、ZooKeeper、客户端、Connect 与监控插件的兼容性。
- 已在预发完成滚动升级、Producer/Consumer 回归和单节点故障演练。
- 每一步升级前都无 Offline Partition、无持续 Under Replicated Partition，且 Lag 在基线内。
- 已备份配置、Topic 元数据、ACL 与 ZooKeeper 快照，并验证隔离恢复流程。
- ZooKeeper 到 KRaft 的迁移另行制定专项方案，不与常规补丁升级混合执行。