企业官网建设流程全解析

• 任务调度
• 大数据
• 后端
• 前端

本篇技术指南围绕 Apache DolphinScheduler 的官方升级文档（docs/docs/en/guide/upgrade/upgrade.md）展开，完整讲解从升级前准备、数据库 Schema 升级、资源中心迁移、血缘数据迁移到服务启动的端到端流程，并结合仓库中dolphinscheduler-tools模块的脚本与源码，说明每一步背后的实现原理。读完本文，你将掌握一套可复制的 DolphinScheduler 版本升级 SOP，并理解升级脚本的工作机制与版本间的不兼容点。

升级前准备（Prepare）

升级不是简单的"下载新包、替换旧包"，尤其是跨大版本升级（如 3.0.x → 3.2.0+），必须先完成以下三项准备工作。

检查不兼容变更（Check Incompatible Change）

官方在升级前强烈建议先阅读不兼容变更清单：incompatible.md。该文档按版本记录了可能破坏现有功能的变更，例如：

• dev 分支：MySQL 驱动从 8.0.16 升级到 8.0.33；环境变量PYTHON_HOME改为PYTHON_LAUNCHER、DATAX_HOME改为DATAX_LAUNCHER；SQL 任务插件中 SQL 参数的正则匹配规则调整；默认 Unix Shell 执行器从sh改为bash；common.properties中的data-quality.jar.name更名为data-quality.jar.dir并改为表示目录等。
• 3.2.0：新资源中心的公共接口移除了description参数；/datasources/tables与/datasources/tableColumnsAPI 新增必填字段database。
• 3.3.0：从资源中心移除udf-manage功能；从任务插件中移除Pigeon。

这些变更可能涉及环境变量名、配置项、API 参数甚至已删除的功能，升级前逐条核对可避免升级后任务无法运行或接口报错。

备份旧版本文件与数据库（Backup）

为避免误操作导致数据丢失，官方建议在升级前按你的部署环境对数据做好备份，至少包括：

• 当前运行版本的配置文件（如bin/env/install_env.sh、bin/env/dolphinscheduler_env.sh、common.properties等）；
• 元数据库（DolphinScheduler 的dolphinscheduler库），它是工作流定义、调度信息、租户、告警等全部元数据的载体；
• 资源存储目录（本地文件系统或 S3/OSS/HDFS 等对象存储中的资源文件）。

备份方式没有统一模板，取决于你的环境（MySQL 可用mysqldump，PostgreSQL 可用pg_dump），但"先备份、后升级"是必须遵守的铁律。

下载最新安装包（Download）

从 DolphinScheduler 官网下载最新的二进制发行包，并将其放到与当前服务运行目录不同的新目录中。后续所有升级命令都默认在这个新目录下执行，这样既能保留旧版本目录作为回退方案，也避免新旧文件混杂。

升级步骤总览（Upgrade）

升级整体分为五步，顺序固定、不可颠倒：

1. 停止所有 DolphinScheduler 服务；
2. 升级数据库（Schema 升级）；
3. 迁移资源（资源中心重构后的一次性迁移）；
4. 迁移血缘数据；
5. 修改配置并启动新版本服务。

第一步：停止所有 DolphinScheduler 服务

根据你的部署方式停止全部服务。如果此前按照集群部署文档部署，可执行：

sh ./script/stop-all.sh

伪集群部署（Pseudo-Cluster）同理。停止服务的目的是确保升级期间没有服务写入数据库和资源存储，避免 Schema 变更或数据迁移过程中出现并发写入冲突。

第二步：升级数据库（Upgrade Database）

数据库升级是核心环节，它负责把旧版本的元数据库结构升级到新版本。步骤如下：

1. 准备数据库驱动

以 MySQL 为例（其他数据库同理，只需替换为对应驱动）：手动下载mysql-connector-java驱动 jar 包，放入新安装包的./tools/libs目录。

2. 导出数据库连接环境变量

将{user}和{password}替换为你的数据库用户名与密码：

export DATABASE=${DATABASE:-mysql} export SPRING_PROFILES_ACTIVE=${DATABASE} export SPRING_DATASOURCE_URL="jdbc:mysql://127.0.0.1:3306/dolphinscheduler?useUnicode=true&characterEncoding=UTF-8&useSSL=false" export SPRING_DATASOURCE_USERNAME={user} export SPRING_DATASOURCE_PASSWORD={password}

这里DATABASE决定激活哪套数据源配置，取值如mysql、postgresql、h2等；SPRING_DATASOURCE_URL需按实际地址、端口和库名修改。

3. 执行升级脚本

sh ./tools/bin/upgrade-schema.sh

源码视角：该脚本在仓库中的原始位置是 dolphinscheduler-tools/src/main/bin/upgrade-schema.sh，被打包后位于安装包的tools/bin/目录。从脚本源码可以看到其工作机制：

