在实际的分布式数据库部署过程中Doris 以其高性能的 MPP 架构和友好的 SQL 支持成为许多数据仓库和实时分析场景的热门选择。然而当我们将 Doris 与 Docker 容器化技术结合时环境隔离带来的便捷性也伴随着网络、存储和节点发现等新的挑战。很多开发者初次尝试在 Docker 中部署 Doris 集群时往往会卡在 FEFrontend和 BEBackend节点的正确配置与相互注册上导致集群无法启动或查询失败。本文旨在解决这一核心痛点。我们将以一个最小化的 Docker 环境为例从零开始逐步演示如何正确配置并启动 Doris 的 FE 和 BE 节点并确保它们能成功组成一个可用的集群。整个过程将覆盖从镜像选择、网络规划、配置文件编写、容器启动到最终的节点注册与状态验证。无论你是正在搭建测试环境还是希望理解 Doris 在容器化部署中的关键配置项都可以按照本文的步骤进行操作和排查。1. 理解 Doris 集群的核心架构与 Docker 化挑战在动手配置之前必须先理解 Doris 集群的基本组成和它们在 Docker 环境下的特殊要求。这能帮助你明白每一步配置的目的而不是盲目复制命令。1.1 FE 与 BE 的角色与职责Doris 集群采用主从架构主要包含两类节点Frontend (FE) 前端节点负责接收用户连接、解析 SQL、生成查询计划、元数据管理及集群调度。FE 节点中又分为 Leader、Follower 和 Observer 三种角色。通常一个生产集群需要至少 1 个 Leader 和 2 个 Follower 以实现高可用。Backend (BE) 后端节点负责数据存储、查询计划执行以及数据压缩、合并等后台任务。数据表的分片Tablet实际存储在 BE 节点上。集群要正常工作FE 和 BE 必须能相互发现并通信。FE 需要知道所有 BE 的地址以进行任务调度BE 也需要向 FE 进行“心跳”汇报并拉取指令。1.2 Docker 部署带来的核心挑战在物理机或虚拟机上部署节点通常使用固定的 IP 或主机名。但在 Docker 中情况变得复杂网络隔离 默认的bridge网络下容器拥有独立的网络命名空间和内部 IP。容器重启后 IP 可能变化导致 FE 和 BE 之间基于 IP 的注册信息失效。服务发现 FE 启动时需要指定自身的元数据目录BE 启动时需要知道至少一个 FE 的地址来进行注册。在动态的容器环境中如何稳定地提供这些地址是关键。存储持久化 FE 的元数据和 BE 的数据必须持久化到宿主机否则容器销毁后所有数据丢失。资源限制 Doris 对内存和 CPU 较为敏感需要在 Docker 中合理分配资源。因此正确的 Docker 部署策略是使用自定义的 Docker 网络提供稳定的主机名解析并将关键的配置目录和数据目录通过卷Volume挂载到宿主机进行持久化。2. 部署前的环境准备与规划一个清晰的规划能避免后续的混乱。我们假设在单台 Linux 宿主机上进行多容器集群部署。2.1 环境与资源要求请确保你的宿主机满足以下条件组件要求说明操作系统Linux (CentOS 7, Ubuntu 18.04)本文以 CentOS 7 为例。Windows/macOS 通过 Docker Desktop 部署思路类似但路径和网络有差异。Docker版本 20.10.0 及以上使用docker --version命令确认。Docker Compose版本 1.29.0 及以上可选但推荐用于编排多容器简化管理。使用docker-compose --version确认。系统资源建议至少 4核 CPU8GB 内存Doris 单个 BE 默认内存配置较高资源不足会导致启动失败。磁盘空间至少 20GB 可用空间用于存放镜像、持久化数据和日志。2.2 项目目录结构规划在宿主机上创建一个清晰的工作目录例如/opt/doris-docker。其子目录结构规划如下/opt/doris-docker/ ├── docker-compose.yml # 容器编排定义文件 ├── network.conf # 自定义网络配置备用 ├── fe/ │ ├── conf/ # FE 配置文件目录挂载卷 │ │ └── fe.conf # FE 主配置文件 │ ├── doris-meta/ # FE 元数据目录挂载卷 │ └── log/ # FE 日志目录挂载卷 ├── be/ │ ├── conf/ # BE 配置文件目录挂载卷 │ │ └── be.conf # BE 主配置文件 │ ├── storage/ # BE 数据存储目录挂载卷 │ └── log/ # BE 日志目录挂载卷 └── scripts/ # 辅助脚本目录 └── wait-for-it.sh # 用于等待服务就绪的脚本这个结构将所有需要修改和持久化的内容都放在了宿主机上容器内只是挂载并使用它们。2.3 获取 Doris 官方 Docker 镜像Apache Doris 在 Docker Hub 上提供了官方镜像apache/doris并通过标签区分 FE 和 BE 组件。建议使用特定版本标签以获得稳定环境。# 拉取指定版本的镜像例如 2.0.4 docker pull apache/doris:2.0.4-fe-x86_64 docker pull apache/doris:2.0.4-be-x86_64 # 或者拉取 latest 标签可能包含最新变更适合测试 # docker pull apache/doris:latest-fe-x86_64 # docker pull apache/doris:latest-be-x86_64使用docker images命令确认镜像已下载成功。3. 配置 Doris FE 节点FE 是集群的大脑需要首先正确启动。我们将使用 Docker Compose 来定义和启动服务。3.1 创建自定义 Docker 网络为了让容器间能通过主机名稳定通信我们创建一个自定义的桥接网络。docker network create --driver bridge --subnet172.20.0.0/16 doris-network创建后可以使用docker network inspect doris-network查看其详细信息。在这个网络中我们可以为容器指定固定的主机名如doris-fe01其他容器可以通过这个主机名访问它无需关心其内部 IP 是否变化。3.2 准备 FE 配置文件在/opt/doris-docker/fe/conf/目录下创建fe.conf文件。这是 FE 最重要的配置文件。以下是一个最小化的关键配置示例# FE 配置 - fe.conf # 元数据目录必须与容器内挂载路径一致 meta_dir /opt/apache-doris/fe/doris-meta # 本 FE 的标识在集群内必须唯一 priority_networks 172.20.0.0/16 # 指定网络范围让 FE 选择此网段的 IP # 或者直接指定监听地址在 Docker 网络内 # edit_log_port 9010 # http_port 8030 # rpc_port 9020 # query_port 9030 # 时区设置避免时间错误 JAVA_OPTS -Xmx4096m -XX:UseG1GC -Duser.timezoneAsia/Shanghai # 日志级别调试时可设为 INFO 或 DEBUG sys_log_level INFO关键解释meta_dir 指向容器内路径。我们后续会将宿主机的fe/doris-meta目录挂载到此实现元数据持久化。priority_networks 这个配置在 Docker 环境中至关重要。它告诉 FE 选择哪个网段的 IP 作为自己的node_identification。如果不配置FE 可能会选择 Docker 网桥如 172.17.0.0/16或其他虚拟网卡的 IP导致 BE 或其他 FE 无法正确访问它。我们将其设置为自定义网络的网段。JAVA_OPTS 调整 JVM 堆内存。对于测试环境4GB 通常足够。生产环境需根据负载调整。3.3 编写 Docker Compose 配置在/opt/doris-docker目录下创建docker-compose.yml文件。我们将先定义 FE 服务。version: 3.8 services: doris-fe: image: apache/doris:2.0.4-fe-x86_64 container_name: doris-fe-01 hostname: doris-fe-01 # 固定主机名用于网络发现 networks: doris-network: ipv4_address: 172.20.0.10 # 可选的固定IP非必须 ports: - 8030:8030 # FE HTTP 端口用于 Web UI 和系统管理 - 9030:9030 # MySQL 协议端口用于客户端连接 volumes: - ./fe/conf/fe.conf:/opt/apache-doris/fe/conf/fe.conf:ro - ./fe/doris-meta:/opt/apache-doris/fe/doris-meta - ./fe/log:/opt/apache-doris/fe/log environment: - FE_SERVERSdoris-fe-01:9010 - FE_ID1 # 健康检查确保服务完全启动 healthcheck: test: [CMD, mysql, -h127.0.0.1, -P9030, -uroot, -e, SHOW FRONTENDS;] interval: 30s timeout: 10s retries: 5 start_period: 60s restart: unless-stopped mem_limit: 4g cpus: 2 networks: doris-network: external: true name: doris-network配置详解hostname: 设置为doris-fe-01。在doris-network中BE 容器可以通过这个主机名直接访问 FE。networks: 将服务接入之前创建的doris-network并可选地分配一个固定 IP172.20.0.10。使用固定 IP 可以避免主机名解析的潜在问题但非必须。ports: 将 FE 的 HTTP 端口8030和 MySQL 查询端口9030映射到宿主机方便我们通过 Web UI 访问和管理以及使用 MySQL 客户端连接。volumes: 将宿主机上的配置、元数据和日志目录挂载到容器内对应路径。:ro表示配置文件只读。environment: 这里设置了两个环境变量。FE_SERVERS在某些启动脚本中用于指定 FE 集群单节点时可省略或只设自己。FE_ID用于指定节点 ID在集群部署中必须唯一。healthcheck: 定义了一个健康检查使用mysql客户端连接 FE 的查询端口并执行简单 SQL。这能确保 Compose 知道 FE 何时真正就绪对于依赖 FE 启动的 BE 服务很重要。mem_limit和cpus: 限制容器资源防止其占用过多宿主机资源。3.4 启动并验证 FE 节点现在可以启动 FE 服务了。# 进入项目目录 cd /opt/doris-docker # 启动 FE 服务-d 表示后台运行 docker-compose up -d doris-fe # 查看容器日志观察启动过程 docker-compose logs -f doris-fe观察日志当看到类似以下输出时表明 FE 启动成功2024-xx-xx xx:xx:xx,xxx INFO (main|1) [Frontend.start():xxx] FE start successfully in xxx ms 2024-xx-xx xx:xx:xx,xxx INFO (main|1) [Frontend.start():xxx] To see FE logs, check fe.log验证 FE 状态通过 MySQL 客户端连接# 使用宿主机映射的端口连接密码默认为空 mysql -h127.0.0.1 -P9030 -uroot连接成功后执行SHOW FRONTENDS\G;命令。你应该能看到一行记录其中Name为doris-fe-01:9010或你配置的主机名和端口Role为FOLLOWER首次启动的节点会自动成为 LeaderIsMaster为trueAlive为true。MySQL [(none)] SHOW FRONTENDS\G; *************************** 1. row *************************** Name: doris-fe-01:9010 IP: 172.20.0.10 EditLogPort: 9010 HttpPort: 8030 QueryPort: 9030 RpcPort: 9020 Role: FOLLOWER IsMaster: true ClusterId: xxxxxxxx Join: true Alive: true ReplayedJournalId: xxx ...通过 Web UI 访问 打开浏览器访问http://宿主机IP:8030。使用用户名root密码为空登录。在导航栏中可以看到“集群信息”等菜单确认 FE 运行正常。4. 配置并注册 Doris BE 节点FE 正常运行后我们就可以添加 BE 节点了。BE 需要向 FE 注册才能加入集群。4.1 准备 BE 配置文件在/opt/doris-docker/be/conf/目录下创建be.conf文件。# BE 配置 - be.conf # 数据存储目录必须与容器内挂载路径一致 storage_root_path /opt/apache-doris/be/storage # 指定 BE 在 Docker 网络中的 IP 地址范围原理同 FE priority_networks 172.20.0.0/16 # BE 的服务端口 be_port 9060 webserver_port 8040 heartbeat_service_port 9050 brpc_port 8060 # JVM 配置 JAVA_OPTS -Xmx8192m -XX:UseG1GC -Duser.timezoneAsia/Shanghai # 其他性能相关配置可根据硬件调整 # sys_log_level INFO # flush_thread_num 4 # compaction_thread_num 4关键解释storage_root_path BE 的数据存储路径。同样需要挂载到宿主机持久化。priority_networks与 FE 配置同理必须设置为 Docker 自定义网络的网段以确保 BE 向 FE 汇报正确的 IP 地址。这是 BE 注册失败的最常见原因之一。端口be_port是 BE 的主要服务端口webserver_port用于 Web 界面heartbeat_service_port用于心跳。4.2 在 Docker Compose 中添加 BE 服务编辑/opt/doris-docker/docker-compose.yml文件在services部分添加 BE 服务的定义。doris-be-01: image: apache/doris:2.0.4-be-x86_64 container_name: doris-be-01 hostname: doris-be-01 networks: doris-network: ipv4_address: 172.20.0.20 # 可选的固定IP volumes: - ./be/conf/be.conf:/opt/apache-doris/be/conf/be.conf:ro - ./be/storage:/opt/apache-doris/be/storage - ./be/log:/opt/apache-doris/be/log environment: - FE_SERVERSdoris-fe-01:9010 # 指定 FE 地址用于 BE 启动时注册 depends_on: doris-fe: condition: service_healthy # 等待 FE 健康检查通过后再启动 restart: unless-stopped mem_limit: 8g # BE 通常需要更多内存 cpus: 4配置详解environment:FE_SERVERS环境变量在这里非常关键。它告诉 BE 容器在启动时应该向哪个 FE 节点发送注册请求。其值就是 FE 服务在 Docker 网络中的地址doris-fe-01:9010主机名edit_log_port。depends_on: 指定了启动顺序依赖并且条件是 FE 服务健康service_healthy。这确保了 BE 启动时 FE 肯定是可用的避免了因 FE 未就绪而导致的注册失败。mem_limit: BE 负责数据存储和计算建议分配比 FE 更多的内存例如 8GB。4.3 启动 BE 并检查注册状态启动 BE 服务并观察其日志。# 启动 BE 服务 docker-compose up -d doris-be-01 # 查看 BE 启动日志 docker-compose logs -f doris-be-01在 BE 日志中你应该看到它成功连接到 FE 并发送心跳... Ixxxxxx xx:xx:xx.xxxxxx xxxxx heartbeat.cpp:xxx] Master FE is doris-fe-01:9010 Ixxxxxx xx:xx:xx.xxxxxx xxxxx heartbeat.cpp:xxx] Successfully report heartbeat to FE. response status: OK ...验证 BE 注册状态 再次通过 MySQL 客户端连接到 FE执行SHOW BACKENDS\G;命令。MySQL [(none)] SHOW BACKENDS\G; *************************** 1. row *************************** BackendId: 10001 IP: 172.20.0.20 -- 注意这里应该是 Docker 网络内的 IP HeartbeatPort: 9050 BePort: 9060 HttpPort: 8040 BrpcPort: 8060 LastStartTime: 2024-xx-xx xx:xx:xx LastHeartbeat: 2024-xx-xx xx:xx:xx Alive: true SystemDecommissioned: false ClusterDecommissioned: false TabletNum: 0 DataUsedCapacity: 0.000 AvailCapacity: 1.000 TB TotalCapacity: 1.000 TB UsedPct: 0.00% MaxDiskUsedPct: 0.00% ErrMsg: Version: 2.0.4-xxx Status: {lastSuccessReportTabletsTime:..., lastStreamLoadTime:-1}重点关注Alive字段是否为true以及IP字段是否是你期望的 Docker 网络 IP如172.20.0.20。如果Alive为false或IP不正确例如是127.0.0.1或宿主机 IP说明注册有问题。5. 常见问题排查与解决方案即使按照上述步骤操作仍可能遇到问题。以下是 Docker 部署 Doris 时最常见的几个“坑”及其解决方案。5.1 FE 或 BE 启动失败日志显示端口被占用现象容器启动后立即退出日志报错Address already in use。原因容器内端口与宿主机映射端口冲突或 Docker 网络内端口冲突。排查检查docker-compose.yml中ports映射的宿主机端口如8030,9030是否已被其他进程占用netstat -tlnp | grep :9030。检查 FE/BE 配置文件中的服务端口如edit_log_port9010,be_port9060是否在 Docker 网络内唯一。确保不同容器的这些内部端口不冲突。解决更换宿主机映射端口例如- 9031:9030。如果是多节点集群确保每个节点的配置文件中的端口定义不冲突。5.2 BE 注册失败SHOW BACKENDS 显示 Alive false现象BE 容器运行正常日志也在发送心跳但 FE 查询显示Alive: falseErrMsg可能有连接超时等错误。原因这是 Docker 部署中最典型的问题。根本原因是 BE 向 FE 汇报的 IP 地址IP字段无法被 FE 反向访问。未配置priority_networksBE 可能使用了 Docker 默认网桥如172.17.0.x的 IP而 FE 在另一个网络或使用了主机名导致无法通信。防火墙/安全组限制宿主机或云服务器的防火墙可能阻止了 Docker 网络网段如172.20.0.0/16内部的通信。FE 的priority_networks也未配置FE 自身选择的 IP 也可能不对导致 BE 即使拿到了正确的 FE 地址FE 也无法响应 BE 的请求。排查与解决确认网络配置进入 BE 容器内部查看它实际使用的 IP。docker exec -it doris-be-01 bash cat /proc/net/fib_trie | grep -B1 -A2 172.20 # 查找 172.20 网段的 IP # 或使用 ip addr show确认该 IP 与SHOW BACKENDS中显示的IP一致并且属于priority_networks指定的网段。双向连通性测试在 BE 容器内尝试 ping FE 的主机名和 IP。docker exec -it doris-be-01 ping doris-fe-01 docker exec -it doris-fe-01 ping doris-be-01如果 ping 不通检查 Docker 网络设置docker network inspect doris-network确认两个容器都在该网络中并且Connectivity为true。检查防火墙临时关闭宿主机防火墙进行测试生产环境请谨慎。# CentOS 7 systemctl stop firewalld # Ubuntu sudo ufw disable终极检查清单FE 和 BE 的priority_networks必须配置且指向同一个Docker 自定义网络网段。docker-compose.yml中所有服务必须连接到同一个自定义网络doris-network。BE 的environment中的FE_SERVERS值必须使用 FE 在 Docker 网络中的主机名或固定 IP后跟正确的edit_log_port默认9010。5.3 通过宿主机 IP 无法访问 FE 的 Web UI 或 MySQL 端口现象浏览器访问http://宿主机IP:8030无法打开或 MySQL 客户端连接宿主机IP:9030失败。原因Docker 端口映射未生效或宿主机防火墙阻止了外部访问。排查检查容器是否正常运行且端口映射正确docker ps查看PORTS列确认有0.0.0.0:8030-8030/tcp这样的映射。在宿主机内部测试curl http://localhost:8030或mysql -h127.0.0.1 -P9030 -uroot。如果宿主机内能通说明是外部网络问题。检查宿主机防火墙规则确保放行了 8030 和 9030 端口。# CentOS 7 放行端口 firewall-cmd --permanent --add-port8030/tcp firewall-cmd --permanent --add-port9030/tcp firewall-cmd --reload5.4 数据或元数据丢失现象容器重启或重建后之前创建的表、数据库或数据不见了。原因没有正确配置持久化卷Volume。Docker 容器的文件系统是临时的。解决确保docker-compose.yml中的volumes映射正确并且宿主机上的目录如./fe/doris-meta,./be/storage存在且有适当的读写权限。在部署前这些目录应该是空的或不存在Docker Compose 会自动创建。5.5 容器资源不足导致进程被 Kill现象容器运行一段时间后突然停止日志显示Killed。原因容器内存或 CPU 使用超出限制被 Docker 或系统 OOM Killer 终止。解决调整docker-compose.yml中的mem_limit和cpus参数为容器分配更多资源。同时也要检查 Doris 自身的 JVM 配置JAVA_OPTS确保堆内存设置-Xmx小于容器的内存限制为操作系统和其他进程留出空间。6. 生产环境部署建议与扩展单节点部署适合测试和开发。对于生产环境需要考虑高可用、可扩展性和可维护性。6.1 构建高可用集群一个高可用的 Doris 集群通常需要3个 FE 节点 1个 Leader2个 Follower。通过docker-compose定义三个 FE 服务配置不同的hostname、FE_ID和元数据目录。在第一个 FE 启动后通过 MySQL 客户端连接使用ALTER SYSTEM ADD FOLLOWER “host:port”;命令添加其他 FE。多个 BE 节点 至少 3 个 BE 以实现数据多副本。同样定义多个 BE 服务确保它们配置正确的FE_SERVERS指向 FE Leader 或 Follower。关键点在于所有节点必须使用相同的自定义 Docker 网络并且priority_networks配置一致。6.2 配置与数据持久化策略配置文件管理 将fe.conf和be.conf纳入版本控制如 Git。使用环境变量或配置中心来管理不同环境开发、测试、生产的差异配置。数据备份 定期备份 FE 的元数据目录doris-meta和 BE 的数据目录storage。可以考虑使用 Docker 卷驱动将数据存储到更可靠的网络存储或云存储上。日志收集 将fe/log和be/log目录挂载到宿主机并接入 ELKElasticsearch, Logstash, Kibana或 LokiGrafana 等日志收集分析系统便于问题排查和监控。6.3 监控与运维健康检查 充分利用 Docker Compose 的healthcheck功能为 FE 和 BE 设置有效的健康检查命令以便编排工具能感知服务状态。资源监控 使用docker stats或 Prometheus cAdvisor Grafana 监控容器的 CPU、内存、网络和磁盘 IO 使用情况。Doris 自身监控 通过 FE 的 Web UI8030端口可以查看集群状态、查询统计和慢查询等信息。对于生产环境建议将 Doris 的监控指标也接入 Prometheus。6.4 版本升级与回滚Doris 版本升级需要谨慎。在 Docker 环境中升级流程可以简化为备份所有持久化数据目录和配置文件。修改docker-compose.yml中的镜像标签为新版本。逐个停止并删除旧容器docker-compose down然后启动新容器docker-compose up -d。Doris 的元数据格式通常向前兼容但务必查阅官方发布说明确认升级路径和注意事项。如果升级失败快速回滚的方式就是使用备份的数据目录并将镜像标签改回旧版本重新启动容器。通过将状态数据、配置与容器本身分离Docker 化部署为 Doris 集群的维护、扩展和迁移提供了极大的灵活性。理解 FE 和 BE 的通信机制并正确配置网络与持久化是成功部署的基石。
在实际的分布式数据库部署过程中Doris 以其高性能的 MPP 架构和友好的 SQL 支持成为许多数据仓库和实时分析场景的热门选择。然而当我们将 Doris 与 Docker 容器化技术结合时环境隔离带来的便捷性也伴随着网络、存储和节点发现等新的挑战。很多开发者初次尝试在 Docker 中部署 Doris 集群时往往会卡在 FEFrontend和 BEBackend节点的正确配置与相互注册上导致集群无法启动或查询失败。本文旨在解决这一核心痛点。我们将以一个最小化的 Docker 环境为例从零开始逐步演示如何正确配置并启动 Doris 的 FE 和 BE 节点并确保它们能成功组成一个可用的集群。整个过程将覆盖从镜像选择、网络规划、配置文件编写、容器启动到最终的节点注册与状态验证。无论你是正在搭建测试环境还是希望理解 Doris 在容器化部署中的关键配置项都可以按照本文的步骤进行操作和排查。1. 理解 Doris 集群的核心架构与 Docker 化挑战在动手配置之前必须先理解 Doris 集群的基本组成和它们在 Docker 环境下的特殊要求。这能帮助你明白每一步配置的目的而不是盲目复制命令。1.1 FE 与 BE 的角色与职责Doris 集群采用主从架构主要包含两类节点Frontend (FE) 前端节点负责接收用户连接、解析 SQL、生成查询计划、元数据管理及集群调度。FE 节点中又分为 Leader、Follower 和 Observer 三种角色。通常一个生产集群需要至少 1 个 Leader 和 2 个 Follower 以实现高可用。Backend (BE) 后端节点负责数据存储、查询计划执行以及数据压缩、合并等后台任务。数据表的分片Tablet实际存储在 BE 节点上。集群要正常工作FE 和 BE 必须能相互发现并通信。FE 需要知道所有 BE 的地址以进行任务调度BE 也需要向 FE 进行“心跳”汇报并拉取指令。1.2 Docker 部署带来的核心挑战在物理机或虚拟机上部署节点通常使用固定的 IP 或主机名。但在 Docker 中情况变得复杂网络隔离 默认的bridge网络下容器拥有独立的网络命名空间和内部 IP。容器重启后 IP 可能变化导致 FE 和 BE 之间基于 IP 的注册信息失效。服务发现 FE 启动时需要指定自身的元数据目录BE 启动时需要知道至少一个 FE 的地址来进行注册。在动态的容器环境中如何稳定地提供这些地址是关键。存储持久化 FE 的元数据和 BE 的数据必须持久化到宿主机否则容器销毁后所有数据丢失。资源限制 Doris 对内存和 CPU 较为敏感需要在 Docker 中合理分配资源。因此正确的 Docker 部署策略是使用自定义的 Docker 网络提供稳定的主机名解析并将关键的配置目录和数据目录通过卷Volume挂载到宿主机进行持久化。2. 部署前的环境准备与规划一个清晰的规划能避免后续的混乱。我们假设在单台 Linux 宿主机上进行多容器集群部署。2.1 环境与资源要求请确保你的宿主机满足以下条件组件要求说明操作系统Linux (CentOS 7, Ubuntu 18.04)本文以 CentOS 7 为例。Windows/macOS 通过 Docker Desktop 部署思路类似但路径和网络有差异。Docker版本 20.10.0 及以上使用docker --version命令确认。Docker Compose版本 1.29.0 及以上可选但推荐用于编排多容器简化管理。使用docker-compose --version确认。系统资源建议至少 4核 CPU8GB 内存Doris 单个 BE 默认内存配置较高资源不足会导致启动失败。磁盘空间至少 20GB 可用空间用于存放镜像、持久化数据和日志。2.2 项目目录结构规划在宿主机上创建一个清晰的工作目录例如/opt/doris-docker。其子目录结构规划如下/opt/doris-docker/ ├── docker-compose.yml # 容器编排定义文件 ├── network.conf # 自定义网络配置备用 ├── fe/ │ ├── conf/ # FE 配置文件目录挂载卷 │ │ └── fe.conf # FE 主配置文件 │ ├── doris-meta/ # FE 元数据目录挂载卷 │ └── log/ # FE 日志目录挂载卷 ├── be/ │ ├── conf/ # BE 配置文件目录挂载卷 │ │ └── be.conf # BE 主配置文件 │ ├── storage/ # BE 数据存储目录挂载卷 │ └── log/ # BE 日志目录挂载卷 └── scripts/ # 辅助脚本目录 └── wait-for-it.sh # 用于等待服务就绪的脚本这个结构将所有需要修改和持久化的内容都放在了宿主机上容器内只是挂载并使用它们。2.3 获取 Doris 官方 Docker 镜像Apache Doris 在 Docker Hub 上提供了官方镜像apache/doris并通过标签区分 FE 和 BE 组件。建议使用特定版本标签以获得稳定环境。# 拉取指定版本的镜像例如 2.0.4 docker pull apache/doris:2.0.4-fe-x86_64 docker pull apache/doris:2.0.4-be-x86_64 # 或者拉取 latest 标签可能包含最新变更适合测试 # docker pull apache/doris:latest-fe-x86_64 # docker pull apache/doris:latest-be-x86_64使用docker images命令确认镜像已下载成功。3. 配置 Doris FE 节点FE 是集群的大脑需要首先正确启动。我们将使用 Docker Compose 来定义和启动服务。3.1 创建自定义 Docker 网络为了让容器间能通过主机名稳定通信我们创建一个自定义的桥接网络。docker network create --driver bridge --subnet172.20.0.0/16 doris-network创建后可以使用docker network inspect doris-network查看其详细信息。在这个网络中我们可以为容器指定固定的主机名如doris-fe01其他容器可以通过这个主机名访问它无需关心其内部 IP 是否变化。3.2 准备 FE 配置文件在/opt/doris-docker/fe/conf/目录下创建fe.conf文件。这是 FE 最重要的配置文件。以下是一个最小化的关键配置示例# FE 配置 - fe.conf # 元数据目录必须与容器内挂载路径一致 meta_dir /opt/apache-doris/fe/doris-meta # 本 FE 的标识在集群内必须唯一 priority_networks 172.20.0.0/16 # 指定网络范围让 FE 选择此网段的 IP # 或者直接指定监听地址在 Docker 网络内 # edit_log_port 9010 # http_port 8030 # rpc_port 9020 # query_port 9030 # 时区设置避免时间错误 JAVA_OPTS -Xmx4096m -XX:UseG1GC -Duser.timezoneAsia/Shanghai # 日志级别调试时可设为 INFO 或 DEBUG sys_log_level INFO关键解释meta_dir 指向容器内路径。我们后续会将宿主机的fe/doris-meta目录挂载到此实现元数据持久化。priority_networks 这个配置在 Docker 环境中至关重要。它告诉 FE 选择哪个网段的 IP 作为自己的node_identification。如果不配置FE 可能会选择 Docker 网桥如 172.17.0.0/16或其他虚拟网卡的 IP导致 BE 或其他 FE 无法正确访问它。我们将其设置为自定义网络的网段。JAVA_OPTS 调整 JVM 堆内存。对于测试环境4GB 通常足够。生产环境需根据负载调整。3.3 编写 Docker Compose 配置在/opt/doris-docker目录下创建docker-compose.yml文件。我们将先定义 FE 服务。version: 3.8 services: doris-fe: image: apache/doris:2.0.4-fe-x86_64 container_name: doris-fe-01 hostname: doris-fe-01 # 固定主机名用于网络发现 networks: doris-network: ipv4_address: 172.20.0.10 # 可选的固定IP非必须 ports: - 8030:8030 # FE HTTP 端口用于 Web UI 和系统管理 - 9030:9030 # MySQL 协议端口用于客户端连接 volumes: - ./fe/conf/fe.conf:/opt/apache-doris/fe/conf/fe.conf:ro - ./fe/doris-meta:/opt/apache-doris/fe/doris-meta - ./fe/log:/opt/apache-doris/fe/log environment: - FE_SERVERSdoris-fe-01:9010 - FE_ID1 # 健康检查确保服务完全启动 healthcheck: test: [CMD, mysql, -h127.0.0.1, -P9030, -uroot, -e, SHOW FRONTENDS;] interval: 30s timeout: 10s retries: 5 start_period: 60s restart: unless-stopped mem_limit: 4g cpus: 2 networks: doris-network: external: true name: doris-network配置详解hostname: 设置为doris-fe-01。在doris-network中BE 容器可以通过这个主机名直接访问 FE。networks: 将服务接入之前创建的doris-network并可选地分配一个固定 IP172.20.0.10。使用固定 IP 可以避免主机名解析的潜在问题但非必须。ports: 将 FE 的 HTTP 端口8030和 MySQL 查询端口9030映射到宿主机方便我们通过 Web UI 访问和管理以及使用 MySQL 客户端连接。volumes: 将宿主机上的配置、元数据和日志目录挂载到容器内对应路径。:ro表示配置文件只读。environment: 这里设置了两个环境变量。FE_SERVERS在某些启动脚本中用于指定 FE 集群单节点时可省略或只设自己。FE_ID用于指定节点 ID在集群部署中必须唯一。healthcheck: 定义了一个健康检查使用mysql客户端连接 FE 的查询端口并执行简单 SQL。这能确保 Compose 知道 FE 何时真正就绪对于依赖 FE 启动的 BE 服务很重要。mem_limit和cpus: 限制容器资源防止其占用过多宿主机资源。3.4 启动并验证 FE 节点现在可以启动 FE 服务了。# 进入项目目录 cd /opt/doris-docker # 启动 FE 服务-d 表示后台运行 docker-compose up -d doris-fe # 查看容器日志观察启动过程 docker-compose logs -f doris-fe观察日志当看到类似以下输出时表明 FE 启动成功2024-xx-xx xx:xx:xx,xxx INFO (main|1) [Frontend.start():xxx] FE start successfully in xxx ms 2024-xx-xx xx:xx:xx,xxx INFO (main|1) [Frontend.start():xxx] To see FE logs, check fe.log验证 FE 状态通过 MySQL 客户端连接# 使用宿主机映射的端口连接密码默认为空 mysql -h127.0.0.1 -P9030 -uroot连接成功后执行SHOW FRONTENDS\G;命令。你应该能看到一行记录其中Name为doris-fe-01:9010或你配置的主机名和端口Role为FOLLOWER首次启动的节点会自动成为 LeaderIsMaster为trueAlive为true。MySQL [(none)] SHOW FRONTENDS\G; *************************** 1. row *************************** Name: doris-fe-01:9010 IP: 172.20.0.10 EditLogPort: 9010 HttpPort: 8030 QueryPort: 9030 RpcPort: 9020 Role: FOLLOWER IsMaster: true ClusterId: xxxxxxxx Join: true Alive: true ReplayedJournalId: xxx ...通过 Web UI 访问 打开浏览器访问http://宿主机IP:8030。使用用户名root密码为空登录。在导航栏中可以看到“集群信息”等菜单确认 FE 运行正常。4. 配置并注册 Doris BE 节点FE 正常运行后我们就可以添加 BE 节点了。BE 需要向 FE 注册才能加入集群。4.1 准备 BE 配置文件在/opt/doris-docker/be/conf/目录下创建be.conf文件。# BE 配置 - be.conf # 数据存储目录必须与容器内挂载路径一致 storage_root_path /opt/apache-doris/be/storage # 指定 BE 在 Docker 网络中的 IP 地址范围原理同 FE priority_networks 172.20.0.0/16 # BE 的服务端口 be_port 9060 webserver_port 8040 heartbeat_service_port 9050 brpc_port 8060 # JVM 配置 JAVA_OPTS -Xmx8192m -XX:UseG1GC -Duser.timezoneAsia/Shanghai # 其他性能相关配置可根据硬件调整 # sys_log_level INFO # flush_thread_num 4 # compaction_thread_num 4关键解释storage_root_path BE 的数据存储路径。同样需要挂载到宿主机持久化。priority_networks与 FE 配置同理必须设置为 Docker 自定义网络的网段以确保 BE 向 FE 汇报正确的 IP 地址。这是 BE 注册失败的最常见原因之一。端口be_port是 BE 的主要服务端口webserver_port用于 Web 界面heartbeat_service_port用于心跳。4.2 在 Docker Compose 中添加 BE 服务编辑/opt/doris-docker/docker-compose.yml文件在services部分添加 BE 服务的定义。doris-be-01: image: apache/doris:2.0.4-be-x86_64 container_name: doris-be-01 hostname: doris-be-01 networks: doris-network: ipv4_address: 172.20.0.20 # 可选的固定IP volumes: - ./be/conf/be.conf:/opt/apache-doris/be/conf/be.conf:ro - ./be/storage:/opt/apache-doris/be/storage - ./be/log:/opt/apache-doris/be/log environment: - FE_SERVERSdoris-fe-01:9010 # 指定 FE 地址用于 BE 启动时注册 depends_on: doris-fe: condition: service_healthy # 等待 FE 健康检查通过后再启动 restart: unless-stopped mem_limit: 8g # BE 通常需要更多内存 cpus: 4配置详解environment:FE_SERVERS环境变量在这里非常关键。它告诉 BE 容器在启动时应该向哪个 FE 节点发送注册请求。其值就是 FE 服务在 Docker 网络中的地址doris-fe-01:9010主机名edit_log_port。depends_on: 指定了启动顺序依赖并且条件是 FE 服务健康service_healthy。这确保了 BE 启动时 FE 肯定是可用的避免了因 FE 未就绪而导致的注册失败。mem_limit: BE 负责数据存储和计算建议分配比 FE 更多的内存例如 8GB。4.3 启动 BE 并检查注册状态启动 BE 服务并观察其日志。# 启动 BE 服务 docker-compose up -d doris-be-01 # 查看 BE 启动日志 docker-compose logs -f doris-be-01在 BE 日志中你应该看到它成功连接到 FE 并发送心跳... Ixxxxxx xx:xx:xx.xxxxxx xxxxx heartbeat.cpp:xxx] Master FE is doris-fe-01:9010 Ixxxxxx xx:xx:xx.xxxxxx xxxxx heartbeat.cpp:xxx] Successfully report heartbeat to FE. response status: OK ...验证 BE 注册状态 再次通过 MySQL 客户端连接到 FE执行SHOW BACKENDS\G;命令。MySQL [(none)] SHOW BACKENDS\G; *************************** 1. row *************************** BackendId: 10001 IP: 172.20.0.20 -- 注意这里应该是 Docker 网络内的 IP HeartbeatPort: 9050 BePort: 9060 HttpPort: 8040 BrpcPort: 8060 LastStartTime: 2024-xx-xx xx:xx:xx LastHeartbeat: 2024-xx-xx xx:xx:xx Alive: true SystemDecommissioned: false ClusterDecommissioned: false TabletNum: 0 DataUsedCapacity: 0.000 AvailCapacity: 1.000 TB TotalCapacity: 1.000 TB UsedPct: 0.00% MaxDiskUsedPct: 0.00% ErrMsg: Version: 2.0.4-xxx Status: {lastSuccessReportTabletsTime:..., lastStreamLoadTime:-1}重点关注Alive字段是否为true以及IP字段是否是你期望的 Docker 网络 IP如172.20.0.20。如果Alive为false或IP不正确例如是127.0.0.1或宿主机 IP说明注册有问题。5. 常见问题排查与解决方案即使按照上述步骤操作仍可能遇到问题。以下是 Docker 部署 Doris 时最常见的几个“坑”及其解决方案。5.1 FE 或 BE 启动失败日志显示端口被占用现象容器启动后立即退出日志报错Address already in use。原因容器内端口与宿主机映射端口冲突或 Docker 网络内端口冲突。排查检查docker-compose.yml中ports映射的宿主机端口如8030,9030是否已被其他进程占用netstat -tlnp | grep :9030。检查 FE/BE 配置文件中的服务端口如edit_log_port9010,be_port9060是否在 Docker 网络内唯一。确保不同容器的这些内部端口不冲突。解决更换宿主机映射端口例如- 9031:9030。如果是多节点集群确保每个节点的配置文件中的端口定义不冲突。5.2 BE 注册失败SHOW BACKENDS 显示 Alive false现象BE 容器运行正常日志也在发送心跳但 FE 查询显示Alive: falseErrMsg可能有连接超时等错误。原因这是 Docker 部署中最典型的问题。根本原因是 BE 向 FE 汇报的 IP 地址IP字段无法被 FE 反向访问。未配置priority_networksBE 可能使用了 Docker 默认网桥如172.17.0.x的 IP而 FE 在另一个网络或使用了主机名导致无法通信。防火墙/安全组限制宿主机或云服务器的防火墙可能阻止了 Docker 网络网段如172.20.0.0/16内部的通信。FE 的priority_networks也未配置FE 自身选择的 IP 也可能不对导致 BE 即使拿到了正确的 FE 地址FE 也无法响应 BE 的请求。排查与解决确认网络配置进入 BE 容器内部查看它实际使用的 IP。docker exec -it doris-be-01 bash cat /proc/net/fib_trie | grep -B1 -A2 172.20 # 查找 172.20 网段的 IP # 或使用 ip addr show确认该 IP 与SHOW BACKENDS中显示的IP一致并且属于priority_networks指定的网段。双向连通性测试在 BE 容器内尝试 ping FE 的主机名和 IP。docker exec -it doris-be-01 ping doris-fe-01 docker exec -it doris-fe-01 ping doris-be-01如果 ping 不通检查 Docker 网络设置docker network inspect doris-network确认两个容器都在该网络中并且Connectivity为true。检查防火墙临时关闭宿主机防火墙进行测试生产环境请谨慎。# CentOS 7 systemctl stop firewalld # Ubuntu sudo ufw disable终极检查清单FE 和 BE 的priority_networks必须配置且指向同一个Docker 自定义网络网段。docker-compose.yml中所有服务必须连接到同一个自定义网络doris-network。BE 的environment中的FE_SERVERS值必须使用 FE 在 Docker 网络中的主机名或固定 IP后跟正确的edit_log_port默认9010。5.3 通过宿主机 IP 无法访问 FE 的 Web UI 或 MySQL 端口现象浏览器访问http://宿主机IP:8030无法打开或 MySQL 客户端连接宿主机IP:9030失败。原因Docker 端口映射未生效或宿主机防火墙阻止了外部访问。排查检查容器是否正常运行且端口映射正确docker ps查看PORTS列确认有0.0.0.0:8030-8030/tcp这样的映射。在宿主机内部测试curl http://localhost:8030或mysql -h127.0.0.1 -P9030 -uroot。如果宿主机内能通说明是外部网络问题。检查宿主机防火墙规则确保放行了 8030 和 9030 端口。# CentOS 7 放行端口 firewall-cmd --permanent --add-port8030/tcp firewall-cmd --permanent --add-port9030/tcp firewall-cmd --reload5.4 数据或元数据丢失现象容器重启或重建后之前创建的表、数据库或数据不见了。原因没有正确配置持久化卷Volume。Docker 容器的文件系统是临时的。解决确保docker-compose.yml中的volumes映射正确并且宿主机上的目录如./fe/doris-meta,./be/storage存在且有适当的读写权限。在部署前这些目录应该是空的或不存在Docker Compose 会自动创建。5.5 容器资源不足导致进程被 Kill现象容器运行一段时间后突然停止日志显示Killed。原因容器内存或 CPU 使用超出限制被 Docker 或系统 OOM Killer 终止。解决调整docker-compose.yml中的mem_limit和cpus参数为容器分配更多资源。同时也要检查 Doris 自身的 JVM 配置JAVA_OPTS确保堆内存设置-Xmx小于容器的内存限制为操作系统和其他进程留出空间。6. 生产环境部署建议与扩展单节点部署适合测试和开发。对于生产环境需要考虑高可用、可扩展性和可维护性。6.1 构建高可用集群一个高可用的 Doris 集群通常需要3个 FE 节点 1个 Leader2个 Follower。通过docker-compose定义三个 FE 服务配置不同的hostname、FE_ID和元数据目录。在第一个 FE 启动后通过 MySQL 客户端连接使用ALTER SYSTEM ADD FOLLOWER “host:port”;命令添加其他 FE。多个 BE 节点 至少 3 个 BE 以实现数据多副本。同样定义多个 BE 服务确保它们配置正确的FE_SERVERS指向 FE Leader 或 Follower。关键点在于所有节点必须使用相同的自定义 Docker 网络并且priority_networks配置一致。6.2 配置与数据持久化策略配置文件管理 将fe.conf和be.conf纳入版本控制如 Git。使用环境变量或配置中心来管理不同环境开发、测试、生产的差异配置。数据备份 定期备份 FE 的元数据目录doris-meta和 BE 的数据目录storage。可以考虑使用 Docker 卷驱动将数据存储到更可靠的网络存储或云存储上。日志收集 将fe/log和be/log目录挂载到宿主机并接入 ELKElasticsearch, Logstash, Kibana或 LokiGrafana 等日志收集分析系统便于问题排查和监控。6.3 监控与运维健康检查 充分利用 Docker Compose 的healthcheck功能为 FE 和 BE 设置有效的健康检查命令以便编排工具能感知服务状态。资源监控 使用docker stats或 Prometheus cAdvisor Grafana 监控容器的 CPU、内存、网络和磁盘 IO 使用情况。Doris 自身监控 通过 FE 的 Web UI8030端口可以查看集群状态、查询统计和慢查询等信息。对于生产环境建议将 Doris 的监控指标也接入 Prometheus。6.4 版本升级与回滚Doris 版本升级需要谨慎。在 Docker 环境中升级流程可以简化为备份所有持久化数据目录和配置文件。修改docker-compose.yml中的镜像标签为新版本。逐个停止并删除旧容器docker-compose down然后启动新容器docker-compose up -d。Doris 的元数据格式通常向前兼容但务必查阅官方发布说明确认升级路径和注意事项。如果升级失败快速回滚的方式就是使用备份的数据目录并将镜像标签改回旧版本重新启动容器。通过将状态数据、配置与容器本身分离Docker 化部署为 Doris 集群的维护、扩展和迁移提供了极大的灵活性。理解 FE 和 BE 的通信机制并正确配置网络与持久化是成功部署的基石。
