QDATA 部署与基础设施报告¶

生成日期：2026-08-27 | 基于源码深度分析

一、服务架构总览¶

qData 采用**三后端 + 一前端**的微服务架构，通过 Docker Compose 编排，支持 light（轻量）和 all（全量）两种部署模式。

┌────────────────────────────────────────────────────────────────────┐
│                         Nginx :80                                   │
│              /prod-api → qdata-api:8080                             │
│              /prod-ai  → qdata-service-ai:8087                      │
│              /         → 前端静态文件                                │
├────────────────────────────────────────────────────────────────────┤
│                                                                    │
│  ┌──────────────────┐  ┌──────────────────┐  ┌──────────────────┐ │
│  │   qdata-api       │  │  qdata-service-ai │  │  qdata-service-  │ │
│  │   :8080           │  │  :8087            │  │  quality :8083   │ │
│  │   JDK 8           │  │  JDK 17           │  │  JDK 8           │ │
│  │   146 Controller  │  │  Text2SQL         │  │  质量规则引擎     │ │
│  └────────┬─────────┘  └──────────────────┘  └────────┬─────────┘ │
│           │                                            │           │
│  ┌────────┼────────────────────────────────────────────┼────────┐  │
│  │        ▼                                            ▼        │  │
│  │  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐        │  │
│  │  │ MySQL/DM8│ │  Redis   │ │ RabbitMQ │ │ MongoDB  │        │  │
│  │  │  :3306   │ │  :6379   │ │  :5672   │ │ :27017   │        │  │
│  │  │  主数据库 │ │  缓存/会话│ │  消息队列 │ │ 错误数据  │        │  │
│  │  └──────────┘ └──────────┘ └──────────┘ └──────────┘        │  │
│  │                                                              │  │
│  │  ┌──────────┐ ┌──────────────────┐ ┌──────────────────────┐ │  │
│  │  │  Neo4j   │ │ DolphinScheduler │ │   Spark + Hadoop     │ │  │
│  │  │  :7687   │ │  :12345          │ │   :7077 / :8020      │ │  │
│  │  │  血缘图谱 │ │  分布式调度       │ │   分布式 ETL          │ │  │
│  │  └──────────┘ └──────────────────┘ └──────────────────────┘ │  │
│  └─────────────────────────────────────────────────────────────┘  │
└────────────────────────────────────────────────────────────────────┘

二、Docker Compose 编排¶

2.1 文件结构¶

文件	说明
`docker-compose.yml`	主入口（DM8 数据库）
`docker-compose-mysql.yml`	MySQL 数据库入口
`docker-compose-base.yml`	基础服务（Redis、RabbitMQ、Nginx、数据库、MongoDB、Neo4j）
`docker-compose-dolphinscheduler.yml`	DolphinScheduler 全家桶
`docker-compose-spark.yml`	Spark Master + Worker
`docker-compose-hadoop.yml`	Hadoop HDFS（NameNode、DataNode、ResourceManager、NodeManager）
`docker-compose-qdata.yml`	三个 qData 后端服务
`docker-compose-demo.yml`	演示数据库（MySQL、Oracle、DM8）
`.env` / `.env.example`	环境变量配置

使用 include 指令组合（需要 Compose v2.20.2+）。

2.2 部署模式¶

Profile	服务数	说明
`light`	~10	核心服务：数据库 + Redis + RabbitMQ + MongoDB + Neo4j + Nginx + 3 个 qData 服务
`all`	~22	全量：light + DolphinScheduler + Spark + Hadoop
`local`	~18	本地开发：all 但不含 Nginx

2.3 完整服务清单（22 个服务）¶

基础服务：

服务	镜像	端口	Profile
`redis`	redis:6-alpine	6379	all, light, local
`rabbitmq`	rabbitmq:3.12-management	5672, 15672	all, light, local
`nginx`	nginx:1.24.0	80	all, light
`dm8`	dm8:mixed	5236	all, light, schema
`mysql`	mysql:8.0	3306	all, light, schema
`mongodb`	mongo:4.4	27017	all, light, schema
`neo4j`	neo4j:4.4.40	7474, 7687	all, light, neo4j

DolphinScheduler：

服务	端口	依赖
`dolphinscheduler-postgresql`	5432	—
`dolphinscheduler-zookeeper`	—	—
`dolphinscheduler-api`	12345, 25333	zookeeper, rabbitmq
`dolphinscheduler-alert`	—	zookeeper, rabbitmq
`dolphinscheduler-master`	—	zookeeper, rabbitmq
`dolphinscheduler-worker`	—	zookeeper, rabbitmq

Spark + Hadoop：

服务	说明
`spark`	Spark Master
`spark-worker-1`	Spark Worker
`namenode`	HDFS NameNode
`datanode`	HDFS DataNode
`resourcemanager`	YARN ResourceManager
`nodemanager`	YARN NodeManager

