kafka-go 多版本测试环境实战:基于 Bitnami Kafka 的 docker-compose 集群配置指南

原创2026-10-13 19:35:261,624 阅读
文章标签:消息队列后端数据工程

kafka-go 多版本测试环境实战:基于 Bitnami Kafka 的 docker-compose 集群配置指南

本文以 kafka-go 仓库中 docker_compose_versions/README.md 为核心,完整讲解如何为指定 Bitnami Kafka 版本编写可用的 docker-compose 文件、如何通过环境变量对齐 kafka-go 测试所需的 server.properties 与 SASL 配置,并给出启动集群、运行测试的标准命令及各版本在 CI(CircleCI)中遇到的典型问题。读完本文,你将掌握"按 Kafka 版本维护 docker-compose"的完整方法论,能够为任意 Bitnami Kafka 版本搭建出可跑通 kafka-go 全部测试用例的本地或 CI 集群。

一、为什么 kafka-go 要"按版本"维护 docker-compose

kafka-go 是使用 Go 编写的 Kafka 客户端库,其测试用例覆盖了大量 Kafka 协议特性,因此 CI 需要真实运行多种 Kafka 版本(0.10、0.11、1.x、2.x、3.x)的 broker。仓库中 docker_compose_versions/ 目录专门用于存放"针对特定 Bitnami Kafka 版本"的 docker-compose 文件:

之所以无法用一份 docker-compose 通吃所有版本,是因为 Bitnami Kafka 镜像在不同版本上的环境变量约定不同、暴露的配置项不同,甚至个别版本存在无法通过环境变量覆盖的缺陷。kafka-go 的测试对集群有硬性要求:sasl.enabled.mechanisms 必须为 PLAIN,SCRAM-SHA-256,SCRAM-SHA-512,同时需要正确的 JAAS 配置。配置不对,集群要么起不来,要么以不符合测试预期的配置启动,直接导致测试失败。

二、第一步:定位目标版本的 Bitnami Kafka 镜像

为特定 Kafka 版本编写 docker-compose,第一件事是找到对应的镜像。原文档给出的完整步骤如下:

  1. 打开 Docker Hub 的 Bitnami Kafka tags 页面,按 NEWEST 排序,定位偏好的镜像版本(例如 2.7.0)。
  2. 阅读 bitnami/containers 仓库中 bitnami/kafka 的 README,重点查看 Notable Changes(重大变更)章节,了解该版本的环境配置约定是否有变化。
  3. 如需理解某个版本的底层搭建方式,进入 bitnami/containers 仓库的 kafka 提交历史(commit history),找到对应 Kafka release 的提交。
  4. 查看该提交下的 README.md、Dockerfile、entrypoint 以及各类初始化脚本,理解"环境变量 → server.properties 配置项"的映射约定;或者直接启动该 Kafka 镜像,在容器内查看映射结果。

关键原则:在 docker-compose 中必须遵循当前版本的环境变量约定。如果环境变量写错,Kafka 集群无法启动,或会以非预期配置启动。

从仓库实际文件可以看出镜像 tag 的选取规律:

docker-compose 文件 镜像
docker-compose-010.yml bitnami/kafka:0.10.2.1
docker-compose-011.yml bitnami/kafka:0.11.0-1-r1
docker-compose-231.yml bitnami/kafka:2.3.1-ol-7-r61
docker-compose-241.yml bitnami/kafka:2.4.1
docker-compose-260.yml bitnami/kafka:2.6.0
docker-compose-270.yml bitnami/kafka:2.7.0
docker-compose-361.yml bitnami/kafka:3.6.1

三、第二步:环境变量约定的分水岭——KAFKA_CFG_ 前缀

这是整个 docker-compose 编写中最重要的约定:自 Kafka 2.3 起,所有对应 server.properties 的 docker-compose 环境变量都以 KAFKA_CFG_<config_with_underscore> 开头,即配置名中的点号(.)替换为下划线(_),再冠以 KAFKA_CFG_ 前缀。

典型映射对照:

