Apache Pinot Docker 镜像实战指南:构建、发布与 Pinot 集群快速部署

原创2026-10-14 09:50:351,835 阅读
文章标签:OLAP数据库大数据流处理

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 clone Pinot 仓库指定分支后执行 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/pinot
    • JAVA_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:

以 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 的四个子命令:

  1. 从 lib/pinot-all-*-jar-with-dependencies.jar 中解出模板的 _schema.json、_config.json、_generator.json 三个文件;
  2. 用 sed 将 schema/config 中的表名替换为目标 TABLE_NAME;
  3. GenerateData 按模板生成 CSV 数据(如 simpleWebsite 默认 354780 行、complexWebsite 默认 631152 行);
  4. CreateSegment 将数据制作为 segment;
  5. AddTable -exec 向 Controller(默认 localhost:9000)注册表;
  6. 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 前缀。
登录后查看全文
pinot