diff --git a/docs/project/qdata/architecture.md b/docs/project/qdata/architecture.md new file mode 100644 index 0000000..46746bf --- /dev/null +++ b/docs/project/qdata/architecture.md @@ -0,0 +1,412 @@ +# QDATA 前后端架构报告 + +> 生成日期：2026-08-27 | 基于源码深度分析 + +--- + +## 一、后端架构（Java / Spring Boot） + +### 1.1 项目概况 + +qData 是一个企业级**数据中台**（Data Governance Platform），由江苏千统科技有限公司开发，版本 **1.6.1**，采用 Apache License 2.0 授权。后端基于 **Java 8** + **Spring Boot 2.5.15** 构建，Maven 多模块单体架构，共 **16 个业务模块** + **12 个框架子模块** + **2 个独立微服务**。 + +| 维度 | 数量 | +|------|------| +| Controller 总数 | **146** | +| REST 端点总数 | **1,242** | +| Service 接口 | **~130** | +| ServiceImpl 实现类 | **~125** | +| DO（实体）类 | **118** | +| VO 类 | **403** | +| DTO 类 | **223** | +| MyBatis Mapper 接口 | **143** | +| Mapper XML 文件 | **109** | +| 数据库表（latest） | **2,095** | + +### 1.2 分层架构 + +``` +┌─────────────────────────────────────────────────────────────┐ +│ qdata-server（入口） │ +│ QDataApplication.java :8080 │ +├─────────────────────────────────────────────────────────────┤ +│ qdata-framework（框架层，12 个子模块） │ +│ auth │ common │ config │ file │ generator │ mybatis │ +│ neo4j│ pay │ quartz │ redis│ security │ websocket │ +├─────────────────────────────────────────────────────────────┤ +│ 业务模块层（10 个模块，api + biz 拆分） │ +│ system │ att │ da │ dg │ dm │ dp │ dpp │ ds │ mc │ ai │ +├─────────────────────────────────────────────────────────────┤ +│ qdata-api-ds（DolphinScheduler 集成接口） │ +├─────────────────────────────────────────────────────────────┤ +│ 独立微服务：service-ai :8087 │ service-quality :8083 │ +└─────────────────────────────────────────────────────────────┘ +``` + +### 1.3 模块清单与职责 + +| 模块 | Controller | 端点 | 职责 | +|------|-----------|------|------| +| `qdata-module-system` | 31 | 209 | 用户、角色、菜单、部门、字典、日志、消息、CA 证书 | +| `qdata-module-da` | 23 | 237 | 数据资产编目、数据源管理、数据发现、资产审计、GIS/视频资产 | +| `qdata-module-att` | 20 | 196 | 分类管理（10 类）、项目管理、标签、规则、客户端 | +| `qdata-module-dpp` | 16 | 158 | ETL 数据集成、数据开发、任务调度、质量任务 | +| `qdata-module-mc` | 13 | 113 | 元数据采集、变更检测、版本管理、方言适配 | +| `qdata-module-dg` | 11 | 87 | 数据分类分级、脱敏规则、敏感数据管理 | +| `qdata-module-dp` | 9 | 85 | 数据标准、数据元、码表映射、逻辑模型、文档管理 | +| `qdata-module-dm` | 6 | 50 | 数据域、数据层、主题域、业务分类 | +| `qdata-module-ds` | 4 | 27 | 数据服务 API 发布、客户端认证、调用日志 | +| `qdata-module-ai` | 3 | 21 | AI 对话、模型管理（内嵌模式） | +| `qdata-framework` | 4 | 33 | 文件上传、代码生成器、Quartz 任务管理 | +| `qdata-service-ai` | 3 | 15 | 独立 AI 服务（JDK 17，Text2SQL） | +| `qdata-service-quality` | 2 | 10 | 独立数据质量服务（MongoDB） | +| `qdata-server` | 1 | 1 | 默认入口 | + +### 1.4 路由设计 + +所有业务 Controller 使用统一的 RESTful 前缀约定： + +| 模块前缀 | 示例路径 | 说明 | +|---------|---------|------| +| `/system/` | `/system/user/list`, `/system/role` | 系统管理 | +| `/da/` | `/da/asset/list`, `/da/datasource` | 数据资产 | +| `/att/` | `/att/project/list`, `/att/tag` | 分类管理 | +| `/dpp/` | `/dpp/etl/task/list`, `/dpp/quality/task` | 数据开发 | +| `/mc/` | `/mc/task/list`, `/mc/db` | 元数据采集 | +| `/dg/` | `/dg/dataCategory/list`, `/dg/desensitize/rule` | 数据治理 | +| `/dp/` | `/dp/model/list`, `/dp/dataElem` | 数据标准 | +| `/dm/` | `/dm/dataDomain/list`, `/dm/dataLayer` | 数据建模 | +| `/ds/` | `/ds/api/list`, `/ds/apiLog` | 数据服务 | +| `/ai/` | `/ai/chatConversation`, `/ai/model` | AI 模块 | +| `/services/v1.0.0/` | 动态注册的 API 端点 | 数据服务运行时 | + +### 1.5 Service 层 + +每个业务模块遵循 **api + biz** 拆分模式： +- `*-api` —— 接口定义、DTO、枚举、领域对象 +- `*-biz` —— 业务逻辑、Controller、ServiceImpl、MyBatis Mapper + +关键 Service 职责： + +| Service | 模块 | 核心职责 | +|---------|------|---------| +| `IDppEtlTaskService` | dpp | ETL 任务 CRUD、发布/下线、调度器集成 | +| `McTaskServiceImpl` | mc | 元数据采集执行、增量/全量、变更检测 | +| `DaAssetServiceImpl` | da | 资产编目、血缘追踪（Neo4j）、发现任务 | +| `DsApiServiceImpl` | ds | API 发布/注销、SQL 解析、在线测试 | +| `QualityTaskExecutorServiceImpl` | quality | 质量规则执行、错误数据存储（MongoDB） | +| `DpModelServiceImpl` | dp | 逻辑模型管理、数据元关联、物化视图 | +| `TokenService` | security | JWT 签发/验证/刷新、Redis 存储 | + +### 1.6 数据模型 + +共 **748** 个模型类（118 DO + 403 VO + 223 DTO + 4 Entity），按模块分布： + +| 模块 | DO | 说明 | +|------|-----|------| +| `da` | 25 | `DaAssetDO`, `DaDatasourceDO`, `DaDiscoveryTaskDO` 等 | +| `att` | 20 | `AttProjectDO`, `AttTagDO`, `AttClientDO` 等 | +| `dpp` | 18 | `DppEtlTaskDO`, `DppEtlNodeDO`, `DppEtlSchedulerDO` 等 | +| `mc` | 12 | `McDbDO`, `McTableDO`, `McColumnDO`, `McTaskDO` 等 | +| `dg` | 11 | `DgDataCategoryDO`, `DgDesensitizeRuleDO` 等 | +| `dp` | 9 | `DpModelDO`, `DpModelColumnDO`, `DpDataElemDO` 等 | +| `quality` | 7 | `QualityRuleEntity`, `CheckErrorData` 等 | +| `dm` | 6 | `DmDataDomainDO`, `DmDataLayerDO` 等 | +| `system` | 5 | `SysConfig`, `SysNotice`, `SysOperLog` 等 | +| `ai` | 3 | `AiModelDO`, `AiChatConversationDO`, `AiChatMessageDO` | +| `ds` | 2 | `DsApiDO`, `DsApiLogDO` | + +### 1.7 认证机制 + +**主认证**：Spring Security 5.7.12 + JWT（HS512） + +``` +┌──────────┐ POST /login ┌──────────────┐ +│ Client │ ──────────────────► │ AuthController│ +└──────────┘ └──────┬───────┘ + │ + ▼ + ┌──────────────────┐ + │ SysLoginService │ + │ · BCrypt 密码校验 │ + │ · 验证码校验 │ + │ · IP 黑名单检查 │ + └────────┬─────────┘ + │ + ▼ + ┌──────────────────┐ + │ TokenService │ + │ · HS512 签发 JWT │ + │ · Redis 存储 │ + │ · 自动续期（20min）│ + └──────────────────┘ +``` + +- Token 通过 `Authorization: Bearer {token}` 传递 +- Redis Key：`login_tokens:{uuid}`，默认 TTL **600 分钟**（10 小时） +- Token 在剩余 **20 分钟**时自动续期 +- 密码加密：**BCrypt** +- CSRF 已禁用（无状态策略） + +**OAuth2 支持**：基于 **SA-Token** 框架，支持全部 4 种授权模式（Authorization Code、Implicit、Password、Client Credentials），路径 `/oauth2/**`。 + +**数据服务客户端认证**：独立的 `DsCheckClientToken` 注解 + `ApiJwtUtil`，7 天 Token + 30 天 Refresh Token。 + +### 1.8 配置管理 + +| 配置项 | 值 | +|--------|-----| +| 服务端口 | 8080 | +| Tomcat 最大线程 | 800 | +| Tomcat 最小空闲线程 | 100 | +| 文件上传上限 | 3,000 MB | +| XSS 过滤路径 | `/system/*`, `/monitor/*`, `/tool/*` | +| i18n 资源包 | 13 个（跨模块） | +| 分页插件 | PageHelper（MySQL 方言） | +| ID 策略 | 自增 + 雪花 ID | + +**数据源支持**：MySQL（主）、DM8、KingbaseES、Oracle、PostgreSQL、SQL Server，通过 `application-dev.yml` 切换。连接池使用 **Alibaba Druid 1.2.23**（初始 5，最大 20）。 + +--- + +## 二、前端架构（Vue 3 / TypeScript） + +### 2.1 技术栈 + +| 类别 | 技术 | 版本 | +|------|------|------| +| 框架 | Vue 3 | ^3.5.21 | +| UI 库 | Element Plus | 2.7.6 | +| 构建工具 | Vite | 5.3.2 | +| 状态管理 | Pinia | 2.1.7 | +| 路由 | Vue Router | 4.4.0 | +| 国际化 | vue-i18n | ^11.4.5 | +| HTTP 客户端 | Axios | 0.28.1 | +| 图表 | ECharts | 5.5.1 | +| 流程图 | AntV X6 | ^2.18.1 | +| 代码编辑器 | Monaco Editor | ^0.52.2 | +| 富文本 | Vue Quill | 1.2.0 | +| Markdown | markdown-it | ^14.1.0 | +| 网络图 | vis-network | ^9.1.13 | +| 表单设计器 | @form-create/designer | ^3.2.11 | +| 文档预览 | @vue-office/docx/excel/pdf | ^1.6.3 / ^1.7.14 / ^2.0.10 | +| 模糊搜索 | Fuse.js | 6.6.2 | +| 拖拽 | vuedraggable | ^4.1.0 | +| 加密 | crypto-js + jsencrypt | ^4.2.0 / 3.3.2 | + +### 2.2 目录结构 + +``` +qdata-ui/src/ +├── api/ # 14 个模块目录，151 个 API 文件 +├── assets/ # 静态资源（197 个 SVG 图标） +├── components/ # 38 个组件目录，83 个文件 +├── composables/ # 5 个组合式函数 +├── directive/ # 4 个自定义指令（copyText, hasPermi, hasRole） +├── layout/ # 12 个布局组件 +├── locales/ # 3 语言 × 18 命名空间 = 54 个翻译文件 +├── plugins/ # 8 个插件（auth, cache, download, modal, tab, i18n） +├── router/ # 27 个路由文件 +├── store/ # 8 个 Pinia Store +├── utils/ # 30 个工具文件 +└── views/ # 13 个模块目录，322 个页面组件 +``` + +### 2.3 路由设计 + +共 **91 个路由声明**，分为两层： + +- **constantRoutes**（公开路由）：来自 18 个路由模块文件，无需权限 +- **dynamicRoutes**（动态路由）：来自 4 个模块文件，由后端菜单接口动态注入 + +路由组件解析使用 `import.meta.glob('./../../views/**/*.vue')` 实现懒加载。`beforeEach` 守卫在路由切换时取消未完成的 HTTP 请求。 + +路由 Top 5： + +| 路由文件 | 路由数 | +|---------|--------| +| `system/public/index.js` | 19 | +| `system/dynamic/index.js` | 10 | +| `dp/document/index.js` | 10 | +| `da/quality/index.js` | 8 | +| `meta/dynamic/index.js` | 8 | + +### 2.4 状态管理 + +**8 个 Pinia Store**： + +| Store | 职责 | +|-------|------| +| `app` | 侧边栏状态、设备类型、UI 尺寸 | +| `user` | 认证信息（Token、用户、角色、权限） | +| `dict` | 字典缓存（内存 KV） | +| `permission` | 动态路由管理、菜单树解析 | +| `settings` | 布局配置（主题色、顶栏、标签页等） | +| `tags-view` | 标签页导航管理 | +| `locale` | 国际化语言切换 | +| `project` | 项目上下文、资产/模型分类树 | + +### 2.5 组件体系 + +**19 个全局注册组件**： + +| 组件 | 说明 | +|------|------| +| `SvgIcon` | SVG 图标渲染器（197 个图标） | +| `Pagination` | 分页封装 | +| `ImageUpload` | 图片上传预览 | +| `FileUpload` | 文件上传 | +| `FileUploadbtn` | 文件上传按钮 | +| `Editor` | 富文本编辑器（Quill） | +| `DictTag` | 字典值标签 | +| `DetailInfo` | 通用详情页头 | +| `DescriptionsInfo` | 描述信息封装 | +| `RightToolbar` | 表格工具栏（列切换、搜索、刷新） | +| `TreeSelect` | 树形下拉选择 | +| `QtTable` / `QtSearchBar` / `QtFormItem` / `QtTabPane` / `QtTagGroup` / `QtWrap` | qData 定制组件 | +| `ImagePreview` | 图片预览灯箱 | +| `GuideTip` | 引导提示 | + +**专用组件**（非全局）： + +| 组件 | 说明 | +|------|------| +| `SqlEditor` | SQL 编辑器（Monaco/CodeMirror，支持 FlinkSQL） | +| `ShellEditor` | Shell 脚本编辑器 | +| `ProTable` | 专业表格组件 | +| `Crontab` | Cron 表达式编辑器（8 个子组件） | +| `MarkdownView` | Markdown 渲染器 | +| `DeptTree` | 部门树选择器 | +| `HeaderSearch` | 头部搜索（Fuse.js 模糊匹配） | + +### 2.6 国际化 + +| 语言 | 命名空间 | 翻译键值对 | 行数 | +|------|---------|-----------|------| +| zh-CN（主） | 18 | ~6,320 | 7,420 | +| en-US | 18 | ~6,200 | 7,130 | +| ja-JP | 18 | ~6,200 | 7,175 | + +最大的命名空间：`dpp`（数据开发）1,636 行，`sys`（系统管理）1,017 行，`da`（数据资产）810 行。 + +### 2.7 构建配置 + +**开发服务器**：端口 81，4 个代理规则： + +| 代理路径 | 目标 | 说明 | +|---------|------|------| +| `/dev-api` | `http://localhost:8080` | 主后端 | +| `/dev-ai` | `http://localhost:8087` | AI 服务 | +| `/jmreport` | `http://localhost:8080` | 报表服务 | +| `/v3/api-docs` | `http://localhost:8080` | Swagger 文档 | + +**构建优化**： +- 手动 chunk 拆分（每个 `node_modules` 包独立分包） +- Gzip/Brotli 压缩（通过 `VITE_BUILD_COMPRESS` 环境变量控制） +- SVG 图标精灵（`vite-plugin-svg-icons`，197 个图标） +- 自动导入（`unplugin-auto-import` + `unplugin-vue-components`） + +### 2.8 文件统计 + +| 类别 | 数量 | +|------|------| +| Vue 文件总数 | **405** | +| JS 文件总数 | **310** | +| TS 文件总数 | **8** | +| 源文件总数 | **730** | +| views/ 下 Vue 文件 | 322 | +| components/ 下 Vue 文件 | 71 | +| API 文件 | 151 | +| 路由文件 | 27 | +| Store 文件 | 8 | +| 翻译文件 | 54 | +| SVG 图标 | 197 | + +--- + +## 三、前后端交互模型 + +### 3.1 通信架构 + +``` +┌────────────────────────────────────────────────────────────────┐ +│ qdata-ui (Vue 3) │ +│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌───────────────┐ │ +│ │ views/ │ │ store/ │ │ router/ │ │ api/ │ │ +│ │ 322 页面 │ │ 8 Store │ │ 91 路由 │ │ 151 API 文件 │ │ +│ └────┬─────┘ └────┬─────┘ └────┬─────┘ └──────┬────────┘ │ +│ │ │ │ │ │ +│ └──────────────┴──────────────┴───────┬───────┘ │ +│ │ Axios │ +└─────────────────────────────────────────────┼───────────────────┘ + │ + ┌─────────────────────────┼────────────────────┐ + │ Nginx :80（生产） │ │ + │ /prod-api → :8080 │ │ + │ /prod-ai → :8087 │ │ + └─────────────────────────┼────────────────────┘ + │ + ┌───────────────────────────────┼────────────────────────┐ + │ │ │ + ▼ ▼ ▼ + ┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐ + │ qdata-api │ │ qdata-service-ai │ │ qdata-service- │ + │ :8080 │ │ :8087 │ │ quality :8083 │ + │ 146 Controller │ │ 3 Controller │ │ 2 Controller │ + │ 1,242 端点 │ │ 15 端点 │ │ 10 端点 │ + └────────┬─────────┘ └──────────────────┘ └──────────────────┘ + │ + ┌────────┼────────┬──────────┬──────────┐ + ▼ ▼ ▼ ▼ ▼ + MySQL Redis RabbitMQ Neo4j MongoDB + /DM8 :6379 :5672 :7687 :27017 +``` + +### 3.2 认证流程 + +1. 前端调用 `POST /login`（用户名 + 密码 + 验证码） +2. 后端 `AuthController` → `SysLoginService` 校验（BCrypt + 验证码 + IP 黑名单） +3. `TokenService` 签发 JWT（HS512），存入 Redis（`login_tokens:{uuid}`，TTL 600min） +4. 前端存储 Token 到 Cookie，后续请求通过 `Authorization: Bearer {token}` 携带 +5. `JwtAuthenticationTokenFilter` 拦截请求，从 Redis 验证 Token 有效性 +6. Token 剩余 20 分钟时自动续期 + +### 3.3 动态菜单与路由 + +1. 前端登录后调用 `getRouters()` 获取后端菜单树 +2. `permission` Store 将菜单树转换为 Vue Router 路由配置 +3. 组件字符串通过 `import.meta.glob` 解析为懒加载组件 +4. `addRoutes()` 动态注入路由，`router.addRoute()` 添加 404 兜底 +5. 侧边栏、顶栏、面包屑均从路由元数据（`meta.title`, `meta.icon`）渲染 + +### 3.4 API 文档 + +- **SpringDoc OpenAPI 3** + **Knife4j** 增强 UI +- 分组：`system`、`example`、`ai`、`dm` +- Swagger UI 路径：`/swagger-ui.html` +- API 文档路径：`/v3/api-docs` +- i18n 支持：`SwaggerI18nCustomizer` 运行时翻译 `@Tag` 和 `@Operation` +- Knife4j 基础认证：`test` / `12313` + +--- + +## 四、文件统计汇总 + +| 维度 | 数量 | +|------|------| +| 后端 Controller | 146 | +| 后端 REST 端点 | 1,242 | +| 后端 Service 接口 | ~130 | +| 后端 DO 类 | 118 | +| 后端 Mapper 接口 | 143 | +| 后端 Mapper XML | 109 | +| 数据库表 | 2,095 | +| 前端 Vue 文件 | 405 | +| 前端 JS/TS 文件 | 318 | +| 前端 API 文件 | 151 | +| 前端路由 | 91 | +| 前端 Pinia Store | 8 | +| 前端组件 | 83 | +| 前端翻译键值对 | ~6,320 | +| SVG 图标 | 197 | +| Docker 服务 | 22 | diff --git a/docs/project/qdata/data-governance-etl.md b/docs/project/qdata/data-governance-etl.md new file mode 100644 index 0000000..61a0533 --- /dev/null +++ b/docs/project/qdata/data-governance-etl.md @@ -0,0 +1,429 @@ +# QDATA 数据治理与 ETL 报告 + +> 生成日期：2026-08-27 | 基于源码深度分析 + +--- + +## 一、ETL 数据集成 + +### 1.1 双引擎架构 + +qData 采用 **DataX + Spark** 双引擎架构： + +| 引擎 | 适用场景 | 数据源支持 | +|------|---------|-----------| +| DataX | RDBMS 间数据库同步（轻量级） | rdbmsreader / rdbmswriter | +| Spark | 复杂转换、CSV/Excel 导入、分布式处理 | DB / CSV / Excel Reader | + +``` +┌──────────────────────────────────────────────────────────┐ +│ qdata-module-dpp │ +│ （ETL 任务管理、调度、监控） │ +├──────────────────────────────────────────────────────────┤ +│ │ +│ ┌─────────────────────┐ ┌─────────────────────────┐ │ +│ │ DataX 引擎 │ │ Spark 引擎 │ │ +│ │ DataXExecutor │ │ EtlApplication │ │ +│ │ DataXJsonBuilder │ │ ReaderFactory │ │ +│ │ Python subprocess │ │ TransitionFactory │ │ +│ │ │ │ WriterFactory │ │ +│ │ · rdbmsreader │ │ │ │ +│ │ · rdbmswriter │ │ · DBReader (3 模式) │ │ +│ │ · VALUE_MAP │ │ · CsvReader │ │ +│ │ · ADD_CONSTANT │ │ · ExcelReader │ │ +│ │ · SELECT_FIELDS │ │ · DBWriter (3 模式) │ │ +│ │ · FIELD_DERIVATION │ │ · 7 种 Transition │ │ +│ └──────────┬──────────┘ └────────────┬────────────┘ │ +│ │ │ │ +│ └─────────┬──────────────────┘ │ +│ ▼ │ +│ ┌──────────────────┐ │ +│ │ DolphinScheduler │ │ +│ │ / Quartz 调度 │ │ +│ └──────────────────┘ │ +└──────────────────────────────────────────────────────────┘ +``` + +### 1.2 DataX 引擎 + +**核心类**： + +| 类 | 职责 | +|----|------| +| `DataXExecutor` | 通过 Python 子进程执行 DataX 任务（`python3 datax.py job.json`） | +| `DataXJsonBuilder` | 生成 DataX job.json 配置，支持 Reader/Writer/Processor 节点 | +| `DataXProperties` | 配置项：`datax.home`、`datax.python-command`、`datax.datax-py-path`、`datax.job-dir` | + +**支持的 Processor**：`VALUE_MAP`（值映射）、`ADD_CONSTANT`（添加常量列）、`SELECT_FIELDS`（列选择）、`FIELD_DERIVATION`（字段派生）。 + +### 1.3 Spark 引擎 + +**入口**：`tech.qiantong.qdata.spark.etl.EtlApplication.main()` + +**执行流程**： +1. 接收 DolphinScheduler 传递的 Base64 编码 JSON 参数（`reader` + `transition[]` + `writer` + `config`） +2. 通过 RabbitMQ 发布 RUNNING 状态 +3. 初始化 Redis（增量游标存储） +4. 创建 `SparkSession` +5. 执行管线：`ReaderFactory` → `TransitionFactory`（N 个转换）→ `WriterFactory` +6. 通过 RabbitMQ 上报 SUCCESS/FAILURE 状态 +7. 成功写入后将增量游标存入 Redis + +**Reader 注册表**： + +| 类型码 | 类 | 说明 | +|--------|-----|------| +| `DB_READER` | `DBReader` | Spark JDBC 读取 | +| `EXCEL_READER` | `ExcelReader` | Excel 文件读取 | +| `CSV_READER` | `CsvReader` | CSV 文件读取 | + +**DBReader 读取模式**： + +| 模式 | 说明 | +|------|------| +| 1 = 全量 | 读取全表 | +| 2 = ID 增量 | 基于 Redis 缓存的 ID 游标 | +| 3 = 时间范围增量 | 支持固定值、时间范围、SQL 表达式 | + +**Transition 注册表**： + +| 类型码 | 类 | 说明 | +|--------|-----|------| +| `SPARK_CLEAN` | `CleanTransition` | 数据清洗（31KB，最复杂的转换） | +| `SORT_RECORD` | `SortTransition` | 排序 | +| `FIELD_DERIVATION` | `FieldDerivationTransition` | 字段派生 | +| `DATA_DEDUPLICATION` | `DataDeduplicationTransition` | 数据去重 | +| `VALUE_MAP` | `ValueMapTransition` | 值映射 | +| `ADD_CONSTANT` | `AddConstantTransition` | 添加常量列 | +| `SELECT_FIELDS` | `SelectFieldsTransition` | 列选择 | + +**Writer 注册表**： + +| 类型码 | 类 | 说明 | +|--------|-----|------| +| `DB_WRITER` | `DBWriter` | Spark JDBC 写入 | + +**DBWriter 写入模式**： + +| 模式 | 说明 | +|------|------| +| 1 = 全量 | 临时表 + 重命名交换 | +| 2 = 追加 | 直接追加写入 | +| 3 = 增量更新 | Upsert（PreparedStatement 批处理） | + +支持 `preSql` / `postSql` 执行，方言适配 Kingbase8、SQL Server、Doris 的表重命名操作。 + +**JDBC 驱动内置**：MySQL 8、DM8、Oracle、KingBase、SQLServer、jtds。 + +### 1.4 调度集成 + +| 调度器 | 模式 | 说明 | +|--------|------|------| +| Quartz | 进程内 | 轻量级，适合单机部署 | +| DolphinScheduler | 分布式 | 通过 HTTP API 集成，31 个端点 | + +**DolphinScheduler API 端点**（定义于 `QianTongDCApiType`）： + +| 类别 | 端点数 | 示例 | +|------|--------|------| +| 项目管理 | 4 | `POST /v2/projects`, `GET /v2/projects/{code}` | +| 流程定义 | 11 | 创建、更新、删除、发布、批量操作、版本管理 | +| 调度管理 | 6 | 创建、更新、上线、下线、预览 | +| 执行管理 | 2 | 启动流程实例、执行流程 | +| 监控查询 | 5 | 流程实例、任务实例、日志 | +| 任务编码 | 1 | 生成任务定义编码 | + +**回调机制**：ETL Spark 任务不直接调用 DolphinScheduler REST API，而是通过 **RabbitMQ** 发布状态更新： +- 交换机：`ds.exchange.processInstance`、`ds.exchange.taskInstance` +- 路由键：`ds.queue.processInstance`、`ds.queue.taskInstance.insert`、`ds.queue.taskInstance.update` + +--- + +## 二、数据开发 + +### 2.1 任务类型 + +| 类型码 | 说明 | +|--------|------| +| 1 | 离线任务 | +| 2 | 实时任务 | +| 3 | 数据开发任务（SQL 脚本） | +| 4 | 作业任务 | + +### 2.2 任务状态 + +| 状态码 | 说明 | +|--------|------| +| -3 | 部分上线 | +| -2 | 草稿 | +| 0 | 下线 | +| 1 | 上线 | + +### 2.3 核心功能 + +- **可视化 ETL 编排**：基于 AntV X6 的拖拽式流程编辑器 +- **SQL 脚本开发**：Monaco Editor 支持的 SQL 编辑与执行 +- **任务版本管理**：节点版本化，支持历史回溯 +- **统计面板**：运行中数量、今日错误数、今日执行数、成功率 + +--- + +## 三、数据质量 + +### 3.1 独立微服务 + +`qdata-service-quality`（端口 8083）独立部署，使用 **MongoDB** 存储错误数据。 + +### 3.2 质量规则引擎 + +**工厂模式**：`QualitySqlGenerateFactory` 根据规则类型分发到对应的 SQL 生成器。 + +**9 种质量规则生成器**： + +| 生成器 | 维度 | 说明 | +|--------|------|------| +| `CharacterValidationGenerator` | 有效性 | 字符格式验证 | +| `CompositeUniquenessGenerator` | 唯一性 | 组合字段唯一性 | +| `DecimalPrecisionGenerator` | 有效性 | 小数精度验证 | +| `EnumValidationGenerator` | 有效性 | 枚举值验证 | +| `GroupFieldCompletenessGenerator` | 完整性 | 分组字段完整性 | +| `LengthValidationGenerator` | 有效性 | 长度验证 | +| `NumericRangeValidationGenerator` | 有效性 | 数值范围验证 | +| `TimeOrderValidationGenerator` | 有效性 | 时间顺序验证 | +| `CommonGenerator` | 通用 | 通用规则 | + +### 3.3 数据库方言注册 + +`ComponentRegistry` 注册了 **6 种数据库方言**： + +| 数据库 | 方言类 | +|--------|--------| +| MySQL | `MySqlQuality` | +| Oracle 12c | `Oracle12cQuality` | +| Oracle | `OracleQuality` | +| SQL Server | `SQLServerQuality` | +| DM8 | `DM8Quality` | +| 默认 | `DefaultQuality` | + +### 3.4 执行流程 + +1. `QualityTaskExecutorServiceImpl.executeTask(taskId)` 提交异步执行（`ThreadPoolTaskExecutor` + Redis 去重锁） +2. 查询任务 → 生成批次号 → 获取数据源对象 → 按数据源 ID 分组 +3. 对每个数据源：连接 → 加载规则 → 通过 `RuleTaskExecutor` 逐条执行规则 +4. 错误数据存入 MongoDB（`CheckErrorData` 文档） +5. 支持 3 种错误数据修改方式： + - `updateType=1`：修改数据 + 更新物理表 + - `updateType=2`：修改备注 + - `updateType=3`：修改修复状态 + +--- + +## 四、元数据管理 + +### 4.1 采集架构 + +`qdata-module-mc` 提供自动化的元数据采集，支持增量/全量两种模式，使用 **Neo4j** 图数据库存储元数据关系。 + +### 4.2 采集流程 + +``` +McTaskServiceImpl.runDaDiscoveryTask(taskId) + │ + ├── Redis 分布式锁（防重复执行） + ├── 创建采集实例 + │ + └── executeTaskSafely(task, instance) + │ + ├── 准备数据源连接 + ├── 加载数据库范围（自定义 / 全部） + ├── 对比数据库列表（新增/删除/变更） + │ + └── 对每个数据库： + ├── 加载表列表 → 对比表列表 + ├── 加载列信息 → 对比列信息 + └── 记录变更日志 +``` + +### 4.3 变更检测 + +| 变更类型 | 说明 | +|---------|------| +| "1" | 表注释变更 | +| "2" | 列新增/删除/修改 | +| "3" | 索引字段变更 | +| "4" | 存储大小变更 | +| "1"-"9"（列级） | 注释、类型、长度、精度、小数位、默认值、主键、外键、可空 | + +### 4.4 数据库方言 + +`DatabaseDialectFactory` 注册的方言： + +| 数据库 | 方言类 | 状态 | +|--------|--------|------| +| MySQL | `MySqlDialect` | 完整实现 | +| Hive | `HiveDialect` | 完整实现 | +| DM8 | `DamengDialect` | 完整实现 | +| Oracle | `OracleDialect` | 占位实现 | +| PostgreSQL | `PostgreSqlDialect` | 占位实现 | +| SQL Server | `AbstractDialect` | 占位实现 | + +方言接口方法：`getStorageEngine()`, `getTableRowCount()`, `getTableIndexes()`, `getTablePartitionFields()`, `isColumnAutoIncrement()`, `getDbMetadata()`, `getTableMetadata()`, `getColumnMetadata()`。 + +--- + +## 五、数据资产 + +### 5.1 资产编目 + +`DaAssetServiceImpl` 是核心服务，集成 **11 个子服务**： + +| 子服务 | 职责 | +|--------|------| +| `IDaAssetColumnService` | 资产字段编目 | +| `IDaAssetApiService` | 资产 API 定义 | +| `IDaAssetApiParamService` | API 参数管理 | +| `IDaAssetGeoService` | 地理空间资产 | +| `IDaAssetGisService` | GIS 资产 | +| `IDaAssetVideoService` | 视频资产 | +| `IDaAssetFilesService` | 文件资产 | +| `IDaAssetThemeRelService` | 资产-主题关联 | +| `IDaAssetProjectRelService` | 资产-项目关联 | +| `IDaDiscoveryTableService` | 发现表管理 | +| `IDaDiscoveryTaskService` | 发现任务管理 | + +### 5.2 数据血缘 + +通过 **Neo4j** 图数据库追踪 ETL 管线的数据血缘： + +| 节点类型 | 标签 | 说明 | +|---------|------|------| +| `TableNode` | `@Node("Table")` | 数据表节点 | +| `TaskNode` | `@Node("Task")` | ETL 任务节点 | + +| 关系类型 | 方向 | 说明 | +|---------|------|------| +| `TABLE_TO_TASK` | Table → Task | 表作为任务输入 | +| `TASK_TO_TABLE` | Task → Table | 任务输出到表 | + +关系属性：`taskId`, `taskCode`, `datasourceHostPort`, `tableName`。 + +`LineageDataService` 支持 Cypher 查询遍历上下游 Table → Task → Table 链路。 + +--- + +## 六、数据服务（API 发布） + +### 6.1 动态 API 注册 + +`MappingHandlerMapping` 使用 Spring 的 `RequestMappingHandlerMapping` 在运行时动态注册/注销 REST API： + +- **URL 模式**：`/services/{version}/{path}`（如 `/services/v1.0.0/user/1`） +- **内部存储**：`ConcurrentHashMap mappings` +- **认证**：`@DsCheckClientToken` 注解 + `ApiJwtUtil` JWT 验证 + +### 6.2 API 服务类型 + +| 类型码 | 说明 | +|--------|------| +| 1 | 数据服务（数据表/SQL 查询） | +| 2 | 模型数据服务 | +| 3 | 第三方 API 代理 | +| 4 | 文件服务 | + +### 6.3 响应类型 + +| 类型码 | 说明 | +|--------|------| +| 1 | 详情（单条记录） | +| 2 | 列表 | +| 3 | 分页 | + +### 6.4 核心功能 + +- **SQL 解析**：`DsApiServiceImpl.sqlParse()` 使用 JSqlParser 解析 SQL，提取请求参数和响应字段 +- **SQL 生成**：`sqlJdbcNamedParameterBuild()` 从表单配置生成带命名参数的 SQL +- **多数据库 SQL 生成**：支持 Kingbase8、PostgreSQL、SQL Server、MySQL、Oracle +- **在线测试**：`serviceTesting()` 支持分页/列表/详情响应测试 +- **异步日志**：`AsyncTask.doTask(DsApiLogDO)` 异步记录 API 调用日志 + +--- + +## 七、数据建模 + +### 7.1 模型类型 + +| 类型码 | 说明 | +|--------|------| +| 1 | 逻辑模型 | +| 2 | 物理模型（从数据源导入） | + +### 7.2 模型分层 + +| 层 | 目标用户 | 说明 | +|----|---------|------| +| 公共层（Public Layer） | 数据开发者 | 明细模型 | +| 应用层（Application Layer） | 业务/分析师 | 聚合模型 | + +### 7.3 核心功能 + +- **逻辑模型管理**：`DpModelServiceImpl` 提供 CRUD、发布状态管理、版本控制 +- **数据元管理**：数据元标准定义、码表映射、数据元-资产关联 +- **物化视图**：`DpModelMaterializedController` 管理物化视图 +- **树形结构**：公共层（业务分类）+ 应用层（主题域） + +--- + +## 八、数据治理 + +### 8.1 数据分类分级 + +`qdata-module-dg` 提供完整的数据分类分级体系： + +| 功能 | Controller | 说明 | +|------|-----------|------| +| 数据分类 | `DgDataCategoryController` | 数据分类目录 | +| 分类子类 | `DgDataCategoryCatController` | 分类细分 | +| 数据级别 | `DgDataLevelController` | 数据分级 | +| 敏感级别 | `DgSensitiveLevelController` | 敏感数据分级 | + +### 8.2 数据脱敏 + +| 功能 | Controller | 说明 | +|------|-----------|------| +| 脱敏规则 | `DgDesensitizeRuleController` | 脱敏规则定义 | +| 脱敏区间 | `DgDesensitizeIntervalController` | 脱敏区间配置 | +| 脱敏字段 | `DgDesensitizeAssetcolumnController` | 资产字段脱敏关联 | +| 白名单 | `DgDesensitizeWhitelistController` | 脱敏白名单 | +| 用户关联 | `DgDesensitizeUserRelController` | 用户-脱敏规则关联 | + +--- + +## 九、AI 智能能力 + +### 9.1 AI 平台支持 + +`AiPlatformEnum` 支持 **19 个 AI 平台**： + +**国内（11 个）**：通义千问（DashScope）、文心一言（百度）、DeepSeek、智谱、星火（讯飞）、豆包（字节）、混元（腾讯）、SiliconFlow、MiniMax、Moonshot（Kimi）、百川。 + +**海外（8 个）**：OpenAI、Azure OpenAI、Anthropic（Claude）、Gemini（Google）、Ollama、StableDiffusion、Midjourney、Suno、Grok。 + +### 9.2 Text2SQL + +`StatisticsPromptBuilder` 实现自然语言到 SQL 的转换： + +- **星型模型支持**：事实表 + 维度表 + 事实-维度关联 +- **数据库方言感知**：MySQL、DM8/Oracle、Kingbase8、PostgreSQL、SQL Server、Doris +- **双回复模式**： + - `CHART` 模式：返回 SQL + 维度 + 度量 + 时间粒度（用于图表渲染） + - `QA` 模式：返回文本或 SQL（用于问答） + +### 9.3 事实-维度表匹配 + +`MatchPromptBuilder` 使用 AI 自动匹配事实表与维度表的关联关系： +- 输入：事实表（表名、别名、描述、列、主键）+ 维度表列表 +- 输出：JSON 格式的关联关系（维度表、事实列名、维度列名、匹配原因） + +### 9.4 独立部署 + +`qdata-service-ai`（端口 8087）独立部署，要求 **JDK 17**，通过 `DualServiceImpl` 实现 12 个空桩接口，使其可脱离其他微服务独立运行。 diff --git a/docs/project/qdata/deployment.md b/docs/project/qdata/deployment.md new file mode 100644 index 0000000..b2cfc7d --- /dev/null +++ b/docs/project/qdata/deployment.md @@ -0,0 +1,409 @@ +# 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` | `