qData 服务：

服务	端口	依赖
`qdata-api`	8080	redis, rabbitmq, dm8/mysql
`qdata-service-quality`	8083	redis, rabbitmq, dm8/mysql, mongodb
`qdata-service-ai`	8087	redis, rabbitmq, dm8/mysql

2.4 网络配置¶

网络名称：qdatanet
子网：172.28.0.0/16
所有服务通过服务名互相访问（如 redis、rabbitmq、dm8）

2.5 命名卷¶

卷	用途
`dolphinscheduler-postgresql`	DS PostgreSQL 数据
`dolphinscheduler-zookeeper`	ZooKeeper 数据
`dolphinscheduler-worker-data`	DS Worker 数据

三、部署管理脚本¶

3.1 qdata.sh 命令¶

命令	说明
`start light`	轻量模式启动
`start all`	全量模式启动
`start local`	本地开发模式
`stop`	停止所有服务
`restart`	重启
`status`	查看服务状态
`logs`	查看日志
`doctor`	环境诊断
`uninstall`	卸载

3.2 启动选项¶

选项	说明
`--db dm8\\|mysql`	选择数据库类型
`--demo`	启动演示数据库
`--offline`	离线模式
`--force`	强制重建

3.3 预检检查¶

检查项	light 要求	all/local 要求
Docker 版本	≥ 20.10.0	≥ 20.10.0
Compose 版本	≥ 2.20.2	≥ 2.20.2
CPU	≥ 4 核	≥ 8 核
内存	≥ 8 GB	≥ 14 GB
Linux 容器模式	是	是
Rootless Docker	拒绝	拒绝
端口可用性	检查	检查
网络子网冲突	检查	检查
包完整性	检查	检查

四、Nginx 配置¶

4.1 主配置¶

配置项	值
Worker 进程	8
最大连接数	3000
Gzip	启用
代理缓冲	启用
Keepalive	300s

4.2 站点配置¶

路径	目标	说明
`/`	`/usr/share/nginx`	Vue SPA（`try_files $uri $uri/ /index.html`）
`/prod-api`	`http://qdata-api:8080`	主后端代理（剥离 `/prod-api/` 前缀）
`/prod-ai`	`http://qdata-service-ai:8087`	AI 服务代理（剥离 `/prod-ai/` 前缀）

配置项	值
`client_max_body_size`	500M
代理超时	600s（connect/send/read）
Keepalive	600s

五、环境变量¶

5.1 qData 核心¶

变量	说明	默认值
`QDATA_HUB`	容器镜像仓库	Aliyun ACR
`QDATA_TAG`	镜像标签	`1.6.1`
`DB_TYPE`	数据库类型	`dm8`

5.2 数据库¶

DM8：

变量	说明
`CASE_SENSITIVE`	大小写敏感（0）
`INSTANCE_NAME`	实例名（QDATA）
`SYSDBA_PWD`	SYSDBA 密码
`QDATA_USER` / `QDATA_PWD`	应用用户

MySQL：

变量	说明
`MYSQL_ROOT_PASSWORD`	Root 密码
`MYSQL_DATABASE`	数据库名（qdata）
`MYSQL_USER` / `MYSQL_PASSWORD`	应用用户

5.3 中间件¶

变量	说明	默认值
`REDIS_PASSWORD`	Redis 密码	—
`EXPOSE_REDIS_PORT`	Redis 端口	6379
`RABBITMQ_DEFAULT_USER`	RabbitMQ 用户	admin
`RABBITMQ_DEFAULT_PASS`	RabbitMQ 密码	—
`MONGO_INITDB_ROOT_USERNAME`	MongoDB 用户	—
`MONGO_INITDB_ROOT_PASSWORD`	MongoDB 密码	—

5.4 DolphinScheduler¶

变量	说明
`DS_HUB`	DS 镜像仓库
`DS_TAG`	DS 镜像标签
`SPRING_DATASOURCE_URL`	DS 数据库 URL
`REGISTRY_ZOOKEEPER_CONNECT_STRING`	ZooKeeper 地址
`SPRING_RABBITMQ_HOST/PORT/USERNAME/PASSWORD`	RabbitMQ 连接

5.5 Spark + Hadoop¶

变量	说明	默认值
`SPARK_MASTER_URL`	Spark Master	`spark://spark:7077`
`SPARK_WORKER_MEMORY`	Worker 内存	5G
`SPARK_WORKER_CORES`	Worker 核数	4
Hadoop 变量	30+ 个	core-site.xml, hdfs-site.xml 等

5.6 前端环境变量¶

