Docker Compose 部署 Doris FE 完整教程（含内存大小修改+避坑指南）

16次阅读

Apache Doris 作为高性能 MPP 分析型数据库，Frontend（FE）节点承担着元数据管理、SQL 解析优化、集群协调等核心职责，是 Doris 集群的“大脑”。相较于单独使用 Docker 容器部署，Docker Compose 可通过配置文件统一管理容器，实现一键启停、环境标准化，大幅简化 Doris FE 的部署与运维成本。

在实际部署过程中，很多同学会遇到 Doris FE 启动失败的问题，其中最常见的就是 OpenJDK 内存申请失败报错，具体如下：

OpenJDK 64-Bit Server VM warning: INFO: os::commit_memory(0x0000000600000000, 8589934592, 0) failed; error='Not enough space' (errno=12)

该报错的核心原因的是 Doris FE 默认 JVM 堆内存配置为 8GB，若服务器可用内存不足，或未合理限制容器内存，就会导致内存申请失败。本文将详细讲解 Docker Compose 部署 Doris FE 的完整流程，重点说明内存大小的两种修改方法，并整合报错排查与解决方案，全程实操落地，兼顾新手友好性和生产环境实用性。

一、前置准备（必做步骤）

部署前需确保环境满足以下条件，避免后续出现兼容性、权限或资源不足问题，为部署过程保驾护航：

系统要求：CentOS 7+/Ubuntu 18.04+（推荐 CentOS 7，兼容性更好，避免 Ubuntu 系统内存限制相关坑）；
Docker 环境：已安装 Docker 19.03+ 和 Docker Compose 2.0+，并启动 Docker 服务（systemctl start docker）；
内存要求：服务器可用内存 ≥ 4GB（测试环境建议 ≥ 8GB，生产环境根据集群规模调整，避免内存不足报错）；
网络要求：开放 8030（FE HTTP 服务端口）、9030（MySQL 客户端连接端口）、9010（FE Thrift 服务端口），避免端口占用；
权限要求：拥有宿主机 root 权限，或可执行 sudo 命令，避免目录挂载、容器操作时权限不足。

补充验证：执行docker -v 和 docker compose version，若能正常显示版本信息，说明 Docker 和 Docker Compose 已安装成功；执行 free -h，查看 available 字段，确认服务器可用内存满足要求。自 Doris 2.1.8 版本后，官方已支持通过 Docker 快速部署，无需手动编译，进一步简化了部署流程。

二、Docker Compose 部署 Doris FE 完整步骤

本次采用 Doris 官方推荐镜像（apachedoris/doris-fe），通过 Docker Compose 配置文件统一管理容器参数，全程命令行操作，步骤清晰，新手可直接复制执行，同时支持数据持久化和配置自定义。

步骤1：创建部署目录（规范管理，避免混乱）

建议创建单独的 Doris FE 部署目录，用于存放 Docker Compose 配置文件、挂载数据、日志和配置文件，便于后续维护和升级：

# 创建根部署目录
mkdir -p /data/doris-fe
# 进入部署目录
cd /data/doris-fe
# 创建挂载子目录（用于数据、日志、配置持久化）
mkdir -p ./conf ./log ./meta
# 赋予目录权限（避免容器内权限不足，无法写入数据）
chmod -R 777 ./conf ./log ./meta

目录说明：conf 挂载 FE 配置文件，log 挂载日志文件，meta 挂载元数据文件，确保容器删除后数据不丢失，这也是生产环境部署的必要操作。

步骤2：编写 Docker Compose 配置文件

在 /data/doris-fe 目录下，创建 docker-compose.yml 配置文件，这是 Docker Compose 部署的核心，包含镜像、端口映射、目录挂载、容器内存限制等关键参数：

