Apache DolphinScheduler 升级兼容性指南：3.0.0 至 3.5.0 破坏性变更全解析-迪斯科星球

Apache DolphinScheduler 升级兼容性指南：3.0.0 至 3.5.0 破坏性变更全解析

【免费下载链接】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 官方升级文档中记录的 3.0.0 至 3.5.0 全部破坏性变更（Incompatible Changes），涵盖配置项重命名与移除、API 返回值瘦身、任务插件下线、数据库表结构变更等，并结合当前仓库源码逐一解释变更动因与升级迁移方法。读者在升级到任一对应版本前，按本文清单逐项核对配置、接口与数据，可有效避免因破坏性变更导致的升级失败或运行异常。

升级前必读：为什么需要关注破坏性变更

DolphinScheduler 在每次大版本演进中都会对配置项、公开 API、任务插件与数据库结构做必要的"减法"。官方在 incompatible.md 中明确要求：升级到对应版本之前，必须先检查该文档。这些变更往往是破坏性的——即升级后旧配置不再生效、旧接口不再可用、旧数据需要迁移，如果不提前处理，轻则功能异常，重则服务无法启动。

本文按版本组织全部变更条目，并尽量给出源码层面的印证与迁移建议，方便你在升级窗口内一次性完成核对。

3.0.0：工作流复制与 SQL 分隔符的行为调整

3.0.0 是本文档覆盖的起始版本，包含两条行为层面的变更，它们不涉及配置项删除，但会直接影响用户操作结果：

工作流复制与导入不再附带 "copy" 后缀（#10607）：3.0.0 之前，复制或导入工作流时系统会自动在名称后追加 "copy" 字样；升级后该行为被移除。如果你或下游系统依赖名称中的 "copy" 后缀做识别（例如脚本按工作流名匹配），升级后需要改用工作流编码（code）作为唯一标识。
SQL 任务默认使用分号作为语句分隔符（#10869）：SQL 任务插件在解析多语句脚本时，默认分隔符由旧行为调整为分号;。如果你现有的 SQL 任务脚本中包含存储过程（通常以//、$$等自定义分隔符定义）或分号出现在字符串字面量中，升级后可能被错误切分，需要核对脚本写法或显式配置分隔符。

3.2.0：配置项重命名、驱动升级与 API 参数调整

3.2.0 是变更较为密集的一个版本，涉及配置文件、插件 API 与数据库驱动三个层面，建议逐条对照升级。

配置项：数据质量相关配置的语义变化

变更条目	影响范围	迁移动作
`data-quality.jar.name`重命名为`data-quality.jar.dir`（#15563）	`common.properties`	原配置表示文件名，新配置表示目录。需将原值改为数据质量 jar 包所在目录路径
移除`data-quality.jar.name`的默认值（#15551）	`common.properties`	升级后该键不再有内置默认值，必须显式配置，否则数据质量相关功能会因找不到 jar 包而失败

环境变量：PYTHON 与 DATAX 的启动器语义

PYTHON_HOME改为PYTHON_LAUNCHER、DATAX_HOME改为DATAX_LAUNCHER（#14523）。这一改动把"目录"语义改为"可执行程序路径"语义，使系统能更精确地定位 Python 解释器与 DataX 启动脚本。升级时需：

在环境配置（环境管理页面或 common.properties 对应环境变量）中将PYTHON_HOME=/path/to/python-dir改为PYTHON_LAUNCHER=/path/to/python；
将DATAX_HOME=/path/to/datax-dir改为DATAX_LAUNCHER=/path/to/datax/bin/datax.py一类完整启动路径。

任务插件行为：Shell 执行器与 Spark 版本参数

默认 Unix Shell 执行器由 sh 改为 bash（#12180）：Shell 类任务默认解释器从sh切换为bash，脚本中依赖 sh 特有行为的写法（如source、数组语法差异）需要回归测试。当前仓库的 common.properties 中shell.interceptor.type=bash与shell.env_source_list=即为该行为的现网默认体现。
移除 Spark 任务的 spark 版本参数（#11860）：Spark 任务不再暴露"spark 版本"选择项，相关提交参数改为按统一方式处理，旧工作流中的该参数在升级后会被忽略。
SQL 任务中 SQL 参数的正则匹配规则变更（#13378）：SQL 任务解析$变量参数时使用的正则表达式被调整，参数命名中含特殊字符的脚本需验证解析结果。

数据源与资源中心 API 调整

