---

最近在梳理 qData 数据中台部署流程时，我把官方文档重新过了一遍，也顺着 Docker 和原生安装两条路线实际捋了一次。

回头看，qData 的部署步骤本身并不算特别难，真正容易让人反复返工的，往往不是“大步骤不会做”，而是一些特别容易被忽略的小细节，比如：

• Docker 和 Docker Compose 装了，但其实不能正常用
• 数据库初始化漏掉了，结果系统“能启动但不能用”
• 原生安装里环境和中间件装好了，但参数没有统一，或者配置的不对
• 调度器配置文件和 qData 主程序的配置文件配置的不对，越配越乱
• qData 服务启动了，但前后端某些链路其实没有真正打通

所以这篇文章不打算按官方文档逐条照抄，而是换个角度，从“第一次部署最容易踩到哪些坑”这个视角来写。
这样更适合第一次接触 qData 的同学边部署边对照，也更方便后面继续拆成 Docker 专篇、原生安装专篇继续展开。

说明：下面出现的核心部署命令，优先采用官方文档中的原命令；像 docker ps、ss -lntp、ps -ef | grep 这类是额外补的自检命令，更适合写成避坑文。

---

---

一、开始之前，先别急着装：这几件事不确认，后面大概率会返工

1. 没先想清楚走 Docker 还是原生安装

qData 官方已经把部署路线拆得很明确：
如果你只是想先把平台快速跑起来，优先看 Docker Compose 部署；如果你想完整掌握环境、数据库、中间件、调度器和 qData 服务之间的依赖关系，那就走原生安装。

我的建议：

• 想快速验证：先 Docker
• 想长期维护：再原生
• 最稳妥：先 Docker 跑通，再原生拆开理解

2. 环境没先检查，做到一半才发现缺依赖

原生安装文档把环境要求写得很清楚：
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

3. 把“服务启动了”当成“部署成功了”

这是第一次部署时最常见的误区。
无论 Docker 还是原生安装，官方文档都把数据库初始化单独列为一步，这其实已经说明：

服务进程起来了，不等于系统真正可用。

所以建议从一开始就养成一个习惯：
每完成一步，就做一次最小化验证。

---

二、Docker 部署最容易踩的几个坑

qData 的 Docker Compose 路线，官方已经预置了前端静态资源、DolphinScheduler、Hadoop、Flink、Spark 以及 .env 等内容，目标就是让用户少折腾环境，先把整个平台跑起来。

1. 坑一：Docker 和 Docker Compose 装了，但其实不能正常用

官方在 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

避坑点：

• 只安装不验证，后面所有报错都像是 qData 的问题，但是可能和 qData 并没有关系
• 用户没加到 docker 组，后面命令要么全带 sudo，要么权限报错
• 版本过低，后面 compose profile 命令可能不稳定

可选自检命令：

docker info
docker ps

2. 坑二：部署包解压了，但数据库类型没改对

官方 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 文件
• 数据库类型没确认，结果初始化和启动命令走了两套口径

3. 坑三：漏掉数据库初始化，结果系统“能启动但不能用”

官方文档明确写了：首次运行必须先初始化数据库。
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，把初始化这一步带过去了
• 脚本权限和换行符问题不处理，重复执行只会一直报错
• 初始化没单独验收，后面页面打不开时很难判断问题在哪一层
  

4. 坑四：容器都起来了，但页面就是打不开

官方给出的启动命令是：

sudo docker-compose --profile all up -d

MySQL 场景：

sudo docker-compose -f docker-compose-mysql.yml --profile all up -d

然后可以查看服务状态：

sudo docker-compose --profile all ps

官方还专门提醒了两件事：

• 首次启动后建议等 1-2 分钟，让容器初始化完成
• 如果访问不了，优先检查服务器防火墙是否开放 80 端口，以及是否有端口占用问题

可选自检命令：

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 结果截图

DolphinScheduler 页面截图

f访问 Spark 页面（需要去docker-compose-spark.yml 把对应的端口打开）

浏览器访问 qData，验证码已经出来了。

