Apache Pinot Docker 镜像实战指南:构建、发布与 Pinot 集群快速部署
Apache Pinot Docker 镜像实战指南:构建、发布与 Pinot 集群快速部署
本文基于 Apache Pinot 仓库 docker/images/pinot/ 目录下的 README 文档,系统讲解 Pinot 官方 Docker 镜像的构建、推送与运行全流程:如何从指定 Git 分支构建并打标签自定义镜像(含 arm64/M1 架构支持)、如何将镜像发布到私有或公开 registry,以及如何用单容器命令或 docker-compose 一键拉起 Zookeeper、Kafka 与 Pinot 的 Controller/Broker/Server 三层集群并加载实时数据。读完本文,你可以独立完成 Pinot 的容器化部署与镜像定制。
镜像整体结构:构建阶段与运行阶段分离
Pinot 的 Docker 镜像定义在 Dockerfile,采用多阶段构建:
-
构建阶段(
AS pinot_build_env):基于apachepinot/pinot-base-build基础镜像,git clonePinot 仓库指定分支后执行 Maven 构建,关键命令为:mvn install package -DskipTests -Pbin-dist -Pbuild-shaded-jar -Djdk.version=${JDK_VERSION} -T1C构建产物复制到
/opt/pinot,并对bin/*.sh赋予可执行权限(见 Dockerfile)。 -
运行阶段:基于
apachepinot/pinot-base-runtime基础镜像,设置环境变量:PINOT_HOME=/opt/pinotJAVA_OPTS="-Xms4G -Xmx4G -Dpinot.admin.system.exit=false"VOLUME声明${PINOT_HOME}/configs与${PINOT_HOME}/data两个持久化目录- 从 Maven 仓库下载
jmx_prometheus_javaagent-0.18.0.jar并建立软链(用于 Prometheus 指标暴露) EXPOSE 9000 8099 8098 8097 8096(Controller/Broker/Server/Admin 端口)ENTRYPOINT ["./bin/pinot-admin.sh"],默认CMD ["-help"]
基础镜像 tag 由 PINOT_BASE_IMAGE_TAG 参数控制,默认为 11-amazoncorretto,即 JDK 11 (Amazon Corretto)。此外仓库还提供:
- Dockerfile.build:仅产出构建环境镜像,Maven 命令中通过
-pl排除了pinot-connectors、pinot-perf、pinot-integration-tests等与运行无关的模块; - Dockerfile.package:基于已有的
pinot-build镜像直接打包运行镜像,适合 CI 流水线中"构建一次、多次打包"的场景; - docker/images/pinot-base/:
apachepinot/pinot-base-build/pinot-base-runtime基础镜像的定义,其中 pinot-base-runtime/ 提供了openjdk、amazoncorretto、ms-openjdk三种 JDK 变体的 Dockerfile。
使用 docker-build.sh 构建自定义镜像
仓库提供的 docker-build.sh 会 checkout Pinot 仓库指定分支并构建镜像。用法(见 README):
./docker-build.sh [Docker Tag] [Git Branch] [Pinot Git URL] [Kafka Version] [Java Version] [JDK Version] [OpenJDK Image]
各参数说明与默认值:
| 参数 | 含义 | 默认值 |
|---|---|---|
Docker Tag |
构建出的镜像名与 tag | pinot:latest |
Git Branch |
要构建的 Pinot 分支 | master |
Pinot Git URL |
要构建的 Pinot 仓库,可指向自己的 fork。注意必须是 https:// 协议,不是 git:// |
https://github.com/apache/pinot.git |
Kafka Version |
构建 Pinot 所依赖的 Kafka 版本 | 2.0 |
Java Version |
Java 构建与运行时镜像版本 | 11 |
JDK Version |
Maven 构建参数 -Djdk.version=${JDK_VERSION} 的取值 |
11 |
OpenJDK Image |
构建与运行时使用的 Base 镜像 | openjdk |
从源码看,当前 docker-build.sh 的实现解析前 5 个参数(
DOCKER_TAG、PINOT_BRANCH、PINOT_GIT_URL、KAFKA_VERSION、JAVA_VERSION)并以docker build --no-cache传入对应的--build-arg;而当前 Dockerfile 中 JDK 与基础镜像实际由JDK_VERSION(默认 11)和PINOT_BASE_IMAGE_TAG(默认11-amazoncorretto)两个 build-arg 决定。以仓库内实际文件为准理解即可。
构建示例
构建自己 fork 上的快照分支并打标签:
./docker-build.sh pinot_fork:snapshot-5.2 snapshot-5.2 https://github.com/your_own_fork/pinot.git
构建 release 版本:
./docker-build.sh pinot:release-0.1.0 release-0.1.0 https://github.com/apache/pinot.git
在 arm64(Mac M1)上构建镜像
在 Apple M1 芯片的 Mac 上,需要指定 arm64 基础镜像(如 arm64v8/openjdk):
./docker-build.sh pinot:latest master https://github.com/apache/pinot.git 2.0 11 11 arm64v8/openjdk
也可以直接调用 docker build:
docker build -t pinot:latest --no-cache --network=host --build-arg PINOT_GIT_URL=https://github.com/apache/pinot.git --build-arg PINOT_BRANCH=master --build-arg JDK_VERSION=11 --build-arg OPENJDK_IMAGE=arm64v8/openjdk -f Dockerfile .
在非 arm64 机器上想交叉构建 arm64 镜像时,可开启 Docker 的 experimental 特性,并加上 --platform linux/arm64:
docker build -t pinot:latest --platform linux/arm64 --no-cache --network=host --build-arg PINOT_GIT_URL=https://github.com/apache/pinot.git --build-arg PINOT_BRANCH=master --build-arg JDK_VERSION=11 --build-arg OPENJDK_IMAGE=arm64v8/openjdk -f Dockerfile .
发布镜像到 Docker Registry
README 给出两种发布方式。要推送到自己的 registry,镜像必须先显式打上带仓库名的 tag。
方式一:使用 docker-push.sh
docker-push.sh 逻辑非常简单:接收一个 tag 参数(缺省为 pinot:latest),然后执行 docker push ${DOCKER_TAG}。例如发布到 apachepinot/pinot 的 DockerHub 仓库:
./docker-push.sh apachepinot/pinot:latest
方式二:先打 tag 再手动 push
docker tag pinot:release-0.1.0 apachepinot/pinot:release-0.1.0
docker push apachepinot/pinot:release-0.1.0
方式三:构建并一步发布(docker-build-and-push.sh)
docker-build-and-push.sh 内部先调用 docker-build.sh 完成构建,再执行 docker push:
./docker-build-and-push.sh apachepinot/pinot:latest master https://github.com/apache/pinot.git
运行镜像:以 pinot-admin.sh 为统一入口
Docker 镜像的入口点是 pinot-admin.sh 脚本,后接的命令子串决定容器内运行哪个角色(StartController / StartBroker / StartServer / AddTable 等)。该脚本由 pinot-tools/pom.xml 中的 appassembler-maven-plugin 生成:pinot-admin 程序的主类为 org.apache.pinot.tools.admin.PinotAdministrator,构建时会随发行包输出到 bin/pinot-admin.sh。
启动 Zookeeper
先拉起一个本地 Zookeeper 容器:
docker pull zookeeper
docker run --name pinot-zookeeper --restart always -p 2181:2181 zookeeper
然后通过 docker inspect 获取其容器内网 IP:
docker inspect pinot-zookeeper|grep IPAddress
"SecondaryIPAddresses": null,
"IPAddress": "172.17.0.2",
"IPAddress": "172.17.0.2",
将得到的地址(本例为 172.17.0.2:2181)作为各组件的 -zkAddress 参数。
启动 Pinot 三大组件
Controller(默认端口 9000):
docker run -p 9000:9000 pinot:release-0.1.0 StartController -zkAddress 172.17.0.2:2181
Broker(默认端口 8099):
docker run -p 8099:8099 pinot:release-0.1.0 StartBroker -zkAddress 172.17.0.2:2181
Server(默认端口 8098):
docker run -p 8098:8098 pinot:release-0.1.0 StartServer -zkAddress 172.17.0.2:2181
这三组端口与 Dockerfile 中的 EXPOSE 9000 8099 8098 8097 8096 完全对应。
QuickStart:docker-compose 一键拉起完整 Pinot 栈
使用 docker-compose 启动集群
docker-compose -f docker-compose.yml up
注意:该 QuickStart 基于 Kafka 2.0 构建的 Pinot 镜像。仓库中的 docker-compose.yml 定义了 5 个服务及其依赖关系:
| 服务 | 镜像 | 端口 | 说明 |
|---|---|---|---|
zookeeper |
zookeeper:latest |
2181 | 单节点(ZOO_MY_ID: 1),数据挂载至 ./pinot-docker-demo/zookeeper/ |
kafka |
confluentinc/cp-kafka:5.3.0 |
9092 | 双 listener(内部 kafka:19092、外部 kafka:9092),连接 zookeeper:2181/kafka |
pinot-controller |
apachepinot/pinot:release-0.7.1 |
9000 | command: StartController -zkAddress zookeeper:2181,数据目录挂载到 ./pinot-docker-demo/pinot/controller |
pinot-broker |
apachepinot/pinot:release-0.7.1 |
8099 | command: StartBroker -zkAddress zookeeper:2181 |
pinot-server |
apachepinot/pinot:release-0.7.1 |
8098 | command: StartServer -zkAddress zookeeper:2181,数据目录挂载到 ./pinot-docker-demo/pinot/server |
各 Pinot 服务通过 depends_on 保证启动顺序:broker/server 依赖 zookeeper、kafka 与 controller。
创建表并从 Kafka 加载数据
启动集群后,复用同一镜像执行工具命令即可建表和灌数据。以 airlineStats 实时表为例(文件路径为镜像内 /opt/pinot 下的相对路径):
创建 airlineStats 表:
docker run --network=pinot_default apachepinot/pinot:release-0.11.0 AddTable -schemaFile examples/stream/airlineStats/airlineStats_schema.json -tableConfigFile examples/stream/airlineStats/docker/airlineStats_realtime_table_config.json -controllerHost pinot-controller -controllerPort 9000 -exec
将飞机统计数据以 Avro 形式写入 Kafka topic flights-realtime:
docker run --network=pinot_default apachepinot/pinot:release-0.11.0 StreamAvroIntoKafka -avroFile examples/stream/airlineStats/rawdata/airlineStats_data.avro -kafkaTopic flights-realtime -kafkaBrokerList kafka:9092 -zkAddress zookeeper:2181
--network=pinot_default 让工具容器加入 compose 网络,从而能通过 pinot-controller、kafka 等服务名互相访问。
数据就绪后,直接在浏览器打开 localhost:9000 即可通过 Controller 的 REST API 查询 Pinot。
镜像内置的示例表配置
镜像内附带了可直接参考的实时表配置与批量导入 job spec:
- examples/docker/table-configs/airlineStats_realtime_table_config.json
- examples/docker/table-configs/meetupRsvp_realtime_table_config.json
- examples/docker/ingestion-job-specs/airlineStats.yaml 与 baseballStats.yaml
以 airlineStats 实时表配置为例,几个关键参数值得注意:
{
"tableType": "REALTIME",
"segmentsConfig": {
"timeColumnName": "DaysSinceEpoch",
"timeType": "DAYS",
"retentionTimeValue": "5",
"segmentPushType": "APPEND",
"segmentAssignmentStrategy": "BalanceNumSegmentAssignmentStrategy",
"replication": "1"
},
"tableIndexConfig": {
"loadMode": "MMAP",
"streamConfigs": {
"streamType": "kafka",
"stream.kafka.topic.name": "flights-realtime",
"stream.kafka.decoder.class.name": "org.apache.pinot.plugin.stream.kafka.KafkaJSONMessageDecoder",
"stream.kafka.consumer.factory.class.name": "org.apache.pinot.plugin.stream.kafka20.KafkaConsumerFactory",
"stream.kafka.broker.list": "kafka:9092",
"stream.kafka.hlc.zk.connect.string": "pinot-zookeeper:2181/kafka",
"realtime.segment.flush.threshold.time": "3600000",
"realtime.segment.flush.threshold.size": "50000",
"stream.kafka.consumer.prop.auto.offset.reset": "smallest"
}
}
}
stream.kafka.decoder.class.name为KafkaJSONMessageDecoder,说明该表消费的是 JSON 消息;stream.kafka.consumer.factory.class.name指向KafkaConsumerFactory(kafka20 插件),与 "QuickStart 基于 Kafka 2.0" 的说明一致;realtime.segment.flush.threshold.time(3600000 毫秒)与realtime.segment.flush.threshold.size(5 万行)分别控制未完成段(unfinished segment)按时间或按行数刷盘的阈值;auto.offset.reset: smallest保证 server 从最早偏移开始消费,便于演示环境拿到全量历史数据。
镜像内容深读:日志、监控与数据生成工具
日志配置
etc/conf/ 目录下预置了四个组件的 Log4j2 配置文件:pinot-controller-log4j2.xml、pinot-broker-log4j2.xml、pinot-server-log4j2.xml 与 pinot-minion-log4j2.xml,随镜像一并复制到 ${PINOT_HOME}/etc。
Prometheus JMX Exporter 监控
Dockerfile 构建期会下载 jmx_prometheus_javaagent-0.18.0.jar。jmx_prometheus_javaagent/README.md 解释了其工作机制:Pinot 通过 PinotJmxReporter 将指标暴露为 JMX mbeans,再由 Prometheus JMX Exporter 抓取。配套的导出配置在 etc/jmx_prometheus_javaagent/configs/ 下按组件拆分(pinot.yml、controller.yml、broker.yml、server.yml、minion.yml),README 建议生产环境使用组件专属配置(如 broker.yml)而非通用的 pinot.yml。本地验证方式是在 JAVA_OPTS 中加入 -javaagent:jmx_prometheus_javaagent.jar=8080:pinot.yml,Prometheus 即可从 8080 端口拉取指标。
generator.sh:从模板一键造数、建表、传段
镜像 bin 目录下的 generator.sh 是一个演示/验证利器,用法为:
./generator.sh [-h] [-a PATH] [-c HOST:PORT] [-s SCHEME] [-t AUTH_TOKEN] [-j PATH] [-n ROWS] TEMPLATE_NAME [TABLE_NAME]
其内部流程串联了 pinot-admin.sh 的四个子命令:
- 从
lib/pinot-all-*-jar-with-dependencies.jar中解出模板的_schema.json、_config.json、_generator.json三个文件; - 用
sed将 schema/config 中的表名替换为目标TABLE_NAME; GenerateData按模板生成 CSV 数据(如simpleWebsite默认 354780 行、complexWebsite默认 631152 行);CreateSegment将数据制作为 segment;AddTable -exec向 Controller(默认localhost:9000)注册表;UploadSegment将 segment 上传至 Controller。
整个链路结束后输出 "Successfully created table ${TABLE_NAME} from template ${TEMPLATE_NAME}",非常适合在新搭建的容器集群上快速验证"建表—导入—可查"的端到端能力。
适用前提与注意事项
- 版本口径:README 中的示例 tag(如
pinot:release-0.1.0、apachepinot/pinot:release-0.11.0)与 docker-compose.yml 中引用的release-0.7.1是文档示例口径;实际构建时以docker-build.sh传入的Git Branch为准,Kafka 依赖版本默认 2.0、JDK 默认 11。 - 构建耗时:
docker build阶段会在容器内完整执行mvn install package(跳过测试),首次构建耗时较长;README 中的--no-cache参数保证了构建环境不缓存,确保分支代码是最新的。 - 端口约定:Controller 9000、Broker 8099、Server 8098 为默认值,可通过各组件自身配置覆盖;镜像
EXPOSE声明了 9000/8099/8098/8097/8096 五个端口。 - Zookeeper 地址传递:单容器模式下必须使用 Zookeeper 容器内网 IP(通过
docker inspect获取);compose 模式下服务间直接用服务名(如zookeeper:2181)。 - 镜像仓库:官方示例镜像发布在 DockerHub 的 apachepinot/pinot 仓库下,推送前请先登录并有对应仓库的写权限;向自己的 registry 发布时务必先
docker tag带上 registry 前缀。