MySQL 驱动从 8.0.16 升级到 8.0.33（#14684）：伴随连接串、时区参数等行为差异，建议升级前在测试环境用 8.0.33 驱动验证既有数据源连接。
/datasources/tables与/datasources/tableColumns接口新增必填字段database（#14406）：调用这两个接口查询表/表字段时，请求中必须携带数据库名，否则请求失败。
新资源中心的公开接口移除description参数（#14394）：调用新资源中心公开接口时不再接受description入参，基于旧接口封装的调用方需要同步改造。

StorageOperate 接口签名变更

StorageOperate的download()方法移除了deleteSource参数（#14084）。该接口位于存储插件 SPI 层，自定义存储插件（如自研的 HDFS/S3 扩展）若实现了download(boolean deleteSource)签名，需同步去掉该参数并重新编译插件。

3.3.0：模块精简与配置体系重构

3.3.0 是架构层面"做减法"的版本：多个模块被移除、配置项被合并，并统一了核心概念命名。

移除的模块与插件

资源中心移除udf-manage（UDF 管理）功能（#16209）：资源中心不再提供 UDF 管理入口，UDF 相关能力需要迁移到新的实现方式。
移除Pigeon任务插件（#16218）：任务类型列表中不再有 Pigeon。
移除Data Quality模块（#16794）：数据质量（Data Quality）整体下线，与之配套的data-quality.jar.dir等配置即使保留也不再生效。
移除Dynamic任务插件（#16482）：动态任务类型被移除。

配置项移除与合并（重点）

3.3.0 对 Worker 与 Master 的线程池配置做了统一重构：

Worker 移除exec-threads，改用physical-task-config（#16790 中physical-task-config.task-executor-thread-size: 100即新配置的真实形态。
Master 移除master-async-task-executor-thread-pool-size，改用logic-task-config：逻辑任务执行线程数改为通过master.logic-task-config.task-executor-thread-count配置（当前仓库 master 端 application.yaml 中以注释形式给出示例默认值）。

升级时若旧配置残留，Spring Boot 不会报错，但新行为不会生效，必须完成键名迁移。

其他变更

代码中统一将process命名为workflow（#16515）：这是面向开发者的命名统一，涉及大量类名、方法名与 API 路径（如ProcessDefinition→WorkflowDefinition），对使用公开 REST API 或 SDK 的调用方有影响，需按新命名更新引用。
弃用 1.x 与 2.x 的升级代码（#16543）：从 1.x/2.x 直接升级到 3.3.0 及以后的路径不再受支持，官方建议先升级到中间版本再继续升级。
移除registry-disconnect-strategy配置（#16821）：注册中心断连策略配置项被移除，相关行为由框架内置逻辑接管。
删除t_ds_worker_group表中无用的other_params_json列（#16860）：升级脚本会处理该列，自定义 SQL 中若引用了该列需要同步清理。

3.4.0 与 3.4.1：参数改名、任务插件下线与导出功能移除

3.4.0 聚焦数据源参数语义修正与任务插件清理，3.4.1 则移除了工作流导入导出。

数据源 SSH 参数改名：publicKey → privateKey

SSH 数据源连接参数中的publicKey字段被改名为privateKey（#17666）。这是一个命名纠错——该字段实际承载的是私钥内容。已经保存的 SSH 数据源在升级后需要重新录入该字段，调用数据源相关 API 时也要使用新字段名。

新增 t_ds_serial_command 表

新增t_ds_serial_command表（#17531），用于串行/依赖场景的命令存储。升级脚本会自动建表，但如果你的环境对数据库账号做了最小权限控制（如禁止 DDL），需提前为升级账号授予建表权限。

安全默认值：python-gateway.auth-token 不再有默认值

api-server/application.yaml中python-gateway.auth-token的默认值被移除（#17801）。升级后若未显式配置该 token，Python Gateway 将拒绝连接。升级时必须先在配置中显式设置强随机 token，再重启 api-server。

ShellCommandExecutor 重构与 Pytorch 插件下线

使用 ShellCommandExecutor 的任务插件被重构（#17790）：Shell 类任务插件的执行器实现被重构，插件内部实现有调整，使用官方发行包的用户无需额外操作，但自定义基于该执行器扩展的插件需要同步适配。
移除 Pytorch 任务插件（#17808）：任务类型列表中不再有 Pytorch。官方特别提示：如果你仍在使用该任务类型，升级前必须手动删除t_ds_task_definition与t_ds_task_definition_log表中task_type = 'PYTORCH'的数据，否则可能导致升级脚本或运行时报错。

3.4.1：移除工作流定义的导入与导出