server.properties 配置 Kafka 2.3+ 环境变量 说明
broker.id KAFKA_CFG_BROKER_ID Broker 唯一 ID
delete.topic.enable KAFKA_CFG_DELETE_TOPIC_ENABLE 是否允许删除 topic
advertised.host.name KAFKA_CFG_ADVERTISED_HOST_NAME 对外公布的 host
advertised.port KAFKA_CFG_ADVERTISED_PORT 对外公布的端口
zookeeper.connect KAFKA_CFG_ZOOKEEPER_CONNECT Zookeeper 地址
auto.create.topics.enable KAFKA_CFG_AUTO_CREATE_TOPICS_ENABLE 是否自动创建 topic
message.max.bytes KAFKA_CFG_MESSAGE_MAX_BYTES 单条消息上限
listeners KAFKA_CFG_LISTENERS 监听器列表
advertised.listeners KAFKA_CFG_ADVERTISED_LISTENERS 对外公布的监听器列表
sasl.enabled.mechanisms KAFKA_CFG_SASL_ENABLED_MECHANISMS 启用的 SASL 机制
authorizer.class.name KAFKA_CFG_AUTHORIZER_CLASS_NAME ACL 授权器类
allow.everyone.if.no.acl.found KAFKA_CFG_ALLOW_EVERYONE_IF_NO_ACL_FOUND 无 ACL 时是否放行所有人

而在 Kafka 2.3 之前(如 0.10、0.11),Bitnami Kafka 使用不同的约定:环境变量直接以 KAFKA_ 开头,例如 KAFKA_BROKER_ID、KAFKA_ZOOKEEPER_CONNECT。对比仓库中两份文件即可直观看到差异:

  • docker-compose-010.yml 使用 KAFKA_BROKER_ID、KAFKA_DELETE_TOPIC_ENABLE、KAFKA_LISTENERS 等 KAFKA_ 前缀;
  • docker-compose-231.yml 全部改用 KAFKA_CFG_BROKER_ID、KAFKA_CFG_DELETE_TOPIC_ENABLE、KAFKA_CFG_LISTENERS 等 KAFKA_CFG_ 前缀。

同时需注意:旧版本的 Bitnami Kafka 约定不同,且通过 docker-compose 环境变量能暴露的 server.properties 配置项十分有限,这正是许多配置需要依赖自定义 entrypoint 追加写入的原因(详见第六节)。

四、第三步:对齐 kafka-go 测试集群的目标 server.properties

kafka-go 的全部测试用例若要成功,Kafka 集群必须生成如下 server.properties,并且通过 KAFKA_OPTS 挂载一份与之匹配的 kafka_jaas.conf(或旧版镜像中的 kafka_server_jaas.conf)。这是原文档给出的目标配置,逐项拆解如下:

advertised.host.name=localhost
advertised.listeners=PLAINTEXT://localhost:9092,SASL_PLAINTEXT://localhost:9093
advertised.port=9092
auto.create.topics.enable=true
broker.id=1
delete.topic.enable=true
group.initial.rebalance.delay.ms=0
listeners=PLAINTEXT://:9092,SASL_PLAINTEXT://:9093
log.dirs=/kafka/kafka-logs-1d5951569d78
log.retention.check.interval.ms=300000
log.retention.hours=168
log.segment.bytes=1073741824
message.max.bytes=200000000
num.io.threads=8
num.network.threads=3
num.partitions=1
num.recovery.threads.per.data.dir=1
offsets.topic.replication.factor=1
port=9092
sasl.enabled.mechanisms=PLAIN,SCRAM-SHA-256,SCRAM-SHA-512
socket.receive.buffer.bytes=102400
socket.request.max.bytes=104857600
socket.send.buffer.bytes=102400
transaction.state.log.min.isr=1
transaction.state.log.replication.factor=1
zookeeper.connect=zookeeper:2181
zookeeper.connection.timeout.ms=6000

各项配置的作用与取值含义:

  • 监听器与网络入口:listeners=PLAINTEXT://:9092,SASL_PLAINTEXT://:9093 同时开启明文与 SASL 两个监听端口;advertised.listeners 向客户端公布 localhost:9092 与 localhost:9093,advertised.host.name=localhost、advertised.port=9092 兼容旧版客户端协议;port=9092 为旧版 Kafka(如 0.10/0.11)所必需。
  • SASL 与 ACL:sasl.enabled.mechanisms=PLAIN,SCRAM-SHA-256,SCRAM-SHA-512 是本仓库测试的硬性要求(对应仓库 sasl/plain/plain.go 与 sasl/scram/scram.go 两种客户端机制的覆盖);KAFKA_CFG_AUTHORIZER_CLASS_NAME 启用 SimpleAclAuthorizer,配合 KAFKA_CFG_ALLOW_EVERYONE_IF_NO_ACL_FOUND=true 避免无 ACL 时拒绝所有客户端。
  • 主题与分区:auto.create.topics.enable=true 允许测试自动建 topic;num.partitions=1、offsets.topic.replication.factor=1、transaction.state.log.replication.factor=1、transaction.state.log.min.isr=1 都是为了让单 broker 集群能够正常运行事务与消费组。
  • 消息大小与线程:message.max.bytes=200000000(约 190 MB)保证大消息测试不触发 MessageSizeTooLarge;socket.request.max.bytes=104857600 与之匹配;num.network.threads=3、num.io.threads=8、num.recovery.threads.per.data.dir=1 为网络/IO 线程配置。
  • 日志保留:log.dirs 为数据目录,log.retention.hours=168(7 天)、log.retention.check.interval.ms=300000(5 分钟)、log.segment.bytes=1073741824(1 GB)为日志保留与分段参数。
  • 协调与连接:group.initial.rebalance.delay.ms=0 关闭消费组初始再平衡延迟,加快测试中的组创建与重平衡;zookeeper.connect=zookeeper:2181 指向 compose 中的 Zookeeper 服务;zookeeper.connection.timeout.ms=6000 为连接超时;socket.send.buffer.bytes / socket.receive.buffer.bytes=102400 为套接字缓冲区。