• 通过DOLPHINSCHEDULER_HOME（默认取脚本上级两级目录）定位安装根目录，并加载bin/env/dolphinscheduler_env.sh获取JAVA_HOME等环境；
• 默认JAVA_OPTS为-server -Xms1g -Xmx1g，并开启了 GC 日志与 OOM HeapDump；
• 将tools/conf、tools/libs/*、tools/sql加入 classpath；
• 以-Dspring.profiles.active=upgrade,${DATABASE}启动主类org.apache.dolphinscheduler.tools.datasource.UpgradeDolphinScheduler。

而入口类 UpgradeDolphinScheduler.java 中的UpgradeRunner会判断：如果schemaIsInitialized()为真则执行upgradeDolphinScheduler()，否则执行initDolphinScheduler()——也就是说同一个脚本同时承担了初始化与升级两种职责，脚本会自动识别库状态。升级逻辑由 DolphinSchedulerManager 调度，并存在按版本分层的升级器（如v130、v132、v200、v320等 upgrader），从源码结构可以看出系统是按目标版本逐步执行升级 SQL 的。

第三步：迁移资源（Migrate Resource）

在 3.2.0 版本重构资源中心后，旧版本的资源变为**未托管（unmanaged）**状态。需要指定一个目标租户，执行一次性迁移脚本，所有资源将被迁移到该租户的.migrate目录下。

脚本入口是 dolphinscheduler-tools/src/main/bin/migrate-resource.sh，打包后位于tools/bin/：

sh ./tools/bin/migrate-resource.sh abc

示例说明：假设目标租户abc已存在，其基础资源路径为/dolphinscheduler/abc/，执行后：

• 原文件资源a/b.sh迁移到/dolphinscheduler/abc/resources/.migrate/a/b.sh；
• 原 UDF 资源x/y.jar迁移到/dolphinscheduler/abc/udf/.migrate/x/y.jar；
• 同时更新 UDF 函数所绑定的资源信息。

源码视角：脚本以-Dspring.profiles.active=resource,${DATABASE}启动主类org.apache.dolphinscheduler.tools.resource.MigrateResource。入口类 MigrateResource.java 中的MigrateResourceRunner会把命令行第一个参数作为目标租户编码：

String targetTenantCode = args[0]; logger.info("Moving all unmanaged resources to tenant: {}", targetTenantCode); migrateResourceService.migrateResourceOnce(targetTenantCode);

即migrate-resource.sh abc中的abc正是args[0]，随后交由 MigrateResourceService 完成文件搬迁与 UDF 绑定关系的更新。注意该迁移是一次性的，执行前请确认目标租户已存在，且迁移对象是你确认无需再手动整理的旧资源。

第四步：升级血缘数据（Upgrade Lineage）

执行：

sh ./tools/bin/migrate-lineage.sh

执行结果：

• 将血缘数据迁移到新表t_ds_process_task_lineage；
• 该脚本只执行 upsert（插入或更新）操作，不会删除数据；如果你需要清理旧数据，可以手动删除。

源码视角：脚本 dolphinscheduler-tools/src/main/bin/migrate-lineage.sh 以-Dspring.profiles.active=lineage,${DATABASE}启动org.apache.dolphinscheduler.tools.lineage.MigrateLineage。入口类 MigrateLineage.java 的MigrateLineageRunner调用migrateLineageService.migrateLineageOnce()完成迁移。值得一提的是，该脚本默认 JVM 堆为-Xms4g -Xmx4g，比前两个脚本（默认 1g）大得多——从这一细节可以看出血缘数据迁移涉及的数据量通常较大，脚本为海量数据处理预留了更大的堆空间。

第五步：升级服务（Upgrade Service）

数据库、资源、血缘都迁移完成后，开始启动新版本服务。

1. 修改配置bin/env/install_env.sh

• 若为伪集群部署，按伪集群部署文档中的"修改配置"一节调整；
• 若为集群部署，按集群部署文档中的"修改配置"一节调整。

这一步需要把install_env.sh中的部署机器列表（如ips、masters、workers等）更新为你当前环境的实际机器与角色规划，重点是对齐旧版本中的 worker 分组配置（详见下文"注意事项"）。

2. 启动所有服务

sh ./bin/start-all.sh

启动后可通过 UI 与任务日志验证升级结果：确认工作流定义、调度、租户、告警等元数据完整，资源文件可正常访问，血缘页面能查询到迁移后的数据。

注意事项：Worker Group 的版本差异（Notice）

Worker Group 的架构在 1.3.1 之前、1.3.1～2.0.0 之间以及 2.0.0 之后有显著差异，升级时需要特别处理，否则会导致 worker 分组错乱。

• 1.3.1 及之前：Worker Group 可以通过 UI 界面直接创建；
• 1.3.1 之后至 2.0.0 之前：Worker Group 只能通过修改 worker 配置来创建；
• 2.0.0 及之后：恢复为通过 Web UI 创建 Worker Group 的功能。

从 1.3.1 升级到 2.0.0 之前的版本怎么办

1. 查询备份数据库

在备份数据库中查询t_ds_worker_group表，重点关注三列：id、name和IP：

2. 修改bin/env/install_env.sh中的 worker 配置

假设要部署的 worker 机器如下：

为了让 worker 分组与旧版本保持一致，需要把workers配置修改为（格式为机器名:分组名，同一分组可写多个机器）：

# worker 服务部署在哪些机器上，同时指定该 worker 属于哪个 worker group workers="ds1:service1,ds2:service2,ds3:service2"

Worker Group 在 1.3.2 中的增强

1.3.1 中一个 worker 只能属于一个 worker group；而 1.3.2 之后至 2.0.0 之前，一个 worker 可以属于多个 worker group，例如：

workers="ds1:service1,ds1:service2"

表示ds1这台机器同时归属于service1和service2两个分组。

2.0.0 之后恢复 UI 创建

2.0.0 及之后版本恢复了在 Web UI 中创建 Worker Group 的功能，升级到这些版本后即可回到界面化管理方式。

结语

DolphinScheduler 的升级流程本质上是一个"停服 → 库结构升级 → 数据迁移 → 配置对齐 → 启动验证"的完整闭环。其中数据库升级由upgrade-schema.sh依据库状态自动区分初始化与升级，资源迁移通过migrate-resource.sh将旧资源收编到指定租户的.migrate目录，血缘迁移通过migrate-lineage.sh以只增不删的 upsert 方式导入新表。升级前务必对照不兼容变更清单逐条核查，并结合 tools 模块源码理解每个脚本的实际行为，才能保证生产环境平稳、无痛地完成版本跃迁。

• 任务调度
• 大数据
• 后端
• 前端