工作流定义（workflow definition）的导入、导出功能被移除（#17940）。此前通过导入/导出做跨环境迁移的用户，需要改用数据库层迁移或手工重建工作流的方式，并在升级前导出备份所有需要保留的工作流定义。

3.5.0：调度补跑策略列新增与实例列表 API 瘦身

3.5.0 是本仓库当前版本，包含一项数据库结构变更和一组 API 返回体精简，升级影响面最广的是 API 调用方。

新增 missed_fire_policy 列：调度漏触发补跑策略

t_ds_schedules表新增missed_fire_policy列（#18464），用于定义调度错过后如何补跑。已有调度记录默认值为FIRE_ALL_MISSED，用于保留旧 QuartzIgnoreMisfires行为——即升级后默认补跑所有漏掉的触发。

三种策略取值可在源码枚举 ScheduleMissedFirePolicy.java 中确认：

枚举值	代码值	含义
`SKIP_MISSED`	0	跳过错过的触发，不补跑
`FIRE_ONCE_NOW`	1	只补跑最近一次错过的触发
`FIRE_ALL_MISSED`	2	补跑所有错过的触发（升级默认值）

对应的建表/升级 DDL 位于 3.5.0 升级脚本，实体字段missedFirePolicy定义于 Schedule.java。如果你不希望升级后自动补跑历史漏触发，需要在升级后把存量调度记录改为0（跳过）或1（只补一次）。

移除过时 API

移除过时的 Dynamic Task 查询 API（#18556）。
移除过时的任务带上游更新 API：PUT /projects/{projectCode}/task-definition/{code}/with-upstream（#18568）。调用方需改用任务定义的普通更新接口并自行管理上游依赖关系。

工作流实例列表 API 返回体瘦身

三个工作流实例列表类接口不再返回一批"重型"字段（#18444）：

GET /projects/{projectCode}/workflow-instances GET /projects/{projectCode}/workflow-instances/top-n GET /projects/{projectCode}/workflow-instances/trigger

移除的字段按性质分为三类：

重型字段（Heavy fields）：commandParam、globalParams、historyCmd、varPool、stateHistory
瞬时字段（Transient fields）：stateDescList、workflowDefinition、dagData、queue、locations、dependenceScheduleTimes
派生属性（Derived properties）：cmdTypeIfComplement、complementData（这两个字段与补数执行相关）

迁移方案：需要上述任一字段时，改为调用详情接口GET /projects/{projectCode}/workflow-instances/{id}，该接口继续返回完整的WorkflowInstance对象。若你的系统在列表页依赖workflowDefinition/dagData渲染 DAG 或依赖varPool展示变量，升级后需改为"先取列表、再按需取详情"的两段式请求，并做好列表接口响应体的容错处理。

升级核对清单（Checklist）

将上述变更整理为可逐项勾选的核对表，建议按版本顺序执行：

3.0.0：核对工作流复制/导入后命名；核对 SQL 任务脚本中分号与自定义分隔符用法。
3.2.0：data-quality.jar.name→data-quality.jar.dir并显式配置；PYTHON_HOME→PYTHON_LAUNCHER、DATAX_HOME→DATAX_LAUNCHER；Shell 默认解释器验证；MySQL 驱动 8.0.33 验证；/datasources/tables、/datasources/tableColumns补充database必填参数；资源中心公开接口去掉description；自定义存储插件适配download()新签名。
3.3.0：确认未依赖已移除的 UDF 管理、Pigeon/Dynamic/Data Quality 模块；Workerexec-threads→physical-task-config.task-executor-thread-size；Mastermaster-async-task-executor-thread-pool-size→logic-task-config.task-executor-thread-count；删除registry-disconnect-strategy；清理对t_ds_worker_group.other_params_json的引用；检查 API/SDK 中process相关命名。
3.4.0：SSH 数据源字段publicKey→privateKey重新录入；为建t_ds_serial_command表准备 DDL 权限；显式配置python-gateway.auth-token；升级前删除task_type = 'PYTORCH'的任务定义数据。
3.4.1：升级前导出/备份工作流定义，迁移方式改为数据库层或手工重建。
3.5.0：确认missed_fire_policy默认补跑策略是否符合预期；移除对 Dynamic 查询 API、with-upstream更新 API 的调用；列表类接口调用方改为"列表 + 详情"两段式获取字段。

以上所有变更条目均可在 incompatible.md 中找到原始记录，升级前请以该文档与当前版本的升级指南为准，并在测试环境完成完整升级演练后再操作生产集群。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析