Apache Kafka Docker 镜像使用指南

概述

本文详细介绍了如何使用 Docker 容器部署和运行 Apache Kafka 消息队列系统。Kafka 作为分布式流处理平台，通过 Docker 容器化部署可以大大简化环境配置和集群管理过程。

环境准备

Docker 版本要求

必须使用 Docker 20.10.4 或更高版本。早期版本在创建容器路径（如 /opt/kafka/config）时可能无法正确设置目录权限，导致容器启动失败并出现如下错误：

===> User
uid=1000(appuser) gid=1000(appuser) groups=1000(appuser)
===> Setting default values of environment variables if not already set.
===> Configuring …
Running in KRaft mode…
/opt/kafka/config/ file not writable

三种配置方式

1. 默认配置启动

如果不提供任何用户配置（文件或环境变量），容器将使用 Kafka 压缩包中自带的默认 KRaft 配置，以单节点组合模式运行。

2. 配置文件方式

通过挂载本地配置文件目录到容器中，可以完全自定义 Kafka 配置：

docker run --volume /path/to/property/folder:/mnt/shared/config -p 9092:9092 apache/kafka:latest

3. 环境变量方式

通过环境变量配置 Kafka 时，必须设置启动 KRaft 节点所需的所有属性。建议使用 Docker Compose 来管理这些环境变量。

环境变量命名规则

• 将 . 替换为 _
• 将 _ 替换为 __（双下划线）
• 将 - 替换为 ___（三下划线）
• 添加 KAFKA_ 前缀

示例：

• abc.def → KAFKA_ABC_DEF
• abc-def → KAFKA_ABC___DEF
• abc_def → KAFKA_ABC__DEF

Log4j 配置

• 通过环境变量配置的 log4j 属性会追加到默认属性文件中
• 使用 KAFKA_LOG4J_ROOT_LOGLEVEL 设置 log4j.rootLogger
• 使用 KAFKA_LOG4J_LOGGERS 添加多个 logger（逗号分隔）

SSL 安全模式配置

推荐通过挂载密钥文件到 /etc/kafka/secrets 目录，并通过以下环境变量配置：

• KAFKA_SSL_KEYSTORE_FILENAME
• KAFKA_SSL_KEYSTORE_CREDENTIALS
• KAFKA_SSL_KEY_CREDENTIALS
• KAFKA_SSL_TRUSTSTORE_FILENAME
• KAFKA_SSL_TRUSTSTORE_CREDENTIALS

注意：必须通过环境变量提供 KAFKA_ADVERTISED_LISTENERS 并包含 SSL 监听器。

实战示例

单节点部署

明文模式

最简单的配置方式，纯环境变量配置：

IMAGE=apache/kafka:latest docker compose -f docker/examples/docker-compose-files/single-node/plaintext/docker-compose.yml up

生产消息：

bin/kafka-console-producer.sh --topic test --bootstrap-server localhost:9092

SSL 模式

使用环境变量配置 SSL：

IMAGE=apache/kafka:latest docker compose -f docker/examples/docker-compose-files/single-node/ssl/docker-compose.yml up

生产消息（需 Java 17+）：

bin/kafka-console-producer.sh --topic test --bootstrap-server localhost:9093 --producer.config ./docker/examples/fixtures/client-secrets/client-ssl.properties

多节点集群

组合模式（Combined Mode）

每个 broker 需要向宿主机暴露唯一端口：

IMAGE=apache/kafka:latest docker compose -f docker/examples/docker-compose-files/cluster/combined/plaintext/docker-compose.yml up

隔离模式（Isolated Mode）

控制器和 broker 分开配置：

IMAGE=apache/kafka:latest docker compose -f docker/examples/docker-compose-files/cluster/isolated/plaintext/docker-compose.yml up

最佳实践

1. 生产环境应为每个 broker 配置独立的 SSL 证书
2. 集群部署时，确保为每个 broker 配置唯一的监听端口
3. 隔离模式下，建议设置 broker 依赖控制器
4. 测试时一次只运行一个示例，避免端口冲突

通过本文介绍的 Docker 部署方式，开发者可以快速搭建 Kafka 开发测试环境，生产环境也可参考这些配置进行适当调整。