kafka-go 多版本测试环境实战:基于 Bitnami Kafka 的 docker-compose 集群配置指南
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-010.yml
- docker-compose-011.yml
- docker-compose-231.yml
- docker-compose-241.yml
- docker-compose-260.yml
- docker-compose-270.yml
- docker-compose-361.yml
之所以无法用一份 docker-compose 通吃所有版本,是因为 Bitnami Kafka 镜像在不同版本上的环境变量约定不同、暴露的配置项不同,甚至个别版本存在无法通过环境变量覆盖的缺陷。kafka-go 的测试对集群有硬性要求:sasl.enabled.mechanisms 必须为 PLAIN,SCRAM-SHA-256,SCRAM-SHA-512,同时需要正确的 JAAS 配置。配置不对,集群要么起不来,要么以不符合测试预期的配置启动,直接导致测试失败。
二、第一步:定位目标版本的 Bitnami Kafka 镜像
为特定 Kafka 版本编写 docker-compose,第一件事是找到对应的镜像。原文档给出的完整步骤如下:
- 打开 Docker Hub 的 Bitnami Kafka tags 页面,按 NEWEST 排序,定位偏好的镜像版本(例如
2.7.0)。 - 阅读 bitnami/containers 仓库中
bitnami/kafka的 README,重点查看 Notable Changes(重大变更)章节,了解该版本的环境配置约定是否有变化。 - 如需理解某个版本的底层搭建方式,进入 bitnami/containers 仓库的 kafka 提交历史(commit history),找到对应 Kafka release 的提交。
- 查看该提交下的
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 机制启动。
社区/仓库曾尝试两种覆盖方式,均告失败:
- 修改 entrypoint:在 docker-compose 的 entrypoint 中先向
server.properties追加sasl.enabled.mechanisms等配置,再执行原entrypoint.sh。结果:Kafka 服务器启动后,server.properties仍会被追加上sasl.enabled.mechanisms的默认值,集群最终仍不带PLAIN,SCRAM-SHA-256,SCRAM-SHA-512启动。 - 挂载 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 客户端实现形成端到端对应。
九、常见问题与排查建议
结合原文档与源码,归纳几条实操排查路径:
- 集群起不来 / 配置未生效:首先确认当前 Bitnami Kafka 版本的环境变量前缀。2.3 之前用
KAFKA_,2.3 起必须用KAFKA_CFG_,否则配置不会映射到server.properties。 - SASL/SCRAM 测试失败:检查
sasl.enabled.mechanisms是否真的包含了PLAIN,SCRAM-SHA-256,SCRAM-SHA-512(v101/v111/v201/v211/v221 无法满足,应直接换版本);检查 JAAS 文件是否生成成功(v231 需要KAFKA_INTER_BROKER_USER等四个环境变量)。 - 部分测试被跳过:
KAFKA_SKIP_NETTEST=1会跳过历史网络测试(conn_test.go);KAFKA_VERSION未设置或设置不当时,版本分支测试(如 describegroups_test.go 中针对 2.3.1 的特殊逻辑)可能不会按预期执行。务必用实际启动的 broker 版本设置KAFKA_VERSION。 - 对照官方参考:对于仓库中没有 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 版本快速搭出可复用的测试集群。