首页
学习
活动
专区
圈层
工具
发布
社区首页 >专栏 >新手必看!qData 数据中台部署避坑指南,90%的人都踩过这些雷

新手必看!qData 数据中台部署避坑指南,90%的人都踩过这些雷

原创
作者头像
用户7648376
修改2026-03-10 23:34:52
修改2026-03-10 23:34:52
410
举报

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

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

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

所以这篇文章不打算按官方文档逐条照抄,而是换个角度,从“第一次部署最容易踩到哪些坑”这个视角来写。

这样更适合第一次接触 qData 的同学边部署边对照,也更方便后面继续拆成 Docker 专篇、原生安装专篇继续展开。

说明:下面出现的核心部署命令,优先采用官方文档中的原命令;像 docker psss -lntpps -ef | grep 这类是额外补的自检命令,更适合写成避坑文。


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

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

qData 官方已经把部署路线拆得很明确:

如果你只是想先把平台快速跑起来,优先看 Docker Compose 部署;如果你想完整掌握环境、数据库、中间件、调度器和 qData 服务之间的依赖关系,那就走原生安装。

我的建议:

  • 想快速验证:先 Docker
  • 想长期维护:再原生
  • 最稳妥:先 Docker 跑通,再原生拆开理解
官方2种部署方式
官方2种部署方式

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

原生安装文档把环境要求写得很清楚:

JDK 1.8、Docker 24.0.7+、Docker Compose 2.20.2+;应用构建阶段还需要 Node.js 18+、npm v10.8.2+、Maven 3.6+。

可以先做一轮基础检查:

代码语言:bash
复制
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 -vdocker-compose -v 验证安装的做法。

官方部署包
官方部署包
代码语言:bash
复制
# 进入 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 命令可能不稳定

可选自检命令:

代码语言:bash
复制
docker info
docker ps
docker 信息
docker 信息

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

官方 Docker 文档里明确提到,如果用 MySQL 作为主库,需要修改 .env,把 DB_TYPE=dm8 改成 DB_TYPE=mysql;同时后续命令要切换到 docker-compose-mysql.yml

代码语言:bash
复制
cd ~/qData/docker
sudo vi .env
代码语言:env
复制
# 数据库类型,可选值:dm8 或 mysql
DB_TYPE=mysql

避坑点:

  • .env 里改了数据库类型,但启动命令还是默认 compose 文件
  • 数据库类型没确认,结果初始化和启动命令走了两套口径
更改数据库启动类型
更改数据库启动类型

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

官方文档明确写了:首次运行必须先初始化数据库。

DM8 默认场景执行:

代码语言:bash
复制
sudo docker-compose --profile schema up -d

如果你用的是 MySQL:

代码语言:bash
复制
sudo docker-compose -f docker-compose-mysql.yml --profile schema up -d

如果初始化时报 entrypoint.sh 权限或 Win 换行符问题,官方也给了处理命令:

代码语言:bash
复制
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

然后再重新执行初始化:

代码语言:bash
复制
sudo docker-compose --profile schema up -d

避坑点:

  • 一上来就 --profile all up -d,把初始化这一步带过去了
  • 脚本权限和换行符问题不处理,重复执行只会一直报错
  • 初始化没单独验收,后面页面打不开时很难判断问题在哪一层
    entrypoint.sh 权限查看截图
    entrypoint.sh 权限查看截图
初始化命令执行过程截图
初始化命令执行过程截图
启动qData命令后容器全部启动截图
启动qData命令后容器全部启动截图

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

官方给出的启动命令是:

代码语言:bash
复制
sudo docker-compose --profile all up -d

MySQL 场景:

代码语言:bash
复制
sudo docker-compose -f docker-compose-mysql.yml --profile all up -d

然后可以查看服务状态:

代码语言:bash
复制
sudo docker-compose --profile all ps

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

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

可选自检命令:

代码语言:bash
复制
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 ps 结果截图
    docker ps 结果截图
    DolphinScheduler 页面
    DolphinScheduler 页面
    yml 把对应的端口打开)
     Spark 页面
    Spark 页面
    出来了。
    浏览器访问 qData
    浏览器访问 qData
    查很被动
  • 只会重启,不会先查端口和防火墙
  • 看到页面打不开,就误判成镜像有问题

Docker 路线里,官方也顺手给了几条常用命令,写进避坑文很有用:

代码语言:bash
复制
# 查看所有服务运行状态
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

你可以在正文里强调一句:

stopdown 不是一回事。

前者是停服务,后者可能直接把测试环境清掉,排查时一定别手快。


三、原生安装最容易踩的几个坑

原生安装官方链路是:环境安装 → 数据库与中间件部署 → 数据初始化 → 应用构建 → 调度器组件部署 → 调度器部署 → qData 服务部署。

这条路线更适合完整掌握依赖关系,但也更容易因为“前后参数不一致”而反复返工。

1. 坑一:JDK 装了,但环境变量没生效

官方环境安装文档里给了 JDK 1.8 的安装和环境变量配置方法:

