kafka-4.1.1-deploy-v2

国内服务器3周前发布 beixibaobao
18 0 0

Apache Kafka 4.1.1 部署全攻略：二进制 + Docker（含持久化挂载、Kafka UI、CLI PATH

本文基于 Kafka 4.1.1，覆盖二进制部署与 Docker 容器部署，并补充：

  • 容器数据持久化挂载
  • Kafka Web UI（Kafka-UI / Kafbat UI）
  • kafka-topics.sh 等 CLI 无法直接使用时的 PATH 处理

目录：

  • 1. 环境 & 版本说明
  • 2. 二进制方式部署 Kafka 4.1.1（单机 KRaft）

    • 2.1 下载与解压
    • 2.2 配置 KRaft 单机模式
    • 2.3 初始化存储目录 & clusterId
    • 2.4 以 systemd 管理 Kafka
    • 2.5 为 CLI 添加 PATH（kafka-topics.sh 等）
  • 3. Docker 容器部署 Kafka 4.1.1（带持久化 & PATH）

    • 3.1 docker run 快速体验
    • 3.2 docker-compose：单机 Kafka + 数据持久化挂载
    • 3.3 容器内使用 kafka-topics.sh 的几种方式
  • 4. 为 Kafka 增加 Web UI（Kafka UI / Kafbat UI）

    • 4.1 在 docker-compose 中集成 kafka-ui
    • 4.2 kafka-ui 常用配置说明
  • 5. 常见问题 FAQ
  • 6. 小结

1. 环境 & 版本说明

1.1 版本选择

  • Kafka：4.1.1
  • 模式：KRaft（不再依赖 ZooKeeper）
  • JDK：17+
  • 操作系统：Linux（CentOS / Rocky / Ubuntu 等均可）
  • Docker / docker-compose（可选）：用于容器部署

1.2 基本约定

  • Kafka 安装目录（传统二进制）：/opt/kafka
  • 数据目录（二进制）：/data/kafka-logs
  • Kafka 容器镜像：apache/kafka:4.1.1
  • 容器内 Kafka 脚本目录：/opt/kafka/bin（官方镜像默认脚本路径）
  • 默认监听端口：9092

2. 二进制方式部署 Kafka 4.1.1（单机 KRaft）

场景：传统虚机 / 物理机上部署一套单机 Kafka（KRaft 模式），适合测试环境、小型项目或作为学习环境。

2.1 下载与解压

# 1）创建安装目录
sudo mkdir -p /opt/kafka
sudo mkdir -p /data/kafka-logs
sudo chown -R $USER:$USER /opt/kafka /data/kafka-logs
# 2）下载 Kafka 4.1.1 二进制包（示例命令，实际可按官网地址替换）
cd /tmp
wget https://downloads.apache.org/kafka/4.1.1/kafka_2.13-4.1.1.tgz
# 3）解压到 /opt/kafka
tar -xzf kafka_2.13-4.1.1.tgz
mv kafka_2.13-4.1.1 /opt/kafka

2.2 配置 KRaft 单机模式

Kafka 4.1.1 默认推荐使用 KRaft 模式，单机配置只需要让一个节点同时承担 controller 和 broker 角色。

编辑 config/kraft/server.properties：

cd /opt/kafka
vim config/kraft/server.properties

核心配置示例：

############################# 基础参数 #############################
# 当前节点唯一 ID
node.id=1
# 节点角色：既是 controller 又是 broker
process.roles=broker,controller
# Controller 监听名
controller.listener.names=CONTROLLER
# Controller 集群成员（单机就是自己）
controller.quorum.voters=1@localhost:9093
############################# 监听配置 #############################
# Kafka 对外监听（客户端连接用）
listeners=PLAINTEXT://0.0.0.0:9092,CONTROLLER://0.0.0.0:9093
# 客户端访问时看到的地址（单机用本机 IP 或域名）
advertised.listeners=PLAINTEXT://你的IP或域名:9092
listener.security.protocol.map=CONTROLLER:PLAINTEXT,PLAINTEXT:PLAINTEXT
inter.broker.listener.name=PLAINTEXT
############################# 数据与日志 #############################
# Kafka 数据目录（建议单独挂盘）
log.dirs=/data/kafka-logs
############################# 其他内置 Topic 副本数 #############################
offsets.topic.replication.factor=1
transaction.state.log.replication.factor=1
transaction.state.log.min.isr=1

