Kafka 命令速查
通用说明
本篇按用途分组收录常用命令，默认三条约定：
- 命令都在
$KAFKA_HOME/bin下，执行前先把这个目录加进PATH。 - 统一用
--bootstrap-server写法，ZooKeeper 时代的--zookeeper在 KRaft 下已不可用。 - 示例里的地址、Topic 名、消费组名按自己环境替换，不必照抄。
Topic 管理
| 命令 | 作用 | 示例 |
|---|---|---|
kafka-topics.sh --create | 创建 Topic，指定分区和副本 | kafka-topics.sh --bootstrap-server localhost:9092 --create --topic order-created --partitions 6 --replication-factor 3 |
kafka-topics.sh --list | 列出所有 Topic | kafka-topics.sh --bootstrap-server localhost:9092 --list |
kafka-topics.sh --describe | 查看分区、Leader、副本、ISR | kafka-topics.sh --bootstrap-server localhost:9092 --describe --topic order-created |
kafka-topics.sh --alter | 扩分区（只能增不能减） | kafka-topics.sh --bootstrap-server localhost:9092 --alter --topic order-created --partitions 12 |
kafka-topics.sh --delete | 删除 Topic 及其数据 | kafka-topics.sh --bootstrap-server localhost:9092 --delete --topic order-created |
kafka-topics.sh --under-replicated | 只列出副本不足的分区 | kafka-topics.sh --bootstrap-server localhost:9092 --describe --under-replicated-partitions |
kafka-configs.sh --alter | 动态修改 Topic 配置 | kafka-configs.sh --bootstrap-server localhost:9092 --alter --entity-type topics --entity-name order-created --add-config retention.ms=259200000 |
kafka-configs.sh --describe | 查看配置及来源 | kafka-configs.sh --bootstrap-server localhost:9092 --describe --entity-type topics --entity-name order-created |
kafka-get-offsets.sh | 查询某时刻各分区 offset | kafka-get-offsets.sh --bootstrap-server localhost:9092 --topic order-created --time -1 |
生产与消费
| 命令 | 作用 | 示例 |
|---|---|---|
kafka-console-producer.sh | 命令行发消息，回车一条 | kafka-console-producer.sh --bootstrap-server localhost:9092 --topic order-created |
kafka-console-producer.sh（带 key） | 按 key 分区发送 | kafka-console-producer.sh --bootstrap-server localhost:9092 --topic order-created --property parse.key=true --property key.separator=: |
kafka-console-consumer.sh | 命令行消费，从头读 | kafka-console-consumer.sh --bootstrap-server localhost:9092 --topic order-created --from-beginning |
kafka-console-consumer.sh（带元信息） | 打印分区、offset、key | kafka-console-consumer.sh --bootstrap-server localhost:9092 --topic order-created --from-beginning --property print.partition=true --property print.offset=true --property print.key=true |
kafka-console-consumer.sh（进组） | 以指定消费组消费 | kafka-console-consumer.sh --bootstrap-server localhost:9092 --topic order-created --group demo-group |
kafka-console-consumer.sh（限条数） | 读到 N 条后退出，适合验证 | kafka-console-consumer.sh --bootstrap-server localhost:9092 --topic order-created --from-beginning --max-messages 10 |
kafka-producer-perf-test.sh | 生产端压测 | kafka-producer-perf-test.sh --topic perf-test --num-records 100000 --record-size 1024 --throughput -1 --producer-props bootstrap.servers=localhost:9092 acks=all |
kafka-consumer-perf-test.sh | 消费端压测 | kafka-consumer-perf-test.sh --bootstrap-server localhost:9092 --topic perf-test --messages 100000 --group perf-group |
消费组
| 命令 | 作用 | 示例 |
|---|---|---|
kafka-consumer-groups.sh --list | 列出所有消费组 | kafka-consumer-groups.sh --bootstrap-server localhost:9092 --list |
kafka-consumer-groups.sh --describe | 查位点、LEO 与 LAG | kafka-consumer-groups.sh --bootstrap-server localhost:9092 --describe --group order-service |
kafka-consumer-groups.sh --members | 查看组内成员及分到的分区 | kafka-consumer-groups.sh --bootstrap-server localhost:9092 --describe --group order-service --members --verbose |
kafka-consumer-groups.sh --state | 查看组状态（Stable/Empty 等） | kafka-consumer-groups.sh --bootstrap-server localhost:9092 --describe --group order-service --state |
kafka-consumer-groups.sh --delete | 删除消费组（需组内无成员） | kafka-consumer-groups.sh --bootstrap-server localhost:9092 --delete --group order-service |
kafka-consumer-groups.sh --reset-offsets | 重置位点到最早/最新/时间点 | kafka-consumer-groups.sh --bootstrap-server localhost:9092 --group order-service --topic order-created --reset-offsets --to-earliest --execute |
kafka-consumer-groups.sh --reset-offsets（时间点） | 回退到指定时间 | kafka-consumer-groups.sh --bootstrap-server localhost:9092 --group order-service --topic order-created --reset-offsets --to-datetime 2026-01-01T00:00:00.000 --execute |
重置位点前必须停消费者
组里还有活跃成员时 --reset-offsets 会直接拒绝执行。先停消费实例，重置完再启动，否则会出现「部分分区重放、部分没重放」的混乱状态。
运维诊断
| 命令 | 作用 | 示例 |
|---|---|---|
kafka-metadata-quorum.sh | 查看 KRaft quorum 与控制器状态 | kafka-metadata-quorum.sh --bootstrap-server localhost:9092 describe --status |
kafka-broker-api-versions.sh | 验证 Broker 连通性与版本 | kafka-broker-api-versions.sh --bootstrap-server localhost:9092 |
kafka-log-dirs.sh | 查看各目录占用与分区分布 | kafka-log-dirs.sh --bootstrap-server localhost:9092 --describe --topic-list order-created |
kafka-reassign-partitions.sh --generate | 生成分区迁移方案 | kafka-reassign-partitions.sh --bootstrap-server localhost:9092 --generate --topics-to-move-json-file topics.json --broker-list "1,2,3" |
kafka-reassign-partitions.sh --execute | 执行迁移并限流 | kafka-reassign-partitions.sh --bootstrap-server localhost:9092 --execute --reassignment-json-file plan.json --throttle 104857600 |
kafka-reassign-partitions.sh --verify | 确认迁移完成 | kafka-reassign-partitions.sh --bootstrap-server localhost:9092 --verify --reassignment-json-file plan.json |
kafka-leader-election.sh | 触发首选副本选举，恢复均衡 | kafka-leader-election.sh --bootstrap-server localhost:9092 --election-type preferred --all-topic-partitions |
kafka-delete-records.sh | 按 offset 删除历史消息 | kafka-delete-records.sh --bootstrap-server localhost:9092 --offset-json-file offsets.json |
kafka-dump-log.sh | 直接解析日志段，确认消息内容 | kafka-dump-log.sh --files /data/kafka/logs/order-created-0/00000000000000000000.log --print-data-log |
kafka-storage.sh random-uuid | 生成集群 ID | kafka-storage.sh random-uuid |
kafka-storage.sh format | 格式化存储目录（仅首次） | kafka-storage.sh format -t xtzWWN4bTjitpL3kfd9s5g -c config/kraft/server.properties |
kafka-server-start.sh | 启动 Broker | kafka-server-start.sh -daemon config/kraft/server.properties |
kafka-server-stop.sh | 停止 Broker | kafka-server-stop.sh |
命令找不到的排查
kafka-topics.sh 报 ClassNotFoundException 或参数不认识，八成是 PATH 里混了两个版本的 Kafka。用 which kafka-topics.sh 确认实际执行的是哪个脚本，版本不匹配时脚本和服务端的协议可能对不上。
速记
- 看健康：
--describe --under-replicated-partitions+kafka-consumer-groups --describe。 - 看空间：
kafka-log-dirs.sh --describe比du准，因为它是从 Kafka 视角统计的。 - 做变更：扩分区只能增、改副本只能 reassign、删数据只能缩保留或按 offset 删。
- 别手删文件：任何磁盘操作优先用 Kafka 自己的命令，直接动
log.dirs会破坏索引。