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 后缀#106073.0.0 之前复制或导入工作流时系统会自动在名称后追加 copy 字样升级后该行为被移除。如果你或下游系统依赖名称中的 copy 后缀做识别例如脚本按工作流名匹配升级后需要改用工作流编码code作为唯一标识。SQL 任务默认使用分号作为语句分隔符#10869SQL 任务插件在解析多语句脚本时默认分隔符由旧行为调整为分号;。如果你现有的 SQL 任务脚本中包含存储过程通常以//、$$等自定义分隔符定义或分号出现在字符串字面量中升级后可能被错误切分需要核对脚本写法或显式配置分隔符。3.2.0配置项重命名、驱动升级与 API 参数调整3.2.0 是变更较为密集的一个版本涉及配置文件、插件 API 与数据库驱动三个层面建议逐条对照升级。配置项数据质量相关配置的语义变化变更条目影响范围迁移动作data-quality.jar.name重命名为data-quality.jar.dir#15563common.properties原配置表示文件名新配置表示目录。需将原值改为数据质量 jar 包所在目录路径移除data-quality.jar.name的默认值#15551common.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#12180Shell 类任务默认解释器从sh切换为bash脚本中依赖 sh 特有行为的写法如source、数组语法差异需要回归测试。当前仓库的 common.properties 中shell.interceptor.typebash与shell.env_source_list即为该行为的现网默认体现。移除 Spark 任务的 spark 版本参数#11860Spark 任务不再暴露spark 版本选择项相关提交参数改为按统一方式处理旧工作流中的该参数在升级后会被忽略。SQL 任务中 SQL 参数的正则匹配规则变更#13378SQL 任务解析$变量参数时使用的正则表达式被调整参数命名中含特殊字符的脚本需验证解析结果。数据源与资源中心 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-manageUDF 管理功能#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 → privateKeySSH 数据源连接参数中的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。升级后若未显式配置该 tokenPython Gateway 将拒绝连接。升级时必须先在配置中显式设置强随机 token再重启 api-server。ShellCommandExecutor 重构与 Pytorch 插件下线使用 ShellCommandExecutor 的任务插件被重构#17790Shell 类任务插件的执行器实现被重构插件内部实现有调整使用官方发行包的用户无需额外操作但自定义基于该执行器扩展的插件需要同步适配。移除 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_MISSED0跳过错过的触发不补跑FIRE_ONCE_NOW1只补跑最近一次错过的触发FIRE_ALL_MISSED2补跑所有错过的触发升级默认值对应的建表/升级 DDL 位于 3.5.0 升级脚本实体字段missedFirePolicy定义于 Schedule.java。如果你不希望升级后自动补跑历史漏触发需要在升级后把存量调度记录改为0跳过或1只补一次。移除过时 API移除过时的 Dynamic Task 查询 API#18556。移除过时的任务带上游更新 APIPUT /projects/{projectCode}/task-definition/{code}/with-upstream#18568。调用方需改用任务定义的普通更新接口并自行管理上游依赖关系。工作流实例列表 API 返回体瘦身三个工作流实例列表类接口不再返回一批重型字段#18444GET /projects/{projectCode}/workflow-instances GET /projects/{projectCode}/workflow-instances/top-n GET /projects/{projectCode}/workflow-instances/trigger移除的字段按性质分为三类重型字段Heavy fieldscommandParam、globalParams、historyCmd、varPool、stateHistory瞬时字段Transient fieldsstateDescList、workflowDefinition、dagData、queue、locations、dependenceScheduleTimes派生属性Derived propertiescmdTypeIfComplement、complementData这两个字段与补数执行相关迁移方案需要上述任一字段时改为调用详情接口GET /projects/{projectCode}/workflow-instances/{id}该接口继续返回完整的WorkflowInstance对象。若你的系统在列表页依赖workflowDefinition/dagData渲染 DAG 或依赖varPool展示变量升级后需改为先取列表、再按需取详情的两段式请求并做好列表接口响应体的容错处理。升级核对清单Checklist将上述变更整理为可逐项勾选的核对表建议按版本顺序执行3.0.0核对工作流复制/导入后命名核对 SQL 任务脚本中分号与自定义分隔符用法。3.2.0data-quality.jar.name→data-quality.jar.dir并显式配置PYTHON_HOME→PYTHON_LAUNCHER、DATAX_HOME→DATAX_LAUNCHERShell 默认解释器验证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-sizeMastermaster-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.0SSH 数据源字段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 中找到原始记录升级前请以该文档与当前版本的 升级指南 为准并在测试环境完成完整升级演练后再操作生产集群。【免费下载链接】dolphinschedulerApache DolphinScheduler is the modern data orchestration platform. Agile to create high performance workflow with low-code项目地址: https://gitcode.com/GitHub_Trending/dol/dolphinscheduler创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考