企业官网建设流程全解析

Apache DolphinScheduler 前端架构深度解析：Vue 3 + Vite + TypeScript 构建现代数据编排平台的 Web 界面

【免费下载链接】dolphinschedulerApache DolphinScheduler is the modern data orchestration platform. Agile to create high performance workflow with low-code项目地址: https://gitcode.com/GitHub_Trending/dol/dolphinscheduler

Apache DolphinScheduler 的 Web 前端模块dolphinscheduler-ui是一套基于Vue 3 + Vite + TypeScript构建的现代化管理界面，采用 Naive UI 作为组件库、AntV X6 实现 DAG 工作流编辑器、ECharts 渲染监控大盘，与 Java 后端（dolphinscheduler-api）通过 axios 解耦通信。本文以该模块的 CLAUDE.md 为骨架，结合仓库源码、配置文件与打包链路，系统讲解其技术选型、目录结构、开发命令、前后端集成方式与典型坑点，帮助读者快速上手开发、排查问题并理解 UI 在整个 DolphinScheduler 发行版中的角色。

一、模块定位：独立构建、随发行版分发的 Web 前端

在 Apache DolphinScheduler 的多模块 Java 工程中，dolphinscheduler-ui是一个独立于 Java 反应堆（reactor）构建的前端子模块：

• 它不参与 Maven 的 Java 编译链，而是使用pnpm构建出静态资源目录dist/；
• dolphinscheduler-dist/pom.xml 声明依赖dolphinscheduler-ui，并在 dolphinscheduler-dist/src/main/assembly/dolphinscheduler-bin.xml 中将dolphinscheduler-ui/dist目录整体打入发行包，最终在安装包的ui/目录下提供前端静态文件。

因此，无论手动打包还是执行./mvnw package，都必须先运行pnpm run build:prod生成dist/，否则发行包内将缺失前端资源（dolphinscheduler-dist/CLAUDE.md 也明确提示"broken UI build breaks the dist build"）。

二、技术栈总览

从 package.json 看，UI 还内置了monaco-editor（用于 Shell/SQL 等任务的代码编辑体验）、protobufjs（部分接口的序列化）、screenfull（全屏）与nprogress（路由进度条）等辅助库，形成了完整的前端工程能力闭环。

三、推荐工具链与版本约束

CLAUDE.md 与模块 README 一致强调版本约束：

• Node 16.x（不要使用 18+）；
• pnpm 7.x。

原因：Node 18/20 自带的新版 OpenSSL 与旧版 webpack/vite 配置存在兼容性问题，Node 版本漂移是 UI 开发中排名第一的破坏性因素。.nvmrc/package.json中的packageManager字段才是权威版本声明，应以仓库实际固定版本为准。

四、常用脚本命令

在dolphinscheduler-ui/目录下执行：

# 1. 安装依赖 pnpm install # 2. 启动 Vite 开发服务器（默认端口 5173） pnpm run dev # 3. 生产构建：vue-tsc 类型检查 + Vite 构建 → dist/ pnpm run build:prod # 4. 代码检查（自动修复 .ts/.tsx/.vue） pnpm run lint # 5. 代码格式化（作用于 src/） pnpm run prettier

对应脚本定义见 package.json：

开发服务器代理逻辑见 vite.config.ts：所有/dolphinscheduler前缀请求被代理到.env.development中的VITE_APP_DEV_WEB_URL。

五、环境变量与前后端联调配置

仓库中存在两个环境文件：

开发环境 .env.development

NODE_ENV=development VITE_APP_DEV_WEB_URL='http://127.0.0.1:12345'

• pnpm run dev启动后，浏览器访问http://localhost:5173；
• 前端请求/dolphinscheduler/...会被 Vite 代理转发到VITE_APP_DEV_WEB_URL，即默认假设dolphinscheduler-api服务运行在本机12345端口；
• 按 README 说明，修改该变量时只需填写http://IP:端口，末尾不要带/，例如http://127.0.0.1:12345。

生产环境 .env.production

NODE_ENV=production VITE_APP_PROD_WEB_URL=''

• pnpm run build:prod打包时需按实际部署场景设置VITE_APP_PROD_WEB_URL，确保打包产物能请求到正确的后端服务地址；
• 为空时走同源策略，即前端与dolphinscheduler-api部署在同一域名下，由反向代理统一转发。

六、顶层源码目录结构