五、第四步:启动集群并运行测试

启动对应版本的 docker-compose

docker-compose -f ./docker_compose_versions/docker-compose-<kafka_version>.yml up -d

例如启动 2.3.1 集群:

docker-compose -f ./docker_compose_versions/docker-compose-231.yml up -d

运行 kafka-go 测试

go clean -cache; KAFKA_SKIP_NETTEST=1 KAFKA_VERSION=<a.b.c> go test -race -cover ./...;

例如针对 2.3.1:

go clean -cache; KAFKA_SKIP_NETTEST=1 KAFKA_VERSION=2.3.1 go test -race -cover ./...

这两个环境变量的作用在源码中有明确依据:

  • KAFKA_VERSION 在 testing/version.go 中被解析为 semver 结构,测试代码通过 KafkaIsAtLeast() 判断当前 broker 协议版本,从而决定是否执行某些版本相关的用例。例如 describegroups_test.go 和 reader_test.go 中都有 os.Getenv("KAFKA_VERSION") == "2.3.1" 的版本分支。
  • KAFKA_SKIP_NETTEST 在 conn_test.go 中被检查:设置后跳过一部分受 Kafka 后续版本行为变化影响的历史网络测试。仓库 README.md 也说明:如果针对 Kafka 2.3.1 或更高版本运行,导出 KAFKA_SKIP_NETTEST=1 会跳过这些测试。

使用 Makefile 快捷方式

仓库根目录的 Makefile 已封装好默认命令:

test:
	KAFKA_SKIP_NETTEST=1 \
	KAFKA_VERSION=2.3.1 \
	go test -race -cover ./...

docker:
	docker compose up -d
  • make docker:直接启动根目录 docker-compose.yml 定义的集群(默认 Bitnami Kafka 2.3.1);
  • make test:等价于 go clean -cache && KAFKA_SKIP_NETTEST=1 KAFKA_VERSION=2.3.1 go test -race -cover ./...。

根目录 docker-compose.yml 与 docker-compose-231.yml 内容几乎一致,可视为仓库 CI 默认使用的标准配置。

六、各版本踩坑实录(CircleCI 实战)

原文档记录了大量在 CircleCI 中实际观察到的版本问题,这些是编写 docker-compose 时最值得参考的经验。

6.1 Kafka v101 / v111 / v201 / v211 / v221:SCRAM 无法启用

kafka-go 全部测试要求集群的 sasl.enabled.mechanisms 为 PLAIN,SCRAM-SHA-256,SCRAM-SHA-512,但经观察,CircleCI 构建使用的 Kafka v101、v111、v201、v211、v221 对 SCRAM 支持存在问题:这些版本没有任何途径覆盖 sasl.enabled.mechanisms,集群最终只能以 PLAIN 机制启动。

社区/仓库曾尝试两种覆盖方式,均告失败:

  1. 修改 entrypoint:在 docker-compose 的 entrypoint 中先向 server.properties 追加 sasl.enabled.mechanisms 等配置,再执行原 entrypoint.sh。结果:Kafka 服务器启动后,server.properties 仍会被追加上 sasl.enabled.mechanisms 的默认值,集群最终仍不带 PLAIN,SCRAM-SHA-256,SCRAM-SHA-512 启动。
  2. 挂载 server.properties 卷:通过 docker-compose volume 挂载自定义 server.properties。结果同样失败,Kafka 启动后仍会被追加默认的 sasl.enabled.mechanisms。

结论(原文档 NOTE):

  • v101、v111、v201、v211、v221 没有对应的 docker-compose 文件,因为 kafka-go 测试用例必须要有 SCRAM 才能成功;
  • v222 没有 Bitnami Kafka 镜像,因此 v221 上的测试是在 v221 上完成的。

6.2 Kafka v231:kafka_jaas.conf 生成权限问题

