使用 Docker 与 Docker Compose 部署 Apache Druid 单机集群:完整快速上手指南

原创2026-09-22 12:04:071,677 阅读
文章标签:数据库OLAP大数据后端

使用 Docker 与 Docker Compose 部署 Apache Druid 单机集群:完整快速上手指南

Apache Druid 是面向实时分析场景的高性能列式数据库,其官方镜像托管于 Docker Hub(apache/druid)。本文基于仓库中 distribution/docker 目录下的官方示例文件,完整讲解如何在一台机器上用 Docker 与 Docker Compose 拉起一套包含 ZooKeeper、PostgreSQL 元数据存储以及六大 Druid 服务的单机集群,并深入剖析容器内的配置机制(environment 文件、druid_ 前缀环境变量、druid.sh 启动脚本)与镜像构建方式。读完本文,你将能够:下载并理解官方 docker-compose.yml 与 environment 文件、按需修改 JVM 内存与 Druid 配置、一键启动与关闭集群,并通过 Druid 控制台 开始加载数据。

在开始之前,建议先阅读 Druid 总体架构概览 与 数据摄入概览,因为后续教程会引用其中的概念;同时请对 Docker 的基本用法有所了解。本教程假设你会从仓库获取所需文件,这些文件同样存在于本地 Druid 安装包与 Druid 源码中(即 distribution/docker/ 目录)。

Apache Druid 的 Web 控制台界面

前置条件

  • 安装了 Docker 与 Docker Compose(新版 Docker 自带 docker compose 子命令)。

Docker 内存要求

默认的 docker-compose.yml 会启动 8 个容器:ZooKeeper、PostgreSQL,以及基于 micro-quickstart 单机参考配置 的 6 个 Druid 服务容器。每个 Druid 服务被配置为最多使用 7 GiB 内存(其中 6 GiB 为直接内存 MaxDirectMemorySize,1 GiB 为堆内存 Xmx),但快速启动过程并不会用完所有这些内存。

对该配置而言,Docker 至少需要为 Druid 集群提供 6 GiB 可用内存。例如在 macOS 的 Docker Desktop 中,需要在 Preferences 中调大内存分配。如果你遇到退出码为 137 的崩溃(OOMKilled 的典型信号),基本可以断定是分配给 Docker 的内存不足。

可以通过修改 Docker environment 文件 中的 DRUID_SINGLE_NODE_CONF 来切换不同的单机模式,例如使用更小的 nano 模式:

DRUID_SINGLE_NODE_CONF=nano-quickstart

各单机参考配置的规格可从 docs/operations/single-server.md 查看:

配置 规格 定位
nano-quickstart 1 CPU、4 GiB RAM 资源受限环境(如小型 Docker 容器)下的有限评估
micro-quickstart 4 CPU、16 GiB RAM 面向笔记本等小型机器的快速评估(默认值)
small / medium / large / xlarge 8~64 CPU、64~512 GiB RAM 面向生产规模单机部署

获取配置文件

创建一个目录用于存放 Druid 的 Docker 文件。仓库源码中的 distribution/docker/docker-compose.yml 会从 Docker Hub 拉取镜像,适合作为示例环境以及试验基于 Docker 的 Druid 配置与部署方式。请把该文件下载(或从源码拷贝)到你创建的目录中。

Compose 文件解析

官方示例 docker-compose.yml 会为每个 Druid 服务创建一个容器,并额外创建 ZooKeeper 容器与作为元数据存储的 PostgreSQL 容器。各服务与端口对应关系如下:

服务 镜像 对外端口 说明
postgres postgres:latest 5432 元数据存储,库/用户/密码均为 druid / druid / FoolishPassword
zookeeper zookeeper:3.5.10 2181 服务发现与协调(需 3.5+ 以支持容器节点)
coordinator apache/druid:31.0.0 8081 段管理与负载均衡
broker apache/druid:31.0.0 8082 查询入口
historical apache/druid:31.0.0 8083 段存储与查询服务
middlemanager apache/druid:31.0.0 8091、8100-8105 数据摄入执行任务(peon 端口区间)
router apache/druid:31.0.0 8888 提供 Web 控制台与统一路由