dolphinscheduler-ui/src/ ├── assets/ # 静态图片 + 字体 ├── components/ # 可复用 UI 部件（表单控件、数据展示、DAG 画布组件） ├── layouts/ # 应用外壳 / 页面框架 ├── locales/ # i18n 翻译（en_US、zh_CN） ├── router/ # Vue Router 配置，每个顶层功能一个模块 ├── service/ # axios 实例 + 每个后端资源一个文件 ├── store/ # Pinia 状态：user、project、locales、theme、timezone、route、ui-setting、file ├── views/ # 页面组件 └── utils/ # 工具函数

6.1 路由：5 大顶层分组

src/router/modules 下按功能拆分为 5 个顶层路由模块：projects（项目管理）、resources（资源中心）、datasource（数据源）、monitor（监控中心）、security（安全中心），外加一个ui-setting（界面设置）。

src/router/routes.ts 使用 Vite 的import.meta.glob('/src/views/**/**.tsx')自动扫描views/下所有 TSX 文件生成组件映射，配合utils.mapping完成路由与页面组件的绑定，新增页面时只需在views/添加 TSX 文件与对应路由模块即可。

6.2 服务层：按后端资源拆分的 API 模块

src/service/modules 下按后端资源拆分出32 个 API 模块：login、logout、users、tenants、worker-groups、queues、alert-group、alert-plugin、data-source、projects、workflow-definition、workflow-instances、task-definition、task-instances、task-group、schedules、executors、monitor、audit、token、environment、cluster、k8s-namespace、log、lineages、projects-analysis、projects-parameter、projects-preference、projects-worker-group、dynamic-dag、dag-menu、ui-plugins、azure等，基本一一对应 dolphinscheduler-api 后端的 Controller 资源。

6.3 状态管理：Pinia stores

src/store 中管理 8 个全局 store：user（用户与会话）、project（项目上下文，含dynamic/dag动态 DAG 状态）、locales（语言）、theme（明暗主题）、timezone（时区）、route（路由辅助）、ui-setting（界面偏好，含 API 超时时间）、file（文件资源）。项目依赖pinia-plugin-persistedstate实现状态持久化。

6.4 页面视图

src/views 下包含：home（首页）、projects（工作流/任务编排，含最复杂的 DAG 编辑器）、datasource（数据源管理）、monitor（监控中心）、resource（资源中心）、security（安全中心）、login（登录）、profile（用户信息）、password（改密）、about（产品信息）、ui-setting（界面设置）。

七、后端集成：axios 封装与拦截器

唯一 axios 封装位于 src/service/service.ts，全项目 API 调用均复用此实例：

const baseRequestConfig: AxiosRequestConfig = { baseURL: import.meta.env.MODE === 'development' ? '/dolphinscheduler' : import.meta.env.VITE_APP_PROD_WEB_URL + '/dolphinscheduler', timeout: uiSettingStore.getApiTimer ? uiSettingStore.getApiTimer : 20000, ... }

关键行为（全部可从源码确认）：

1. baseURL 双模式：开发模式为/dolphinscheduler（由 Vite 代理转发）；生产模式为VITE_APP_PROD_WEB_URL + '/dolphinscheduler'，通常同源部署在反向代理之后。
2. 请求拦截器（service.ts）：自动注入sessionId请求头（取自userStore），并读取languagecookie 注入language请求头。
3. 响应拦截器（service.ts）：统一解包后端{ code, msg, data }三层结构——code === 0时直接返回data；code缺失（非标准结构）时原样返回；其他 code 触发handleError（开发模式打印日志 +window.$message.error）并抛出错误。
4. 401 / 504 统一处理（service.ts）：清空userStore中的会话信息并跳转/login。
5. 参数序列化：使用qs.stringify(params, { arrayFormat: 'repeat' })，数组参数以重复键（a=1&a=2）形式提交。

重要提醒（来自 CLAUDE.md）：本项目没有生成 OpenAPI SDK，后端方法签名与这些 TypeScript 封装各自独立演进。后端 Controller 变更后，前端往往要到运行时出现 4xx / 5xx 才能发现回归。开发时改动接口务必前后端联动验证。

八、i18n 国际化机制

