3. Kafka 命令行操作：从 Topic 到消费组，手把手过一遍

说实话，很多初学者一上来就扎进代码，结果连 Topic 怎么建、消息怎么发都没搞明白。我个人觉得，命令行操作是理解 Kafka 内部机制最快的方式。你敲一遍命令，比看十页文档都管用。

这一节，我们就用最直接的方式，把 Kafka 命令行里最常用的几个操作过一遍。创建 Topic、查看列表、生产消息、消费消息、查看消费组状态。嗯，就这五个，但每一个都有坑。

3.1 创建 Topic：别急着敲命令，先想清楚分区和副本

创建 Topic 的命令很简单，但参数怎么配，才是关键。

# 创建一个名为 "test-topic" 的 Topic，3 个分区，2 个副本
kafka-topics.sh --create \
  --bootstrap-server localhost:9092 \
  --topic test-topic \
  --partitions 3 \
  --replication-factor 2

这里有几个点要注意：

• 分区数（partitions）：决定了 Topic 的并行处理能力。分区越多，吞吐量越高，但也会增加元数据管理的开销。我个人习惯，初期先设 3-6 个分区，后续根据流量再调整。
• 副本因子（replication-factor）：决定了数据的冗余程度。生产环境至少 2 或 3。如果集群只有 1 台 Broker，副本因子只能设为 1，否则会报错。
• --bootstrap-server vs --zookeeper：老版本用 Zookeeper 连接，新版本（2.8+）推荐用 --bootstrap-server。我建议你直接用新方式，省得以后迁移麻烦。

3.2 查看 Topic 列表：确认你的 Topic 真的建好了

创建完 Topic，第一件事就是确认它是否真的存在。

# 查看所有 Topic 列表
kafka-topics.sh --list --bootstrap-server localhost:9092

# 查看某个 Topic 的详细信息（分区、副本、Leader 等）
kafka-topics.sh --describe --bootstrap-server localhost:9092 --topic test-topic

--list 会输出所有 Topic 的名称，简单直接。--describe 则会输出更详细的信息，包括每个分区的 Leader、副本分布、ISR（In-Sync Replicas）等。你想想看，这些信息对于排查问题有多重要。

命令	输出内容	适用场景
--list	Topic 名称列表	快速查看有哪些 Topic
--describe	分区、副本、Leader、ISR 等详细信息	排查分区分布不均、副本同步延迟等问题

3.3 生产消息：用控制台生产者发几条数据试试

Topic 建好了，接下来就是往里面塞数据。Kafka 提供了一个控制台生产者，非常适合测试。

# 启动控制台生产者
kafka-console-producer.sh --bootstrap-server localhost:9092 --topic test-topic

# 输入消息内容，每行一条
> Hello, Kafka!
> This is my first message.
> 第三行消息，带中文也没问题。

输入完消息后，按 Ctrl+C 退出。这里有个细节：默认情况下，生产者不会等待所有副本确认，而是 Leader 确认后就返回。如果你需要更高的可靠性，可以加 --producer-property acks=all。

# 高可靠性模式：等待所有副本确认
kafka-console-producer.sh --bootstrap-server localhost:9092 \
  --topic test-topic \
  --producer-property acks=all

3.4 消费消息：看看数据能不能正常读出来

消息生产完了，总得验证一下能不能消费。控制台消费者就是干这个的。

# 启动控制台消费者，从最新消息开始消费
kafka-console-consumer.sh --bootstrap-server localhost:9092 \
  --topic test-topic \
  --from-beginning

--from-beginning 表示从 Topic 的最早消息开始消费。如果不加这个参数，默认只消费启动后产生的新消息。你想想看，如果你只是想看历史数据，不加这个参数就什么都看不到。

3.5 查看消费组状态：确认消费者有没有掉队

生产环境里，消费组的状态监控是重中之重。Kafka 提供了专门的命令来查看消费组的偏移量（Offset）和延迟（Lag）。

# 查看所有消费组
kafka-consumer-groups.sh --bootstrap-server localhost:9092 --list

# 查看某个消费组的详细信息（包括每个分区的偏移量和延迟）
kafka-consumer-groups.sh --bootstrap-server localhost:9092 \
  --group my-consumer-group \
  --describe

--describe 的输出中，CURRENT-OFFSET 表示当前消费到的位置，LOG-END-OFFSET 表示 Topic 的最新消息位置，LAG 就是两者的差值。如果 LAG 持续增大，说明消费者处理速度跟不上生产速度。

字段	含义	正常范围
CURRENT-OFFSET	当前消费到的偏移量	持续增长
LOG-END-OFFSET	Topic 的最新消息偏移量	持续增长
LAG	消费延迟（LOG-END-OFFSET - CURRENT-OFFSET）	接近 0 或稳定在较小值

3.6 本章知识体系：一张图看懂命令行操作

下面这张图把本章的核心操作和它们之间的关系梳理了一下。你一看就明白。

这张图里，Kafka 集群是核心，所有操作都围绕它展开。创建 Topic 和查看 Topic 列表是前置操作，生产消息和消费消息是核心流程，查看消费组状态则是运维监控的关键。你按这个顺序操作，基本不会乱。

3.7 避坑指南：我这些年踩过的命令行坑

最后，分享几个我实际项目中遇到的坑，希望能帮你少走弯路。

• 连接地址写错：--bootstrap-server 的端口是 9092，不是 2181。我见过有人把 Zookeeper 的端口写进来，结果命令一直报错。
• 副本因子超过 Broker 数量：如果集群只有 3 台 Broker，副本因子不能设为 4，否则创建 Topic 时会报 Replication factor: 4 larger than available brokers: 3。
• 消费者不加 --from-beginning：默认只消费新消息，如果你需要看历史数据，一定要加这个参数。
• 消费组名称写错：查看消费组状态时，组名必须完全匹配，大小写敏感。我建议你复制粘贴，别手敲。