在 Bitnami Kafka v2.3 中,KAFKA_CFG_ 前缀约定已生效,但它不会读取自定义填充的 kafka_jaas.conf。经过大量调试发现,原因是容器进程没有足够权限创建 kafka_jaas.conf。解决办法是在 docker-compose 中增加以下四个环境变量,让镜像自行生成 kafka_jaas.conf:

KAFKA_INTER_BROKER_USER: adminplain
KAFKA_INTER_BROKER_PASSWORD: admin-secret
KAFKA_BROKER_USER: adminplain
KAFKA_BROKER_PASSWORD: admin-secret
  • KAFKA_INTER_BROKER_USER / KAFKA_INTER_BROKER_PASSWORD:broker 间通信(inter-broker)使用的 PLAIN 账号密码;
  • KAFKA_BROKER_USER / KAFKA_BROKER_PASSWORD:客户端连接 broker 使用的 PLAIN 账号密码。

该问题在 Kafka v2.3 之后的版本中未再出现。完整可参考的配置见 docker-compose-231.yml。

七、版本与 docker-compose 文件对照表

原文档的 References 章节按版本整理了可用的 docker-compose 参考文件与对应镜像 tag,汇总如下:

Kafka 版本 docker-compose 参考文件 镜像 tag
v010(0.10.2.1) docker-compose-010.yml bitnami/kafka:0.10.2.1
v011(0.11.0) docker-compose-011.yml bitnami/kafka:0.11.0-1-r1
v101(1.0.1) N/A(SCRAM 问题,无文件) bitnami/kafka:1.0.1
v111(1.1.1) N/A(SCRAM 问题,无文件) bitnami/kafka:1.1.1
v201(2.0.1) N/A(SCRAM 问题,无文件) bitnami/kafka:2.0.1
v211(2.1.1) N/A(SCRAM 问题,无文件) bitnami/kafka:2.1.1
v221(2.2.1) N/A(SCRAM 问题,无文件) bitnami/kafka:2.2.1
v231(2.3.1) docker-compose-231.yml bitnami/kafka:2.3.1-ol-7-r61

原文档只覆盖到 v231;从仓库目录看,docker_compose_versions/ 后续还补充了 2.4.1、2.6.0、2.7.0、3.6.1 四个版本的 docker-compose 文件(见 docker-compose-241.yml、docker-compose-260.yml、docker-compose-270.yml、docker-compose-361.yml),这些版本均使用 KAFKA_CFG_ 前缀。另外 3.6.1 的授权器类名已更新为 kafka.security.authorizer.AclAuthorizer(旧版本为 kafka.security.auth.SimpleAclAuthorizer),这是跨版本维护时需要注意的差异之一。

八、深入:docker-compose 文件结构剖析

8.1 双服务编排:Zookeeper + Kafka

所有版本的文件都采用相同的双服务结构(以 docker-compose-010.yml 为例):

version: '3'
services:
  zookeeper:
    container_name: zookeeper
    hostname: zookeeper
    image: bitnami/zookeeper:latest
    ports:
      - 2181:2181
    environment:
      ALLOW_ANONYMOUS_LOGIN: yes
  kafka:
    container_name: kafka
    image: bitnami/kafka:0.10.2.1
    restart: on-failure:3
    links:
      - zookeeper
    ports:
      - 9092:9092
      - 9093:9093
    ...

要点:Zookeeper 固定使用 bitnami/zookeeper:latest,开放 2181 端口并允许匿名登录;Kafka 服务通过 links 关联 Zookeeper,同时暴露 9092(PLAINTEXT)与 9093(SASL_PLAINTEXT)两个端口;restart: on-failure:3 保证容器异常退出时自动重启。

8.2 entrypoint 的三种玩法

由于各版本镜像能力不同,entrypoint 承担了不同的"补配置"职责:

(1)旧版(0.10.2.1):写 JAAS 文件 + 建 SCRAM 用户

docker-compose-010.yml 在 entrypoint 中先用 echo -e 写入 kafka_server_jaas.conf(包含 ScramLoginModule 与 PlainLoginModule 两段配置,账号 adminscram/adminplain、密码 admin-secret),再调用 kafka-configs.sh 创建 SCRAM 用户,最后执行原入口:

entrypoint:
  - "/bin/bash"
  - "-c"
  - echo -e 'KafkaServer {