代码语言:bash
复制
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
代码语言:bash
复制
# /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
代码语言:bash
复制
source /etc/profile
java -version

避坑点:

  • JDK 解压了,但 JAVA_HOME 没配
  • 配了 /etc/profile,但没 source
  • 后面 ZooKeeper、Java 服务启动失败,根因其实在这里
    java -version 输出截图
    java -version 输出截图

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

官方数据初始化文档里,以 DM8 为例,要求把 init-qdata.sql 放到 /data/dm8 下,然后进入容器执行初始化。

代码语言:bash
复制
# 查看容器
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 放错路径
  • 初始化失败后没单独确认,后面功能页报错才回头查
    使用数据库工具查看数据表是否已经创建完毕
    使用数据库工具查看数据表是否已经创建完毕

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

代码语言:bash
复制
# 项目根目录下
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

前端构建命令则是:

代码语言:bash
复制
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 版本不对,最后都在构建阶段集中爆出来

可选自检命令:

代码语言:bash
复制
ls -lh qdata-server/target/
ls -lh qdata-quality/target/
ls -lh qData/qdata-ui/dist/

4. 坑四:DolphinScheduler 调度器部署

官方把“调度器组件部署”和“调度器部署”分成了两篇,这一点本身就很值得写进避坑文。Spark、Flink 属于能力组件,DolphinScheduler 才是调度器本体。

调度器组件示例

代码语言:bash
复制
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 环境变量:

代码语言:bash
复制
nano ~/.bashrc
# 末尾追加(设置成你自己的服务器ip地址)
export SPARK_MASTER_HOST=192.168.3.38

source ~/.bashrc

调度器部署示例

代码语言:bash
复制
sudo mkdir -p /dolphinscheduler

tar -xzvf apache-dolphinscheduler-3.2.2-bin.tar.gz

创建部署用户并配置 sudo 免密:

代码语言:bash
复制
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 免密,后面权限问题很难看
  • 资源中心目录没提前建好
资源文件夹、park / flink 目录截图
资源文件夹、park / flink 目录截图

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

官方 qData 服务部署文档给出的后端启动命令是:

qdata-server.jar 用 8083,qdata-quality.jar 用 8088,最终访问地址写的是 http://服务器IP:8082

代码语言:bash
复制
# 启动 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 &

可选自检命令:

代码语言:bash
复制
ps -ef | grep qdata
ss -lntp | grep -E '8082|8083|8088'
curl -I http://127.0.0.1:8082

提醒:

真正容易混乱的不是“服务能不能启动”,而是 Nginx 监听端口、前端访问地址、后端启动端口、反向代理目标端口这几套口径必须保持一致。

一旦这里没统一,就很容易出现“后端是好的,页面却打不开”这种典型问题。


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

1. 先用 Docker 跑通整体流程

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

代码语言:bash
复制
# 首次初始化
sudo docker-compose --profile schema up -d

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

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

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

建议顺序:

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

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

1. 服务状态是否正常

代码语言:bash
复制
docker ps
ps -ef | grep java

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

代码语言:bash
复制
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 主流程跑通
  • 再按原生安装把每一层拆开理解
  • 每完成一步,都做一次最小化验证

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

原创声明:本文系作者授权腾讯云开发者社区发表,未经许可,不得转载。

如有侵权,请联系 cloudcommunity@tencent.com 删除。

原创声明:本文系作者授权腾讯云开发者社区发表,未经许可,不得转载。

如有侵权,请联系 cloudcommunity@tencent.com 删除。

评论
登录后参与评论
0 条评论
热度
最新
推荐阅读
目录
  • 一、开始之前,先别急着装:这几件事不确认,后面大概率会返工
    • 1. 没先想清楚走 Docker 还是原生安装
    • 2. 环境没先检查,做到一半才发现缺依赖
    • 3. 把“服务启动了”当成“部署成功了”
  • 二、Docker 部署最容易踩的几个坑
    • 1. 坑一:Docker 和 Docker Compose 装了,但其实不能正常用
    • 2. 坑二:部署包解压了,但数据库类型没改对
    • 3. 坑三:漏掉数据库初始化,结果系统“能启动但不能用”
    • 4. 坑四:容器都起来了,但页面就是打不开
  • 三、原生安装最容易踩的几个坑
    • 1. 坑一:JDK 装了,但环境变量没生效
    • 2. 坑二:数据库初始化没当回事,结果系统一直“半可用”
    • 4. 坑四:DolphinScheduler 调度器部署
      • 调度器组件示例
      • 调度器部署示例
    • 5. 坑五:qData 服务启动了,但前后端并没有真正打通
  • 四、如果想少走弯路,我更建议按这个顺序部署
    • 1. 先用 Docker 跑通整体流程
    • 2. 再按原生安装拆开理解每一层
  • 五、部署完成后,建议重点检查这几项
    • 1. 服务状态是否正常
    • 2. 页面和端口是否可访问
    • 3. 数据初始化是否完成
    • 4. 前后端链路是否打通
  • 总结
领券
问题归档专栏文章快讯文章归档关键词归档开发者手册归档开发者手册 Section 归档