变量	开发	生产
`VITE_APP_BASE_API`	`/dev-api`	`/prod-api/`
`VITE_APP_BASE_AI`	`/dev-ai/`	`/prod-ai/`
`VITE_APP_AUTH_TYPE`	`client`	`client`
`VITE_APP_AES_KEY`	`AD42F6697B035B75`	`AD42F6697B035B75`
`VITE_BUILD_COMPRESS`	—	`gzip`

六、数据库版本管理¶

6.1 SQL 脚本结构¶

sql/
├── mysql/
│   ├── initialization/    # 全量初始化脚本（V1.0.6 ~ V1.6.1 + latest）
│   └── upgrade/           # 增量升级脚本
├── dm/
│   ├── initialization/    # DM8 初始化脚本
│   └── upgrade/           # DM8 增量升级
└── dolphinscheduler/
    └── upgrade/           # DS 数据更新

6.2 版本升级路径（13 步）¶

步骤	升级路径	变更规模
1	V1.0.6 → V1.0.7	极小（76B 数据）
2	V1.0.7 → V1.0.8	小（3.6KB）
3	V1.0.8 → V1.1.0	极小（483B）
4	V1.1.0 → V1.1.1	小（816B）
5	V1.1.1 → V1.1.2	极小（314B）
6	V1.1.2 → V1.2.0	中（5.6KB schema + 26.8KB data）
7	V1.2.0 → V1.3.0	中（4.7KB schema + 5.8KB data）
8	V1.3.0 → V1.4.0	大（38.5KB schema + 19.8KB data）
9	V1.4.0 → V1.5.2	中（8.2KB schema + 9.6KB data）
10	V1.5.2 → V1.5.3	无变更
11	V1.5.3 → V1.5.4	小（1KB data only）
12	V1.5.4 → V1.6.0	小（2.4KB schema only）
13	V1.6.0 → V1.6.1	中（947B schema + 5.8KB data）

6.3 表数量增长¶

版本	表数量
V1.0.6 ~ V1.1.2	746
V1.2.0	756
V1.3.0	761
V1.4.0	770
V1.5.4	770
V1.6.0	2,094
V1.6.1	2,095

V1.6.0 发生了**重大 Schema 扩展**（+1,324 表），表数量从 770 激增至 2,094。

七、CI/CD¶

7.1 GitHub Actions¶

.github/workflows/release.yml 实现 Release 自动化：

触发条件：推送 v* 标签
功能：从注解标签提取 Release Notes，通过 gh release create 创建/更新 GitHub Release
不包含：构建产物、运行测试、推送 Docker 镜像

7.2 Docker 镜像¶

Dockerfile 位于：

服务	Dockerfile 路径
qdata-server	`qdata-server/docker/Dockerfile`
qdata-service-quality	`qdata-service-quality/docker/Dockerfile`
qdata-service-ai	`qdata-ai-server/docker/Dockerfile`

镜像推送到 Aliyun ACR（crpi-kf13onfj0v8f6jax.cn-shanghai.personal.cr.aliyuncs.com/qiantongkeji）。

八、API 文档配置¶

配置项	值
框架	SpringDoc OpenAPI 3 + Knife4j
分组	`system`, `example`, `ai`, `dm`
Swagger UI	`/swagger-ui.html`
API Docs	`/v3/api-docs`
Knife4j	启用（zh-CN，基础认证 test/12313）
i18n	`SwaggerI18nCustomizer` 运行时翻译 `@Tag` 和 `@Operation`

九、部署前置条件¶

组件	版本要求
JDK	1.8（AI 服务需 17）
Node.js	18+
yarn	v1.22.22+
Maven	3.6+
Docker	20.10.0+
Docker Compose	2.20.2+
DM8	大小写不敏感，GB18030 编码
Redis	5.0+
RabbitMQ	任意版本

十、前端构建配置¶

10.1 开发服务器¶

配置	值
端口	81
host	true
自动打开浏览器	是

10.2 代理规则¶

路径	目标	重写
`/dev-api`	`http://localhost:8080`	剥离前缀
`/dev-ai`	`http://localhost:8087`	剥离前缀
`/jmreport`	`http://localhost:8080`	无
`/v3/api-docs`	`http://localhost:8080`	无

10.3 Vite 插件¶

插件	说明
`@vitejs/plugin-vue`	Vue 3 SFC 支持
`unplugin-auto-import`	Vue/Router/Pinia API 自动导入
`unplugin-vue-setup-extend-plus`	`<script setup>` 命名扩展
`vite-plugin-svg-icons`	SVG 图标精灵（197 个）
`vite-plugin-compression`	Gzip/Brotli 压缩（构建时）
`vite-plugin-monaco-editor-esm`	Monaco Editor ESM 支持

10.4 构建优化¶

手动 chunk 拆分：每个 node_modules 包独立分包
路径别名：~ → 项目根，@ → src/
支持扩展名：.mjs, .js, .ts, .jsx, .tsx, .json, .vue
PostCSS：移除 SCSS @charset 警告