Apache Doris 单机部署指南:从零搭建高性能实时分析数据库测试环境
Apache Doris 是一个开源的、基于 MPP 架构的高性能实时分析型数据库,由百度贡献并捐赠给 Apache 基金会。它最大的特点就是快,特别是在海量数据的实时查询和分析场景下,性能表现非常出色。对于想快速上手体验、进行本地开发测试,或者学习其架构原理的同学来说,单机版部署是最高效的入门方式。这篇文章就带你从零开始,在单台机器上完成 Apache Doris 的部署、启动和基础功能验证,让你在最短时间内跑起来一个可用的 Doris 环境。
单机版部署的核心价值在于“轻量”和“快速”。你不需要准备多台服务器,也不需要复杂的集群配置,一台普通的开发机(Linux 或 Mac)就能搞定。无论是想用它来替代 MySQL 做复杂分析,还是作为 Flink、Kafka 等流处理框架的数据目的地进行测试,单机版都能满足需求。本文将重点介绍两种主流的单机部署方式:Docker 快速启动和手动二进制包部署,并详细对比它们的优缺点、资源占用和适用场景。读完本文,你将能独立完成 Doris 单机环境的搭建、基础 SQL 操作,并了解常见问题的排查方法。
1. 核心能力速览
在深入部署细节前,我们先通过一个表格快速了解单机版 Apache Doris 的核心特性和部署要求,帮助你判断是否适合你的场景。
| 能力项 | 说明 |
|---|---|
| 项目类型 | 高性能、实时分析型数据库 (MPP) |
| 开源协议 | Apache License 2.0 |
| 主要功能 | 实时数据导入、高并发低延迟查询、标准 SQL 支持、与 Hadoop/Spark/Flink 生态集成 |
| 单机部署模式 | 所有组件 (FE, BE) 部署在同一台机器,模拟集群行为 |
| 推荐硬件 | 最低 4核 CPU,8GB 内存,50GB 磁盘空间。建议 8核 CPU,16GB 内存以上以获得更好体验。 |
| 内存/磁盘占用 | 启动后内存占用约 2-4GB(视数据量),磁盘占用随数据增长。无显存要求。 |
| 支持平台 | Linux (Ubuntu/CentOS 等主流发行版)、macOS (通过 Docker)、Windows (通过 WSL2 或 Docker) |
| 启动方式 | 1. Docker 一键脚本 (最快) 2. 手动下载二进制包部署 (更灵活) |
| 是否支持 API | 是,提供 MySQL 协议接口 (端口 9030)、HTTP REST API (端口 8030) |
| 是否支持批量任务 | 是,支持通过 Stream Load、Broker Load、Routine Load 等方式批量导入数据。 |
| 适合场景 | 本地开发测试、功能验证、概念验证(POC)、个人学习、小规模数据分析和实验。 |
| 不适合场景 | 生产环境 。单机版不具备高可用和数据冗余能力,机器故障会导致服务中断和数据丢失。 |
2. 适用场景与使用边界
单机版 Doris 的核心目标是提供一个轻量、无依赖的沙箱环境。它非常适合以下几类用户:
- 开发者与学习者 :想要了解 Doris 的功能特性、SQL 语法、数据导入导出流程,而不必关心复杂的分布式集群运维。
- 数据架构师/分析师 :需要在本地验证 Doris 对特定业务查询的性能,或者测试其与现有数据管道(如 Flink CDC、Kafka)的兼容性。
- 高校学生与研究人员 :用于课程设计、数据库实验或学术研究,单机部署降低了环境搭建的复杂度。
重要使用边界与警告 :
- 非生产用途 :官方文档明确警告,本文介绍的快速部署方法 仅用于本地开发和测试,请勿用于生产环境 。生产环境必须部署多副本、多节点集群以保证数据可靠性和服务高可用。
- 数据易丢失 :无论是 Docker 部署还是单机二进制部署,数据都存储在本地。容器销毁或机器重启可能导致数据丢失。务必做好重要数据的备份。
- 资源限制 :单机部署所有组件共享同一台机器的资源,其性能和处理能力有上限,无法体现 Doris 分布式架构的横向扩展优势。
- 功能完整性 :大部分核心功能在单机版上均可使用,但一些依赖多节点交互的高级特性(如某些数据均衡策略)可能无法完全体验。
3. 环境准备与前置条件
开始部署前,请确保你的环境满足以下基本要求。我们将分别针对 Docker 方式 和 手动部署方式 进行说明。
3.1 通用前置条件
- 操作系统 :推荐使用 Ubuntu 20.04/22.04 或 CentOS 7/8 等主流 Linux 发行版。macOS 可通过 Docker Desktop 运行。Windows 用户建议使用 WSL2 (Ubuntu) 或 Docker Desktop。
- 网络 :能够访问互联网,以下载 Docker 镜像或二进制安装包。
- 用户权限 :建议使用普通用户操作,避免直接使用 root。如果必须使用 root,请注意命令差异。
3.2 Docker 部署环境准备
如果你的目标是 最快速度体验 ,Docker 是最佳选择。
- Docker Engine :版本 20.10.0 或更高。安装命令可参考 Docker 官方文档。
- Docker Compose :部分脚本可能用到,建议安装。
- 磁盘空间 :至少预留 5GB 空间用于拉取镜像和存储数据。
- 内存 :建议为 Docker 分配至少 4GB 内存。
在终端执行 docker --version 和 docker-compose --version 验证安装。
3.3 手动部署环境准备
如果你需要更深入地了解组件构成和配置,或者环境无法安装 Docker,可以选择手动部署。
- Java 环境 :Apache Doris 依赖 Java 运行环境。 推荐使用 Java 17 。确保
JAVA_HOME环境变量已正确设置。# 检查Java版本 java -version # 检查JAVA_HOME echo $JAVA_HOME - 系统参数调整 :Doris 对文件描述符数量和虚拟内存区域有较高要求,需要修改系统限制。
注意:修改 limits.conf 后需要重新登录终端会话才能生效。# 1. 修改最大文件打开数 sudo vi /etc/security/limits.conf # 在文件末尾添加 * soft nofile 1000000 * hard nofile 1000000 # 2. 修改虚拟内存区域数量 (对于Linux) sudo vi /etc/sysctl.conf # 在文件末尾添加 vm.max_map_count=2000000 # 使配置生效 sudo sysctl -p - 磁盘空间 :建议预留 20GB 以上空间,用于存放二进制包、日志和数据。
4. 安装部署与启动方式
我们将详细介绍两种部署方式的完整步骤。
4.1 方式一:使用 Docker 快速启动(推荐新手)
这是官方提供的、最快捷的体验方式,自 Doris 2.1.8 版本后支持。
步骤 1:下载快速启动脚本 从 Doris 官方 GitHub 仓库或文档站获取 start-doris.sh 脚本,并赋予执行权限。
# 假设脚本已下载到当前目录
chmod 755 start-doris.sh
步骤 2:启动 Doris 集群 运行脚本,并通过 -v 参数指定要启动的 Doris 版本,例如最新的 3.0.8。
bash start-doris.sh -v 3.0.8
脚本会自动拉取对应版本的 Docker 镜像,并启动一个包含 1 个 FE (Frontend) 和 1 个 BE (Backend) 的容器集群。
步骤 3:验证集群状态 等待脚本执行完毕(通常需要1-2分钟拉取镜像)。之后,使用 MySQL 客户端连接 Doris 的 FE 节点进行验证。
# 检查 FE 状态,确保 Join 和 Alive 均为 true
mysql -uroot -P9030 -h127.0.0.1 -e 'SELECT `host`, `join`, `alive` FROM frontends()'
# 检查 BE 状态,确保 Alive 为 true (或 1)
mysql -uroot -P9030 -h127.0.0.1 -e 'SELECT `host`, `alive` FROM backends()'
如果看到类似下面的输出,说明单机集群已成功启动并运行。
# FE 状态
+-----------+------+-------+
| host | join | alive |
+-----------+------+-------+
| 127.0.0.1 | true | true |
+-----------+------+-------+
# BE 状态
+-----------+-------+
| host | alive |
+-----------+-------+
| 127.0.0.1 | 1 |
+-----------+-------+
4.2 方式二:手动部署二进制包
这种方式更接近生产部署的流程,有助于理解 Doris 的组件架构。
步骤 1:下载二进制包 访问 Apache Doris 官网下载页面 ,选择适合你操作系统的最新稳定版二进制包(如 apache-doris-3.0.8-bin-x64.tar.gz )。下载后解压。
tar -zxvf apache-doris-3.0.8-bin-x64.tar.gz
cd apache-doris-3.0.8-bin-x64
步骤 2:部署 Frontend (FE) FE 是 Doris 的前端节点,负责元数据管理、查询解析和规划。
- 配置 FE :编辑
fe/conf/fe.conf文件,至少需要设置JAVA_HOME和priority_networks。
找到并修改以下配置(根据你的实际路径):vi fe/conf/fe.conf# 指定你的 Java 17 安装路径 JAVA_HOME = /usr/lib/jvm/java-17-openjdk-amd64 # 指定 FE 监听的 IP 段,单机部署可设为本地回环地址 priority_networks = 127.0.0.1/32 - 启动 FE :
./fe/bin/start_fe.sh --daemon - 验证 FE 启动 :查看日志
fe/log/fe.log或使用 MySQL 客户端连接。
看到mysql -uroot -P9030 -h127.0.0.1 -e "show frontends;"Alive和IsMaster为true即表示启动成功。
步骤 3:部署 Backend (BE) BE 是后端节点,负责数据存储和查询执行。
- 配置 BE :编辑
be/conf/be.conf文件。
同样设置vi be/conf/be.confJAVA_HOME和priority_networks:JAVA_HOME = /usr/lib/jvm/java-17-openjdk-amd64 priority_networks = 127.0.0.1/32 - 启动 BE :
./be/bin/start_be.sh --daemon - 将 BE 加入集群 :通过已启动的 FE 执行 SQL 命令添加 BE 节点。
在 MySQL 客户端中执行:mysql -uroot -P9030 -h127.0.0.1ALTER SYSTEM ADD BACKEND "127.0.0.1:9050"; - 验证 BE 状态 :
确认mysql -uroot -P9030 -h127.0.0.1 -e "show backends;"Alive列为true。
至此,手动部署的单机 Doris 集群已搭建完成。
5. 功能测试与效果验证
环境启动后,我们通过一系列 SQL 操作来验证 Doris 的核心功能是否正常工作。
5.1 连接数据库
使用任意 MySQL 客户端(如命令行 mysql 、DBeaver、Navicat)连接 Doris。
mysql -uroot -P9030 -h127.0.0.1
默认无密码。连接成功后,提示符会变为 MySQL [(none)]> 。
5.2 创建数据库与表
执行以下 SQL,创建一个测试数据库和一张表。这里我们创建一个包含多种数据类型(TINYINT, DECIMAL, CHAR, INT)的表。
-- 创建数据库
CREATE DATABASE demo_db;
USE demo_db;
-- 创建测试表
CREATE TABLE IF NOT EXISTS user_behavior (
user_id INT,
item_id BIGINT,
category_id INT,
behavior_type VARCHAR(10),
ts DATETIME
)
DUPLICATE KEY(user_id, item_id) -- 指定排序列
DISTRIBUTED BY HASH(user_id) BUCKETS 10 -- 分桶方式
PROPERTIES (
"replication_num" = "1" -- 单机部署,副本数设为1
);
执行成功无报错,说明建表语法支持正常。
5.3 数据导入测试
Doris 支持多种数据导入方式。这里测试最直接的 INSERT INTO 和流式导入 Stream Load 。
方式 A:使用 INSERT INTO(小批量数据)
INSERT INTO user_behavior VALUES
(1001, 20001, 101, 'pv', '2024-07-28 10:00:00'),
(1001, 20002, 102, 'buy', '2024-07-28 10:05:00'),
(1002, 20001, 101, 'cart', '2024-07-28 10:10:00'),
(1003, 20003, 103, 'pv', '2024-07-28 10:15:00');
执行后应返回 Query OK, 4 rows affected 。
方式 B:使用 Stream Load(模拟批量文件导入) 准备一个 CSV 文件 test_data.csv :
1004,20004,104,fav,2024-07-28 10:20:00
1005,20005,105,pv,2024-07-28 10:25:00
在 Linux 终端下,使用 curl 命令通过 HTTP API 导入:
curl -u root: \
-H “label:test_load_1” \
-H “column_separator:,” \
-T ./test_data.csv \
http://127.0.0.1:8030/api/demo_db/user_behavior/_stream_load
返回的 JSON 中 “Status”: “Success” 表示导入成功。
5.4 数据查询测试
执行一些典型的分析查询,验证 Doris 的查询能力。
-- 1. 简单查询所有数据
SELECT * FROM user_behavior ORDER BY ts;
-- 2. 聚合查询:统计每种用户行为类型的数量
SELECT behavior_type, COUNT(*) as cnt FROM user_behavior GROUP BY behavior_type;
-- 3. 条件过滤与排序:查询用户1001的所有行为,按时间倒序
SELECT * FROM user_behavior WHERE user_id = 1001 ORDER BY ts DESC;
-- 4. 时间函数使用:按小时统计PV量
SELECT DATE_FORMAT(ts, ‘%Y-%m-%d %H:00:00’) as hour_time, COUNT(*) as pv_count
FROM user_behavior
WHERE behavior_type = ‘pv’
GROUP BY hour_time;
如果所有查询都能快速返回正确结果,说明 Doris 的 SQL 引擎工作正常。
5.5 简单性能观察
插入更多数据(例如,使用循环或准备一个万行级别的 CSV 文件通过 Stream Load 导入),然后执行 SELECT COUNT(*) FROM user_behavior; 和带过滤条件的聚合查询,感受其响应速度。单机版对于百万级以内的数据量,简单查询通常在秒级甚至毫秒级返回。
6. 接口 API 与批量任务
除了 MySQL 协议,Doris 提供了丰富的 HTTP REST API 用于集成和自动化,这对于批量任务尤其重要。
6.1 核心 HTTP API 简介
- Stream Load :用于流式或小批量数据导入,上文已演示。这是 最常用 的 API。
- 查询执行 :通过
/api/query提交 SQL 查询,以 JSON 格式获取结果。 - 任务管理 :查看导入作业状态等。
6.2 使用 Python 调用 Stream Load API 实现批量任务
以下是一个简单的 Python 脚本示例,演示如何自动化批量数据导入。
import requests
import json
import time
def stream_load_to_doris(file_path, table, host=‘127.0.0.1’, port=8030, db=‘demo_db’, user=‘root’, password=’’):
“””
使用Stream Load API将文件数据导入Doris
“””
url = f‘http://{host}:{port}/api/{db}/{table}/_stream_load’
headers = {
‘Authorization’: ‘Basic ‘ + (user + ‘:’ + password).encode(‘utf-8’).b64encode().decode(),
‘label’: f‘batch_load_{int(time.time())}‘, # 唯一标签,用于去重
‘column_separator’: ‘,’, # CSV列分隔符
}
try:
with open(file_path, ‘rb’) as f:
response = requests.put(url, headers=headers, data=f, timeout=30)
result = response.json()
if result.get(‘Status’) == ‘Success’:
print(f“导入成功! Label: {result.get(‘Label’)}“)
return True
else:
print(f“导入失败: {result}“)
return False
except Exception as e:
print(f“请求异常: {e}“)
return False
# 使用示例
if __name__ == ‘__main__’:
# 假设有一个数据文件 batch_data.csv
success = stream_load_to_doris(‘./batch_data.csv’, ‘user_behavior’)
print(“批量导入任务执行完成。” if success else “任务失败。”)
你可以将此脚本结合定时任务(如 crontab)或工作流调度器(如 DolphinScheduler),实现定时的批量数据同步任务。
6.3 批量任务注意事项
- Label 去重 :
label是导入任务的唯一标识。Doris 默认保证相同 label 的导入任务仅成功执行一次。这对于实现“精确一次”语义的批量任务至关重要。 - 错误处理 :脚本中应增加更完善的错误处理和重试机制,例如网络异常重试、解析失败告警等。
- 资源控制 :大批量导入时,注意监控 BE 节点的内存和磁盘 IO,避免影响查询性能。可通过调整
be.conf中的load_process_max_memory_limit_percent等参数进行控制。
7. 资源占用与性能观察
了解单机部署下 Doris 的资源消耗模式,有助于规划机器配置和排查性能问题。
7.1 进程与内存占用
部署完成后,使用 ps 和 top 命令观察进程。
# 查看Doris相关进程
ps aux | grep -E ‘(fe|be)‘ | grep -v grep
# 查看内存占用概况 (示例输出)
# USER PID %CPU %MEM VSZ RSS TTY STAT START TIME COMMAND
# doris 12345 2.3 8.5 5.8g 3.4g ? Sl 10:00 2:30 /java … org.apache.doris.PaloFe
# doris 23456 5.1 15.2 8.2g 6.1g ? Sl 10:00 5:10 /java … org.apache.doris.PaloBe
- FE 进程 :主要占用 JVM 堆内存,默认约 2-4GB,负责元数据管理和查询规划,CPU 消耗相对较低。
- BE 进程 :占用内存较多,包括 JVM 堆内存和用于数据查询的本地内存(如向量化计算缓存)。它是资源消耗的主力,尤其在数据导入和复杂查询时。
7.2 磁盘空间占用
数据主要存储在 BE 节点的 storage 目录下(手动部署路径为 be/storage )。你可以使用 du 命令查看。
# 查看BE数据目录大小
du -sh /path/to/apache-doris/be/storage
磁盘占用会随着数据量和副本数(单机 replication_num=1 )线性增长。
7.3 性能观察点
- 导入速度 :使用
SHOW LOAD;命令查看历史导入任务的状态、耗时和数据量,计算导入速率。 - 查询响应 :在 MySQL 客户端中执行
SHOW PROC ‘/current_queries’;可以查看当前正在执行的查询及其耗时。 - 系统监控 :Doris 内置了 Web UI(FE 的
http_port,默认 8030),访问http://127.0.0.1:8030可以查看简单的系统监控和查询统计。
7.4 如何降低资源占用(开发环境)
对于纯粹的学习和功能验证,如果资源紧张,可以调整配置:
- 调整 JVM 堆内存 :修改
fe/conf/fe.conf和be/conf/be.conf中的-Xmx和-Xms参数(在JAVA_OPTS中),例如设置为-Xmx2g -Xms2g。 - 减少 BE 存储路径 :
be.conf中的storage_root_path可以指向一个较小但速度较快的磁盘(如 SSD)。 - 关闭不必要的日志 :调整
log级别为WARN以减少日志输出和磁盘写入。
8. 常见问题与排查方法
部署和运行过程中可能会遇到一些问题,下表列出了常见问题及解决方法。
| 问题现象 | 可能原因 | 排查方式 | 解决方案 |
|---|---|---|---|
| MySQL 客户端连接失败 | 1. FE 未启动 2. 端口被占用 3. 网络或防火墙限制 |
1. ps aux | grep fe 2. netstat -tlnp | grep 9030 3. 查看 fe/log/fe.warn.log |
1. 启动 FE 2. 杀死占用端口的进程或修改 fe/conf/fe.conf 中的 query_port 3. 检查防火墙规则 |
BE 添加失败 ( show backends 中 Alive 为 false) |
1. BE 未启动 2. FE 与 BE 网络不通 3. 心跳端口未开放 |
1. ps aux | grep be 2. 检查 be.conf 和 fe.conf 的 priority_networks 3. 查看 be/log/be.WARNING |
1. 启动 BE 2. 确保配置的 IP 可互相访问,单机建议都用 127.0.0.1 3. 检查 be_heartbeat_port (默认9050) 是否被防火墙拦截 |
Stream Load 导入返回 Fail 或 Label Already Exists |
1. 数据格式错误 2. Label 重复 3. 表不存在或列不匹配 |
1. 查看返回的 JSON 中的 Message 字段 2. 检查 label 是否唯一 3. 核对表名和列分隔符 |
1. 根据错误信息修正数据或格式 2. 更换一个新的 label 3. 确认数据库、表名和 CSV 列数 |
| 查询速度慢 | 1. 数据未正确分桶 2. 缺少合适的索引(Rollup) 3. 资源不足 |
1. EXPLAIN 查看查询计划 2. 分析查询模式 3. 监控 top 和 iostat |
1. 考虑按查询条件重新设计分桶键 2. 为高频查询创建 Rollup 表(物化视图) 3. 升级硬件或优化配置 |
Docker 部署时提示 Error: Docker environment not detected (Mac) |
Docker 命令行工具未在 PATH 中 | 执行 docker version 测试 |
创建符号链接: sudo ln -s /Applications/Docker.app/Contents/Resources/bin/docker /usr/local/bin/docker |
启动时报错 Too many open files |
系统文件描述符限制太低 | ulimit -n |
按照 3.3 节 修改 /etc/security/limits.conf 并重启会话 |
| Java 版本不兼容 | 使用了过低或过高的 Java 版本 | java -version |
必须安装 Java 17 ,并正确设置 JAVA_HOME 环境变量。 |
通用排查流程 :
- 查日志 :遇到任何问题,首先查看对应组件的日志文件,日志路径通常在
fe/log/和be/log/下,重点关注.warn.log和.error.log。 - 查状态 :使用
SHOW FRONTENDS;和SHOW BACKENDS;确认组件状态。 - 查网络 :使用
ping、telnet检查组件间网络连通性(如 FE 的 9030 端口,BE 的 9050 端口)。 - 查资源 :使用
free -h、df -h、top检查内存、磁盘和 CPU 使用情况。
9. 最佳实践与使用建议
为了让你的单机 Doris 环境更稳定、高效,遵循以下实践建议:
- 环境隔离 :为 Doris 创建专用的操作系统用户(如
doris),避免使用 root 运行,提高安全性。 - 目录规划 :手动部署时,将数据目录(
storage_root_path)放在独立的、容量大的磁盘分区上,与系统盘和应用日志分离。 - 配置备份 :在修改
fe.conf或be.conf前,先备份原文件。每次升级版本时,注意对比配置文件的差异。 - 数据备份 :单机版数据易丢失,定期对重要测试数据使用
BACKUP命令或导出为 CSV/Parquet 文件进行备份。 - 版本管理 :关注 Apache Doris 官网 和 GitHub Releases ,及时获取新版本和 bug 修复。升级前务必在测试环境充分验证。
- 连接管理 :在应用程序中,使用连接池来管理到 Doris 的 MySQL 连接,避免频繁创建和销毁连接带来的开销。
- 测试流程标准化 :对于需要反复验证的功能,可以编写 SQL 脚本或 Python 程序,将建表、导入、查询、清理等步骤自动化,提高效率。
- 明确使用边界 :时刻记住这是 单机测试环境 。任何关于性能、高可用、大规模并发的结论,都需要在真正的分布式生产集群中重新验证。
10. 总结与下一步
通过本文,你应该已经成功在单机环境下部署并运行了 Apache Doris,体验了其作为实时分析数据库的基础功能。单机版部署的核心价值在于 快速搭建、零成本学习 ,让你能够无障碍地接触和测试 Doris 的各项特性,为后续在生产环境中的评估和应用打下坚实基础。
最值得尝试的下一步 :
- 体验更多数据导入方式 :尝试使用
Broker Load从 HDFS 或 S3 导入数据,或者使用Routine Load从 Kafka 实时订阅数据,这是 Doris 在实时数仓中的核心能力。 - 探索高级特性 :创建 物化视图(Rollup) 来加速特定查询,或者使用 动态分区 功能管理时间序列数据。
- 集成生态工具 :尝试使用 Flink-Doris-Connector 实现 CDC 数据实时同步,或使用 dbt 等工具在 Doris 上进行数据转换。
- 向集群部署过渡 :当你理解了单机部署的各个组件后,可以尝试规划一个由 3 个 FE(实现高可用)和多个 BE(实现水平扩展)组成的生产级集群部署方案。
单机部署是起点,不是终点。希望这篇文章能帮你扫清入门障碍,顺利开启 Apache Doris 的高性能数据分析之旅。如果在部署中遇到其他问题,建议多查阅官方文档和活跃的 GitHub 社区,大部分常见问题都能找到解决方案。
更多推荐



所有评论(0)