最近在梳理 qData 数据中台部署流程时,我把官方文档重新过了一遍,也顺着 Docker 和原生安装两条路线实际捋了一次。
回头看,qData 的部署步骤本身并不算特别难,真正容易让人反复返工的,往往不是“大步骤不会做”,而是一些特别容易被忽略的小细节,比如:
所以这篇文章不打算按官方文档逐条照抄,而是换个角度,从“第一次部署最容易踩到哪些坑”这个视角来写。
这样更适合第一次接触 qData 的同学边部署边对照,也更方便后面继续拆成 Docker 专篇、原生安装专篇继续展开。
说明:下面出现的核心部署命令,优先采用官方文档中的原命令;像 docker ps、ss -lntp、ps -ef | grep 这类是额外补的自检命令,更适合写成避坑文。
qData 官方已经把部署路线拆得很明确:
如果你只是想先把平台快速跑起来,优先看 Docker Compose 部署;如果你想完整掌握环境、数据库、中间件、调度器和 qData 服务之间的依赖关系,那就走原生安装。
我的建议:

原生安装文档把环境要求写得很清楚:
JDK 1.8、Docker 24.0.7+、Docker Compose 2.20.2+;应用构建阶段还需要 Node.js 18+、npm v10.8.2+、Maven 3.6+。
可以先做一轮基础检查:
java -version
docker -v
docker-compose -v
node -v
npm -v
mvn -v
这是第一次部署时最常见的误区。
无论 Docker 还是原生安装,官方文档都把数据库初始化单独列为一步,这其实已经说明:
服务进程起来了,不等于系统真正可用。
所以建议从一开始就养成一个习惯:
每完成一步,就做一次最小化验证。
qData 的 Docker Compose 路线,官方已经预置了前端静态资源、DolphinScheduler、Hadoop、Flink、Spark 以及 .env 等内容,目标就是让用户少折腾环境,先把整个平台跑起来。
官方在 Linux 场景下给了离线安装命令和安装源文件(在百度网盘中,但是指南 Ubuntu 系统),也给了把当前用户加入 docker 用户组、以及用 docker -v、docker-compose -v 验证安装的做法。

# 进入 Docker 安装包目录(路径肯需要调整,根据解压后的路径来)
cd ~/20.04离线安装docker-24.0.7
# 安装 Docker 组件
sudo dpkg -i containerd.io_1.6.9-1_amd64.deb \
docker-ce_24.0.7-1~ubuntu.20.04~focal_amd64.deb \
docker-ce-cli_24.0.7-1~ubuntu.20.04~focal_amd64.deb \
docker-compose-plugin_2.6.0~ubuntu-focal_amd64.deb
# 将当前用户加入 docker 用户组
sudo usermod -aG docker $USER
newgrp docker
# 验证安装
sudo docker -v
sudo docker-compose -v避坑点:
可选自检命令:
docker info
docker ps
官方 Docker 文档里明确提到,如果用 MySQL 作为主库,需要修改 .env,把 DB_TYPE=dm8 改成 DB_TYPE=mysql;同时后续命令要切换到 docker-compose-mysql.yml。
cd ~/qData/docker
sudo vi .env# 数据库类型,可选值:dm8 或 mysql
DB_TYPE=mysql避坑点:
.env 里改了数据库类型,但启动命令还是默认 compose 文件
官方文档明确写了:首次运行必须先初始化数据库。
DM8 默认场景执行:
sudo docker-compose --profile schema up -d如果你用的是 MySQL:
sudo docker-compose -f docker-compose-mysql.yml --profile schema up -d如果初始化时报 entrypoint.sh 权限或 Win 换行符问题,官方也给了处理命令:
cd ~/qData
sudo chmod -R 755 docker
sudo chown -R $USER:$USER ./docker
sed -i 's/\r$//' ./database/dm8/entrypoint.sh
sed -i 's/\r$//' ./database/dm8/entrypoint-arm64.sh
ls -l ./database/dm8/entrypoint.sh然后再重新执行初始化:
sudo docker-compose --profile schema up -d避坑点:
--profile all up -d,把初始化这一步带过去了


官方给出的启动命令是:
sudo docker-compose --profile all up -dMySQL 场景:
sudo docker-compose -f docker-compose-mysql.yml --profile all up -d然后可以查看服务状态:
sudo docker-compose --profile all ps官方还专门提醒了两件事:
可选自检命令:
docker ps --format "table {{.Names}}\t{{.Status}}"
ss -lntp | grep -E '80|12345|8080'
curl -I http://127.0.0.1:80避坑点:
docker-compose ps 结果截图




