Apache Doris 是一个开源的、高性能的、实时的分析型数据库由百度贡献并捐赠给 Apache 基金会。它专为在线分析处理OLAP场景设计能够处理 PB 级别的数据并提供亚秒级的查询响应。对于 Python 开发者而言Doris 不仅提供了标准的 MySQL 协议接口还拥有强大的 Python 客户端支持使其能够无缝集成到 Python 数据分析、机器学习以及数据可视化的工作流中。这篇文章将直接切入主题带你完成从零开始的 Apache Doris 部署并重点演示如何通过 Python 连接、操作 Doris 数据库以及如何将其与 Apache Superset 这样的 BI 工具结合实现数据的可视化分析。整个过程将聚焦于实际可操作的步骤包括环境准备、服务启动、Python 连接、数据操作和可视化集成并会指出部署和使用过程中可能遇到的常见问题及其解决方案。无论你是想搭建一个本地测试环境还是为项目引入一个高性能的 OLAP 数据库这篇文章都能提供一条清晰的路径。1. 核心能力速览在深入部署细节之前我们先快速了解 Apache Doris 的核心特性这有助于判断它是否适合你的项目。能力项说明项目类型实时分析型数据库 (OLAP)开源协议Apache License 2.0主要接口MySQL 协议 (端口 9030)兼容大部分 MySQL 客户端和驱动Python 支持官方pydoris库支持 Python 3.9/3.10/3.11部署方式支持单机部署用于开发测试和集群部署用于生产硬件门槛内存和磁盘 I/O 是关键。单机测试建议 8GB 以上内存SSD 硬盘。CPU 核心数影响并发查询性能。启动方式通过二进制包或 Docker 镜像启动提供 Web UI (端口 8030) 和 MySQL 协议端口 (9030)是否支持 API支持通过 MySQL 协议或 RESTful API部分管理功能是否支持批量任务支持可通过INSERT INTO SELECT、Stream Load、Broker Load等方式高效导入海量数据适合场景实时数据看板、用户行为分析、日志分析、即席查询、与 Superset/Tableau 等 BI 工具集成2. 适用场景与使用边界Apache Doris 并非万能数据库理解其适用边界能帮助你更好地决策。它非常适合以下场景实时数据分析需要对最新产生的数据如用户点击流、交易日志进行快速聚合、筛选和查询。交互式 BI 报表作为 Superset、Tableau、FineBI 等 BI 工具的后端数据库支撑复杂的多维分析和仪表盘。数据仓库查询层作为数据湖如 Hive或事务型数据库如 MySQL之上的加速查询层。Python 数据科学栈集成通过pydoris或sqlalchemy-doris在 Jupyter Notebook 或 Python 脚本中直接查询分析数据。它可能不适合以下场景高并发在线事务处理 (OLTP)如频繁的单行增删改查。Doris 的强项是批量导入和复杂查询。非结构化数据存储如图片、视频、文档。Doris 是结构化/半结构化数据分析引擎。极低成本存储虽然支持冷热数据分层但相比纯粹的对象存储成本仍较高。使用边界与合规提醒数据安全生产环境务必通过防火墙、VPC 网络隔离、细粒度的用户权限控制来保护数据访问。资源隔离在多租户环境下需合理配置资源组避免单一查询耗尽集群资源。数据合规确保导入 Doris 的数据已获得合法授权遵守相关数据隐私法规。3. 环境准备与前置条件开始部署前请确保你的环境满足以下要求。我们将以Linux (CentOS 7/8 或 Ubuntu 20.04/22.04)系统为例进行说明。操作系统64位 Linux 发行版推荐 CentOS 7 或 Ubuntu 18.04。macOS 和 Windows 可通过 Docker 方式运行。Java 环境Doris 依赖 Java 运行环境。需要安装JDK 8 或 JDK 11推荐 OpenJDK。# 检查 Java 版本 java -version # 输出应类似openjdk version 1.8.0_392Python 环境用于后续的 Python 客户端连接和 BI 工具集成。推荐使用Python 3.9 至 3.11。# 检查 Python 版本 python3 --version # 输出应类似Python 3.9.18硬件资源内存建议至少8GB。FE前端进程约占用 2-4GBBE后端进程占用更多取决于数据量和并发。磁盘建议使用SSD。需要为数据存储预留足够空间例如 100GB。CPU建议 4 核以上。网络与端口确保以下端口在防火墙中开放或可本地访问8030: FE HTTP 端口Web UI 和 REST API9030: FE MySQL 协议端口应用程序连接8040: BE HTTP 端口9050: BE 心跳端口集群内部通信4. 安装部署与启动方式我们将采用官方二进制包进行单机部署这是最快速的上手方式。4.1 下载 Doris访问 Apache Doris 官网下载页 或 GitHub Releases选择适合你系统的版本。例如我们下载apache-doris-2.0.4-bin-x64.tar.gz。# 假设下载到 /opt/software 目录 cd /opt/software wget https://archive.apache.org/dist/doris/2.0.4/apache-doris-2.0.4-bin-x64.tar.gz tar -zxvf apache-doris-2.0.4-bin-x64.tar.gz cd apache-doris-2.0.44.2 部署 FEFrontendFE 负责元数据管理、客户端连接和查询规划。# 进入 FE 目录 cd fe # 修改 FE 配置文件 conf/fe.conf主要关注以下项单机可先保持默认 # meta_dir ${DORIS_HOME}/doris-meta # 元数据存储路径 # http_port 8030 # rpc_port 9020 # query_port 9030 # MySQL 协议端口 # 启动 FE ./bin/start_fe.sh --daemon # 检查日志确认启动成功 tail -f log/fe.log # 看到 “thrift server started with port 9020” 等字样表示启动成功4.3 部署 BEBackendBE 负责数据存储和查询执行。# 返回 Doris 根目录进入 BE 目录 cd ../be # 修改 BE 配置文件 conf/be.conf # storage_root_path ${DORIS_HOME}/storage # 数据存储路径可配置多个用分号隔开 # webserver_port 8040 # heartbeat_service_port 9050 # brpc_port 8060 # 启动 BE ./bin/start_be.sh --daemon # 检查日志确认启动成功 tail -f log/be.log # 看到 “heartbeat service start successfully” 等字样表示启动成功4.4 集群初始化与 BE 节点添加访问 Web UI浏览器打开http://你的服务器IP:8030使用默认账号root密码为空登录。初始化集群首次登录会引导你设置root密码完成初始化。添加 BE 节点在 Web UI 导航栏进入集群-后端点击添加后端。后端主机填写你的服务器 IP。心跳端口9050与be.conf配置一致。点击提交。稍等片刻状态应为Alive。至此一个单机版的 Doris 集群已经启动并运行。你可以通过 MySQL 客户端如mysql命令连接端口9030进行测试。5. 功能测试与效果验证Python 连接与操作现在我们来验证 Doris 的核心功能通过 Python 进行连接、建表、插入数据和查询。5.1 安装 Python 客户端首先安装 Doris 的官方 Python 客户端pydoris。pip install pydoris # 验证安装 pip list | grep pydoris # 预期输出pydoris 1.1.05.2 基础连接与操作测试创建一个 Python 脚本doris_test.py进行基本操作。# doris_test.py from pydoris import DorisClient # 1. 建立连接 client DorisClient( host127.0.0.1, # 你的 FE 节点 IP port9030, # FE MySQL 协议端口 userroot, password你设置的密码, # 如果未改密码则为空字符串 databasetest_db # 连接后默认使用的数据库 ) try: # 2. 创建数据库 client.execute(CREATE DATABASE IF NOT EXISTS test_db) print(Database test_db created or already exists.) # 3. 创建表 create_table_sql CREATE TABLE IF NOT EXISTS test_db.user_behavior ( user_id BIGINT, 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 ); client.execute(create_table_sql) print(Table user_behavior created or already exists.) # 4. 插入数据 (Stream Load 模拟) insert_sql INSERT INTO test_db.user_behavior VALUES (10001, 20001, 1, pv, 2024-01-01 10:00:00), (10001, 20002, 2, buy, 2024-01-01 10:05:00), (10002, 20001, 1, pv, 2024-01-01 10:10:00), (10002, 20003, 3, cart, 2024-01-01 10:15:00); client.execute(insert_sql) print(Data inserted successfully.) # 5. 查询数据 query_sql SELECT user_id, COUNT(*) as action_count, SUM(CASE WHEN behavior_type buy THEN 1 ELSE 0 END) as buy_count FROM test_db.user_behavior GROUP BY user_id ORDER BY action_count DESC; result client.query(query_sql) print(\nQuery Result:) for row in result: print(row) # 6. 查看表结构 desc_result client.query(DESC test_db.user_behavior) print(\nTable Structure:) for row in desc_result: print(row) except Exception as e: print(fAn error occurred: {e}) finally: # 7. 关闭连接 client.close()运行脚本python doris_test.py预期输出应能成功创建数据库、表插入数据并打印出分组聚合的查询结果和表结构。这证明 Python 到 Doris 的连接和基本 DDL/DML 功能正常。5.3 批量数据导入测试Doris 的优势在于海量数据批量导入。测试Stream Load方式这是一种高效的 HTTP 推送方式。 首先准备一个 CSV 文件sample_data.csv10003,20004,4,pv,2024-01-01 11:00:00 10003,20005,5,buy,2024-01-01 11:05:00 10004,20004,4,cart,2024-01-01 11:10:00然后使用 Python 的requests库模拟 Stream Load# stream_load_test.py import requests import base64 # Doris FE 的 HTTP 地址和端口 fe_host 127.0.0.1 fe_http_port 8030 table_name test_db.user_behavior user root password 你设置的密码 # 1. 读取 CSV 文件内容 with open(sample_data.csv, rb) as f: data f.read() # 2. 构建 Stream Load 请求 url fhttp://{fe_host}:{fe_http_port}/api/{table_name}/_stream_load headers { Authorization: Basic base64.b64encode(f{user}:{password}.encode()).decode(), Expect: 100-continue, format: csv, # 数据格式 column_separator: ,, # 列分隔符 line_delimiter: \n, # 行分隔符 } files {file: (data.csv, data)} response requests.put(url, headersheaders, filesfiles, timeout30) # 3. 解析响应 print(fStatus Code: {response.status_code}) print(fResponse Body: {response.text})判断成功标准HTTP 状态码为200且响应体 JSON 中Status字段为Success。这证明 Doris 的批量导入通道工作正常。6. 接口 API 与批量任务集成除了 Python 客户端Doris 还提供了多种方式供外部系统集成非常适合构建自动化数据管道。6.1 通过 MySQL 协议集成任何支持 MySQL 协议的客户端或库都可以连接 Doris。这是最通用的方式。# 使用 PyMySQL 连接 (另一种方式) import pymysql connection pymysql.connect( host127.0.0.1, port9030, userroot, password你设置的密码, databasetest_db, charsetutf8mb4 ) cursor connection.cursor() cursor.execute(SELECT VERSION()) print(fDoris Version: {cursor.fetchone()[0]}) cursor.close() connection.close()6.2 使用 RESTful API 进行管理Doris FE 提供了 RESTful API 用于部分集群管理操作如查看表信息、取消查询等。# 示例通过 curl 查看集群信息 curl -u root:密码 http://127.0.0.1:8030/api/cluster6.3 设计批量任务对于定时的批量数据导入可以结合调度系统如 Apache Airflow, DolphinScheduler和 Doris 的多种导入方式Broker Load从 HDFS、S3 等外部存储系统导入。Routine Load持续消费 Kafka 等消息队列中的数据。Spark Connector通过 Spark 进行复杂的数据处理和导入。一个简单的 Airflow DAG 示例如下概念# 伪代码展示思路 from airflow import DAG from airflow.operators.bash_operator import BashOperator from datetime import datetime default_args { owner: data_team, start_date: datetime(2024, 1, 1), } dag DAG(doris_daily_etl, default_argsdefault_args, schedule_intervaldaily) # 任务1: 从业务库导出数据到 CSV extract_task BashOperator( task_idextract_data, bash_commandpython /path/to/extract.py, dagdag ) # 任务2: 使用 curl 调用 Doris Stream Load API 导入 load_task BashOperator( task_idload_to_doris, bash_commandcurl -u user:pass -T /path/to/data.csv -H format:csv http://doris-fe:8030/api/db.table/_stream_load, dagdag ) # 任务3: 触发后续的聚合分析查询 analyze_task BashOperator( task_idrun_aggregation, bash_commandpython /path/to/run_analysis.py, dagdag ) extract_task load_task analyze_task7. 资源占用与性能观察部署后需要监控 Doris 的资源使用情况以便进行容量规划和性能调优。通过 Web UI 监控访问http://FE_IP:8030登录后进入监控面板。可以查看FE JVM 内存、BE 磁盘使用率、查询耗时分布、导入任务状态等关键指标。通过 SQL 命令查看-- 查看 BE 节点状态和负载 SHOW BACKENDS\G -- 查看正在运行的查询 SHOW PROC /current_queries; -- 查看慢查询默认超过1秒 SHOW PROC /slow_queries;性能优化观察点内存复杂的聚合查询或大表 Join 可能消耗大量 BE 内存。观察SHOW BACKENDS中的LastHeartbeat和Alive状态以及UsedCapacity。磁盘 I/O数据导入和 Compaction 操作会带来密集的 I/O。确保 BE 数据目录在 SSD 上。CPU高并发查询场景下CPU 使用率会上升。可以通过top或htop命令在服务器上直接观察be进程的 CPU 占用。网络在集群部署中BE 节点间的数据传输会占用网络带宽。降低资源占用的通用建议合理分区分桶根据查询模式设计表的分区Partition和分桶Bucket避免全表扫描。使用物化视图对频繁的聚合查询创建物化视图空间换时间。控制查询并发在 Web UI 或通过资源组Resource Group限制单个用户的查询并发数。及时删除过期数据使用PARTITION功能可以快速删除整个历史分区释放空间。8. 常见问题与排查方法部署和使用过程中你可能会遇到以下问题。问题现象可能原因排查方式解决方案FE/BE 启动失败端口被占用、Java 版本不兼容、配置文件错误、元数据目录权限不足。查看fe/log/fe.log或be/log/be.log中的错误日志。1.netstat -tlnp | grep 端口号检查端口。2. 确认 Java 版本为 8 或 11。3. 检查配置文件路径和格式。4. 确保doris-meta和storage目录有写权限。Python 连接超时或拒绝网络不通、防火墙未开放端口、FE 服务未启动、密码错误。1.telnet FE_IP 9030测试端口连通性。2. 检查 FE 进程ps aux | grep fe。3. 通过 MySQL 客户端直接连接验证密码。1. 配置防火墙开放 8030, 9030 端口。2. 重启 FE 服务。3. 通过 Web UI 重置密码。pydoris安装失败或导入错误Python 版本不兼容、pip 源问题、依赖冲突。查看pip install的错误信息。1. 确认 Python 版本为 3.9, 3.10, 3.11。2. 使用pip install pydoris -i https://pypi.tuna.tsinghua.edu.cn/simple换源。3. 在干净的虚拟环境中安装。在 Superset 中添加 Doris 数据源时找不到选项Superset 环境中未安装pydoris驱动。在 Superset 所在环境执行pip list | grep pydoris。在 Superset 的 Python 环境中安装pydoris并重启 Superset 服务。查询速度慢表未设置分区/分桶、缺少合适的索引Rollup、硬件资源不足、SQL 写法不佳。1. 使用EXPLAIN查看查询执行计划。2. 通过SHOW BACKENDS观察节点负载。1. 优化表结构增加分区和分桶。2. 为高频查询列创建 Rollup物化索引。3. 优化 SQL避免SELECT *使用谓词下推。Stream Load 导入失败CSV 格式不符、列数不匹配、数据中存在脏数据、网络超时。查看 Stream Load 返回的 JSON 响应中的Message和ErrorURL字段。1. 严格匹配column_separator,line_delimiter等参数。2. 使用max_filter_ratio参数容忍部分错误行。3. 检查网络稳定性增大超时时间。BE 节点状态为Dead心跳失败、BE 进程挂掉、网络分区。1. 检查 BE 机器网络和防火墙。2. 查看 BE 日志be/log/be.WARNING。3. 在 FE 上执行SHOW BACKENDS;。1. 重启 BE 进程./bin/start_be.sh --daemon。2. 如果数据副本未丢失节点恢复后会自动同步。3. 若节点无法恢复需通过DROP BACKEND和ADD BACKEND操作替换。9. 最佳实践与使用建议基于以上步骤和常见问题总结一些工程化实践建议开发与生产环境分离使用 Docker Compose 或独立的虚拟机部署开发测试环境生产环境使用物理机或云主机集群并配置监控告警。版本管理记录 Doris、pydoris以及相关客户端如 Superset的具体版本号便于问题复现和升级。配置管理将fe.conf和be.conf纳入版本控制如 Git记录每次变更。数据目录规划为storage_root_path配置多块 SSD 磁盘路径提升 I/O 能力。元数据目录meta_dir建议放在可靠存储上。连接管理在 Python 应用中使用连接池如DBUtils管理 Doris 连接避免频繁创建和销毁连接带来的开销。导入任务监控对于重要的批量导入任务Broker Load/Routine Load务必检查其状态 (SHOW LOAD WHERE LABEL ‘xxx’)并设置失败告警。权限最小化创建业务专用的数据库用户并授予其最小必要的权限如只读、只写特定库表避免使用root账号进行业务操作。备份与恢复定期备份 FE 的元数据目录。对于重要表可以考虑使用BACKUP和RESTORE命令进行数据备份或者通过EXPORT导出到对象存储。10. 总结与下一步通过本文你应该已经成功在单机环境下部署了 Apache Doris并通过 Python 完成了从连接、建表、插入到查询的全流程验证还了解了如何将其与 Superset 集成进行可视化。最值得尝试的点Doris 对 MySQL 协议的高度兼容性使得几乎任何能连接 MySQL 的工具都能无缝接入极大降低了使用门槛。其卓越的实时分析性能在处理亿级数据量的聚合查询时优势明显。最先应该验证的功能在你自己的业务数据集上尝试使用Stream Load或INSERT INTO SELECT导入一批数据然后运行几个典型的聚合查询感受其查询速度。同时用EXPLAIN命令查看执行计划理解 Doris 是如何工作的。最容易踩的坑忘记安装pydoris导致 Superset 连接失败务必在 BI 工具的环境中也安装对应的 Python 驱动。内存不足导致 BE 进程 OOM初次部署时务必监控 BE 的内存使用情况根据数据量调整mem_limit等参数。表设计不合理导致查询慢不要一上来就导入数据先花时间根据查询模式设计好分区键和分桶数。后续扩展方向集群部署将 FE 和 BE 部署到多台机器实现高可用和水平扩展。冷热数据分层将历史冷数据自动归档到对象存储如 S3降低存储成本。对接完整数据栈将 Doris 作为实时数仓的一环上游对接 Flink/Kafka 进行实时数据摄入下游对接 BI 工具和数据服务 API。深度性能调优学习使用Colocate Join、物化视图、Bitmap 索引等高级功能来优化特定查询场景。建议将本文中的配置和脚本保存下来作为你未来 Doris 项目的部署和连接基准。