生产环境建议使用多节点 KRaft 集群，并将 replication.factor 设置为 3 及以上。

2.3 初始化存储目录 & clusterId

在 KRaft 模式下，需要先生成一个 clusterId，并格式化日志目录：

cd /opt/kafka
# 1）生成 clusterId（只执行一次）
./bin/kafka-storage.sh random-uuid
# 假设输出：abc123-xxxx-yyyy-zzzz
# 2）使用生成的 clusterId 格式化存储目录
./bin/kafka-storage.sh format       -t abc123-xxxx-yyyy-zzzz       -c config/kraft/server.properties

2.4 以 systemd 管理 Kafka

新建 systemd 服务：/etc/systemd/system/kafka.service：

[Unit]
Description=Apache Kafka 4.1.1 (KRaft)
After=network.target
[Service]
Type=simple
User=kafka
Group=kafka
Environment="KAFKA_HOME=/opt/kafka"
Environment="PATH=/opt/kafka/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin"
WorkingDirectory=/opt/kafka
ExecStart=/opt/kafka/bin/kafka-server-start.sh /opt/kafka/config/kraft/server.properties
ExecStop=/opt/kafka/bin/kafka-server-stop.sh
Restart=on-failure
RestartSec=5
[Install]
WantedBy=multi-user.target

启动与查看：

sudo systemctl daemon-reload
sudo systemctl enable kafka
sudo systemctl start kafka
sudo systemctl status kafka

2.5 为 CLI 添加 PATH（kafka-topics.sh 等）

如果你希望在任意目录直接执行 kafka-topics.sh、kafka-console-consumer.sh 等命令，推荐在用户环境中配置 PATH：

# 1）配置环境变量
echo 'export KAFKA_HOME=/opt/kafka' >> ~/.bashrc
echo 'export PATH=$KAFKA_HOME/bin:$PATH' >> ~/.bashrc
# 2）重新加载配置
source ~/.bashrc

之后即可直接在终端使用：

kafka-topics.sh --bootstrap-server localhost:9092 --list
kafka-topics.sh --bootstrap-server localhost:9092 --create       --topic demo-topic       --partitions 3       --replication-factor 1

这样既解决了二进制部署环境下 CLI 不在 PATH 的问题，也为后续脚本/自动化运维提供便利。

3. Docker 容器部署 Kafka 4.1.1（带持久化 & PATH）

场景：偏向容器化 & Dev / Test 环境，使用官方 apache/kafka:4.1.1 镜像。

3.1 docker run 快速体验

官方文档中给出的最小示例：

docker run -d --name kafka -p 9092:9092 apache/kafka:4.1.1

容器启动后，Kafka 会默认使用 KRaft 模式。由于脚本位于 /opt/kafka/bin，容器内需要使用绝对路径调用：

# 查看 clusterId
docker exec -it kafka /opt/kafka/bin/kafka-cluster.sh cluster-id --bootstrap-server localhost:9092
# 创建测试 Topic
docker exec -it kafka /opt/kafka/bin/kafka-topics.sh       --bootstrap-server localhost:9092       --create --topic demo --partitions 3 --replication-factor 1
# 生产消息
docker exec -it kafka /opt/kafka/bin/kafka-console-producer.sh       --bootstrap-server localhost:9092       --topic demo
# 消费消息
docker exec -it kafka /opt/kafka/bin/kafka-console-consumer.sh       --bootstrap-server localhost:9092       --topic demo --from-beginning

直接在容器内输入 kafka-topics.sh 会报 command not found，原因就是 /opt/kafka/bin 没有加到 PATH。下面会专门处理。

