消息队列 / 系统课时
使用命令行管理 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。
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预期输出
CREATE_OK--partitions 3 创建 3 个分区,--replication-factor 1 表示每个分区只有 1 份副本。创建命令成功只说明元数据写入成功,下一步仍应查看 Topic 的实际分布。
查看分区与副本分布
先列出 Topic,再用 --describe 查看目标 Topic。描述结果是检查 KRaft 集群元数据最直接的入口。
"$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 版本变化。
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 个。
"$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预期输出
ALTER_OK
Topic: cli.orders TopicId: <ID> PartitionCount: 6 ReplicationFactor: 1 Configs: ...扩分区不会重新排列旧消息,新增分区从空日志开始。若生产者按 Key 分区,分区总数变化还可能改变同一 Key 后续消息映射到的分区,因此不要把“扩分区”当成无成本操作。
删除并验证
删除前再次确认 Topic 名称。命令返回后,控制器还可能需要短时间完成元数据清理,因此列表中若暂时仍能看到它,稍后再检查一次。
"$KAFKA_HOME/bin/kafka-topics.sh" \
--bootstrap-server "$BOOTSTRAP_SERVER" \
--delete \
--topic cli.orders >/dev/null \
&& echo DELETE_REQUEST_SENT预期输出
DELETE_REQUEST_SENT随后验证 Topic 是否已经消失。
"$KAFKA_HOME/bin/kafka-topics.sh" \
--bootstrap-server "$BOOTSTRAP_SERVER" \
--list | grep -Fx "cli.orders" || echo TOPIC_NOT_FOUND预期结果
TOPIC_NOT_FOUND如果删除长期没有生效,应检查 Broker 是否允许 Topic 删除以及控制器日志,而不是反复执行同一条命令。日常管理中,始终把“执行变更”和“重新 describe/list 验证结果”视为一组操作。