5. 坑五：不会停、不会看、不会重启，后面排查很被动

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 服务部署。
这条路线更适合完整掌握依赖关系，但也更容易因为“前后参数不一致”而反复返工。

1. 坑一：JDK 装了，但环境变量没生效

官方环境安装文档里给了 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:$PATH

source /etc/profile
java -version

避坑点：

• JDK 解压了，但 JAVA_HOME 没配
• 配了 /etc/profile，但没 source
• 后面 ZooKeeper、Java 服务启动失败，根因其实在这里
  

2. 坑二：数据库初始化没当回事，结果系统一直“半可用”

官方数据初始化文档里，以 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

避坑点：

• 数据库服务起来了，就默认初始化也完成了
• 初始化 SQL 放错路径
• 初始化失败后没单独确认，后面功能页报错才回头查
  

3. 坑三：应用构建最容易暴露前面环境问题

官方应用构建文档里，后端打包的核心命令是：

# 项目根目录下
mvn clean package -Dmaven.test.skip

构建结果包括：

• qdata-server/target/qdata-server.jar
• qdata-quality/target/qdata-quality.jar
• qdata-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

避坑点：

• 后端 jar 没打出来，就急着部署服务
• 前端 build 成功了，但静态资源没拷贝到正确位置
• Node / yarn / Maven 版本不对，最后都在构建阶段集中爆出来

可选自检命令：

ls -lh qdata-server/target/
ls -lh qdata-quality/target/
ls -lh qData/qdata-ui/dist/

4. 坑四：DolphinScheduler 调度器部署

官方把“调度器组件部署”和“调度器部署”分成了两篇，这一点本身就很值得写进避坑文。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 flink

Spark 环境变量：

nano ~/.bashrc
# 末尾追加（设置成你自己的服务器ip地址）
export SPARK_MASTER_HOST=192.168.3.38

source ~/.bashrc

调度器部署示例

sudo 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

避坑点：

• Spark/Flink 没准备好，却一直怀疑 DolphinScheduler 本体
• 忘了给部署用户 sudo 免密，后面权限问题很难看
• 资源中心目录没提前建好

5. 坑五：qData 服务启动了，但前后端并没有真正打通

官方 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 监听端口、前端访问地址、后端启动端口、反向代理目标端口这几套口径必须保持一致。
一旦这里没统一，就很容易出现“后端是好的，页面却打不开”这种典型问题。

---

四、如果想少走弯路，我更建议按这个顺序部署

1. 先用 Docker 跑通整体流程

先解决“有没有结果”的问题，再回头看细节。

# 首次初始化
sudo docker-compose --profile schema up -d

# 启动全部服务
sudo docker-compose --profile all up -d

# 查看状态
sudo docker-compose --profile all ps

2. 再按原生安装拆开理解每一层

建议顺序：

1. 环境准备
2. 数据库与中间件
3. 数据初始化
4. 应用构建
5. 调度器组件
6. 调度器本体
7. qData 服务

---

五、部署完成后，建议重点检查这几项

1. 服务状态是否正常

docker ps
ps -ef | grep java

2. 页面和端口是否可访问

ss -lntp | grep -E '80|8082|8083|8088|12345'
curl -I http://127.0.0.1:80

3. 数据初始化是否完成

重点确认：

• 数据库里是否已存在 qData 所需对象
• 不是只有数据库服务起来，而是初始化也真正完成

4. 前后端链路是否打通

重点确认：

• 前端页面是否能访问
• 前端接口调用是否正常
• 后端是否能访问数据库和中间件
• 调度链路是否可用

---

总结

回头看这次 qData 部署过程，我最大的感受是：

真正容易踩坑的，往往不是“大步骤不会做”，而是“小细节没提前确认”。

如果你只是想快速体验平台，Docker Compose 路线会更适合；
如果你想完整掌握环境、数据库、中间件、调度器和服务之间的关系，那么原生安装更有价值。

如果是第一次接触 qData，我更建议你：

• 先把 Docker 主流程跑通
• 再按原生安装把每一层拆开理解
• 每完成一步，都做一次最小化验证

这样不仅更容易建立整体认知，也更方便在遇到问题时快速判断自己到底卡在哪一层。