Kafka 本地开发环境 + 可视化 UI 快速搭建与排坑记录

本地搭建 Kafka + UI 开发环境遇坑总结

适合初学者、小型开发项目、需要使用 Kafka + UI 进行消息流调试的各类场景。本文记录了我在使用 Docker Compose 本地搭建 Kafka + Redpanda UI 开发环境过程中遇到的典型坑与完整解决方案，适合所有需要快速上手 Kafka 可视化管理与测试的开发者。

一、为什么要搭建 Kafka + UI

在开发中，Kafka 通常被用作消息队列、事件总线、静态分布式处理等场景，但相比 RabbitMQ 等开箱即用工具，Kafka 一般需要配合下列环境操作：

配合 Zookeeper
需要自己创建 topic
没有 UI 不方便调试
配置错误后报错不明确

因此，我们定义一套简洁版 Kafka + Redpanda Console + Mongo + CLI 的本地开发环境，实现可视化、可测试、可扩展。

二、使用的镜像 & 环境

Docker Desktop + docker-compose + 以下镜像：

Kafka Broker: confluentinc/cp-kafka:7.5.0
Zookeeper: confluentinc/cp-zookeeper:7.5.0
Kafka UI: docker.io/redpandadata/console:latest
Mongo: mongo:6.0
Kafka CLI: redpandadata/redpanda:v23.3.9（用于 rpk produce)

配合版本约定：Docker 20+ / docker-compose v2+ / Windows 10+ / Linux / Mac

三、docker-compose.yml 完整配置

所有镜像会在首次运行 docker compose up -d 时自动拉取，无需手动下载。

在包含 docker-compose.yml 的目录中执行该命令即可启动服务。

yaml 复制代码

docker-compose.yml:

version: '3.8'
services:

  zookeeper:
    image: confluentinc/cp-zookeeper:7.5.0
    environment:
      ZOOKEEPER_CLIENT_PORT: 2181
      ZOOKEEPER_TICK_TIME: 2000

  kafka:
    image: confluentinc/cp-kafka:7.5.0
    depends_on:
      - zookeeper
    ports:
      - "9092:9092"
    environment:
      KAFKA_BROKER_ID: 1
      KAFKA_ZOOKEEPER_CONNECT: zookeeper:2181
      KAFKA_LISTENER_SECURITY_PROTOCOL_MAP: PLAINTEXT:PLAINTEXT
      KAFKA_ADVERTISED_LISTENERS: PLAINTEXT://kafka:9092
      KAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR: 1
  
  kafka-ui:
    image: docker.io/redpandadata/console:latest
    ports:
      - "8081:8080"
    environment:
      - KAFKA_BROKERS=kafka:9092

  mongo:
    image: mongo:6.0
    container_name: mongo
    ports:
      - "27017:27017"
    volumes:
      - mongo_data:/data/db

volumes:
  mongo_data:

四、遇到的坑 & 错误

1. 混淆了 Redpanda Console 的商业版与社区版

原因： 搜索 Redpanda Console 时，第一结果通常指向商业试用版本（例如 quickstart.tar.gz）

解决： 切换为社区版镜像: docker.io/redpandadata/console:latest

原因： 前端 JS 尝试连接后端 /api/auth，后端未启动或未对外启动

解决： 删除缓存，重新启动。使用 Incognito 方式访问或 DevTools 重缓存。

3. Kafka UI 无法连接 kafka，报 [::1]:9092

原因： UI 内部连接 localhost，应连接 kafka 容器名

解决： KAFKA_BROKERS=kafka:9092 + ADVERTISED_LISTENERS=PLAINTEXT://kafka:9092

4. the input device is not a TTY

原因： Git Bash / MinTTY 不支持 TTY

解决： 使用 PowerShell / CMD ，或前缀 winpty

五、如何测试发送 Kafka 消息

🧵 创建 Topic（通过 Redpanda Console UI）

打开浏览器访问：http://localhost:8081
左侧点击 Topics
点击右上角的 + Create topic 按钮（或 Create Topic）
输入 Topic 名称，例如：test-topic
分区数和副本数使用默认值即可，点击 Create

创建完成后，你可以在 Topic 列表中看到 test-topic，点击进入后可：

查看基本信息
查看消息列表
甚至设置保留策略、分区详情等

📝 注意：你必须先创建 topic，Kafka 才能正确地接受发送的消息，否则会提示 Unknown topic or partition 错误。

🛠 使用 CLI 工具发送测试消息

使用 Kafka 自带的 CLI 工具 kafka-console-producer 即可满足消息发送需求(在terminal中运行命令)：

shell 复制代码

# 进入 kafka 容器
> docker exec -it docker-dev-env-kafka-1 bash

# 执行生产者命令
> kafka-console-producer --bootstrap-server kafka:9092 --topic test-topic

# 输入内容并回车
Hello from CLI

# 使用 Ctrl + C 退出

然后即可在 Redpanda Console UI 中查看消息。

Redpanda Console UI 查看

打开 http://localhost:8081
点击 Topics 进入 test-topic
切换到 Messages
可看到上面 CLI 发送的消息

六、总结 & 可备份的开发环境

模块	状态	备注
Kafka Broker	✅ 已启动	基础服务
Redpanda Console UI	✅ 可进入，无需登录	管理与可视化
CLI Producer	✅ 可用	本地测试生产消息
Topic 管理	✅ 可创建、查看消息	可通过 UI 完成
MongoDB	🟡 可选	用于配套数据库需求
UI 问题处理	✅ 全部解决	各种报错已排查清楚

如果本文对你有帮助，欢迎点赞、收藏、关注支持，

也欢迎在评论区交流你的使用体验或问题！