qData数据中台安装

组件	版本要求	说明
操作系统	Windows 10/11	需要 WSL2 支持
Docker Desktop	29.x+	基于 WSL2 后端
Docker Compose	v5.x	内置于 Docker Desktop
Node.js	18+	用于编译前端
Yarn	1.22.x	前端包管理器
内存	≥ 16GB	至少为 WSL2 分配 10-12GB
CPU	≥ 8 核	至少为 WSL2 分配 6-8 核

二、第 0 步：检查硬件

2.1 查看内存和 CPU

打开 PowerShell（管理员）：
powershell
# 查看物理内存
wmic memorychip get capacity
# 输出示例：17179869184 字节 = 16GB

# 查看 CPU
wmic cpu get name,NumberOfCores,NumberOfLogicalProcessors
# 输出示例：AMD Ryzen 7 7700 8-Core Processor, 8 核, 16 线程

❌ 如果小于 16GB：建议先升级内存条。强行运行会导致 Docker 反复崩溃，浪费时间。

⚠️ 重要警告：本项目启动后会同时运行 20 个容器，包括 4 个数据库（MySQL + PostgreSQL + MongoDB + 达梦DM8）、4 个 Hadoop 节点、Spark、DolphinScheduler 全家桶（6 个容器）等。如果你的电脑内存只有 8GB，请先升级到 16GB 再继续，否则 Docker 会反复崩溃，容器永远起不来。

三、第 1 步：安装 Docker Desktop和WSL2（Docker Desktop和WSL2安装不分先后）

3.1 下载安装Docker

链接1：https://docs.docker.com/get-started/get-docker/

链接2：https://www.docker.com/

从 Docker 官网下载 Docker Desktop for Windows。

3.2 WSL2 安装

第一步：启用 WSL 2 的必要功能

打开「控制面板」→「程序」→「启用或关闭 Windows 功能」。
勾选以下功能：

点击「确定」，系统会自动完成配置并提示重启电脑。

第二步：安装 WSL 2

（WSL2 可以理解为 Windows 里的一个 “Linux 虚拟机”，你可以在里面安装 Ubuntu 等 Linux 系统，像用真实的 Linux 电脑一样操作）

以管理员身份打开 PowerShell（切记一定要是管理员的身份打开，不然权限不够）执行命令：
powershell
```
wsl --install
```
等待安装完成后，重启电脑。
重启后，设置你的 Linux 用户名和密码。
验证安装，在 PowerShell 中执行：
powershell
```
wsl --list --verbose
```
确保默认发行版的版本号为 2。

3.2 验证安装

3.3.1 Docker和WSL的验证

操作步骤

以管理员身份打开 Windows PowerShell
依次执行以下三条命令，查看输出结果

# 查看 Docker 版本
docker --version

# 查看 Docker Compose 版本
docker compose version

# 查看 WSL 运行状态
wsl --list --verbose

（默认设置：一般来说不使用docker用于默认，而是Ubuntu默认的，如果前面是有*的就是默认选项，可以用wsl --set-default Ubuntu进行切换到Ubuntu）

✅ 确认 `docker-desktop` 状态为 Running (WSL2)。

3.3.2如何进入WSL

操作步骤

以管理员身份打开 Windows PowerShell
输入wsl即可进入Ubuntu

3.4 Git版本控制工具安装

链接：https://git-scm.com/install/windows

四、第 2 步：配置 WSL2 内存和 CPU（⭐ 最关键）

这是最容易踩坑的一步。WSL2 默认限制内存很小，不修改的话 20+ 个容器根本跑不起来。

4.1 检查默认配置

WSL2 默认只分配 50% 主机内存。如果没配置过，实际限制约 8GB（16GB 主机 × 50%）。

❌ Docker 反复报 500 Internal Server Error
❌ 容器启动后 30 秒内全部 Exited (255)
❌ DolphinScheduler Master 日志到 Jetty 初始化就中断了
❌ docker stats 显示 RAM=0, CPU=0
❌ Docker 日志里全是 no route to host 192.168.65.7
以上所有症状的根因都是同一个：WSL2 内存被耗尽，Docker 的 Linux VM 被 OOM Killer 杀掉了。

4.2 创建/修改 '.wslconfig'（如果没有'.wslconfig'则不用理会）

在 Windows 用户目录下创建 `C:\Users\<你的用户名>\.wslconfig`：

