kafka主题管理详解 - kafka-topics.sh

在 Kafka 的 KRaft 模式（无 ZooKeeper）中， kafka-topics.sh 工具用于管理主题（topics），包括创建、查看、修改和删除等操作。以下是其详细使用方法：

基本语法

kafka-topics.sh --bootstrap-server <kafka-broker-host:port> [命令选项]

注意：在 KRaft 模式下，不再使用 --zookeeper 参数，而是通过 --bootstrap-server 连接到 Kafka broker。

常用命令选项

1. 创建主题（create）

kafka-topics.sh --bootstrap-server localhost:9092 \
  --create \
  --topic <topic-name> \
  --partitions <num-partitions> \
  --replication-factor <replication-factor> \
  [--config <key=value>]  # 可选的主题配置

示例：

# 创建一个名为 "user-tracking" 的主题，3个分区，1个副本
kafka-topics.sh --bootstrap-server localhost:9092 \
  --create \
  --topic user-tracking \
  --partitions 3 \
  --replication-factor 1 \
  --config retention.ms=86400000  # 数据保留1天

注意： 复制因子不能大于可用的 broker 数量

在 Kafka 中，复制因子不能大于可用的 broker 数量，因为每个副本需要存储在不同的 broker 上以保证高可用性。

否则会报错：

Error while executing topic command : Unable to replicate the partition 2 time(s): The target replication factor of 2 cannot be reached because only 1 broker(s) are registered.

2. 查看所有主题（list）

kafka-topics.sh --bootstrap-server localhost:9092 --list

执行演示：

3. 查看主题详情（describe）

kafka-topics.sh --bootstrap-server localhost:9092 \
  --describe \
  --topic <topic-name>  # 不指定则查看所有主题详情

示例：

4. 修改主题配置（alter）

kafka-topics.sh --bootstrap-server localhost:9092 \
  --alter \
  --topic <topic-name> \
  [--partitions <new-num-partitions>]  # 只能增加分区数
  [--config <key=value>]  # 添加或修改配置
  [--delete-config <key>]  # 删除配置

增加分区数

示例：

# 增加分区数到5
kafka-topics.sh --bootstrap-server localhost:9092 \
  --alter \
  --topic user-tracking \
  --partitions 5

演示：

5. 删除主题（delete）

kafka-topics.sh --bootstrap-server localhost:9092 \
  --delete \
  --topic <topic-name>

注意：删除主题需要 broker 配置 delete.topic.enable=true（默认已开启）。
删除操作是异步的，执行完这条命令不代表主题立即就被删除了。它仅仅是被标记成“已删除”状态而已。Kafka 会在后台默默地开启主题删除操作。

演示：

6. 其他有用选项

• --if-exists：操作仅在主题存在时执行（如删除、修改）
• --if-not-exists：操作仅在主题不存在时执行（如创建）

示例：

# 仅在主题存在时删除
kafka-topics.sh --bootstrap-server localhost:9092 \
  --delete \
  --topic user-tracking \
  --if-exists

常见配置参数

可以通过 --config 选项设置的常用主题配置：

• retention.ms：数据保留时间（毫秒）
• retention.bytes：每个分区保留的数据量上限
• cleanup.policy：清理策略（delete 或 compact）
• max.message.bytes：单条消息的最大字节数