org.apache.kafka.common.security.scram.ScramLoginModule required
 username="adminscram"
 password="admin-secret";
 org.apache.kafka.common.security.plain.PlainLoginModule required
 username="adminplain"
 password="admin-secret"
 user_adminplain="admin-secret";
  };' > /opt/bitnami/kafka/config/kafka_server_jaas.conf; /opt/bitnami/kafka/bin/kafka-configs.sh --zookeeper zookeeper:2181 --alter --add-config 'SCRAM-SHA-256=[password=admin-secret-256],SCRAM-SHA-512=[password=admin-secret-512]' --entity-type users --entity-name adminscram; exec /app-entrypoint.sh /start-kafka.sh

(2)0.11.0:追加 server.properties + 写 JAAS + 建 SCRAM 用户

docker-compose-011.yml 额外多了一步:该版本镜像不识别某些 server.properties 配置,因此在 entrypoint 中先用 echo -e '...' >> 向 /opt/bitnami/kafka/config/server.properties 追加 sasl.enabled.mechanisms、message.max.bytes、auto.create.topics.enable、port 四项关键配置,其余步骤与旧版一致。文件注释也明确说明:"0.11.0 image is not honoring some configs required in server.properties"(0.11.0 镜像不会遵循 server.properties 中的部分必需配置)。

(3)2.3.1:仅建 SCRAM 用户

docker-compose-231.yml 的 entrypoint 只调用 kafka-configs.sh 创建 SCRAM 用户,JAAS 文件改由第五节中的 KAFKA_INTER_BROKER_USER 等四个环境变量让镜像自行生成:

entrypoint:
  - "/bin/bash"
  - "-c"
  - /opt/bitnami/kafka/bin/kafka-configs.sh --zookeeper zookeeper:2181 --alter --add-config "SCRAM-SHA-256=[password=admin-secret-256],SCRAM-SHA-512=[password=admin-secret-512]" --entity-type users --entity-name adminscram; exec /entrypoint.sh /run.sh

(4)2.4.1 及以后:写 kafka_jaas.conf + 建 SCRAM 用户

docker-compose-241.yml、docker-compose-260.yml、docker-compose-270.yml、docker-compose-361.yml 采用统一模式:entrypoint 中先写入 kafka_jaas.conf(注意 2.4 起文件名从 kafka_server_jaas.conf 变为 kafka_jaas.conf),再创建 SCRAM 用户,最后执行 /entrypoint.sh /run.sh。

kafka-configs.sh 创建的 adminscram 用户(SCRAM-SHA-256/512 凭据分别为 admin-secret-256 / admin-secret-512)与 JAAS 中的 adminplain 用户(PLAIN 凭据 admin-secret)共同构成了测试所需的完整 SASL 账号体系,与仓库 sasl 目录下的 PLAIN、SCRAM 客户端实现形成端到端对应。

九、常见问题与排查建议

结合原文档与源码,归纳几条实操排查路径:

  1. 集群起不来 / 配置未生效:首先确认当前 Bitnami Kafka 版本的环境变量前缀。2.3 之前用 KAFKA_,2.3 起必须用 KAFKA_CFG_,否则配置不会映射到 server.properties。
  2. SASL/SCRAM 测试失败:检查 sasl.enabled.mechanisms 是否真的包含了 PLAIN,SCRAM-SHA-256,SCRAM-SHA-512(v101/v111/v201/v211/v221 无法满足,应直接换版本);检查 JAAS 文件是否生成成功(v231 需要 KAFKA_INTER_BROKER_USER 等四个环境变量)。
  3. 部分测试被跳过:KAFKA_SKIP_NETTEST=1 会跳过历史网络测试(conn_test.go);KAFKA_VERSION 未设置或设置不当时,版本分支测试(如 describegroups_test.go 中针对 2.3.1 的特殊逻辑)可能不会按预期执行。务必用实际启动的 broker 版本设置 KAFKA_VERSION。
  4. 对照官方参考:对于仓库中没有 docker-compose 文件的版本,可以回查 bitnami/containers 仓库中该版本提交下的 README、Dockerfile、entrypoint 与初始化脚本,确认环境变量与 server.properties 的映射关系;也可直接启动镜像后在容器内检查实际生成的配置。

结语

kafka-go 的 docker_compose_versions/ 目录用真实踩坑经历证明了"按 Kafka 版本维护 docker-compose"的必要性:环境变量约定(KAFKA_CFG_ 前缀)、JAAS 文件生成权限、SCRAM 机制可用性都会随版本变化。掌握"先查镜像 tag → 再查 Notable Changes 与 commit history → 对齐 KAFKA_CFG_ 约定 → 用 entrypoint 补齐镜像不支持的能力 → 用 KAFKA_VERSION + KAFKA_SKIP_NETTEST 跑测试"这一整套流程,你就能为任意 Bitnami Kafka 版本快速搭出可复用的测试集群。

登录后查看全文
kafka-go