Compose 文件还会创建一个名为 druid_shared 的命名卷作为深度存储(deep storage),用于在各 Druid 服务之间共享与保存段(segments)和任务日志。该卷在容器内挂载为 /opt/shared。此外每个服务还有独立的命名卷(如 coordinator_var、broker_var、historical_var、middle_var、router_var)挂载到 /opt/druid/var,用于存放各服务自身的运行数据。

值得注意的依赖关系:所有 Druid 服务都 depends_on 于 zookeeper 与 postgres;broker、historical、middlemanager、router 还依赖 coordinator,确保启动顺序正确。

Environment 文件

Druid 的示例 docker-compose.yml 通过 Docker 的 env_file 机制 文件来指定完整的 Druid 配置(包括下文 配置项 中介绍的环境变量)。该文件默认名为 environment,必须与 docker-compose.yml 放在同一目录。示例文件中的选项非常适合尝试 Druid 与运行教程。

需要强调的是,这种单文件方式并不适合生产系统。官方建议改用 DRUID_COMMON_CONFIG 与 DRUID_CONFIG_${service} 的组合,或使用针对特定服务定制的 environment 文件(详见 druid.sh 的实现)。

示例 environment 文件的关键内容(节选):

# Java tuning
#DRUID_XMX=1g
#DRUID_XMS=1g
#DRUID_MAXNEWSIZE=250m
#DRUID_NEWSIZE=250m
#DRUID_MAXDIRECTMEMORYSIZE=6172m
DRUID_SINGLE_NODE_CONF=micro-quickstart

druid_emitter_logging_logLevel=debug

druid_extensions_loadList=["druid-histogram", "druid-datasketches", "druid-lookups-cached-global", "postgresql-metadata-storage", "druid-multi-stage-query"]

druid_zk_service_host=zookeeper

druid_metadata_storage_type=postgresql
druid_metadata_storage_connector_connectURI=jdbc:postgresql://postgres:5432/druid
druid_metadata_storage_connector_user=druid
druid_metadata_storage_connector_password=FoolishPassword

druid_storage_type=local
druid_storage_storageDirectory=/opt/shared/segments
druid_indexer_logs_type=file
druid_indexer_logs_directory=/opt/shared/indexing-logs

druid_processing_numThreads=2
druid_processing_numMergeBuffers=2

配置项

Druid Docker 容器通过容器内设置的环境变量完成配置,Docker Compose 将 environment 文件中的值注入容器。这些变量还可以额外指定指向 标准 Druid 配置文件 的路径,这些文件必须存在于容器内。默认值对快速启动足够,生产系统则需要修改默认值。

基础配置(内存)

变量 作用 默认值
DRUID_MAXDIRECTMEMORYSIZE 设置 Java 最大直接内存(-XX:MaxDirectMemorySize) 6 GiB
DRUID_XMX 设置 Java 最大堆大小(-Xmx) 1 GB

生产配置

变量 作用
DRUID_CONFIG_COMMON 指向 Druid 公共属性文件(common runtime properties)的完整路径
DRUID_CONFIG_${service} 指向某个服务属性文件(service runtime properties)的完整路径,如 DRUID_CONFIG_broker
JAVA_OPTS 设置 Java 启动参数

日志配置

变量 作用
DRUID_LOG4J 原样设置整个 log4j.xml 配置内容(示例见 environment 文件 中的 DRUID_LOG4J= 行)
DRUID_LOG_LEVEL 覆盖默认的 Log4j 日志级别(当前仅当既有级别为 INFO 时生效)
DRUID_SERVICE_LOG4J 原样设置针对某个服务的 log4j.xml 配置内容
DRUID_SERVICE_LOG_LEVEL 在服务级 log4j 中覆盖默认日志级别

高级内存配置

变量 作用 默认值
DRUID_XMS 设置 Java 初始堆大小(-Xms) 1 GB
DRUID_MAXNEWSIZE 设置 Java 最大新生代大小(-XX:MaxNewSize) —
DRUID_NEWSIZE 设置 Java 新生代大小(-XX:NewSize) —

