天河区建设和水务局网站湛江市建网站

---

Kafka 主题 retention.ms 配置修改及深度问题排查指南

版本

bash-5.1# kafka-topics.sh --version
2.8.1 (Commit:839b886f9b732b15)

背景

在 Kafka 中，主题（Topic）的数据存储受 retention.ms（数据保留时间）和 retention.bytes（存储容量）限制。当主题数据占用过多磁盘空间时，需要调整这些参数。
重点是不能进行重启，因为重启会影响业务，这是关键问题
但配置修改和运维过程中可能遇到各种问题，本文将深入探讨以下内容：

1. 如何正确修改 retention.ms 配置
2. Kafka 主题状态异常（如 Isr: 0）的排查思路
3. 常见问题场景与解决方案

---

查看 Kafka 主题当前状态

使用 kafka-topics.sh 查看主题的完整配置和分区状态：

kafka-topics.sh --bootstrap-server localhost:9092 --describe --topic hawk_log

示例输出：

Topic: hawk_log	TopicId: Pi2TJRFxQSWcnToN3jDPsQ	PartitionCount: 1	ReplicationFactor: 1	
Configs: segment.bytes=1073741824Topic: hawk_log	Partition: 0	Leader: 0	Replicas: 0	Isr: 0

关键字段解析：

• PartitionCount: 1：主题仅有一个分区（Partition 0）。
• ReplicationFactor: 1：无数据冗余，副本数为 1（生产环境建议至少 3）。
• Replicas: 0：所有副本位于 Broker ID 0。
• Isr: 0：当前同步的副本列表为空，说明副本未正确同步。

---

修改 retention.ms 配置的正确方式

为什么不能使用 kafka-topics.sh？

尝试直接通过 kafka-topics.sh 修改配置时会报错：

kafka-topics.sh --bootstrap-server localhost:9092 --alter --topic hawk_log --config retention.ms=86400000

错误提示：

Option combination "[bootstrap-server],[config]" can't be used with option "[alter]"

原因：

• kafka-topics.sh 主要用于主题的创建、删除、列表查询等基础操作。
• 动态配置修改（如 retention.ms）需通过 kafka-configs.sh 实现，这是 Kafka 设计上的职责分离。

使用 kafka-configs.sh 动态更新配置

执行以下命令调整 retention.ms：

kafka-configs.sh --bootstrap-server localhost:9092 \--entity-type topics \--entity-name hawk_log \--alter \--add-config retention.ms=86400000  # 1天（单位：毫秒）

验证配置生效：

kafka-configs.sh --bootstrap-server localhost:9092 \--entity-type topics \--entity-name hawk_log \--describe

输出应包含 retention.ms=86400000：

Configs for topic 'hawk_log' are retention.ms=86400000,segment.bytes=1073741824

---

深入解析 retention 配置

retention.ms 与 retention.bytes 的关系

• 触发条件：满足任一条件即删除数据。
  • retention.ms：数据保留时间（默认 7 天）。
  • retention.bytes：分区最大数据容量（默认 -1，无限制）。

配置生效机制

• 动态生效：无需重启 Broker，但需确保 log.retention.check.interval.ms（默认 5 分钟）已配置，Kafka 会周期性检查清理条件。
• 日志段（Segment）机制：数据删除以日志段为单位，只有非活跃段（不再写入的段）才会被清理。

---

ISR 异常（Isr: 0）深度排查

什么是 ISR？

• ISR（In-Sync Replicas）：与 Leader 副本保持同步的副本集合。
• Leader：负责处理客户端读写请求的副本。
• Replicas：所有副本列表。

异常场景：Isr: 0 表示所有副本均未同步，可能导致数据不可用。

常见原因

1. Broker 宕机：托管副本的 Broker 离线。
2. 网络分区：Broker 间通信中断。
3. 磁盘故障：副本数据写入失败。
4. 资源不足：CPU、内存或文件句柄耗尽。

排查步骤

步骤 1：检查 Broker 进程状态

# 确认 Broker 进程运行
ps -ef | grep kafka# 检查服务端口监听
netstat -tuln | grep 9092

步骤 2：分析 Kafka 日志

日志路径通常为 $KAFKA_HOME/logs/server.log：

# 查找 ERROR 或 WARN 级别日志
grep -E "ERROR|WARN" server.log# 关键错误示例：
# - Broker registration failed （ZooKeeper 连接问题）
# - Not enough replicas in ISR （副本同步失败）

步骤 3：验证 ZooKeeper 状态

Kafka 依赖 ZooKeeper 管理元数据，需确保 ZooKeeper 集群健康：

# 进入 ZK 命令行工具
zkCli.sh -server localhost:2181# 查看 Broker 注册信息
ls /brokers/ids

步骤 4：手动触发 Leader 选举

如果 Broker 已恢复但 ISR 仍异常，可尝试重新选举 Leader：

kafka-leader-election.sh --bootstrap-server localhost:9092 \--topic hawk_log \--partition 0 \--election-type preferred

步骤 5：强制重新分配副本

适用场景：副本损坏或 Broker 不可恢复。

1. 创建副本分配计划 reassign.json：

{"version": 1,"partitions": [{"topic": "hawk_log","partition": 0,"replicas": [0]  // 假设 Broker 0 已恢复，仍分配给它}]
}

2. 执行重新分配：

kafka-reassign-partitions.sh --bootstrap-server localhost:9092 \--reassignment-json-file reassign.json \--execute

---

生产环境最佳实践

1. 副本数设置：ReplicationFactor 至少为 3，确保高可用。
2. 监控告警：
   • 使用 JMX 监控 UnderReplicatedPartitions、IsrShrinksPerSec。
   • 集成 Prometheus + Grafana 可视化监控。
3. 定期清理策略检查：

   kafka-log-dirs.sh --bootstrap-server localhost:9092 --describe --topic-list hawk_log
   

4. 避免单点故障：分散分区副本到不同机架或可用区。

---

常见问题 FAQ

Q1：修改 retention.ms 后数据未立即删除？

• 原因：清理周期由 log.retention.check.interval.ms 控制（默认 5 分钟），且只清理非活跃段。

Q2：如何同时设置时间与容量保留策略？

• 示例：--add-config retention.ms=86400000,retention.bytes=1073741824

Q3：ReplicationFactor=1 的风险是什么？

• 数据丢失：一旦唯一副本损坏，数据将无法恢复。

Q4：ISR 长时间未恢复怎么办？

• 优先恢复故障 Broker，必要时重建副本。

---

总结

通过本文，你掌握了以下技能：

1. 动态调整 retention 配置：使用 kafka-configs.sh 而非 kafka-topics.sh。
2. ISR 异常处理：从 Broker 状态、日志分析到副本重分配的全链路排查。
3. 生产环境加固建议：副本数、监控、清理策略的最佳实践。

Kafka 运维需要细致的问题定位和预防性设计，希望本指南助你游刃有余应对各类挑战！🚀