使用 Docker Compose 快速搭建 Kafka + AKHQ

一、整体架构说明

本方案包含两个服务：

• Kafka：使用官方 apache/kafka:latest 镜像，采用 KRaft（无 ZooKeeper）模式
• AKHQ：一个轻量级的 Kafka Web 管理界面

架构示意：

+------------+        +--------+
|   Browser  | -----> |  AKHQ  |
+------------+        +--------+
                              |
                              v
                         +----------+
                         |  Kafka   |
                         +----------+

---

二、Docker Compose 配置

完整的 docker-compose.yml 如下：

services:
  kafka:
    image: apache/kafka:latest
    container_name: kafka
    ports:
      - "9092:9092"
      - "9093:9093"
    environment:
      KAFKA_NODE_ID: 1
      KAFKA_PROCESS_ROLES: broker,controller
      KAFKA_LISTENERS: PLAINTEXT://0.0.0.0:9092,CONTROLLER://0.0.0.0:9093
      KAFKA_ADVERTISED_LISTENERS: PLAINTEXT://10.160.160.116:9092
      KAFKA_CONTROLLER_LISTENER_NAMES: CONTROLLER
      KAFKA_CONTROLLER_QUORUM_VOTERS: 1@kafka:9093
      KAFKA_LOG_DIRS: /var/lib/kafka/data
    volumes:
      - kafka-data:/var/lib/kafka/data

  akhq:
    image: tchiotludo/akhq
    container_name: akhq
    ports:
      - "9000:8080"
    environment:
      AKHQ_CONFIGURATION: |
        akhq:
          connections:
            kafka:
              properties:
                bootstrap.servers: "10.160.160.116:9092"
    depends_on:
      - kafka

volumes:
  kafka-data:

---

三、Kafka 配置详解（KRaft 模式）

1. 为什么使用 KRaft

Kafka 从 2.8+ 开始引入 KRaft，并在新版本中逐步替代 ZooKeeper，优势包括：

• 架构更简单
• 运维成本更低
• 启动速度更快

本示例中 Kafka 同时承担：

• Broker（消息存储与读写）
• Controller（元数据管理）

KAFKA_PROCESS_ROLES: broker,controller

---

2. 端口说明

端口	说明
9092	Kafka 客户端访问端口
9093	KRaft Controller 通信端口

---

3. Listener 与 Advertised Listener

KAFKA_LISTENERS: PLAINTEXT://0.0.0.0:9092,CONTROLLER://0.0.0.0:9093
KAFKA_ADVERTISED_LISTENERS: PLAINTEXT://10.160.160.116:9092

• KAFKA_LISTENERS：Kafka 在容器内监听的地址
• KAFKA_ADVERTISED_LISTENERS：对外暴露给客户端的访问地址

⚠️ 注意：

• 10.160.160.116 必须是 宿主机或可被客户端访问的 IP

• 如果配置错误，会导致：

  • AKHQ 能连上，但生产者/消费者无法通信

---

4. Controller 选举配置

KAFKA_CONTROLLER_LISTENER_NAMES: CONTROLLER
KAFKA_CONTROLLER_QUORUM_VOTERS: 1@kafka:9093

• 单节点模式下：

  • node.id = 1
  • Controller 通过 kafka:9093 进行通信

---

5. 数据持久化

volumes:
  - kafka-data:/var/lib/kafka/data

• 使用 Docker Volume 保存 Kafka 日志
• 容器重启后数据不会丢失

---

四、AKHQ 配置说明

AKHQ 是一个非常好用的 Kafka Web UI，支持：

• Topic 管理
• Consumer Group 查看
• 消息浏览与搜索
• ACL / Schema Registry（可选）

1. 访问地址

http://localhost:9000

---

2. Kafka 连接配置

AKHQ_CONFIGURATION: |
  akhq:
    connections:
      kafka:
        properties:
          bootstrap.servers: "10.160.160.116:9092"

• 这里的 bootstrap.servers 必须与 Kafka 对外地址一致
• AKHQ 会使用该地址创建 Admin / Consumer / Producer 客户端

---

五、启动与验证

1. 启动服务

docker compose up -d

2. 查看容器状态

docker ps

3. 访问 AKHQ

浏览器打开：

http://localhost:9000

1. 卸载服务

docker compose down 或 docker compose down -v(同时删除Kafka 数据)

若能看到 Kafka 集群信息，说明配置成功 ✅

---

六、常见问题

1. 客户端连不上 Kafka

90% 的问题来自：

• KAFKA_ADVERTISED_LISTENERS 配置错误
• IP 不可达（容器 / 宿主机 / 局域网）

建议：

• 本机访问：localhost
• 局域网访问：宿主机内网 IP
• 云服务器：公网 IP

---

2. 是否适合生产环境？

❌ 不建议直接用于生产，原因：

• 单节点 Kafka
• 无认证（PLAINTEXT）
• 无监控、无备份

但非常适合：

✅ 学习
✅ 开发调试
✅ POC 验证

---

七、总结

通过 Docker Compose：

• 几分钟即可启动 Kafka（KRaft 模式）
• 搭配 AKHQ，Kafka 运维与调试体验大幅提升

---