[wsl2]
memory=12GB # 为 WSL2 分配 12GB（主机 16GB 的建议值）
swap=4GB # 交换空间
processors=8 # CPU 核心数
localhostForwarding=true

> 如果你的主机是 32GB，可以把 memory 设为 20GB-24GB。
> 如果你的主机是 8GB……建议放弃，资源不够（本人亲测）。

4.3 让配置生效

powershell
# 步骤1. 打开 PowerShell（管理员），关闭所有 WSL 实例
wsl --shutdown

# 步骤2. 完全退出 Docker Desktop
# 任务栏右下角 Docker 图标 → 右键 → Quit Docker Desktop

# 3. 等待 10 秒后重新启动 Docker Desktop

# 4. 验证 WSL 内存已更新
wsl -d Ubuntu -- free -h
# total used free shared buff/cache available
# Mem: 11Gi xxx xxx xxx xxx xxx

> ✅ 确认 `total` 显示约 11-12GB（略小于配置值，因为 WSL 内核会占用一部分）。

五、第 3 步：获取项目代码

# 克隆项目（或从网盘下载后解压）

操作步骤（远程克隆方法）

window+R，输入cmd，进入
输入 wsl 进入Ubuntu
切换到需要放在哪里（本人在/opt下）（cd /opt）
通过Git远程克隆拉取【 git clone https://gitee.com/qiantongtech/qData.git】

cd qData/docker
---------------------------------------------------------------------------------------------------------------------------------
> 项目目录结构确认：
> docker/
> ├── .env # 环境变量配置
> ├── docker-compose.yml # 主编排文件（include 所有子文件）
> ├── docker-compose-base-mysql.yml # 基础服务（MySQL, Redis, RabbitMQ, Nginx 等）
> ├── docker-compose-dolphinscheduler.yml # DolphinScheduler 全家桶
> ├── docker-compose-spark.yml                # Spark Master + Worker
> ├── docker-compose-hadoop.yml             # Hadoop (NameNode, DataNode 等)
> ├── docker-compose-qdata.yml                # qData 后端服务
> ├── docker-compose-demo.yml                # Demo 数据
> ├── dolphinscheduler/
> │ ├── logs/ # DS 日志（挂载到容器内）
> │ ├── soft/ # DataX, Spark, Flink 等软链接目录
> │ └── sql/ # DS 数据库初始化脚本
> └── nginx/
> ├── dist/ # ⚠️ 前端编译产物（需要手动构建后放入）
> ├── nginx.conf
> └── sites/

六、第 4 步：安装前端构建工具

项目后端可以用 Docker 跑，但前端需要本地编译。

6.1 安装 Node.js（这个是在Ubuntu中的）

从 https://nodejs.org 下载安装 Node.js 24.x LTS（或使用 nvm）。

操作步骤（通过npm方法）

window+R，输入cmd，进入
输入 wsl 进入Ubuntu
sudo apt install -y nodejs

检查验证：

```powershell
node --version # v24.12.0
npm --version # 11.6.2

6.2 安装 Yarn

操作步骤（通过npm方法）

window+R，输入cmd，进入
输入 wsl 进入Ubuntu
npm install -g yarn

```powershell
npm install -g yarn
yarn --version # 1.22.22

七、第 5 步：编译前端（⭐ 关键步骤）

7.1 问题现象

直接启动 Docker 后访问 `http://localhost` 返回 403 Forbidden。nginx 错误日志显示：

directory index of "/usr/share/nginx/" is forbidden
rewrite or internal redirection cycle while internally redirecting to "/index.html"

7.2 根因

`docker/nginx/dist/` 目录是空的。docker-compose 把这个目录挂载到 nginx 的 `/usr/share/nginx/`，没有 `index.html`，nginx 找不到首页就返回 403。
项目源码中的 `nginx/dist/` 目录有个占位文件叫 `dist文件夹整个粘贴到此处`，意思是需要你把编译好的 dist 粘贴进去。

7.3 编译步骤

打开 PowerShell（或任意终端），依次执行：

# 1. 进入前端项目目录
cd qData/qdata-ui

# 2. 安装依赖（约 2-3 分钟，取决于网络）
yarn install

# 安装过程中可能会报 marked@17.0.6 要求 Node >= 20
# 如果 Node 版本较低，使用：
yarn install --ignore-engines