version: '3.8'
services:
  doris-fe:
    # 采用官方 Doris FE 镜像，可指定版本（如 :2.0.0、:3.0.3），默认最新稳定版
    image: apachedoris/doris-fe
    # 容器命名，便于后续操作（如启动、停止、进入容器）
    container_name: doris-fe
    # 赋予容器特权，避免权限不足问题（如挂载目录、修改配置）
    privileged: true
    # 端口映射：宿主机端口:容器端口，对应 FE 核心端口
    ports:
      - "8030:8030"   # FE HTTP 服务端口（Web 管理、API 调用）
      - "9030:9030"   # MySQL 客户端连接端口（用于执行 SQL、管理集群）
      - "9010:9010"   # FE Thrift 服务端口（与 BE 节点通信）
    # 目录挂载：将宿主机目录挂载到容器，实现数据持久化和配置自定义
    volumes:
      - ./conf:/opt/apache-doris/fe/conf
      - ./log:/opt/apache-doris/fe/log
      - ./meta:/opt/apache-doris/fe/meta
    # 容器内存限制（可选，建议配置，避免容器占用过多宿主机内存）
    deploy:
      resources:
        limits:
          memory: 8g  # 限制容器最大内存为 8GB，可根据服务器配置调整
    # 环境变量配置（核心：指定 FE 节点 ID 和集群信息）
    environment:
      - FE_ID=1  # FE 节点 ID，单节点默认为 1，集群部署需唯一
      - FE_SERVERS="fe:127.0.0.1:9010"  # FE 节点地址，单节点无需修改
    # 启动策略：容器退出后自动重启（可选，提升可用性）
    restart: always
    # 网络配置：使用自定义网络，便于后续添加 BE 节点组成集群
    networks:
      - doris-net

# 自定义网络，隔离 Doris 集群网络环境
networks:
  doris-net:
    driver: bridge

关键说明：

镜像选择：若需指定 Doris 版本，可在镜像后添加版本标签，如 apachedoris/doris-fe:3.0.3，建议使用稳定版（如 2.0.0、3.0.3），避免开发版兼容性问题；
内存限制：deploy.resources.limits.memory 用于限制容器最大内存，建议设置为 FE JVM 堆内存 + 2GB（预留内存供容器内部其他进程使用）；
环境变量：FE_ID 是 FE 节点唯一标识，单节点默认为 1，若部署 FE 集群（1主2备），需为每个节点分配不同 ID；
网络配置：自定义网络 doris-net，后续若添加 BE 节点，可直接加入该网络，实现 FE 与 BE 通信，无需额外配置端口映射。

步骤3：启动 Doris FE 容器

配置文件编写完成后，在 /data/doris-fe 目录下，执行以下命令，通过 Docker Compose 一键启动容器：

# 后台启动容器（-d 表示后台运行）
docker compose up -d
# 查看容器状态，确认启动情况
docker compose ps

若输出结果中，STATUS 为 Up（健康状态），说明容器启动成功；若启动失败（STATUS 为 Exited），大概率是内存不足，可先查看日志定位问题（后续会详细讲解）：

# 查看 Doris FE 容器日志，排查启动失败原因
docker compose logs -f doris-fe

步骤4：验证 FE 启动成功

提供两种验证方式，任选其一即可，确保 FE 正常运行，可正常对外提供服务：

Web 管理界面验证：浏览器输入 http://宿主机IP:8030，默认账号 root，密码为空，能成功登录并看到 FE 节点信息，即说明启动正常；
MySQL 客户端验证：若宿主机已安装 MySQL 客户端，执行以下命令连接 FE，能成功连接即正常（需开放 9030 端口）： mysql -h 127.0.0.1 -P 9030 -uroot
日志验证：执行 docker compose logs -f doris-fe，若出现 start fe success 或 Join and Alive are true，则说明 FE 启动成功，可正常参与集群运行。

三、核心操作：Docker Compose 环境下修改 Doris FE 内存大小

Doris FE 的内存核心是 JVM 堆内存，默认配置为 8GB（-Xmx8g -Xms8g），若服务器内存不足（如 8核16G 及以下），或容器内存限制过低，会触发本文开头的内存报错。以下提供两种修改方式，按需选择，均支持永久生效，适配不同部署场景。

核心原则：Docker 容器内存限制 ≥ FE JVM 堆内存 + 2GB，避免容器内存不足导致 JVM 内存申请失败；JVM 堆内存 -Xmx 和 -Xms 建议设为相同，避免动态扩容消耗资源，影响 FE 运行稳定性，同时建议设置为物理内存的 70%-80%，预留部分内存给堆外操作。

方式1：修改挂载的配置文件（推荐，生产环境首选）

适合已创建挂载目录（如步骤1中的 ./conf）的场景，直接修改宿主机挂载的 fe.conf 文件，无需进入容器，修改后重启容器即可生效，且修改内容永久保留（即使容器删除，重新启动后仍生效）。

