Apache DolphinScheduler版本升级指南：平滑迁移至最新版
项目地址: https://gitcode.com/gh_mirrors/do/dolphinscheduler 引言：为何升级刻不容缓？
你是否正面临以下痛点：数据工作流调度延迟、任务依赖管理混乱、跨团队协作效率低下？Apache DolphinScheduler作为现代数据编排平台，通过持续版本迭代解决了这些核心问题。本文将带你完成从准备到验证的全流程升级，确保业务无感知迁移至最新版，同时解锁低代码工作流设计、多租户隔离、千万级任务调度等企业级能力。
读完本文你将掌握：
- 升级前的兼容性检查与环境备份策略
- 四种部署模式（Standalone/Cluster/Docker/K8s）的升级路径
- 数据库与资源中心的无缝迁移方案
- 常见故障的诊断与回滚机制
一、升级准备：规避90%的潜在风险
1.1 兼容性检查清单
在执行升级前，必须确认当前版本与目标版本间的不兼容变更。DolphinScheduler采用语义化版本控制（x.y.z）：
- 主版本号(x)：架构级变更，需手动迁移（如1.x → 2.x）
- 次版本号(y)：功能迭代，可能包含不兼容API变更
- 修订号(z)：Bug修复，完全兼容升级
通过以下命令查看不兼容变更文档：
# 查看官方不兼容变更记录
cat docs/docs/en/guide/upgrade/incompatible.md
1.2 环境备份方案
数据库备份（以MySQL为例）：
# 完整备份数据库
mysqldump -u${USERNAME} -p${PASSWORD} -h${HOST} --databases dolphinscheduler > dolphinscheduler_backup_$(date +%Y%m%d).sql
# 验证备份文件
ls -lh dolphinscheduler_backup_*.sql | awk '{print $5, $9}'
配置文件备份：
# 创建备份目录
mkdir -p /opt/dolphinscheduler_backup/{conf,logs,script}
# 备份关键配置
cp -r ./conf/* /opt/dolphinscheduler_backup/conf/
cp -r ./script/* /opt/dolphinscheduler_backup/script/
cp ./bin/env/install_env.sh /opt/dolphinscheduler_backup/
1.3 硬件资源检查
最新版对服务器资源要求： | 组件 | CPU核心数 | 内存 | 磁盘空间 | 网络带宽 | |------|----------|------|----------|----------| | Master | ≥4核 | ≥8GB | ≥100GB | ≥1Gbps | | Worker | ≥8核 | ≥16GB | ≥500GB | ≥1Gbps | | 数据库 | ≥8核 | ≥16GB | ≥1TB | ≥1Gbps |
通过以下命令检查当前资源使用情况：
# 查看CPU负载
top -bn1 | grep "Cpu(s)"
# 检查内存使用
free -h
# 磁盘空间检查
df -h /opt/dolphinscheduler
二、多场景升级实战：从部署模式选择最优路径
2.1 集群模式升级（生产环境推荐）
步骤1：停止现有服务
# 停止所有服务
sh ./script/stop-all.sh
# 验证服务状态
jps | grep -E "MasterServer|WorkerServer|ApiApplicationServer"
步骤2：数据库升级
设置环境变量并执行升级脚本：
# 配置数据库连接信息
export DATABASE=mysql
export SPRING_DATASOURCE_URL="jdbc:mysql://127.0.0.1:3306/dolphinscheduler?useSSL=false&serverTimezone=UTC"
export SPRING_DATASOURCE_USERNAME=root
export SPRING_DATASOURCE_PASSWORD=password
# 执行升级脚本
sh ./tools/bin/upgrade-schema.sh
脚本执行成功标志：
...
2024-09-14 10:23:45.678 [main] INFO UpgradeSchema - Schema upgrade completed successfully
2024-09-14 10:23:45.679 [main] INFO UpgradeSchema - Total executed SQL files: 12
步骤3：资源中心迁移（3.2.0+必需）
3.2.0版本重构了资源中心，需执行迁移脚本：
# 指定目标租户（需提前在系统存在）
sh ./tools/bin/migrate-resource.sh etl_tenant
# 验证迁移结果
ls -l /dolphinscheduler/etl_tenant/resources/.migrate/
迁移后资源路径变化： | 原路径 | 新路径 | |--------|--------| | /resources/a/b.sh | /dolphinscheduler/etl_tenant/resources/.migrate/a/b.sh | | /udf/x/y.jar | /dolphinscheduler/etl_tenant/udf/.migrate/x/y.jar |
步骤4：服务升级与启动
# 同步配置文件（仅修改差异部分）
cp /opt/dolphinscheduler_backup/conf/application.yaml ./conf/
cp /opt/dolphinscheduler_backup/conf/dolphinscheduler_env.sh ./conf/
# 修改安装环境配置
vi ./bin/env/install_env.sh
# 关键配置项：
# - JAVA_HOME=/usr/local/jdk1.8.0_381
# - DATABASE=mysql
# - SPRING_DATASOURCE_URL=jdbc:mysql://127.0.0.1:3306/dolphinscheduler
# 启动所有服务
sh ./bin/start-all.sh
# 检查服务状态
sh ./script/status-all.sh
2.2 Kubernetes环境升级
使用Helm进行一键升级：
# 添加官方Helm仓库
helm repo add dolphinscheduler https://apache.github.io/dolphinscheduler-helm
# 升级Chart包
helm upgrade --install dolphinscheduler \
--create-namespace --namespace dolphinscheduler \
oci://registry-1.docker.io/apache/dolphinscheduler-helm \
--version 3.2.0 \
--set image.tag=3.2.0 \
--set worker.replicas=3 \
--set master.replicas=2
自定义资源配置示例：
# values.yaml
worker:
resources:
requests:
cpu: 4
memory: 8Gi
limits:
cpu: 8
memory: 16Gi
keda:
enabled: true # 启用自动扩缩容
minReplicaCount: 2
maxReplicaCount: 10
应用自定义配置：
helm upgrade dolphinscheduler -f values.yaml oci://registry-1.docker.io/apache/dolphinscheduler-helm --version 3.2.0
2.3 Docker Compose快速升级
# 下载最新docker-compose.yml
wget https://raw.githubusercontent.com/apache/dolphinscheduler/dev/deploy/docker/docker-compose.yml -O docker-compose-new.yml
# 备份当前配置
mv docker-compose.yml docker-compose-old.yml
mv docker-compose-new.yml docker-compose.yml
# 拉取最新镜像并重启
docker-compose pull
docker-compose up -d
# 执行数据库升级
docker-compose exec tools sh -c "tools/bin/upgrade-schema.sh"
三、核心组件迁移详解
3.1 数据库平滑迁移
DolphinScheduler使用统一的升级脚本管理数据库变更，支持MySQL、PostgreSQL等主流数据库。升级流程：
执行升级命令：
# 设置数据库连接
export DATABASE=postgresql
export SPRING_DATASOURCE_URL="jdbc:postgresql://127.0.0.1:5432/dolphinscheduler"
export SPRING_DATASOURCE_USERNAME=postgres
export SPRING_DATASOURCE_PASSWORD=password
# 执行升级
sh ./tools/bin/upgrade-schema.sh
# 验证升级结果
echo "SELECT version FROM t_ds_version;" | psql -h 127.0.0.1 -U postgres -d dolphinscheduler
3.2 资源中心迁移（3.2.0+重点）
3.2.0版本重构了资源中心，引入租户隔离机制。执行迁移脚本：
# 迁移指定租户的资源
sh ./tools/bin/migrate-resource.sh etl_tenant
# 验证迁移结果
ls -l /dolphinscheduler/etl_tenant/resources/.migrate/
迁移前后目录结构对比：
# 迁移前（1.x/2.x）
/resources
├── a.sh
└── dir/
└── b.sql
# 迁移后（3.2.0+）
/dolphinscheduler/etl_tenant/resources
└── .migrate/
├── a.sh
└── dir/
└── b.sql
3.3 工作流 lineage数据迁移
为提升工作流血缘分析性能，3.2.0版本重构了lineage存储结构：
# 执行lineage迁移
sh ./tools/bin/migrate-lineage.sh
# 验证迁移数据量
echo "SELECT COUNT(*) FROM t_ds_process_task_lineage;" | mysql -u${USERNAME} -p${PASSWORD} dolphinscheduler
四、升级后验证与优化
4.1 健康检查清单
| 检查项 | 验证命令 | 预期结果 |
|---|---|---|
| 服务状态 | jps | 所有Master/Worker进程正常运行 |
| API可用性 | curl -I http://localhost:12345/actuator/health | HTTP 200 OK |
| 数据库连接 | tail -f logs/api-server.log | 无数据库连接错误 |
| 工作流执行 | 提交测试工作流 | 任务成功完成，无异常日志 |
4.2 性能优化建议
JVM参数调优（针对Master节点）：
# 修改conf/env/dolphinscheduler_env.sh
export MASTER_JAVA_OPTS="-Xms4g -Xmx8g -XX:+UseG1GC -XX:MaxGCPauseMillis=200"
数据库优化：
-- MySQL索引优化
ALTER TABLE t_ds_task_instance ADD INDEX idx_task_instance_4 (process_instance_id, state);
-- 调整连接池大小
SET GLOBAL max_connections = 1000;
任务调度优化：
# conf/application-master.yaml
master:
task:
commit:
batch:
size: 100 # 批量提交任务数量
interval: 500ms # 提交间隔
五、常见问题与解决方案
5.1 数据库升级失败
症状：执行upgrade-schema.sh时报主键冲突错误
Caused by: java.sql.SQLIntegrityConstraintViolationException: Duplicate entry '123' for key 'PRIMARY'
解决方案：
# 恢复数据库备份
mysql -u${USERNAME} -p${PASSWORD} dolphinscheduler < dolphinscheduler_backup_*.sql
# 手动执行增量SQL
cd tools/sql/upgrade/3.1.5_schema
for sql in *.sql; do mysql -u${USERNAME} -p${PASSWORD} dolphinscheduler < $sql; done
5.2 资源中心文件访问权限问题
症状：任务执行报"Permission denied"错误
java.io.FileNotFoundException: /dolphinscheduler/tenant/resources/script.sh (Permission denied)
解决方案：
# 修复资源目录权限
chown -R dolphinscheduler:dolphinscheduler /dolphinscheduler
chmod -R 755 /dolphinscheduler/*/resources
5.3 升级后任务依赖断裂
原因：1.x版本的任务依赖表达式在2.x版本中语法变更 修复：使用脚本批量更新依赖表达式
# 导出需要更新的工作流定义
curl -X GET "http://localhost:12345/dolphinscheduler/projects/{projectId}/workflow-definitions" -o workflows.json
# 使用Python脚本批量替换依赖表达式
python3 - <<END
import json
with open("workflows.json") as f:
data = json.load(f)
for wf in data['data']['totalList']:
if 'conditions' in wf['processDefinitionJson']:
# 将旧语法${VAR}替换为新语法\${VAR}
wf['processDefinitionJson'] = wf['processDefinitionJson'].replace('${', '\${')
# 导入更新后的定义
# curl -X POST ...
END
六、总结与展望
通过本文档，你已掌握DolphinScheduler的完整升级流程，包括环境准备、多模式升级路径、核心组件迁移及优化技巧。建议建立常态化升级机制：
- 小版本升级：每季度执行z版本更新（如3.2.0 → 3.2.1）
- 功能升级：每半年评估y版本特性（如3.2.x → 3.3.0）
- 架构升级：重大版本变更（如2.x → 3.x）需制定专项迁移计划
下一版本将重点提升：
- 云原生部署体验（K8s Operator支持）
- AI任务调度优化（GPU资源调度）
- 实时数据处理能力（Flink/Spark集成增强）
立即行动，通过以下命令启动升级：
# 克隆官方仓库
git clone https://gitcode.com/gh_mirrors/do/dolphinscheduler
cd dolphinscheduler
# 执行升级流程
./tools/bin/upgrade-schema.sh # 数据库升级
./script/start-all.sh # 启动服务
祝你的数据编排之旅更加高效！
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