3.2 docker-compose：单机 Kafka + 数据持久化挂载

测试环境下，推荐使用 docker-compose 统一管理 Kafka + UI。
首先，新建目录：

mkdir -p ~/kafka-single
cd ~/kafka-single
mkdir -p data

新建 docker-compose.yml：

version: "3.9"
services:
  kafka:
    image: apache/kafka:4.1.1
    container_name: kafka
    ports:
      - "9092:9092"
    environment:
      # 让容器内可以直接执行 kafka-topics.sh 等命令
      - PATH=/opt/kafka/bin:$PATH
      # （可选）自定义监听配置，简单场景下用默认即可
      # - KAFKA_LISTENERS=PLAINTEXT://0.0.0.0:9092
      # - KAFKA_ADVERTISED_LISTENERS=PLAINTEXT://localhost:9092
    volumes:
      # 将 Kafka 数据目录持久化到宿主机
      - ./data:/var/lib/kafka/data
    restart: unless-stopped

关键点说明：

  • PATH=/opt/kafka/bin:$PATH：

    • 解决你提到的 容器内无法直接使用 kafka-topics.sh 问题；
    • 进入容器后可以直接 kafka-topics.sh --help，无需写绝对路径。
  • ./data:/var/lib/kafka/data：

    • 将 Kafka 的数据目录挂载到宿主机；
    • 即使删除容器，./data 中的 Topic/数据仍会保留；
    • /var/lib/kafka/data 是官方镜像默认 log.dirs 的挂载位置之一。

启动：

docker compose up -d
docker compose ps

3.3 容器内使用 kafka-topics.sh 的几种方式

Kafka 官方镜像的 CLI 在 /opt/kafka/bin 下，你可以按照自己的习惯选择不同方式使用。

方式 1：docker exec + 绝对路径（最标准）

docker exec -it kafka /opt/kafka/bin/kafka-topics.sh       --bootstrap-server localhost:9092 --list

方式 2：进入容器后设置 PATH（一次性）

docker exec -it kafka /bin/sh
# 容器内执行
export PATH=/opt/kafka/bin:$PATH
kafka-topics.sh --bootstrap-server localhost:9092 --list

方式 3：在 docker-compose 中直接配置 PATH（推荐）

上面的 docker-compose.yml 已经添加：

environment:
  - PATH=/opt/kafka/bin:$PATH

这样：

docker exec -it kafka /bin/sh
kafka-topics.sh --bootstrap-server localhost:9092 --list

就能直接用，适合你在容器内经常做调试和运维。

4. 为 Kafka 增加 Web UI（Kafka UI / Kafbat UI）

Kafka 自带的 CLI 虽然强大，但很多时候你会希望有一个 Web UI 来：

  • 浏览 Topic / Partition / 消费组
  • 在线生产 / 消费测试消息
  • 查看 lag / offsets 等信息

比较常见的 UI 有：

  • Kafka UI / Kafbat UI（kafbat/kafka-ui，此前为 provectuslabs/kafka-ui）
  • Kafdrop
  • AKHQ

这里用官方文档中推荐的 Kafbat UI 为例。

4.1 在 docker-compose 中集成 kafka-ui

基于前文的 docker-compose.yml，加入一个 kafka-ui 服务：

version: "3.9"
services:
  kafka:
    image: apache/kafka:4.1.1
    container_name: kafka
    ports:
      - "9092:9092"
    environment:
      - PATH=/opt/kafka/bin:$PATH
    volumes:
      - ./data:/var/lib/kafka/data
    restart: unless-stopped
  kafka-ui:
    image: kafbat/kafka-ui:latest
    container_name: kafka-ui
    ports:
      - "8080:8080"
    environment:
      # 启用动态配置
      - DYNAMIC_CONFIG_ENABLED=true
      # 配置第 0 个集群
      - KAFKA_CLUSTERS_0_NAME=local
      - KAFKA_CLUSTERS_0_BOOTSTRAPSERVERS=kafka:9092
    depends_on:
      - kafka
    restart: unless-stopped

启动：

