AutoMQ（Apache Kafka Docker 镜像）使用指南：默认配置、文件输入与环境变量三种启动方式全解-北京尧图网络

AutoMQApache Kafka Docker 镜像使用指南默认配置、文件输入与环境变量三种启动方式全解【免费下载链接】automqDiskless Kafka® on S3. 10x Cost-Effective. No Cross-AZ Traffic Cost. Autoscale in seconds. Single-digit ms latency. Multi-AZ Availability.项目地址: https://gitcode.com/GitHub_Trending/au/automq本篇技术指南基于仓库 docker/examples/README.md 展开系统讲解如何在 Docker 容器中启动 Kafka 兼容服务包括默认配置、文件输入、环境变量三种配置注入方式环境变量命名规则与 log4j 配置技巧SSL 加密模式以及单节点与多节点集群Combined / Isolated 两种 KRaft 部署形态的完整 Docker Compose 示例。读完本文你将掌握从零搭建 plaintext/SSL 的 Kafka 单机与三节点集群并能够用仓库内置客户端脚本完成生产与消费验证。三种配置启动方式总览Kafka 服务在 Docker 容器中可以通过以下三种方式启动配置优先级从低到高为默认配置文件输入环境变量默认配置Default configs不向容器传入任何用户配置直接使用 Kafka 发行包内置的默认配置即 tarball 中打包的config/server.properties等文件文件输入File input通过 Docker volume 把宿主机上的属性文件目录挂载进容器替换容器内的默认配置文件环境变量Environment variables以KAFKA_前缀环境变量注入配置会覆盖文件输入与默认配置中的同名属性。三条原则需要先记住只要提供了任何用户配置默认配置就不再生效整体替换而非增量合并环境变量定义的属性会覆盖文件输入与默认配置中的同名属性推荐的复杂场景做法是使用 Docker Compose 文件统一管理环境变量。默认配置启动如果docker run时既不挂载属性文件目录、也不设置任何KAFKA_*环境变量容器会直接使用镜像中/opt/kafka/config下随发行包打包的默认配置文件启动docker run -p 9092:9092 apache/kafka:latest从 docker/jvm/launch 可以看到容器启动入口的实际行为先调用KafkaDockerWrapper setup处理配置目录--default-configs-dir /etc/kafka/docker、--mounted-configs-dir /mnt/shared/config、--final-configs-dir /opt/kafka/config随后才exec kafka-server-start.sh /opt/kafka/config/server.properties启动 broker。也就是说配置的最终落地目录是/opt/kafka/config默认配置、挂载文件与环境变量三者在启动脚本阶段被合并/覆盖为最终的server.properties。文件输入方式File Input当需要以文件形式提供完整配置时使用文件输入方式准备一个包含 Kafka 属性文件的本地文件夹例如server.properties通过 Docker volume 将其挂载到容器内固定路径/mnt/shared/config该目录中的属性文件会替换容器内的默认配置文件。挂载命令示例docker run --volume path/to/property/folder:/mnt/shared/config -p 9092:9092 apache/kafka:latest从 docker/jvm/launch 可见KafkaDockerWrapper setup的--mounted-configs-dir /mnt/shared/config参数正是读取该挂载目录将其内容作为最终配置来源。属性文件只会被 Docker 容器读取不会回写宿主机。仓库中给出了一个可直接对照的完整文件输入示例见下文单节点 · File Input小节其属性文件位于 docker/examples/fixtures/file-input/server.properties覆盖了advertised.listeners、listener.security.protocol.map、ssl.keystore.location、ssl.truststore.location等完整配置项。使用环境变量注入配置环境变量命名规则环境变量方式无需任何文件只需遵循下述命名规则将server.properties中的属性名转换为KAFKA_前缀的环境变量名属性名中的字符环境变量中的转换说明.点_单下划线例如abc.def→KAFKA_ABC_DEF_下划线__双下划线例如abc_def→KAFKA_ABC__DEF-连字符___三下划线例如abc-def→KAFKA_ABC___DEF无前缀KAFKA_转换完成后统一加前缀典型映射示例abc.def→KAFKA_ABC_DEFabc-def→KAFKA_ABC___DEFabc_def→KAFKA_ABC__DEF常用环境变量可直接传入例如CLUSTER_IDKRaft 模式必需的集群 ID。命令行注入方式docker run --env CONFIG_NAMECONFIG_VALUE -p 9092:9092 apache/kafka:latest注意文档明确建议优先使用 Docker Compose 文件来组织环境变量配置可读性与可维护性更好。log4j 配置注入log4j 属性文件log4j.properties、tools-log4j.properties与server.properties的处理方式不同通过环境变量提供的 log4j 配置会被追加到镜像自带的默认 log4j 属性文件末尾而不是整体替换KAFKA_LOG4J_ROOT_LOGLEVEL设置log4j.rootLogger的值同时作用于log4j.properties与tools-log4j.propertiesKAFKA_LOG4J_LOGGERS以逗号分隔的单个字符串向log4j.properties追加 logger。例如设置KAFKA_LOG4J_LOGGERSproperty1value1,property2value2容器内log4j.properties会追加两行log4j.logger.property1value1 log4j.logger.property2value2环境变量覆盖文件输入的示例docker/examples/docker-compose-files/single-node/file-input/docker-compose.yml 同时使用了文件输入与环境变量/mnt/shared/config挂载了 server.properties而CLUSTER_ID、KAFKA_NODE_ID、KAFKA_CONTROLLER_QUORUM_VOTERS、KAFKA_LISTENERS等通过环境变量补充/覆盖例如文件中的process.rolesbroker会被环境变量KAFKA_PROCESS_ROLES: broker,controller覆盖为 combined 模式直观展示了环境变量优先的覆盖语义。在 SSL 模式下运行SSL 模式的推荐做法是密钥文件挂载环境变量注入配置二者配合使用。密钥文件挂载将密钥/信任库文件挂载到容器内固定路径/etc/kafka/secrets并通过环境变量只提供文件名与凭据文件名由镜像内脚本自动推导完整路径并提取密码写入server.properties环境变量含义KAFKA_SSL_KEYSTORE_FILENAMEkeystore 文件名如kafka01.keystore.jksKAFKA_SSL_KEYSTORE_CREDENTIALS存放 keystore 密码的凭据文件名如kafka_keystore_credsKAFKA_SSL_KEY_CREDENTIALS存放 key 密码的凭据文件名如kafka_ssl_key_credsKAFKA_SSL_TRUSTSTORE_FILENAMEtruststore 文件名如kafka.truststore.jksKAFKA_SSL_TRUSTSTORE_CREDENTIALS存放 truststore 密码的凭据文件名如kafka_truststore_creds必须成组提供的 SSL 配置请通过环境变量设置KAFKA_ADVERTISED_LISTENERS确保其中包含一个SSLlistener以真正启用 SSL 模式若改用文件输入提供 SSL 属性则advertised.listeners也必须一起写在文件里不能单独用环境变量分开提供结论SSL 属性与advertised.listeners应当作为一个整体要么全部走文件输入、要么全部走环境变量若 SSL 属性同时来自文件输入与环境变量环境变量值覆盖文件输入值与通用覆盖规则一致文件输入方式需要正确设置 truststore/keystore 的完整路径可参考 docker/examples/fixtures/file-input/server.properties 中/etc/kafka/secrets/...的写法。单节点示例docker/examples/docker-compose-files/single-node目录包含三个快速上手示例用于理解各种配置输入方式。以下命令均需在仓库根目录执行并通过IMAGE变量指定镜像apache/kafka:latest为 JVM 镜像apache/kafka-native:latest为 GraalVM 原生镜像# JVM 版 IMAGEapache/kafka:latest docker compose command # 原生版 IMAGEapache/kafka-native:latest docker compose command提示若计划使用本仓库的 CLI 脚本请先确保相关 jars 已构建完成。Plaintext纯环境变量配置文件docker/examples/docker-compose-files/single-node/plaintext/docker-compose.yml这是最简单的 Compose 文件全部配置通过环境变量提供environment: KAFKA_NODE_ID: 1 KAFKA_LISTENER_SECURITY_PROTOCOL_MAP: CONTROLLER:PLAINTEXT,PLAINTEXT:PLAINTEXT,PLAINTEXT_HOST:PLAINTEXT KAFKA_ADVERTISED_LISTENERS: PLAINTEXT_HOST://localhost:9092,PLAINTEXT://broker:19092 KAFKA_PROCESS_ROLES: broker,controller KAFKA_CONTROLLER_QUORUM_VOTERS: 1broker:29093 KAFKA_LISTENERS: CONTROLLER://:29093,PLAINTEXT_HOST://:9092,PLAINTEXT://:19092 KAFKA_INTER_BROKER_LISTENER_NAME: PLAINTEXT KAFKA_CONTROLLER_LISTENER_NAMES: CONTROLLER CLUSTER_ID: 4L6g3nShT-eMCtK--X86sw KAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR: 1 KAFKA_GROUP_INITIAL_REBALANCE_DELAY_MS: 0 KAFKA_TRANSACTION_STATE_LOG_MIN_ISR: 1 KAFKA_TRANSACTION_STATE_LOG_REPLICATION_FACTOR: 1 KAFKA_LOG_DIRS: /tmp/kraft-combined-logs要点解读显式提供了KAFKA_LISTENERS如果未提供默认逻辑会基于KAFKA_ADVERTISED_LISTENERS把其中的 host 替换为0.0.0.0自动生成CLUSTER_ID已给出但并非强制——容器内存在默认 cluster idKAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR必须显式设为 1单节点下若使用 Kafka 默认值 3__consumer_offsets主题无法满足副本因子会启动失败容器hostname与container_name保持一致便于 docker 网络内互相解析。启动与验证# 从仓库根目录执行 IMAGEapache/kafka:latest docker compose -f docker/examples/docker-compose-files/single-node/plaintext/docker-compose.yml upbin/kafka-console-producer.sh --topic test --bootstrap-server localhost:9092SSL环境变量密钥挂载配置文件docker/examples/docker-compose-files/single-node/ssl/docker-compose.ymlvolumes: - ../../../fixtures/secrets:/etc/kafka/secrets environment: KAFKA_LISTENER_SECURITY_PROTOCOL_MAP: SSL:SSL,CONTROLLER:PLAINTEXT,SSL-INTERNAL:SSL KAFKA_ADVERTISED_LISTENERS: SSL://localhost:9093,SSL-INTERNAL://broker:19093 KAFKA_LISTENERS: SSL://:9093,CONTROLLER://:29093,SSL-INTERNAL://:19093 KAFKA_INTER_BROKER_LISTENER_NAME: SSL-INTERNAL KAFKA_SSL_KEYSTORE_FILENAME: kafka01.keystore.jks KAFKA_SSL_KEYSTORE_CREDENTIALS: kafka_keystore_creds KAFKA_SSL_KEY_CREDENTIALS: kafka_ssl_key_creds KAFKA_SSL_TRUSTSTORE_FILENAME: kafka.truststore.jks KAFKA_SSL_TRUSTSTORE_CREDENTIALS: kafka_truststore_creds KAFKA_SSL_CLIENT_AUTH: required KAFKA_SSL_ENDPOINT_IDENTIFICATION_ALGORITHM: 要点解读secrets 目录仓库内为 docker/examples/fixtures/secrets挂载到/etc/kafka/secrets使用环境变量方式时文件必须放在/etc/kafka/secrets因为脚本会依据该路径推导文件全路径环境变量里只写文件名KAFKA_SSL_ENDPOINT_IDENTIFICATION_ALGORITHM置空是因为示例证书未设置 hostname生产环境一般不需要客户端侧 truststore/keystore 配置参考 docker/examples/fixtures/client-secrets/client-ssl.properties。启动与验证需 Java 17IMAGEapache/kafka:latest docker compose -f docker/examples/docker-compose-files/single-node/ssl/docker-compose.yml upbin/kafka-console-producer.sh --topic test --bootstrap-server localhost:9093 \ --producer.config ./docker/examples/fixtures/client-secrets/client-ssl.propertiesFile Input文件输入 SSL配置文件docker/examples/docker-compose-files/single-node/file-input/docker-compose.yml此处 SSL 配置通过文件输入提供注意与纯环境变量方式的差异属性文件中必须写完整路径如ssl.keystore.location/etc/kafka/secrets/kafka01.keystore.jks而非文件名相比 SSL 示例多了一个 volume 挂载../../../fixtures/file-input:/mnt/shared/config环境变量提供的配置会覆盖文件输入配置。启动与验证需 Java 17IMAGEapache/kafka:latest docker compose -f docker/examples/docker-compose-files/single-node/file-input/docker-compose.yml upbin/kafka-console-producer.sh --topic test --bootstrap-server localhost:9093 \ --producer.config ./docker/examples/fixtures/client-secrets/client-ssl.properties多节点集群示例docker/examples/docker-compose-files/cluster目录包含面向真实多节点场景的示例分为Combinedbroker 与 controller 同进程与Isolatedcontroller 独立进程两种 KRaft 部署形态每种形态各提供 plaintext 与 SSL 两个版本。通用要点双 Listener 设计无论 combined 还是 isolated要让 broker 之间、broker 与客户端之间都能互通都需要引入两个 listener内部 listener如PLAINTEXT/SSL-INTERNAL供 broker 间通信inter-broker通过KAFKA_INTER_BROKER_LISTENER_NAME指定advertised 地址使用容器 hostname保证 docker 网络内 broker 可互相发现外部 listener如PLAINTEXT_HOST/SSL供客户端连接advertised 地址指向宿主机侧端口示例中为localhost:主机映射端口。同时利用每个 broker 设置的hostname使 listener 地址与容器名对齐保证解析正确。每个 broker 必须向宿主机暴露唯一端口例如三节点 plaintext 中 broker-1/2/3 容器内均监听 9092分别映射到宿主 29092/39092/49092。Combined · Plaintext配置文件docker/examples/docker-compose-files/cluster/combined/plaintext/docker-compose.yml三个kafka-1/2/3服务每个都设置KAFKA_PROCESS_ROLES: broker,controllerKAFKA_CONTROLLER_QUORUM_VOTERS: 1kafka-1:9093,2kafka-2:9093,3kafka-3:9093构成三节点 KRaft 仲裁KAFKA_LISTENERS与KAFKA_ADVERTISED_LISTENERS按节点差异化配置PLAINTEXT://kafka-N:19092内部、PLAINTEXT_HOST://localhost:主机端口外部。IMAGEapache/kafka:latest docker compose -f docker/examples/docker-compose-files/cluster/combined/plaintext/docker-compose.yml upbin/kafka-console-producer.sh --topic quickstart-events --bootstrap-server localhost:29092Combined · SSL配置文件docker/examples/docker-compose-files/cluster/combined/ssl/docker-compose.yml与 plaintext 同理broker 间通信使用SSL-INTERNAL客户端到 broker 使用SSLKAFKA_SSL_ENDPOINT_IDENTIFICATION_ALGORITHM置空是因为示例证书未配置 hostname生产环境按需调整示例为简洁起见所有 broker 共用同一套凭据生产环境务必为每个 broker 准备各自的 secrets。IMAGEapache/kafka:latest docker compose -f docker/examples/docker-compose-files/cluster/combined/ssl/docker-compose.yml upbin/kafka-console-producer.sh --topic test --bootstrap-server localhost:29093 \ --producer.config ./docker/examples/fixtures/client-secrets/client-ssl.propertiesIsolated · Plaintext配置文件docker/examples/docker-compose-files/cluster/isolated/plaintext/docker-compose.ymlcontroller 与 broker 分开部署controller-1/2/3只运行controller角色KAFKA_LISTENERS: CONTROLLER://:9093kafka-1/2/3运行broker角色KAFKA_NODE_ID分别为 4/5/6并显式声明depends_on三个 controller保证启动顺序。listener 布局与 combined 相同。IMAGEapache/kafka:latest docker compose -f docker/examples/docker-compose-files/cluster/isolated/plaintext/docker-compose.yml upbin/kafka-console-producer.sh --topic quickstart-events --bootstrap-server localhost:29092Isolated · SSL配置文件docker/examples/docker-compose-files/cluster/isolated/ssl/docker-compose.yml与 combined SSL 基本一致区别在于controller 使用PLAINTEXTlistenerKAFKA_LISTENERS: CONTROLLER://:29092仅暴露在 docker 网络内broker 的SSL-INTERNAL仅用于 broker 间通信broker 挂载 secrets 并设置KAFKA_SSL_*系列环境变量。IMAGEapache/kafka:latest docker compose -f docker/examples/docker-compose-files/cluster/isolated/ssl/docker-compose.yml upbin/kafka-console-producer.sh --topic test --bootstrap-server localhost:29093 \ --producer.config ./docker/examples/fixtures/client-secrets/client-ssl.properties所有示例每次只运行一个切换示例前请先关闭当前运行的 Compose 服务避免端口与资源冲突。容器启动链路的源码印证以上三种配置方式并非黑盒魔法其底层实现可以在镜像启动脚本中直接确认。docker/jvm/launch 是 JVM 版镜像的容器入口核心流程为若未显式设置KAFKA_JMX_OPTS则注入默认 JMX 配置并在设置KAFKA_JMX_PORT时补全com.sun.management.jmxremote.rmi.port等属性docker/jvm/launch打印Using provided cluster id $CLUSTER_ID确认 KRaft 集群 ID 来源docker/jvm/launch调用kafka-run-class.sh kafka.docker.KafkaDockerWrapper setup同时传入三个目录默认配置目录/etc/kafka/docker、挂载配置目录/mnt/shared/config、最终输出目录/opt/kafka/configdocker/jvm/launch最后exec kafka-server-start.sh /opt/kafka/config/server.properties启动服务docker/jvm/launch。由此可以推断KafkaDockerWrapper负责把默认配置挂载文件环境变量三类输入合并/覆盖为/opt/kafka/config/server.properties这正是本文三种配置方式优先级规则环境变量文件输入默认配置的代码落点。仓库同时维护了原生镜像入口 docker/native/launch 与官方镜像对齐目录 docker/docker_official_images/3.7.0/jvm/launch二者保持一致语义。本仓库的 Docker 镜像构建体系集中在 docker/jvm/Dockerfile 与 docker/native/Dockerfile并通过 docker/automq-feat-kafka-docker.patch 承载对上游 Kafka Docker 镜像的定制如 docker/scripts/pre_start.sh 中的/opt/automq符号链接与 ZGC 性能参数注入读者可在实际使用镜像前深入研读这些构建文件。总结与排障提示围绕 docker/examples/README.md 与 docker/examples/docker-compose-files 目录可以快速复现的部署矩阵如下场景配置方式关键点单节点 Plaintext纯环境变量必须显式设置KAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR1单节点 SSL环境变量 /etc/kafka/secrets挂载提供文件名与凭据文件名脚本推导路径单节点 File Input/mnt/shared/config挂载属性文件内写完整路径环境变量可覆盖集群 Combined双 listener内部 listener 用 hostname外部 listener 映射宿主唯一端口集群 Isolatedcontroller 与 broker 分离brokerdepends_oncontrollercontroller 常驻PLAINTEXT排障时建议依次核对单节点是否设置了KAFKA_OFFSETS_TOPIC_REPLICATION_FACTORSSL 场景advertised.listeners是否与 SSL 属性成组提供集群场景各 broker 是否使用唯一宿主端口、内部 listener 是否使用容器 hostname是否先关闭了上一个示例再启动新示例。所有配置项均可在仓库 config/server.properties 与 config/kraft/broker.properties 中查找默认值与注释说明。【免费下载链接】automqDiskless Kafka® on S3. 10x Cost-Effective. No Cross-AZ Traffic Cost. Autoscale in seconds. Single-digit ms latency. Multi-AZ Availability.项目地址: https://gitcode.com/GitHub_Trending/au/automq创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

