1. 升级背景与版本差异分析从DolphinScheduler 1.3.4升级到3.1.2属于跨越两个大版本的升级这中间经历了架构的重大调整和功能重构。1.3.4版本发布于2020年采用的是主从架构而3.1.2版本已经完全重构为微服务架构。这种架构变化带来了几个关键差异点API接口变更3.x版本完全重写了REST API1.x版本的API调用方式不再兼容数据库结构变化工作流定义表、任务实例表等核心表结构都发生了变更调度引擎升级从基于Quartz的调度改为自研的分布式调度引擎权限模型重构从简单的用户-租户模型升级为RBAC权限体系重要提示直接从1.3.4升级到3.1.2是不被官方支持的必须按照1.3.4 → 2.0.5 → 3.1.2的顺序逐步升级。跳过中间版本会导致数据库迁移失败。2. 升级前的准备工作2.1 环境检查清单在开始升级前需要确保环境满足以下要求硬件资源Master节点至少4核CPU/8GB内存Worker节点至少2核CPU/4GB内存磁盘空间元数据库预留10GB以上空间软件依赖JDK版本必须使用JDK 81.3.4升级到JDK 113.1.2数据库驱动MySQL驱动需要从5.x升级到8.xZooKeeper从3.4.x升级到3.6.x数据备份# 备份元数据库 mysqldump -uroot -p dolphinscheduler ds_backup_1.3.4.sql # 备份资源文件 tar -czvf ds_resources_1.3.4.tar.gz /opt/dolphinscheduler/resources/*2.2 版本升级路径规划由于大版本跨度较大必须分阶段升级第一阶段1.3.4 → 2.0.5需要先升级到2.0.5这个过渡版本此版本开始支持自动数据库迁移第二阶段2.0.5 → 3.1.2需要处理微服务化带来的配置变更注意API服务的拆分api-server和master-server分离3. 第一阶段1.3.4到2.0.5升级实操3.1 数据库迁移问题处理执行升级脚本时遇到的典型错误ERROR 1071 (42000): Specified key was too long; max key length is 767 bytes这是因为MySQL的innodb_large_prefix设置问题解决方案-- 临时修改配置 SET GLOBAL innodb_file_formatBarracuda; SET GLOBAL innodb_file_per_tableON; SET GLOBAL innodb_large_prefixON; -- 对已有表重建 ALTER TABLE t_ds_process_instance ROW_FORMATDYNAMIC;3.2 配置文件合并技巧新旧版本配置项差异较大建议采用以下合并策略保留旧版conf/config/install_config.conf中的worker分组信息从新版安装包中获取conf/application.yaml的基础配置特别注意以下关键参数迁移1.3.4配置项2.0.5对应位置注意事项server.portserver.port (application.yaml)需要改为api.server.portspring.datasource.urlspring.datasource.dynamic.datasource.master.url改为多数据源配置dolphin.scheduler.zk.quorumspring.zk.quorumZK地址配置位置变化4. 第二阶段2.0.5到3.1.2升级挑战4.1 微服务拆分带来的问题3.x版本将单体应用拆分为多个微服务需要特别注意服务发现配置# conf/registry.properties registry.plugin.namezookeeper registry.servers127.0.0.1:2181API网关调整旧版直接访问api-server新版需要通过gateway-server访问默认端口123454.2 数据库迁移的坑执行upgrade-schema.sh脚本时常见问题表字段缺失错误Caused by: java.sql.SQLException: Column task_definition_version not found解决方法手动执行遗漏的DDL语句ALTER TABLE t_ds_task_definition ADD COLUMN task_definition_version int DEFAULT 1;数据兼容性问题 对于复杂的工作流定义建议先在测试环境导出2.0.5的工作流JSON在3.1.2环境重新导入5. 升级后验证与调优5.1 基础功能验证清单服务健康检查curl http://localhost:12345/dolphinscheduler/actuator/health工作流测试创建包含Shell、SQL、HTTP等任务类型的测试工作流验证上下游依赖关系是否正常告警通知测试测试邮件、Webhook等告警方式特别注意告警插件SPI接口变更5.2 性能调优建议针对3.1.2版本的优化参数# conf/master.properties master.exec.threads100 master.exec.task.num20 master.dispatch.task.num30 # conf/worker.properties worker.exec.threads50 worker.heartbeat.interval106. 回滚方案设计6.1 数据库回滚步骤停止所有3.1.2服务恢复2.0.5版本的数据库mysql -uroot -p dolphinscheduler ds_backup_2.0.5.sql启动2.0.5服务6.2 配置回滚注意事项恢复旧版install_config.conf时要注意Worker分组的机器IP可能已经变化租户配置需要重新关联资源文件回滚rm -rf /opt/dolphinscheduler/resources/* tar -xzvf ds_resources_2.0.5.tar.gz -C /opt/dolphinscheduler/7. 特别注意事项自定义插件处理1.x版本的告警插件需要重写实现新的AlertPluginSPI接口重新打包放到libs/plugin/alert目录跨版本API适配 如果业务系统调用了DS的API需要替换API客户端为3.x版本SDK修改接口路径如/v1/projects替代/projects小文件存储问题 3.x版本默认使用HDFS存储小文件如果沿用本地存储# conf/common.properties resource.storage.typeHDFS resource.storage.upload.base.path/tmp/dolphinscheduler升级过程中如果遇到ProcessDefinition json deserialize failed等序列化问题建议使用新版UI重新创建工作流定义而不是直接迁移旧版JSON。