druid_ 前缀环境变量:通用配置通道

除上述特殊环境变量外,容器内启动 Druid 的脚本会把任何以 druid_ 前缀开头的环境变量作为命令行配置使用。例如:

druid_metadata_storage_type=postgresql

会被翻译成 Druid 进程 Java 启动命令中的选项:

-Ddruid.metadata.storage.type=postgresql

其转换规则是:环境变量名中的下划线 _ 对应配置键中的点 .(druid_ 前缀本身对应 druid.),例如 druid_zk_service_host=zookeeper 最终成为 -Ddruid.zk.service.host=zookeeper。这一机制的完整实现可参见 druid.sh 中遍历 env | grep ^druid_ 并调用 setKey 的逻辑。

修改控制台端口

注意 Druid 使用 8888 端口提供 Web 控制台,该端口也常被 Jupyter 等工具占用。为避免冲突,可以修改 docker-compose.yml 中 router 服务的 ports 段。例如把控制台暴露到宿主机的 9999 端口:

    container_name: router
    ...
    ports:
      - "9999:8888"

启动集群

cd 到包含配置文件的目录——即你前面创建的目录(或本地安装 Druid 后安装目录中的 distribution/docker/)。

使用前台方式启动并附加 shell:

docker compose up

或使用后台方式运行:

docker compose up -d

集群启动完成后,即可在 http://localhost:8888](http://localhost:8888) 访问 [Web 控制台,该界面由 Druid Router 进程 提供。

所有 Druid 进程完全启动需要几秒钟。如果在服务刚启动时立刻打开控制台,可能会看到一些可以安全忽略的错误。

使用集群

集群就绪后,可以继续跟随 快速上手教程:加载数据(如 原生批量摄入教程)开始摄入数据。生产环境中,你还需要完善自己的 docker-compose.yml,按需增加外部服务依赖。

可以通过 Docker 进入 Druid 容器并打开 shell 进行探索:

docker exec -ti <id> sh

其中 <id> 是通过 docker ps 查到的容器 ID。Druid 安装在容器内的 /opt/druid;负责消费上述环境变量并启动 Druid 的脚本位于 /druid.sh(即仓库中的 distribution/docker/druid.sh)。

关闭集群:

docker compose down

你的数据会以一组 Docker 卷 的形式持久化,重启 Druid 集群后依然可用。

深入底层:druid.sh 的配置组装流程

