消息队列 / 系统课时

使用命令行管理 Topic

使用命令行管理 Topic

本节用 Kafka 自带 CLI 完成 Topic 的创建、查看、扩分区和删除,并通过 --describe 核对分区、Leader、副本与 ISR。示例默认连接本机 KRaft 集群,做完后你能独立判断 Topic 是否按预期建立和变更。

学习目标

  • 使用 kafka-topics.sh 创建、列出、描述、修改和删除 Topic
  • 从描述结果中读懂分区数、Leader、Replicas 与 ISR
  • 识别扩分区、修改副本因子和删除操作的关键边界

创建并确认 Topic

以下示例假设 Kafka 安装在 /opt/kafka,Broker 对外监听 localhost:9092。单节点实验环境只能使用副本因子 1;如果集群有至少 3 个 Broker,可把副本因子改为 3。

bash
export KAFKA_HOME=/opt/kafka
export BOOTSTRAP_SERVER=localhost:9092

"$KAFKA_HOME/bin/kafka-topics.sh" \
  --bootstrap-server "$BOOTSTRAP_SERVER" \
  --create \
  --topic cli.orders \
  --partitions 3 \
  --replication-factor 1 >/dev/null \
  && echo CREATE_OK

预期输出

text
CREATE_OK

--partitions 3 创建 3 个分区,--replication-factor 1 表示每个分区只有 1 份副本。创建命令成功只说明元数据写入成功,下一步仍应查看 Topic 的实际分布。

查看分区与副本分布

先列出 Topic,再用 --describe 查看目标 Topic。描述结果是检查 KRaft 集群元数据最直接的入口。

bash
"$KAFKA_HOME/bin/kafka-topics.sh" \
  --bootstrap-server "$BOOTSTRAP_SERVER" \
  --list

"$KAFKA_HOME/bin/kafka-topics.sh" \
  --bootstrap-server "$BOOTSTRAP_SERVER" \
  --describe \
  --topic cli.orders

预期结果中应能看到 cli.orders,并出现 3 条分区记录。Broker ID、Topic ID 以及部分附加字段会随环境和 Kafka 版本变化。

text
cli.orders

Topic: cli.orders  TopicId: <ID>  PartitionCount: 3  ReplicationFactor: 1  Configs: ...
Topic: cli.orders  Partition: 0  Leader: <ID>  Replicas: <ID>  Isr: <ID>
Topic: cli.orders  Partition: 1  Leader: <ID>  Replicas: <ID>  Isr: <ID>
Topic: cli.orders  Partition: 2  Leader: <ID>  Replicas: <ID>  Isr: <ID>

Leader 是当前负责该分区读写的 Broker;Replicas 是该分区的副本集合;Isr 是与 Leader 保持同步、可参与故障切换的副本集合。健康情况下,复制因子为 1 时 Replicas 与 Isr 都只有一个 Broker ID。

修改分区数

Kafka CLI 可以增加已有 Topic 的分区数,但不能把分区数减少。下面把 cli.orders 从 3 个分区扩到 6 个。

bash
"$KAFKA_HOME/bin/kafka-topics.sh" \
  --bootstrap-server "$BOOTSTRAP_SERVER" \
  --alter \
  --topic cli.orders \
  --partitions 6 >/dev/null \
  && echo ALTER_OK

"$KAFKA_HOME/bin/kafka-topics.sh" \
  --bootstrap-server "$BOOTSTRAP_SERVER" \
  --describe \
  --topic cli.orders | head -n 1

预期输出

text
ALTER_OK
Topic: cli.orders  TopicId: <ID>  PartitionCount: 6  ReplicationFactor: 1  Configs: ...

扩分区不会重新排列旧消息,新增分区从空日志开始。若生产者按 Key 分区,分区总数变化还可能改变同一 Key 后续消息映射到的分区,因此不要把“扩分区”当成无成本操作。

删除并验证

删除前再次确认 Topic 名称。命令返回后,控制器还可能需要短时间完成元数据清理,因此列表中若暂时仍能看到它,稍后再检查一次。

bash
"$KAFKA_HOME/bin/kafka-topics.sh" \
  --bootstrap-server "$BOOTSTRAP_SERVER" \
  --delete \
  --topic cli.orders >/dev/null \
  && echo DELETE_REQUEST_SENT

预期输出

text
DELETE_REQUEST_SENT

随后验证 Topic 是否已经消失。

bash
"$KAFKA_HOME/bin/kafka-topics.sh" \
  --bootstrap-server "$BOOTSTRAP_SERVER" \
  --list | grep -Fx "cli.orders" || echo TOPIC_NOT_FOUND

预期结果

text
TOPIC_NOT_FOUND

如果删除长期没有生效,应检查 Broker 是否允许 Topic 删除以及控制器日志,而不是反复执行同一条命令。日常管理中,始终把“执行变更”和“重新 describe/list 验证结果”视为一组操作。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

使用命令行管理 Topic

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通