# 3. 编译前端（约 2-5 分钟，3671 个模块）
# 如果遇到 "JavaScript heap out of memory" 错误：
export NODE_OPTIONS="--max-old-space-size=4096"
yarn build:prod

# 4. 复制编译产物到 nginx 目录
rm -rf ../docker/nginx/dist
mkdir -p ../docker/nginx/dist
cp -r dist/* ../docker/nginx/dist/

# 5. 验证
ls ../docker/nginx/dist/
# 应该看到：index.html, assets/, favicon.ico 等文件
```
⚠️ 注意：如果你在 WSL 的 `/opt/qData` 路径下操作，使用 Linux 路径（`/opt/qData/qdata-ui`），不要在 Windows 侧用 `\\wsl.localhost\...` UNC 路径运行 `yarn`——CMD.EXE 不支持 UNC 路径作为工作目录，会导致构建失败。

7.4 构建成功标志

构建成功后，终端会显示类似：

✓ 3671 modules transformed.
Done in 145.93s.

同时 qdata-ui/dist/ 目录下会生成文件：

dist/
├── index.html
├── assets/
│   ├── index-xxxxx.js
│   ├── index-xxxxx.css
│   └── ...
├── favicon.ico
└── ...

7.5 复制编译产物到 nginx

# Windows PowerShell 方式：
Remove-Item -Recurse -Force "docker\nginx\dist\*"
Copy-Item -Recurse -Force "qdata-ui\dist\*" "docker\nginx\dist\"

# WSL / Git Bash 方式：
rm -rf docker/nginx/dist/*
cp -r qdata-ui/dist/* docker/nginx/dist/

# 验证
ls docker/nginx/dist/
# 应该看到: index.html, assets/, favicon.ico, ...

八、第 6 步：启动 Docker 服务

8.1 启动全部服务

第 1 步：修改.env文件（用的是mysql数据库）

cd /opt/qData/docker
sudo vi .env
# 数据库类型，可选值：dm8 或 mysql
DB_TYPE=mysql

第 2 步：用 MySQL 版本的 compose 文件重新部署

# 修复权限和脚本（依次执行）
sudo chmod -R 755 .
sudo chown -R $USER:$USER .
sudo find . -name "*.sh" -exec sed -i 's/\r$//' {} \;

# 先只启动数据库，初始化 MySQL 表结构（首次运行必执行！！）
sudo docker compose -f docker-compose-mysql.yml --profile schema up -d

⚠️ 注意：MySQL 首次初始化可能需要 1-3 分钟（取决于电脑性能），请等待 docker-mysql-1 状态变为 Up (healthy) 后再继续下一步。

补充：如果window上启动了mysql，要给他关掉，不然两个系统会端口冲突，导致Ubuntu上的mysql运行失败

等 MySQL 初始化完成（docker ps 中看到 mysql 容器为 healthy），大概需要 1-2 分钟（一定要等待一会）：

# 查看 MySQL 是否就绪
sudo docker ps --filter "name=mysql"

第 3 步：启动所有服务(等待大概2-5分钟)

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

第 4 步：检查服务状态

# 所有容器应该都是 healthy 或 running
sudo docker ps -a

# 查看 qdata-api 日志，确认数据库连接成功
sudo docker logs docker-qdata-api-1 --tail 30

第 5 步：访问页面

打开浏览器访问 http://localhost（Nginx 代理到了 80 端口），默认账号密码：

- 用户名：qData
- 密码：qData123

-管理员：admin
-密码：qData123

九、第 7 步：验证服务

9.1 验证 nginx（前端）

curl -s -o /dev/null -w "HTTP Status: %{http_code}\n" http://localhost/
# 预期：HTTP Status: 200
浏览器访问 `http://localhost`，应该看到 qData 登录页面。

9.2 验证 DolphinScheduler API
curl http://localhost:12345/dolphinscheduler/actuator/health
# 预期：{"status":"UP","components":{...}}

9.3 验证 qData 后端
curl http://localhost:8080/actuator/health
# 预期：{"status":"UP"}

9.4 验证 RabbitMQ 管理界面
浏览器访问 `http://localhost:15672`，使用 `.env` 中配置的账号密码登录：
用户名：`admin`
密码：`qData123`

9.5 验证 Redis
docker exec docker-redis-1 redis-cli ping
# 预期：PONG

9.6 验证 MySQL
docker exec docker-mysql-1 mysql -uroot -p"$(grep MYSQL_ROOT_PASSWORD .env | cut -d= -f2)" -e "SELECT 1"
# 预期：1

十、常见问题排查

10.1 Docker 反复 500 错误 / 容器全部 Exited

症状：
request returned 500 Internal Server Error for API route and version
http://%2F%2F.%2Fpipe%2FdockerDesktopLinuxEngine/v1.54/containers/json
排查：
powershell
# 检查 Docker 后端日志
notepad "$env:LOCALAPPDATA\Docker\log\host\com.docker.backend.exe.log"

# 如果看到：
# still dialing 192.168.65.7:2376: connect tcp 192.168.65.7:2376: no route to host
根因：Docker Desktop 的 WSL2 VM 因 OOM 崩溃，`192.168.65.7` 这个内部地址无法访问。
解决：
检查 `.wslconfig` 中 `memory` 是否 ≥ 10GB
如果不满足，增加内存限制
执行 `wsl --shutdown`，重启 Docker Desktop

10.2 容器启动后立即 Exited (255)

症状：`docker ps -a` 显示所有容器 Status 为 `Exited (255)`。
根因：退出码 255 表示容器被 Docker 守护进程强制终止。通常是因为 WSL 被关闭（`wsl --shutdown`）或 VM 崩溃。
解决：
```bash
docker compose -f docker-compose.yml --profile all up -d

10.3 Master 容器日志在 Jetty 初始化后中断

症状：
[INFO] o.e.j.u.log:[170] - Logging initialized @59906ms to org.eclipse.jetty.util.log.Slf4jLog
（之后没有任何日志）
容器 `docker stats` 显示 RAM=0, CPU=0。
根因：WSL2 内存耗尽，JVM 进程被 OOM Killer 杀掉。
解决：增加 `.wslconfig` 的 `memory` 值，重启 WSL 和 Docker Desktop。

10.4 nginx 403 Forbidden

症状：访问 `http://localhost` 返回 403，nginx 日志显示：
directory index of "/usr/share/nginx/" is forbidden
rewrite or internal redirection cycle while internally redirecting to "/index.html"
根因：`docker/nginx/dist/` 目录为空，前端没有编译。
解决：按第五章步骤编译前端并复制 dist 到 nginx 目录。

10.5 容器重启失败：mount 路径不存在

症状：
Error: failed to create shim task: OCI runtime create failed:
error mounting ... to rootfs at "/usr/share/nginx": no such file or directory
根因：WSL 实例重建后，Docker 的 bind mount 路径失效。
解决：使用 `docker compose up -d --force-recreate <service>` 重建容器。

十一、关键文件速查

文件   说明
`C:\Users\<用户名>\.wslconfig`   WSL2 内存和 CPU 配置
`docker/.env`   所有环境变量（数据库密码、端口等）
`docker/docker-compose.yml`   主编排文件
`docker/nginx/dist/`   前端编译产物挂载目录
`docker/dolphinscheduler/logs/`   DolphinScheduler 各组件日志
`docker/nginx/logs/`   nginx 访问和错误日志

十二、快速启动检查清单

从零开始部署 qData 的完整流程检查清单：

>1.  确认硬件：内存 ≥ 16GB，CPU ≥ 8 核
>2.  安装 Docker Desktop（勾选 WSL2）
>3.  安装 Node.js 20+ 和 Yarn
>4.  配置 C:\Users\<用户名>\.wslconfig  (memory=12GB, processors=8)
>5.  wsl --shutdown → 重启 Docker Desktop
>6.  验证 WSL 内存：wsl -d Ubuntu -- free -h（确认 total ≈ 11Gi）
>7.  git clone 项目代码
>8.  确认 .env 中 DB_TYPE=mysql
>9.  cd qdata-ui && yarn install
>10. yarn build:prod（OOM 则加 NODE_OPTIONS="--max-old-space-size=4096"）
>11. cp -r dist/* ../docker/nginx/dist/
>12. cd ../docker && docker compose --profile schema up -d（等数据库 healthy）
>13. docker compose --profile all up -d（等所有容器 healthy）
>14. docker ps → 确认 20 个容器全部 Up
>15. curl localhost → HTTP 200
>16. 浏览器 http://localhost → qData 登录页 🎉