AutoMQ（Apache Kafka Docker 镜像）使用指南：默认配置、文件输入与环境变量三种启动方式全解

相关推荐

Flutter iOS混合开发安全防护与混淆实战

一条命令分享开发服务器：portless Tailscale Funnel 与 ngrok 公网分享实战

AI编程Agent闭环：工具选型检查项与协作调整

更多资讯

OpenCreator：视频翻译配音一键出片的本地开源AI工作台

Gemini 结构化输出实战：使用 Instructor 与 Google GenAI SDK 构建类型安全的数据提取

React 进阶概念实战指南：PropTypes、Styled Components、Redux、Context API 与自定义 Hooks（cu/curriculum 课程精讲）

LangChain4j 集成 Tavily Web Search Engine：配置、API 与源码级原理详解

使用 AWS CLI 的 associate-external-connection 命令为 CodeArtifact 仓库添加外部连接

Lighttools 8.4.0光学仿真入门：建模、光度学与实战要点

今日更新

基于高阶循环谱的MPSK载波频率估计与MATLAB实现

MiniPdf方：.NET开源Office转PDF的高效解决方案

Solon AI v3.10：Java全栈智能体开发框架解析

本周精选

AI驱动的自动化专利分析平台技术解析

LeetCode-Go 题解：1252. Cells with Odd Values in a Matrix（奇数值单元格计数）双解法剖析

在线答疑系统Java毕设实战：Spring Boot前后端分离与状态流转

本月热门

基于YOLO的焊缝缺陷检测：从数据标注到工业部署全流程实践

分布式服务的决策记录

创业产品的首版范围

读完文章，想聊聊您的网站？