编辑宿主机挂载的 fe.conf 配置文件： vim /data/doris-fe/conf/fe.conf若 conf 目录为空（首次部署），可先从容器中复制默认配置文件到宿主机挂载目录，再进行修改： # 从容器中复制默认 fe.conf 到宿主机挂载目录 docker cp doris-fe:/opt/apache-doris/fe/conf/fe.conf /data/doris-fe/conf/
找到 JAVA_OPTS 配置项（默认在文件顶部），修改 -Xmx（最大堆内存）和 -Xms（初始堆内存）的值，根据服务器配置适配调整：推荐配置（对应不同服务器配置，直接复制使用）：注意：JVM 堆内存最低不低于 2GB，否则可能导致 FE 运行时内存溢出（OOM），影响元数据管理和 SQL 执行；同时可根据需求调整元数据与查询管理相关参数，如 max_conn_per_user（单用户最大连接数），避免高并发场景下内存不足。
1. 8核16G 服务器（单 FE 节点，测试/小型集群）： JAVA_OPTS="-Xmx4g -Xms4g -XX:MetaspaceSize=512m -XX:MaxMetaspaceSize=1024m -XX:+UseG1GC"
2. 16核32G 服务器（单 FE 节点，中型集群）： JAVA_OPTS="-Xmx8g -Xms8g -XX:MetaspaceSize=512m -XX:MaxMetaspaceSize=1024m -XX:+UseG1GC"
3. 32核64G 服务器（主 FE 节点，大型集群）： JAVA_OPTS="-Xmx16g -Xms16g -XX:MetaspaceSize=1024m -XX:MaxMetaspaceSize=2048m -XX:+UseG1GC"
保存文件并退出，重启 Doris FE 容器，使内存配置生效： # 停止容器 docker compose stop # 启动容器（后台运行） docker compose up -d # 查看日志，确认重启成功，内存配置已生效 docker compose logs -f doris-fe
验证修改：进入容器，查看 JVM 进程，确认内存配置已更新： # 进入 Doris FE 容器 docker exec -it doris-fe /bin/bash # 查看 JVM 进程，确认 -Xmx 和 -Xms 参数已修改 ps -ef | grep java输出结果中，若能看到修改后的内存参数（如 -Xmx4g -Xms4g），则说明修改成功。

方式2：修改 Docker Compose 配置文件（通过环境变量覆盖）

适合不想修改 fe.conf 文件，或需要通过配置文件统一管理所有参数的场景，直接在 docker-compose.yml 中添加环境变量，覆盖默认 JVM 内存配置，重启容器后生效，同样支持永久生效。

编辑 Docker Compose 配置文件：vim /data/doris-fe/docker-compose.yml
在 environment 节点下，添加 JAVA_OPTS 环境变量，指定修改后的内存参数，示例如下（以修改为 4GB 为例）： environment: - FE_ID=1 - FE_SERVERS="fe:127.0.0.1:9010" # 添加 JAVA_OPTS 环境变量，覆盖默认内存配置 - JAVA_OPTS="-Xmx4g -Xms4g -XX:MetaspaceSize=512m -XX:MaxMetaspaceSize=1024m -XX:+UseG1GC"同时，建议调整容器内存限制（deploy.resources.limits.memory），使其匹配 JVM 堆内存，示例：memory: 6g（4GB JVM 堆内存 + 2GB 预留内存）。
保存文件并退出，重启容器，使配置生效： docker compose down # 停止并删除容器（数据已挂载，不会丢失） docker compose up -d # 重新启动容器
验证修改：同方式1，进入容器查看 JVM 进程，或查看日志，确认内存配置已生效。

补充：Ubuntu 系统 Docker 内存限制启用（避坑）

若使用 Ubuntu 系统，执行 docker info若出现 No swap limit support 警告，说明 Docker 内存限制功能未启用，此时 deploy.resources.limits.memory 参数无效，需先配置内核参数，重启服务器后生效：

# 编辑 grub 配置文件
vim /etc/default/grub
# 修改 GRUB_CMDLINE_LINUX 配置，添加内存限制参数
GRUB_CMDLINE_LINUX="cgroup_enable=memory swapaccount=1"
# 更新 grub 并重启服务器
sudo update-grub
sudo reboot

