Apache 自2.0.1版本后增加了版本自动升级功能，官方文档提供了一键升级脚本：

sh ./script/create-dolphinscheduler.sh

如果只是跨小版本的更新，那么只用执行脚本就好了，但跨多个大版本升级时依然容易出现一些问题，特此总结。

（适用于 1.x → 2.x 或 2.x → 3.x 版本升级）

一、升级前准备工作

1. 数据备份

   • 数据库备份：备份 DolphinScheduler 元数据库（MySQL/PostgreSQL）

     mysqldump -u[用户名] -p[密码] dolphinscheduler > dolphinscheduler_backup.sql

   • 配置文件备份：备份 conf/ 目录下的所有配置文件（如 application.yaml、common.properties等）

   • 资源文件备份：备份 resources/ 目录下的自定义脚本、JAR 包等资源

2. 版本兼容性检查

   • 确认当前版本是否支持直接升级到目标版本（如从 2.0.5 升级到 3.1.0 需参考官方兼容性矩阵）

   • 检查 JDBC 驱动、ZooKeeper 等依赖组件版本是否满足目标版本要求

3. 环境检查

   • 确保服务器资源（CPU/内存/磁盘）满足新版本最低要求

   • 停止所有正在运行的调度任务，避免升级过程中任务状态丢失

二、升级步骤

停止 dolphinscheduler 所有服务

根据你部署方式停止 dolphinscheduler 的所有服务，如果你是通过集群部署来部署你的 dolphinscheduler 的话，可以通过 sh ./script/stop-all.sh 停止全部服务。

数据库升级

修改./bin/env/dolphinscheduler_env.sh 中的如下配置（{user}和{password}改成你数据库的用户名和密码），然后运行升级脚本。

下面以 MySQL 为例，别的数据库仅需要修改成对应的配置即可。请先手动下载 mysql-connector-java 驱动 jar 包 并添加到 ./tools/libs 目录下，修改 ./bin/env/dolphinscheduler_env.sh 文件

    shell    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}

执行数据库升级脚本：sh ./tools/bin/upgrade-schema.sh

服务升级

修改 bin/env/install_config.conf 配置内容

• 伪集群部署请参照伪集群部署(Pseudo-Cluster)修改相关配置

• 集群部署请参照集群部署(Cluster)修改相关配置

然后运行命令 sh ./bin/start-all.sh 重启全部服务。

三、升级后验证

1. 服务状态检查

   curl http://localhost:12345/dolphinscheduler/actuator/health  # 检查API健康状态tail -n 100 logs/api-server.log                               # 查看日志是否有异常

2. 任务执行验证

   • 手动触发一个测试工作流，确认调度、任务执行、告警通知正常

   • 检查历史任务状态是否完整迁移

3. 功能兼容性验证

   • 确认原有 API 接口、自定义插件、租户配置等功能正常

   • 验证 UI 操作（如工作流定义、任务依赖配置）无报错

四、回滚方案

1. 数据库恢复

   mysql -u[用户名] -p[密码] dolphinscheduler < dolphinscheduler_backup.sql

2. 服务回滚

   • 停止新版本服务，恢复旧版本安装目录

   • 使用旧版本配置文件启动服务

五、注意事项

1. 版本跳跃升级

   • 若从 1.x 升级到 3.x，需按顺序逐步升级（如 1.3.9 → 2.0.5 → 3.1.0）

2. 数据库迁移

   • 若切换数据库类型（如 MySQL → PostgreSQL），需使用 sql/create 目录下的对应脚本重建库

3. 插件兼容性

   • 自定义告警插件、任务类型需适配新版本 SPI 接口

4. 社区资源

   • 升级问题优先参考 官方升级文档

   • 紧急问题可提交 GitHub Issue

附：版本升级流程图

graph TD    A[备份数据] --> B{部署类型}    B -->|单机/集群| C[停止服务]    B -->|Kubernetes| D[修改Helm版本]    C --> E[替换安装包]    D --> E    E --> F[执行数据库脚本]    F --> G[合并配置文件]    G --> H[启动服务]    H --> I[验证功能]    I --> J{成功?}    J -->|是| K[完成]    J -->|否| L[回滚]

通过本指南，您可安全完成 DolphinScheduler 版本升级并最大限度降低业务中断风险。建议在测试环境充分验证后再进行生产环境升级。