Docker 路线里,官方也顺手给了几条常用命令,写进避坑文很有用:
# 查看所有服务运行状态
sudo docker-compose --profile all ps
# 暂停 qData 所有服务(数据不丢)
sudo docker-compose --profile all stop
# 重启所有服务
sudo docker-compose --profile all restart
# 完全关闭并删除数据(恢复默认环境)
sudo docker-compose --profile all down
sudo docker-compose --profile schema down你可以在正文里强调一句:
stop 和 down 不是一回事。
前者是停服务,后者可能直接把测试环境清掉,排查时一定别手快。
原生安装官方链路是:环境安装 → 数据库与中间件部署 → 数据初始化 → 应用构建 → 调度器组件部署 → 调度器部署 → qData 服务部署。
这条路线更适合完整掌握依赖关系,但也更容易因为“前后参数不一致”而反复返工。
官方环境安装文档里给了 JDK 1.8 的安装和环境变量配置方法:
sudo mkdir -p /opt/java
sudo tar zxvf jdk-8u201-linux-x64.tar.gz -C /opt/java/
sudo mv /opt/java/jdk1.8.0_201 /opt/java/openjdk# /etc/profile 末尾追加
export JAVA_HOME=/opt/java/openjdk
export JRE_HOME=${JAVA_HOME}/jre
export CLASSPATH=.:${JAVA_HOME}/lib:${JRE_HOME}/lib
export PATH=.:${JAVA_HOME}/bin:$PATHsource /etc/profile
java -version避坑点:
JAVA_HOME 没配/etc/profile,但没 source
官方数据初始化文档里,以 DM8 为例,要求把 init-qdata.sql 放到 /data/dm8 下,然后进入容器执行初始化。
# 查看容器
docker ps -a
# 进入容器
docker exec -it <container_id> bash
# 连接数据库
/home/dmdba/dmdb/bin/disql SYSDBA/InC3tmU4bijT4vkl
# 创建用户、模式及授权
create user "QDATA" identified by "2LKqLVMQ!xVDT$Qx" hash with SHA512 salt;
grant "PUBLIC","SOI","DBA" to "QDATA";
# 初始化数据库
set define off
set CHAR_CODE UTF8
/home/dmdba/data/init-qdata.sql
set define on避坑点:

官方应用构建文档里,后端打包的核心命令是:
# 项目根目录下
mvn clean package -Dmaven.test.skip构建结果包括:
qdata-server/target/qdata-server.jarqdata-quality/target/qdata-quality.jarqdata-etl/target/qdata-etl-3.8.8.jar前端构建命令则是:
cd qData/qdata-ui
yarn install
npm run build:prod
sudo mkdir -p ./www/qdata
sudo cp -r dist/* ./www/qdata避坑点:
可选自检命令:
ls -lh qdata-server/target/
ls -lh qdata-quality/target/
ls -lh qData/qdata-ui/dist/官方把“调度器组件部署”和“调度器部署”分成了两篇,这一点本身就很值得写进避坑文。Spark、Flink 属于能力组件,DolphinScheduler 才是调度器本体。
sudo mkdir -p /opt/soft
sudo chmod -R 777 /opt/soft
cd /opt/soft
sudo tar -zxvf spark-3.5.6-bin-hadoop3.tgz
sudo mv spark-3.5.6-bin-hadoop3 spark
cd /opt/soft
sudo unzip flink-1.17.2.zip
sudo mv flink-1.17.2 flinkSpark 环境变量:
nano ~/.bashrc
# 末尾追加(设置成你自己的服务器ip地址)
export SPARK_MASTER_HOST=192.168.3.38
source ~/.bashrcsudo mkdir -p /dolphinscheduler
tar -xzvf apache-dolphinscheduler-3.2.2-bin.tar.gz创建部署用户并配置 sudo 免密:
sudo useradd dolphinscheduler
echo 'dolphinscheduler:Str0ng@Pass!' | sudo chpasswd
sudo sed -i '$adolphinscheduler ALL=(ALL) NOPASSWD: NOPASSWD: ALL' /etc/sudoers
sudo sed -i 's/Defaults requiretty/#Defaults requiretty/g' /etc/sudoers
sudo chown -R dolphinscheduler:dolphinscheduler apache-dolphinscheduler-*-bin
sudo chmod -R 755 apache-dolphinscheduler-*-bin
sudo chown -R dolphinscheduler:dolphinscheduler /dolphinscheduler
sudo chown -R dolphinscheduler:dolphinscheduler /tmp/dolphinscheduler避坑点:

官方 qData 服务部署文档给出的后端启动命令是:
qdata-server.jar 用 8083,qdata-quality.jar 用 8088,最终访问地址写的是 http://服务器IP:8082。
# 启动 qdata-server
nohup java -server -jar \
-Djava.security.egd=file:/dev/./urandom \
-Dspring.profiles.active=prod \
-Dserver.port=8083 \
qdata-server.jar >>/dev/null &
# 启动 qdata-quality
nohup java -server -jar \
-Djava.security.egd=file:/dev/./urandom \
-Dspring.profiles.active=prod \
-Dserver.port=8088 \
qdata-quality.jar >>/dev/null &可选自检命令:
ps -ef | grep qdata
ss -lntp | grep -E '8082|8083|8088'
curl -I http://127.0.0.1:8082提醒:
真正容易混乱的不是“服务能不能启动”,而是 Nginx 监听端口、前端访问地址、后端启动端口、反向代理目标端口这几套口径必须保持一致。
一旦这里没统一,就很容易出现“后端是好的,页面却打不开”这种典型问题。
先解决“有没有结果”的问题,再回头看细节。
# 首次初始化
sudo docker-compose --profile schema up -d
# 启动全部服务
sudo docker-compose --profile all up -d
# 查看状态
sudo docker-compose --profile all ps建议顺序:
docker ps
ps -ef | grep javass -lntp | grep -E '80|8082|8083|8088|12345'
curl -I http://127.0.0.1:80重点确认:
重点确认:
回头看这次 qData 部署过程,我最大的感受是:
真正容易踩坑的,往往不是“大步骤不会做”,而是“小细节没提前确认”。
如果你只是想快速体验平台,Docker Compose 路线会更适合;
如果你想完整掌握环境、数据库、中间件、调度器和服务之间的关系,那么原生安装更有价值。
如果是第一次接触 qData,我更建议你:
这样不仅更容易建立整体认知,也更方便在遇到问题时快速判断自己到底卡在哪一层。
原创声明:本文系作者授权腾讯云开发者社区发表,未经许可,不得转载。
如有侵权,请联系 cloudcommunity@tencent.com 删除。
原创声明:本文系作者授权腾讯云开发者社区发表,未经许可,不得转载。
如有侵权,请联系 cloudcommunity@tencent.com 删除。