重启后，重新启动 Doris FE 容器，内存限制即可生效。此外，建议调整系统虚拟内存区域，避免内存相关报错，执行以下命令永久修改并立即生效： cat >> /etc/sysctl.conf << EOF vm.max_map_count = 2000000 EOF # 立即生效 sudo sysctl -p

四、常见问题：Docker Compose 部署 FE 内存报错（errno=12）完整解决

若启动容器时，出现 os::commit_memory failed; error='Not enough space' (errno=12) 报错，按以下步骤排查解决，优先级从高到低，新手优先执行方案1，可快速解决问题。

（一）错误核心解析

先拆解报错信息，避免误判（很多同学会误以为是磁盘空间不足，实则与磁盘无关）：

8589934592 对应 8GB 内存：这是 Doris FE 启动时，JVM 试图向容器（或宿主机）提交的内存大小（主要是堆内存）；
error='Not enough space'：核心原因是 容器内存限制过低、宿主机可用内存不足，或系统虚拟内存限制过低；
errno=12：对应系统错误码 ENOMEM，明确表示“没有足够的内存或地址空间供进程使用”。

常见诱因：Doris FE 默认 JVM 堆内存 8GB，若宿主机可用内存不足 8GB，或 Docker 容器内存限制低于 8GB，就会触发该报错，这也是测试环境中最易出现的问题。

（二）3步快速排查

检查宿主机可用内存：执行 free -h，重点关注 available 字段，要求available ≥ JVM 堆内存 + 2-4GB 预留内存；
检查容器内存限制：执行 docker inspect doris-fe | grep Memory，查看容器最大内存限制，若低于 JVM 堆内存，需调高容器内存；
检查系统虚拟内存限制：执行 ulimit -v（查看进程虚拟内存上限）和 cat /proc/sys/vm/max_map_count（查看 mmap 区域数上限），合格标准：ulimit -v ≥ 8388608 KB（8GB）、vm.max_map_count ≥ 65530。

（三）分步解决方案

方案1：降低 FE 的 JVM 堆内存（最直接、最推荐）

按照本文第三部分“修改 Doris FE 内存大小”的方法，将 JVM 堆内存调整为适配宿主机/容器的大小（如 8核16G 服务器改为 4GB），修改后重启容器，即可快速解决报错。这是最常用的解决方案，无需调整宿主机配置，适配所有场景。

方案2：调高 Docker 容器内存限制

若宿主机内存充足（如 16核32G），但容器内存限制过低，可修改 docker-compose.yml 中的 deploy.resources.limits.memory 参数，调高容器内存，示例：

deploy:
  resources:
    limits:
      memory: 10g  # 调高为 10GB，匹配 8GB JVM 堆内存

修改后，重启容器即可：docker compose down && docker compose up -d。

方案3：调高系统虚拟内存与地址空间限制

若宿主机和容器内存充足，但仍报错，需放开系统内存限制，分临时生效和永久生效两种方式，生产环境推荐永久生效：

临时生效（当前会话有效，重启服务器后失效）： ulimit -v unlimited # 放开虚拟内存上限（无限制） ulimit -n 65535 # 放开文件描述符限制，避免后续其他报错 sysctl -w vm.max_map_count=65530 # 调高 mmap 区域数上限设置完成后，重新启动容器即可。
永久生效（重启服务器后仍有效，生产环境推荐）： # 编辑 limits.conf 文件，添加内存和文件描述符限制 echo "* soft memlock unlimited" >> /etc/security/limits.conf echo "* hard memlock unlimited" >> /etc/security/limits.conf echo "* soft nofile 65535" >> /etc/security/limits.conf echo "* hard nofile 65535" >> /etc/security/limits.conf # 编辑 sysctl.conf 文件，添加 mmap 限制 echo "vm.max_map_count=65530" >> /etc/sysctl.conf # 使配置立即生效 sysctl -p

方案4：释放宿主机内存（临时应急）

若宿主机内存被其他无关进程占用过多，可临时释放内存（生产环境需避开业务高峰，避免影响其他服务）：

# 清理系统缓存（慎用，会清空缓存，短期可能影响读取性能）
sync && echo 3 > /proc/sys/vm/drop_caches
# 查看占用内存最高的进程
top -o %mem
# 杀死无关高内存进程（替换 <PID> 为实际进程ID）
kill -9 <PID>

方案5：关闭 Swap（Doris 官方推荐）