理解 druid.sh 的实现,有助于在生产环境中正确使用各类配置变量。该脚本的核心流程如下:

  1. 准备只读友好的配置目录:将 /opt/druid/conf/druid 拷贝到 /tmp/conf/druid,从而允许根文件系统以只读方式挂载。
  2. 按单机或集群模式解析配置路径:若设置了 DRUID_SINGLE_NODE_CONF,则从 conf/druid/single-server/<mode>/ 下解析 _common、historical、middleManager、coordinator|overlord、broker、router 对应的子目录;否则回退到 conf/druid/cluster/ 下的完整集群配置。nano-quickstart、micro-quickstart 等模式的选择就在这一步生效。
  3. 注入外部配置:若设置了 DRUID_CONFIG_COMMON,直接覆盖 common.runtime.properties;若设置了 DRUID_CONFIG_${service}(如 DRUID_CONFIG_broker),则覆盖对应服务的 runtime.properties。
  4. 展开环境变量:遍历所有以 druid_ 开头的环境变量,通过 setKey 函数把 druid.xxx.yyy 键写入对应服务的 runtime.properties 或 common.runtime.properties(键的转换即上文所述的下划线→点规则,同时用 __ 保留字面下划线)。
  5. 应用 JVM 参数:DRUID_XMX、DRUID_XMS、DRUID_MAXNEWSIZE、DRUID_NEWSIZE、DRUID_MAXDIRECTMEMORYSIZE 通过 setJavaKey 写入各服务 jvm.config;随后与 JAVA_OPTS 合并,并追加 -Ddruid.node.type=$SERVICE 供 log4j2 模板区分节点类型。
  6. 应用日志配置:DRUID_LOG4J / DRUID_LOG_LEVEL 作用于公共 log4j2.xml,DRUID_SERVICE_LOG4J / DRUID_SERVICE_LOG_LEVEL 作用于服务级 log4j2.xml。
  7. 创建运行目录:默认创建 var/tmp、var/druid/segments、var/druid/indexing-logs 等目录(可用 DRUID_DIRS_TO_CREATE 覆盖)。
  8. 启动进程:最终执行 exec bin/run-java ${JAVA_OPTS} -cp $COMMON_CONF_DIR:$SERVICE_CONF_DIR:lib/*:... org.apache.druid.cli.Main server $@,即进入 Druid 的 CLI 入口 org.apache.druid.cli.Main 以 server 子命令启动对应服务。

此外,仓库还提供 peon.sh,它与 druid.sh 高度相似,但专门用于 Kubernetes Overlord 扩展场景(kubernetes-overlord-extensions),通过 org.apache.druid.cli.Main internal peon 启动 peon 进程,并支持通过 TASK_JSON 环境变量以 base64+gzip 形式传入任务定义。

自行构建镜像

仓库中的 distribution/docker/README.md 说明了从源码构建镜像的方法。在仓库根目录执行:

DOCKER_BUILDKIT=1 docker build -t apache/druid:tag -f distribution/docker/Dockerfile .

在 Apple M1/M2(arm64)上构建时,需要先在仓库根目录构建 Druid 发行包,再关闭源码内构建:

mvn clean package -DskipTests -Pdist
DOCKER_BUILDKIT=1 docker build -t apache/druid:tag -f distribution/docker/Dockerfile --build-arg BUILD_FROM_SOURCE=false .

构建完成后,修改 docker-compose.yml 中的镜像 tag 为你构建的 tag,即可本地运行:

docker compose -f distribution/docker/docker-compose.yml up

从 Dockerfile 可以看到镜像的关键设计:

  • 构建阶段显式使用 --platform=linux/amd64 的 Maven 镜像在 x64 上构建发行包(web-console 依赖在 arm64 上有已知问题,见源码注释),最终产物仅为 JAR,因此不影响最终镜像跨架构运行;
  • 运行时基础镜像为 gcr.io/distroless/java17-debian12,配合 busybox 提供基础 shell 工具,并创建非 root 用户 druid(UID 1000)以 USER druid 运行,安全性更好;
  • /opt/druid(安装目录)、/opt/shared(共享段与任务日志)、/opt/druid/var(各服务运行数据)为约定挂载点,ENTRYPOINT 为 /druid.sh。

使用 MySQL 作为元数据存储

官方镜像只包含 PostgreSQL 元数据存储连接器。如果需要 MySQL 连接器,可以基于基础镜像使用 Dockerfile.mysql 扩展:

docker build -t apache/druid:tag-mysql --build-arg DRUID_RELEASE=apache/druid:tag -f distribution/docker/Dockerfile.mysql .

其中 apache/druid:tag 是作为基础镜像的 Druid 版本(同理还有 MariaDB 变体 Dockerfile.mariadb)。同时需要在 environment 文件中把元数据存储相关配置切换为 MySQL,例如 druid_metadata_storage_type=mysql 并修改连接 URI。

常见问题与生产建议

  • 退出码 137:几乎总是 Docker 可用内存不足所致,请在 Docker Desktop 或宿主机层面调大内存配额,或改用更小的 nano-quickstart 模式。
  • 端口冲突:8888(控制台)、5432(PostgreSQL)、2181(ZooKeeper)等端口与宿主机常用服务可能冲突,可在 compose 文件的 ports 段映射到其他宿主机端口。
  • 持久化:不要删除 compose 文件底部 volumes: 声明的命名卷(metadata_data、druid_shared 及各服务 _var 卷),它们承载了元数据库、段数据与任务日志。
  • 生产化方向:使用 DRUID_CONFIG_COMMON / DRUID_CONFIG_${service} 挂载独立配置文件,替换单文件 environment 方式;结合 Kubernetes configMap 挂载配置(druid.sh 注释中明确说明了这一设计意图);为每个服务定制日志与 JVM 参数。
登录后查看全文
druid