• 当前支持en_US、zh_CN两种语言，语言包位于 src/locales；
• 语言切换偏好通过js-cookie写入languagecookie（package.json 依赖js-cookie ^3.0.1）；
• 语言状态同时由 Pinialocalesstore 管理，请求时由 axios 请求拦截器读取 cookie 注入请求头，保证前端界面语言与后端返回文案一致。

九、生产构建与 gzip 预压缩

vite.config.ts 中通过vite-plugin-compression配置了 gzip 预压缩：

viteCompression({ verbose: true, disable: false, threshold: 10240, // 仅压缩超过 10KB 的文件 algorithm: 'gzip', ext: '.gz', deleteOriginFile: false // 保留原文件 })

注意两点：

• 生产构建 base 路径为/dolphinscheduler/ui/（vite.config.ts），部署时需保证静态资源可通过该路径访问；
• 调试"某个文件加载不出来"时，先确认服务器是否正确返回.gz变体，因为很多场景是压缩文件未随服务器配置正确服务。

十、最复杂的视图：AntV X6 DAG 编辑器

工作流编排是 DolphinScheduler 的核心能力，其 DAG 编辑器位于 src/views/projects/workflow/components/dag，是全项目最复杂、最需要谨慎改动的视图。目录下约 30 个文件，覆盖了完整的图编辑能力：

DAG 编辑器把"工作流定义 ↔ 图数据模型"做了双向映射，涉及节点状态展示（运行中/成功/失败着色）、拖拽、连线、自动布局、批量回填等大量交互逻辑，改动风险高，社区在 CLAUDE.md 中明确建议"Touch carefully"。

十一、测试策略：无单测，依赖 E2E

• dolphinscheduler-ui模块没有配置单元测试，仓库中不存在*.spec.ts/*.test.ts；
• 前端功能由 dolphinscheduler-e2e 模块以 Selenium 驱动的浏览器端到端测试覆盖（UI + API 集成场景）。

十二、常见坑点清单（Gotchas）

综合 CLAUDE.md 与源码，在实际开发中优先排查以下问题：

1. Node 版本漂移：必须使用固定 Node 16.x + pnpm 7.x，18/20 会因 OpenSSL 变化破坏构建。
2. 忘记构建 dist：发行打包前务必先执行pnpm run build:prod，dolphinscheduler-dist直接从dolphinscheduler-ui/dist取材（dolphinscheduler-bin.xml）。
3. 接口变更回归：无 OpenAPI SDK，后端签名变化需运行时才能发现，改动接口前后端要同步验证。
4. gzip 预压缩：生产环境文件以.gz变体提供，排查加载失败先看服务器是否正确服务压缩文件。
5. 代理与 baseURL：开发走/dolphinscheduler代理（目标VITE_APP_DEV_WEB_URL，默认 12345 端口），生产走VITE_APP_PROD_WEB_URL + /dolphinscheduler，两个环境变量别配错。
6. DAG 编辑器高复杂度：涉及 src/views/projects/workflow/components/dag 的改动需格外谨慎，回归测试要覆盖拖拽、连线、状态回填等核心交互。

十三、与其他模块的关系

dolphinscheduler-api ←─ HTTP/JSON ── dolphinscheduler-ui（本模块） │ │ pnpm run build:prod │ ▼ dolphinscheduler-dist ── 打包 dist/ → 发行包 ui/ 目录 ▲ dolphinscheduler-e2e ── 基于 Selenium 的集成测试（UI + API）

• dolphinscheduler-api：UI 调用的后端服务，提供登录、项目、工作流、任务、数据源、监控等 REST API；
• dolphinscheduler-dist：在发行包中打包dist/到ui/目录；
• dolphinscheduler-e2e：对集成后的 UI + API 进行浏览器端到端测试。

结语

dolphinscheduler-ui以 Vue 3 + Vite + TypeScript 的现代前端工程栈，承载了 DolphinScheduler 全部可视化能力——从登录鉴权、项目管理、数据源配置，到基于 AntV X6 的 DAG 工作流编排、基于 ECharts 的监控大盘，再到完善的双语国际化与明暗主题。理解其"独立构建、后端解耦、dist 交付"的定位，掌握环境变量、axios 拦截器、路由自动映射与构建链路，就能在 dolphinscheduler-ui 中高效地开发与排障。

【免费下载链接】dolphinschedulerApache DolphinScheduler is the modern data orchestration platform. Agile to create high performance workflow with low-code项目地址: https://gitcode.com/GitHub_Trending/dol/dolphinscheduler