Swap 分区（交换分区）会将内存数据交换到磁盘，导致 Doris FE 运行卡顿，甚至间接引发内存申请失败，Doris 官方建议关闭 Swap，提升运行效率：

# 临时关闭 Swap
swapoff -a
# 永久关闭 Swap（注释 /etc/fstab 中的 Swap 配置，重启后生效）
sed -i '/swap/s/^/#/' /etc/fstab

五、生产环境配置建议（避坑指南）

1. 内存配置推荐（Docker Compose + FE JVM 匹配）

结合 Doris 官方建议和实际运维经验，整理不同服务器配置对应的 Docker 容器内存和 FE JVM 内存推荐配置，避免盲目设置，确保 FE 稳定运行：

宿主机配置	Docker 容器内存限制	FE JVM 配置（JAVA_OPTS）	适用场景
8核16G	8GB	-Xmx4g -Xms4g -XX:MetaspaceSize=512m -XX:MaxMetaspaceSize=1024m -XX:+UseG1GC	单 FE 节点，测试/小型集群（10节点以内）
16核32G	16GB	-Xmx8g -Xms8g -XX:MetaspaceSize=512m -XX:MaxMetaspaceSize=1024m -XX:+UseG1GC	单 FE 节点，中型集群（10-50节点）
32核64G	32GB	-Xmx16g -Xms16g -XX:MetaspaceSize=1024m -XX:MaxMetaspaceSize=2048m -XX:+UseG1GC	主 FE 节点，大型集群（50+节点）
64核128G	64GB	-Xmx32g -Xms32g -XX:MetaspaceSize=2048m -XX:MaxMetaspaceSize=4096m -XX:+UseG1GC	主 FE 节点，超大型集群/高并发场景

2. 其他生产环境注意事项

数据持久化必做：务必保留目录挂载（conf、log、meta），避免容器删除后元数据、日志和配置丢失，这是生产环境部署的核心要求；同时可定期备份 meta 目录，防止元数据损坏导致 FE 无法启动；
版本选择：建议使用 Doris 稳定版镜像（如 2.0.0、3.0.3），避免使用开发版，减少兼容性问题；若需升级版本，可直接修改 docker-compose.yml 中的镜像标签，重启容器即可；
集群部署建议：生产环境建议部署 FE 集群（1主2备），主备节点内存配置需一致，在 docker-compose.yml 中复制 fe 服务配置，修改 FE_ID 和容器名称，加入同一网络即可实现集群部署；同时可配置 BE 节点，组成完整 Doris 集群，提升可用性；
日志排查：若 FE 运行异常，优先查看挂载目录下的日志（./log/fe.log），或执行 docker compose logs -f doris-fe，快速定位问题；若出现 OutOfMemoryError，说明 JVM 堆内存设置过低，需适当调高；
安全配置：生产环境中，需为 MySQL 客户端 root 用户设置密码（通过 SET PASSWORD FOR 'root' = PASSWORD('your_password'); ），避免未授权访问；同时限制宿主机端口访问，仅开放给需要连接的服务和IP；
内存优化：高并发场景下，可调整 FE 查询相关参数，如 qe_max_connection（总查询连接数限制），避免并发过高导致内存不足；同时启用内存溢出到磁盘功能（enable_spill=true），减少 OOM 风险。

六、总结

Docker Compose 部署 Doris FE 的核心优势是“配置统一、一键启停、环境标准化”，相较于单独 Docker 部署，更适合生产环境运维和集群扩展。而内存配置是部署过程中的核心坑点——默认 8GB JVM 堆内存易导致内存申请失败，解决核心是“根据宿主机/容器内存，合理调整 JVM 堆内存，确保容器内存与 JVM 内存匹配”。

新手可按以下流程快速部署：前置环境准备 → 创建部署目录 → 编写 Docker Compose 配置 → 启动容器 → 验证服务 → 按需修改内存大小。若遇到内存报错，优先降低 JVM 堆内存，再根据需求调整容器内存和系统限制，即可快速解决问题。

生产环境中，需重点关注数据持久化、内存匹配和集群高可用，结合本文推荐的配置方案，可有效避免内存报错和数据丢失问题，确保 Doris FE 稳定运行，为 Doris 集群提供可靠的前端支撑。

正文完

可以使用微信扫码关注公众号（ID：xzluomor）