本地快速上手 Kafka：用 Docker 5 分钟跑通生产消费链路

Apache Kafka 是当下最流行的消息中间件之一，但初学者常被它的依赖（如 ZooKeeper）、配置和网络问题劝退。其实，在本地开发环境中，借助 Docker Compose，我们可以在几分钟内搭建一个可运行的 Kafka 集群，并亲手体验消息的发送与接收。

本文将以最简洁的方式，带你用 Docker 跑通 Kafka 的经典 ZooKeeper 模式（兼容 Kafka 3.0 以下所有版本），并完成一次完整的“生产者 → 消费者”测试。

💡 提示：虽然 Kafka 3.3+ 已支持去 ZooKeeper 的 KRaft 模式，但对新手而言，ZooKeeper 模式文档更全、社区支持更好。我们先掌握基础，再进阶。

第一步：准备 docker-compose.yml

在你的工作目录下新建一个 docker-compose.yml 文件，内容如下：

version: '3'
services:
  zookeeper:
    image: confluentinc/cp-zookeeper:7.4.0
    container_name: zookeeper
    environment:
      ZOOKEEPER_CLIENT_PORT: 2181
    ports:
      - "2181:2181"

  kafka:
    image: confluentinc/cp-kafka:7.4.0
    container_name: kafka
    depends_on:
      - zookeeper
    ports:
      - "9092:9092"
    environment:
      KAFKA_BROKER_ID: 1
      KAFKA_ZOOKEEPER_CONNECT: zookeeper:2181
      KAFKA_ADVERTISED_LISTENERS: PLAINTEXT://localhost:9092
      KAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR: 1

配置说明：

使用 Confluent 官方镜像（生产级、文档完善）。
KAFKA_ADVERTISED_LISTENERS 设为 localhost:9092，确保本机应用能正常连接。
单节点部署，replication-factor=1，完全适用于开发测试。

第二步：启动服务

在 docker-compose.yml 所在目录执行：

1	docker-compose up -d

稍等几秒，Kafka 和 ZooKeeper 就会启动。你可以用以下命令查看日志确认状态：

1	docker-compose logs -f kafka

看到类似 KafkaServer started 的日志，说明服务已就绪。

第三步：创建测试 Topic

进入 Kafka 容器：

1	docker exec -it kafka bash

在容器内创建一个名为 test-topic 的 Topic：

kafka-topics --create \
  --bootstrap-server localhost:9092 \
  --replication-factor 1 \
  --partitions 1 \
  --topic test-topic

验证是否创建成功：

1	kafka-topics --list --bootstrap-server localhost:9092

你应该能看到 test-topic 出现在列表中。

第四步：启动消费者

仍在 Kafka 容器中，运行消费者命令：

kafka-console-consumer \
  --bootstrap-server localhost:9092 \
  --topic test-topic \
  --from-beginning

此时终端会阻塞等待消息。别急，我们另开一个终端窗口来发送消息。

🔔 注意：--from-beginning 表示从最早的消息开始消费。如果不加这个参数，只会收到新消息。

第五步：启动生产者

打开新的终端，再次进入 Kafka 容器：

1	docker exec -it kafka bash

启动生产者：

1
2
3

kafka-console-producer \
  --bootstrap-server localhost:9092 \
  --topic test-topic

现在，你可以直接输入消息，每按一次回车，就发送一条：

1
2
3

Hello Kafka!
This is a test from my local machine.
Kafka is awesome!

验证结果

切换回消费者终端，你会看到刚刚输入的消息逐行打印出来：

1
2
3

Hello Kafka!
This is a test from my local machine.
Kafka is awesome!

✅ 恭喜！你已经成功跑通 Kafka 的生产-消费链路。

清理环境（可选）

测试完成后，可以一键清理：

1	docker-compose down

如果你想保留数据（比如下次启动还能看到历史消息），可以在 docker-compose.yml 中为 Kafka 和 ZooKeeper 添加 volume 挂载。

常见问题 & 小贴士

本地应用连不上 Kafka？
请务必检查 KAFKA_ADVERTISED_LISTENERS 是否设为 localhost:9092。如果设成 kafka:9092，容器外就无法解析。
消息发了但消费者收不到？
确认消费者是否加了 --from-beginning；或者确保生产者和消费者使用的是同一个 topic 名称。
想用 Python 写客户端？
推荐 confluent-kafka（性能好）或 kafka-python（上手快）。连接地址就是 localhost:9092。
想尝试无 ZooKeeper 的 KRaft 模式？
我们后续会单独写一篇，支持 Kafka 3.3+ 的纯 Docker KRaft 部署方案。