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)的兼容性。
  • 高校学生与研究人员 :用于课程设计、数据库实验或学术研究,单机部署降低了环境搭建的复杂度。

重要使用边界与警告

  1. 非生产用途 :官方文档明确警告,本文介绍的快速部署方法 仅用于本地开发和测试,请勿用于生产环境 。生产环境必须部署多副本、多节点集群以保证数据可靠性和服务高可用。
  2. 数据易丢失 :无论是 Docker 部署还是单机二进制部署,数据都存储在本地。容器销毁或机器重启可能导致数据丢失。务必做好重要数据的备份。
  3. 资源限制 :单机部署所有组件共享同一台机器的资源,其性能和处理能力有上限,无法体现 Doris 分布式架构的横向扩展优势。
  4. 功能完整性 :大部分核心功能在单机版上均可使用,但一些依赖多节点交互的高级特性(如某些数据均衡策略)可能无法完全体验。

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 对文件描述符数量和虚拟内存区域有较高要求,需要修改系统限制。
    # 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
    
    注意:修改 limits.conf 后需要重新登录终端会话才能生效。
  • 磁盘空间 :建议预留 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 的前端节点,负责元数据管理、查询解析和规划。

  1. 配置 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
    
  2. 启动 FE
    ./fe/bin/start_fe.sh --daemon
    
  3. 验证 FE 启动 :查看日志 fe/log/fe.log 或使用 MySQL 客户端连接。
    mysql -uroot -P9030 -h127.0.0.1 -e "show frontends;"
    
    看到 Alive IsMaster true 即表示启动成功。

步骤 3:部署 Backend (BE) BE 是后端节点,负责数据存储和查询执行。

  1. 配置 BE :编辑 be/conf/be.conf 文件。
    vi be/conf/be.conf
    
    同样设置 JAVA_HOME priority_networks
    JAVA_HOME = /usr/lib/jvm/java-17-openjdk-amd64
    priority_networks = 127.0.0.1/32
    
  2. 启动 BE
    ./be/bin/start_be.sh --daemon
    
  3. 将 BE 加入集群 :通过已启动的 FE 执行 SQL 命令添加 BE 节点。
    mysql -uroot -P9030 -h127.0.0.1
    
    在 MySQL 客户端中执行:
    ALTER SYSTEM ADD BACKEND "127.0.0.1:9050";
    
  4. 验证 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 批量任务注意事项

  1. Label 去重 label 是导入任务的唯一标识。Doris 默认保证相同 label 的导入任务仅成功执行一次。这对于实现“精确一次”语义的批量任务至关重要。
  2. 错误处理 :脚本中应增加更完善的错误处理和重试机制,例如网络异常重试、解析失败告警等。
  3. 资源控制 :大批量导入时,注意监控 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 性能观察点

  1. 导入速度 :使用 SHOW LOAD; 命令查看历史导入任务的状态、耗时和数据量,计算导入速率。
  2. 查询响应 :在 MySQL 客户端中执行 SHOW PROC ‘/current_queries’; 可以查看当前正在执行的查询及其耗时。
  3. 系统监控 :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 环境变量。

通用排查流程

  1. 查日志 :遇到任何问题,首先查看对应组件的日志文件,日志路径通常在 fe/log/ be/log/ 下,重点关注 .warn.log .error.log
  2. 查状态 :使用 SHOW FRONTENDS; SHOW BACKENDS; 确认组件状态。
  3. 查网络 :使用 ping telnet 检查组件间网络连通性(如 FE 的 9030 端口,BE 的 9050 端口)。
  4. 查资源 :使用 free -h df -h top 检查内存、磁盘和 CPU 使用情况。

9. 最佳实践与使用建议

为了让你的单机 Doris 环境更稳定、高效,遵循以下实践建议:

  1. 环境隔离 :为 Doris 创建专用的操作系统用户(如 doris ),避免使用 root 运行,提高安全性。
  2. 目录规划 :手动部署时,将数据目录( storage_root_path )放在独立的、容量大的磁盘分区上,与系统盘和应用日志分离。
  3. 配置备份 :在修改 fe.conf be.conf 前,先备份原文件。每次升级版本时,注意对比配置文件的差异。
  4. 数据备份 :单机版数据易丢失,定期对重要测试数据使用 BACKUP 命令或导出为 CSV/Parquet 文件进行备份。
  5. 版本管理 :关注 Apache Doris 官网 GitHub Releases ,及时获取新版本和 bug 修复。升级前务必在测试环境充分验证。
  6. 连接管理 :在应用程序中,使用连接池来管理到 Doris 的 MySQL 连接,避免频繁创建和销毁连接带来的开销。
  7. 测试流程标准化 :对于需要反复验证的功能,可以编写 SQL 脚本或 Python 程序,将建表、导入、查询、清理等步骤自动化,提高效率。
  8. 明确使用边界 :时刻记住这是 单机测试环境 。任何关于性能、高可用、大规模并发的结论,都需要在真正的分布式生产集群中重新验证。

10. 总结与下一步

通过本文,你应该已经成功在单机环境下部署并运行了 Apache Doris,体验了其作为实时分析数据库的基础功能。单机版部署的核心价值在于 快速搭建、零成本学习 ,让你能够无障碍地接触和测试 Doris 的各项特性,为后续在生产环境中的评估和应用打下坚实基础。

最值得尝试的下一步

  1. 体验更多数据导入方式 :尝试使用 Broker Load 从 HDFS 或 S3 导入数据,或者使用 Routine Load 从 Kafka 实时订阅数据,这是 Doris 在实时数仓中的核心能力。
  2. 探索高级特性 :创建 物化视图(Rollup) 来加速特定查询,或者使用 动态分区 功能管理时间序列数据。
  3. 集成生态工具 :尝试使用 Flink-Doris-Connector 实现 CDC 数据实时同步,或使用 dbt 等工具在 Doris 上进行数据转换。
  4. 向集群部署过渡 :当你理解了单机部署的各个组件后,可以尝试规划一个由 3 个 FE(实现高可用)和多个 BE(实现水平扩展)组成的生产级集群部署方案。

单机部署是起点,不是终点。希望这篇文章能帮你扫清入门障碍,顺利开启 Apache Doris 的高性能数据分析之旅。如果在部署中遇到其他问题,建议多查阅官方文档和活跃的 GitHub 社区,大部分常见问题都能找到解决方案。

Logo

汇聚全球AI编程工具,助力开发者即刻编程。

更多推荐