docker compose up -d

访问：

  • 浏览器打开：http://localhost:8080
  • 在界面中可以看到 local 集群，查看 Topic、消费组等信息。

4.2 kafka-ui 常用配置说明

上述环境变量含义简要说明：

  • DYNAMIC_CONFIG_ENABLED=true

    • 允许通过配置文件 / UI 动态添加集群。
  • KAFKA_CLUSTERS_0_NAME=local

    • 第 0 个集群的显示名称。
  • KAFKA_CLUSTERS_0_BOOTSTRAPSERVERS=kafka:9092

    • 与 Kafka 容器通信使用的地址，kafka 是 service 名（容器内部 DNS）。
    • 如果 UI 与 Kafka 不在同一 docker 网络，需要写实际 IP / 域名，例如 192.168.1.10:9092。

如需管理多个集群，可以继续增加：

environment:
  - DYNAMIC_CONFIG_ENABLED=true
  - KAFKA_CLUSTERS_0_NAME=local
  - KAFKA_CLUSTERS_0_BOOTSTRAPSERVERS=kafka:9092
  - KAFKA_CLUSTERS_1_NAME=prod
  - KAFKA_CLUSTERS_1_BOOTSTRAPSERVERS=prod-kafka-1:9092,prod-kafka-2:9092,prod-kafka-3:9092

5. 常见问题 FAQ

Q1：容器内执行 kafka-topics.sh 提示 command not found？

原因：

  • 官方 apache/kafka 镜像把脚本放在 /opt/kafka/bin，但默认 PATH 没有包含这个目录。

解决方式：三选一（推荐第 3 种一次性配置好）：

  1. 每次 docker exec 使用绝对路径：
    docker exec -it kafka /opt/kafka/bin/kafka-topics.sh ...
  2. 进入容器后手动 export PATH=/opt/kafka/bin:$PATH
  3. 在 docker-compose.yml 中配置：
    environment: ["PATH=/opt/kafka/bin:$PATH"]

Q2：删除容器后，Topic / 数据丢失？

原因：

  • 没有把 Kafka 的数据目录挂载到宿主机，容器删除时文件系统同时被销毁。

解决方式：

  • 在 compose 中挂载：

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

  • 删除容器后重新创建，./data 中的数据仍会被 Kafka 复用。

Q3：Kafka UI 显示集群 Offline / 无法连接？

核查步骤：

  1. kafka 服务是否正常运行：docker compose ps；
  2. kafka-ui 的 KAFKA_CLUSTERS_0_BOOTSTRAPSERVERS 是否写对：

    • docker 内部用 kafka:9092；
    • 外部 IP / 域名环境用 节点IP:9092；
  3. Kafka 的 listeners / advertised.listeners 是否配置正确（尤其是在跨主机访问时）；
  4. 如启用了 TLS/SASL，需要在 kafka-ui 中补齐对应的认证配置。

6. 小结

本文在原有 Kafka 4.1.1 部署文档的基础上，补充和优化了三个你在实际使用中非常关键的点：

  1. CLI PATH 处理：

    • 明确了 /opt/kafka/bin 是官方镜像脚本目录；
    • 给出了二进制环境和容器环境下统一的 PATH 配置方案。

  2. 数据持久化挂载：

    • 指定了 /var/lib/kafka/data 为容器内数据目录挂载点；
    • 避免删除容器后 Topic / 消息直接蒸发。

  3. Kafka Web UI 集成：

    • 通过 kafbat/kafka-ui 一键接入 Kafka；
    • 提供了基础的环境变量配置，方便你在测试 / 开发环境快速联调。

你可以直接将本文保存为 kafka-4.1.1-deploy.md 上传到 CSDN / 个人博客发布，如果后续你还要扩展“多节点 KRaft 集群”、“K8s/Helm 部署”，也可以与我之前给你的 kafka-4.1.1-cluster-k8s-helm.md 组成一个 Kafka 系列教程。

© 版权声明
文章版权归作者所有，未经允许请勿转载。

相关文章

标签云