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