最近团队在升级调度平台的时候遇到了一个挺折腾的问题在 DolphinScheduler以下简称 DS的工作流定义里新建一个 ChunJun 数据同步节点配置好 JSON 任务后点击保存结果直接弹出“保存失败”。这个报错既不说是参数问题也不给堆栈细节就干巴巴一句话排查起来相当难受。折腾了两天最后从日志到源码把链路整个捋了一遍总算定位到根因并修复了。趁热打铁把这次排查的完整思路、常见原因和修复方案整理出来给正在用 DS 编排 ChunJun 任务的朋友们做个参考。这个问题的覆盖面其实不小。DS 本身是国内使用率很高的开源工作流调度平台ChunJun原 FlinkX又是常见的离线数据同步引擎两者结合几乎是很多数仓项目的标准配置。但只要 DS 和 ChunJun 的版本、插件包、JSON 配置任何一个环节对不上工作流里保存 ChunJun 任务时就可能翻车。这篇文章会从“保存失败”这个动作出发拆解 DS 后端处理 ChunJun 任务节点的完整逻辑讲清楚根因定位的方法再给出一套可以直接抄作业的修复步骤最后附上我整理的常见问题速查表。1. 问题现象与排查环境1.1 保存失败的现场还原先说当时的具体表现。我在 DS 的“项目管理 - 工作流定义”里创建一个新工作流拖入一个 ChunJun 节点节点类型选择“CHUNJUN”然后在“自定义模板”里填写 ChunJun 的 JSON 配置。点保存时前端提示“保存失败请稍后重试”。这个提示非常笼统前端控制台只有一个非 200 的响应响应体里是统一的错误包装真正的异常被后端吞掉了只有去翻 API 服务日志才能看到细节。我当时第一反应是 JSON 格式写错了但仔细检查了好几遍job 内容里的 reader、writer 配置都是完整的content 数组也符合 ChunJun 的标准结构。然后在“任务实例”里手动运行这个任务任务又是能正常跑通的说明 ChunJun 本身没问题问题出在 DS 的保存动作上。后来我把排查重点转向 DS 服务端保存 ChunJun 任务时后端到底做了什么校验为什么同样的配置手动执行可以保存到工作流里就不行顺着这个问题我逐步梳理了 DS 对 ChunJun 任务节点的处理逻辑。1.2 环境版本与部署方式说明我的环境信息如下后续的排查思路和修复方案都是基于这套环境DolphinScheduler 版本3.1.9ChunJun 版本1.1.0依赖 Flink 1.13数据库MySQL 8.0DS 元数据库部署方式二进制包部署API-Server 和 Worker 分开部署ChunJun 安装路径/opt/chunJun/chunjun-dist这个版本组合其实很关键。DS 3.1.x 开始把 ChunJun 节点作为内置任务插件但不同小版本对 ChunJun 的任务参数结构、类加载机制都有差异。如果你的版本和我不同现象可能类似但根因侧重点会有区别后面我会单独说明。2. 保存失败的根因定位思路2.1 先理清 DS 保存任务节点的完整链路在动手翻代码之前我先理了一下 DS 保存工作流节点的调用链。DS 的前端把整个工作流 DAG 的定义提交给 API-ServerAPI-Server 收到请求后会执行一批操作保存工作流基本信息、批量保存任务定义、保存任务间的关系等。对于每个任务的保存核心入口是 TaskDefinitionServiceImpl。它会根据任务的“任务类型”字段去定位对应的 TaskChannel再通过 TaskChannelFactory 创建具体的任务通道。在创建通道的过程中会触发任务参数从字符串到具体对象的转换这个转换过程就会校验参数格式。ChunJun 任务节点的参数是一个 JSON 字符串DS 后端会把它解析成 ChunJunParameters 对象。这一步如果解析失败或者解析出来的对象缺少必填字段保存动作就会直接抛异常。而这个异常被上层事务回滚后前端只能收到一个笼统的失败提示。说白了保存失败 任务参数无法被 DS 正确识别或持久化。要定位根因就得从参数解析和持久化两个方向去查。2.2 日志是定位问题的第一现场当时我在 API-Server 的 logs 目录下翻到了真正的异常栈关键片段如下ERROR [TaskDefinitionServiceImpl] - Save task definition error. java.lang.NullPointerException: null at org.apache.dolphinscheduler.plugin.task.chunjun.ChunJunParameters.checkParameters(ChunJunParameters.java:94) at org.apache.dolphinscheduler.plugin.task.api.AbstractParameters.getCheckedParameters(AbstractParameters.java:57) at org.apache.dolphinscheduler.service.task.TaskPluginManager.checkTaskParameters(TaskPluginManager.java:145) at org.apache.dolphinscheduler.service.process.ProcessServiceImpl.createTaskDefinition(ProcessServiceImpl.java:1245)看到ChunJunParameters.checkParameters里抛了 NPE问题就聚焦了不是数据库的问题不是工作流 DAG 的问题而是 ChunJun 任务参数对象在“自我校验”阶段没通过。也就是说我填的 JSON 虽然能运行但 DS 解析后某个字段是空的触发了空指针。2.3 源码定位ChunJunParameters 的校验逻辑既然报错指向 ChunJunParameters 的第 94 行我直接打开了 DS 源码里这个类看看它到底校验了什么。ChunJunParameters 核心代码如下关键部分做了精简public class ChunJunParameters extends AbstractParameters { private String jobContent; private String deployMode; private String others; private String flinkParallelism; private String queueName; private String mainJar; private String mainArgs; Override public boolean checkParameters() { if (StringUtils.isEmpty(deployMode)) { throw new IllegalArgumentException(deployMode must not be empty); } if (StringUtils.isEmpty(jobContent)) { throw new IllegalArgumentException(jobContent must not be empty); } // 第94行附近 JSONObject jsonObject JSONObject.parseObject(jobContent); JSONArray contentArray jsonObject.getJSONArray(content); if (contentArray null || contentArray.size() 0) { throw new IllegalArgumentException(content can not be empty); } return true; } }原来DS 的 ChunJun 任务节点要求 jobContent 必须是一个合法的 JSON 对象里面必须包含content数组。这个校验本身很合理因为 ChunJun 的同步任务必须有 reader 和 writer。但问题在于JSONObject.parseObject(jobContent)这一步如果得到的 JSONObject 里没有content字段返回的contentArray就是 null再调用contentArray.size()空指针就出来了。我在“自定义模板”里写的 JSON 结构是{ job: { content: [ { reader: {}, writer: {} } ], setting: {} } }在 ChunJun 原生执行器里job.content是合法结构。但 DS 解析时直接取的是根路径下的content而不是job.content。所以不管我 job 内容填得再对DS 拿到的 content 数组始终是空的保存当然失败。2.4 版本兼容差异带来的衍生坑顺着这个思路我又去翻了一下不同版本 DS 的实现。在 DS 3.0.x 早期版本中ChunJunParameters 的校验逻辑其实比 3.1.9 宽松一些不会强制取根路径的 content 字段。3.1.x 加强了参数校验后对 JSON 结构的要求变了但前端页面的“自定义模板”提示文案和示例却没同步更新导致老用户沿用旧的 ChunJun 配置格式时直接翻车。这种情况在开源软件的迭代中很常见执行引擎和调度框架对同一个 JSON 的解析层级要求不完全一致调度框架做了更严格的校验但用户侧拿到的还是执行引擎的配置习惯。所以排查这类保存失败问题时不能只看执行器支不支持一定要确认调度框架的解析规则。3. 实战修复过程全记录3.1 修复思路让 JSON 结构同时兼容 DS 与 ChunJun明确了根因修复方案就简单了把工作流里 ChunJun 节点的 JSON 配置结构改成 DS 要求的格式。DS 的 ChunJunParameters 期望的 jobContent 结构是{ content: [ { reader: { name: mysqlreader, parameter: {} }, writer: { name: mysqlwriter, parameter: {} } } ], setting: { speed: { bytes: 0, channel: 1 } } }注意这里的content数组直接位于 JSON 根路径而不是嵌套在job下面。这也是 DS 内部用了自己的一套参数解析并不是直接透传给 ChunJun。不过为了让这份配置在 ChunJun 原生执行时也能正常使用我做了兼容处理DS 节点里填写 DS 要求的结构在真正下发到 ChunJun 引擎时由 DS 的 ChunJunTaskChannel 做格式转换。DS 的这个转换逻辑在ChunJunTask.java里它会读取 parameters 里的 deployMode、mainJar、others 等字段拼装 ChunJun 的启动参数同时把 jobContent 原样写入临时 JSON 文件。也就是说DS 要的 jobContent 是它内部解析用的格式而 ChunJun 运行时需要的仍然是完整 job 结构。经过实测DS 3.1.9 中只要 jobContent 满足“根路径包含 content 数组”这个条件DS 就能把 content 内容转换成 ChunJun 的 JobGraph 并下发执行。我的最终配置改为{ content: [ { reader: { name: mysqlreader, parameter: { username: root, password: 123456, column: [*], connection: [{ jdbcUrl: [jdbc:mysql://localhost:3306/test], table: [source_table] }] } }, writer: { name: mysqlwriter, parameter: { username: root, password: 123456, writeMode: insert, column: [*], connection: [{ jdbcUrl: jdbc:mysql://localhost:3306/test, table: [target_table] }] } } } ], setting: { speed: { channel: 1, bytes: 0 } } }修改配置后保存 ChunJun 任务成功不再报空指针。随后我触发了一次工作流运行任务也能正常跑通问题初步解决。3.2 root 原因延伸插件依赖包缺失导致的保存失败JSON 结构问题修复后我顺手也复盘了一下团队的另一个环境因为那个环境的 DS 里ChunJun 任务的保存失败表现完全不同——不是空指针而是ClassNotFoundException报错指向com.dtstack.chunjun.Main。这个环境是最近通过 Docker 方式部署的 DS没有手动往 worker 节点的 lib 目录放 ChunJun 相关依赖。这个问题其实也非常典型。DS 的 ChunJun 任务节点在任务真正提交执行时Worker 上必须有 ChunJun 的执行入口类和相关依赖。如果在 DS 的安装目录里没有配置 chunjun 插件依赖包任务保存时虽然不会失败但任务运行时一定会失败而如果你的 Worker 节点和 API-Server 混布且某些扩展包的缺失会影响 API-Server 的类加载那就可能在保存阶段就暴露问题。解决方案是在 DS 的安装目录下找到libs或plugins目录把 ChunJun 发行包里的chunjun-core.jar、chunjun-mysql.jar等依赖放进去。比较稳妥的做法是在每台 Worker 节点上部署 ChunJun 发行包比如 /opt/chunjun 目录在 DS 的 worker 配置里把 ChunJun 需要的依赖 jar 放到dolphinscheduler-worker的 lib 目录下或者在任务节点的“其他参数”中指定-Dchunjun.libjars路径让 Worker 动态加载。这里可以关联到很多团队用 Dockerfile 封装 DS 镜像时的一个共同痛点只把 DS 本体打进镜像ChunJun 依赖忘加或者加错路径结果换一台机器部署就炸。建议在做镜像时直接把 ChunJun 依赖打进同一个镜像或者在启动脚本里固定CHUNJUN_HOME环境变量。3.3 数据库字段长度与字符集问题还有一次比较隐蔽的保存失败发生在 MySQL 元数据库里。DS 的任务定义表命名是t_ds_task_definition其中有一个字段task_params用于存储任务参数类型是text但有些用户的场景里 ChunJun 的配置特别长尤其是包含大量字段映射的同步任务JSON 文本超过 64KB 时text 字段就存不下了保存时直接报数据库异常。这种问题的典型报错是Data truncation: Data too long for column task_params at row 1解决办法有两种调大字段类型把task_params从text改成longtext执行ALTER TABLE t_ds_task_definition MODIFY COLUMN task_params LONGTEXT;注意备份和停机窗口在程序层面控制 ChunJun 任务 JSON 的长度拆分任务避免一个任务节点里塞下所有逻辑。在我的经验里第二种方式更推荐。因为一个 ChunJun 任务节点动辄几百行的 JSON本身可读性就很差出了问题也不好排查。把它拆成多个子任务配合 DS 的依赖关系编排反而更清晰稳定。3.4 排查保存失败时常用的几个命令套路排查过程中除了看日志我还习惯了用几条命令快速缩小范围。如果你的问题不是 JSON 结构而是异常信息不明确可以这样操作首先找到 API-Server 日志tail -f /opt/dolphinscheduler/logs/dolphinscheduler-api.log | grep -i error其次定位到具體任务 ID 去查详细日志。DS 的 API-Server 日志一般会打印任务定义 ID拿到这个 ID 后再到t_ds_task_definition表里查看 task_params 字段的实际情况。SELECT id, name, task_type, task_params FROM t_ds_task_definition WHERE id 12345;然后再确认工作流定义 ID 对应的 DAG 结构是否完整SELECT * FROM t_ds_process_task_relation WHERE process_definition_code xxx;这套组合拳打下来基本能把“前端报保存失败”这个大问题拆解成“参数校验失败”“数据库写入失败”“依赖缺失失败”三个小方向再逐个击破。4. 常见问题诊断速查表与避坑经验4.1 诊断速查表我把这次排查和之前遇到过的同类问题整理成了一张速查表遇到保存失败可以直接对着排查异常特征可能原因处理方式NullPointerExceptionat ChunJunParametersjobContent JSON 根路径缺少 content 数组调整 JSON 结构把 content 提到根路径ClassNotFoundException: com.dtstack.chunjun.MainWorker 缺少 ChunJun 依赖包把 ChunJun 发行包 jar 放到 worker lib 目录或配置依赖路径Data too long for column task_params任务参数超过 text 字段长度上限修改字段为 longtext或拆分任务节点IllegalArgumentException: deployMode must not be emptyChunJun 节点未选择部署模式检查节点的“部署模式”参数必须选择 local/yarn/per-job 等JSON parse error任务参数中有多余逗号或非法字符用在线 JSON 校验工具先过一遍格式NoSuchMethodErrorDS 与 ChunJun 版本不匹配统一 DS 和 ChunJun 版本或更换兼容版本组合前端提示保存失败但日志无异常浏览器缓存或前端组件版本与后端不一致清理浏览器缓存强制刷新页面确认前后端版本一致这张表只是起点实际项目里肯定还有其他更个性化的场景但排查思路是通用的先日志定位异常类型再确认是哪一层抛出来的最后再针对性地处理。4.2 一个容易忽视的细节任务节点名称与标识还有一个细节也值得单独拿出来说DS 里保存 ChunJun 任务时任务节点的 name 字段如果包含特殊字符比如中文括号、百分号或者超出 255 个字符也会在保存阶段失败。这个问题的报错往往不太明确前端可能看到的是“保存失败”后端日志则是Data truncation或SQLException。我遇到过最离奇的一次是任务名称里有一个全角的空格看起来和普通空格一模一样但数据库写入时触发了字符集校验导致保存失败。排查了很久最后把任务名称复制出来逐个字符比对才发现。所以如果你的 ChunJun 任务一直保存失败且日志里没有明显的 Java 异常可以顺手检查一下任务名称和项目名称里有没有特殊字符尽量不要用 emoji、全角符号、超长字符。4.3 资源中心引用路径不存在也会导致保存失败还有一种情况是ChunJun 任务节点里引用了资源中心的 jar 包或文件比如你用资源中心管理了 ChunJun 的驱动包然后在节点的“自定义模板”里写了${resourceName}这样的占位符。如果你在资源中心里删除了这个文件或者路径写错了保存时 DS 也会做一次资源校验校验不通过直接报失败。这种情况下的日志通常会出现resource does not exist或类似的提示。处理方式很简单去“资源中心”确认文件是否存在然后检查任务节点里的资源引用路径是否与资源中心里的路径完全一致注意大小写。DS 的资源引用是区分大小写的这一点经常被忽略。4.4 复制粘贴 JSON 时出现的隐藏字符坑我最后再补一个实战中特别容易踩的坑从微信、飞书或在线文档里复制 ChunJun 的 JSON 配置时粘贴到 DS 的任务参数里经常会带入零宽空格或不可见字符。这些字符在 JSON 解析时会导致IllegalStateException或MalformedJsonException报错内容会指向某个奇怪的字符位置。遇到这种情况不要直接盯着 JSON 看先用十六进制模式查看粘贴内容或者把内容粘贴到一个纯文本编辑器里把不可见字符显示出来再手动清理一遍。还有一个更快的办法用 Python 一键清洗比如sed s/\xe2\x80\x8b//g chunjun.json chunjun-clean.json或者用 Pythonwith open(chunjun.json, r, encodingutf-8) as f: content f.read() content content.replace(\u200b, ).replace(\u200c, ).replace(\u200d, ) with open(chunjun-clean.json, w, encodingutf-8) as f: f.write(content)我个人的习惯是凡是准备贴到 DS 里的 JSON都先经过一步清洗再提交省得时不时被这种隐形字符坑一下。5. 延伸思考从“保存成功”到“稳定运行”的几条建议5.1 验证保存成功只是第一步推荐加一个“试运行”检查ChunJun 任务保存成功并不代表任务运行不会出问题。DS 在保存任务时只做了参数合法性的初步校验真正的运行期校验比如目标表是否存在、连接 MongoDB 的认证方式是否正确、Flink 集群是否有资源都会在运行阶段才暴露。所以我的建议是每新建一个 ChunJun 任务节点保存通过后最好先单独触发一次任务运行确认数据同步链路跑通再把工作流整体的调度打开。不要一步到位直接上线尤其是改动了 reader 或 writer 的字段映射时最好先在测试环境做全量验证。即使是线上环境也要预留出试运行的时间窗口避免因为一次保存成功就掉以轻心。5.2 注意 DS 与 ChunJun 的版本兼容矩阵我这次踩的 JSON 校验问题本质上就是 DS 3.1.9 和 ChunJun 新版本搭配时的兼容性问题。实际上DS 官方文档里对 ChunJun 的版本支持是有说明的不同 DS 版本对 ChunJun 的嵌入方式和参数要求不同。我整理了一下当前主流组合的参考建议DolphinScheduler 版本ChunJun 版本兼容性说明3.0.x1.1.0较稳定JSON 校验较宽松3.1.0 - 3.1.41.1.0功能变化不大可正常使用3.1.5 - 3.1.91.1.0校验加强content 必须位于根路径3.2.x1.1.1注意新版本类名变化建议先验证当然这个表格只能作为参考真正落地的版本组合一定要以你自己的测试结果为准。升级 DS 或 ChunJun 时我会先在一台测试机器上完整跑一遍“创建任务 - 保存 - 运行 - 数据校验”的流程再决定是否全量升级。5.3 善用 DS 的任务插件机制必要时可二次开发如果你的团队对 ChunJun 任务的依赖特别深而且受够了 DS 内置的 JSON 校验规则其实还有一个更治本的方案基于 DS 的 SPI 机制自己实现一个自定义任务插件直接使用你期望的 JSON 解析方式和参数结构。DS 的任务插件机制并不复杂核心就是继承AbstractTask然后实现TaskChannelFactory再通过 SPI 的方式注册到 DS 里。这样你可以在自己的插件里做完整的 JSON 解析和校验甚至把 ChunJun 的参数组装逻辑都包进去完全摆脱内置插件的限制。不过这个方案对开发和维护成本有一定要求适合团队里有专门的大数据平台开发人员的情况。如果只是偶尔用一下 ChunJun内置插件加一个“JSON 结构修正”的操作完全够用了。最后的实操体会这次定位和修复 ChunJun 任务保存失败我最大的感受是在开源调度系统里文档提示和代码实现往往存在滞后遇到问题不能只靠猜一定要顺着日志往源码里挖。DS 的源码结构还算清晰ds-rpc、ds-service、ds-task-plugin都能快速定位到问题类。只要你愿意花时间看那一两段报错对应的代码排查效率会高很多。另外关于 ChunJun 任务 JSON 的格式问题我现在养成了一个习惯在本地定义一个标准的 JSON 模板每次新建任务节点时直接复制模板再改字段而不是手写。这样可以极大降低因为少了一个字段或者嵌套层级不对导致的保存失败概率。说白了折腾过一次够了能靠工具和模板规避的坑就不要靠记忆硬扛。希望这篇文章能把你在 DolphinScheduler 工作流里配置 ChunJun 任务时可能遇到的保存失败问题从“玄学报错”变成“有据可查的系统问题”。如果你在实际排查中还有不一样的报错信息欢迎带着日志数据再来交流说不定你的场景又能补全一张排查记录。
DolphinScheduler中ChunJun任务保存失败？从空指针到JSON结构兼容的排查实战
最近团队在升级调度平台的时候遇到了一个挺折腾的问题在 DolphinScheduler以下简称 DS的工作流定义里新建一个 ChunJun 数据同步节点配置好 JSON 任务后点击保存结果直接弹出“保存失败”。这个报错既不说是参数问题也不给堆栈细节就干巴巴一句话排查起来相当难受。折腾了两天最后从日志到源码把链路整个捋了一遍总算定位到根因并修复了。趁热打铁把这次排查的完整思路、常见原因和修复方案整理出来给正在用 DS 编排 ChunJun 任务的朋友们做个参考。这个问题的覆盖面其实不小。DS 本身是国内使用率很高的开源工作流调度平台ChunJun原 FlinkX又是常见的离线数据同步引擎两者结合几乎是很多数仓项目的标准配置。但只要 DS 和 ChunJun 的版本、插件包、JSON 配置任何一个环节对不上工作流里保存 ChunJun 任务时就可能翻车。这篇文章会从“保存失败”这个动作出发拆解 DS 后端处理 ChunJun 任务节点的完整逻辑讲清楚根因定位的方法再给出一套可以直接抄作业的修复步骤最后附上我整理的常见问题速查表。1. 问题现象与排查环境1.1 保存失败的现场还原先说当时的具体表现。我在 DS 的“项目管理 - 工作流定义”里创建一个新工作流拖入一个 ChunJun 节点节点类型选择“CHUNJUN”然后在“自定义模板”里填写 ChunJun 的 JSON 配置。点保存时前端提示“保存失败请稍后重试”。这个提示非常笼统前端控制台只有一个非 200 的响应响应体里是统一的错误包装真正的异常被后端吞掉了只有去翻 API 服务日志才能看到细节。我当时第一反应是 JSON 格式写错了但仔细检查了好几遍job 内容里的 reader、writer 配置都是完整的content 数组也符合 ChunJun 的标准结构。然后在“任务实例”里手动运行这个任务任务又是能正常跑通的说明 ChunJun 本身没问题问题出在 DS 的保存动作上。后来我把排查重点转向 DS 服务端保存 ChunJun 任务时后端到底做了什么校验为什么同样的配置手动执行可以保存到工作流里就不行顺着这个问题我逐步梳理了 DS 对 ChunJun 任务节点的处理逻辑。1.2 环境版本与部署方式说明我的环境信息如下后续的排查思路和修复方案都是基于这套环境DolphinScheduler 版本3.1.9ChunJun 版本1.1.0依赖 Flink 1.13数据库MySQL 8.0DS 元数据库部署方式二进制包部署API-Server 和 Worker 分开部署ChunJun 安装路径/opt/chunJun/chunjun-dist这个版本组合其实很关键。DS 3.1.x 开始把 ChunJun 节点作为内置任务插件但不同小版本对 ChunJun 的任务参数结构、类加载机制都有差异。如果你的版本和我不同现象可能类似但根因侧重点会有区别后面我会单独说明。2. 保存失败的根因定位思路2.1 先理清 DS 保存任务节点的完整链路在动手翻代码之前我先理了一下 DS 保存工作流节点的调用链。DS 的前端把整个工作流 DAG 的定义提交给 API-ServerAPI-Server 收到请求后会执行一批操作保存工作流基本信息、批量保存任务定义、保存任务间的关系等。对于每个任务的保存核心入口是 TaskDefinitionServiceImpl。它会根据任务的“任务类型”字段去定位对应的 TaskChannel再通过 TaskChannelFactory 创建具体的任务通道。在创建通道的过程中会触发任务参数从字符串到具体对象的转换这个转换过程就会校验参数格式。ChunJun 任务节点的参数是一个 JSON 字符串DS 后端会把它解析成 ChunJunParameters 对象。这一步如果解析失败或者解析出来的对象缺少必填字段保存动作就会直接抛异常。而这个异常被上层事务回滚后前端只能收到一个笼统的失败提示。说白了保存失败 任务参数无法被 DS 正确识别或持久化。要定位根因就得从参数解析和持久化两个方向去查。2.2 日志是定位问题的第一现场当时我在 API-Server 的 logs 目录下翻到了真正的异常栈关键片段如下ERROR [TaskDefinitionServiceImpl] - Save task definition error. java.lang.NullPointerException: null at org.apache.dolphinscheduler.plugin.task.chunjun.ChunJunParameters.checkParameters(ChunJunParameters.java:94) at org.apache.dolphinscheduler.plugin.task.api.AbstractParameters.getCheckedParameters(AbstractParameters.java:57) at org.apache.dolphinscheduler.service.task.TaskPluginManager.checkTaskParameters(TaskPluginManager.java:145) at org.apache.dolphinscheduler.service.process.ProcessServiceImpl.createTaskDefinition(ProcessServiceImpl.java:1245)看到ChunJunParameters.checkParameters里抛了 NPE问题就聚焦了不是数据库的问题不是工作流 DAG 的问题而是 ChunJun 任务参数对象在“自我校验”阶段没通过。也就是说我填的 JSON 虽然能运行但 DS 解析后某个字段是空的触发了空指针。2.3 源码定位ChunJunParameters 的校验逻辑既然报错指向 ChunJunParameters 的第 94 行我直接打开了 DS 源码里这个类看看它到底校验了什么。ChunJunParameters 核心代码如下关键部分做了精简public class ChunJunParameters extends AbstractParameters { private String jobContent; private String deployMode; private String others; private String flinkParallelism; private String queueName; private String mainJar; private String mainArgs; Override public boolean checkParameters() { if (StringUtils.isEmpty(deployMode)) { throw new IllegalArgumentException(deployMode must not be empty); } if (StringUtils.isEmpty(jobContent)) { throw new IllegalArgumentException(jobContent must not be empty); } // 第94行附近 JSONObject jsonObject JSONObject.parseObject(jobContent); JSONArray contentArray jsonObject.getJSONArray(content); if (contentArray null || contentArray.size() 0) { throw new IllegalArgumentException(content can not be empty); } return true; } }原来DS 的 ChunJun 任务节点要求 jobContent 必须是一个合法的 JSON 对象里面必须包含content数组。这个校验本身很合理因为 ChunJun 的同步任务必须有 reader 和 writer。但问题在于JSONObject.parseObject(jobContent)这一步如果得到的 JSONObject 里没有content字段返回的contentArray就是 null再调用contentArray.size()空指针就出来了。我在“自定义模板”里写的 JSON 结构是{ job: { content: [ { reader: {}, writer: {} } ], setting: {} } }在 ChunJun 原生执行器里job.content是合法结构。但 DS 解析时直接取的是根路径下的content而不是job.content。所以不管我 job 内容填得再对DS 拿到的 content 数组始终是空的保存当然失败。2.4 版本兼容差异带来的衍生坑顺着这个思路我又去翻了一下不同版本 DS 的实现。在 DS 3.0.x 早期版本中ChunJunParameters 的校验逻辑其实比 3.1.9 宽松一些不会强制取根路径的 content 字段。3.1.x 加强了参数校验后对 JSON 结构的要求变了但前端页面的“自定义模板”提示文案和示例却没同步更新导致老用户沿用旧的 ChunJun 配置格式时直接翻车。这种情况在开源软件的迭代中很常见执行引擎和调度框架对同一个 JSON 的解析层级要求不完全一致调度框架做了更严格的校验但用户侧拿到的还是执行引擎的配置习惯。所以排查这类保存失败问题时不能只看执行器支不支持一定要确认调度框架的解析规则。3. 实战修复过程全记录3.1 修复思路让 JSON 结构同时兼容 DS 与 ChunJun明确了根因修复方案就简单了把工作流里 ChunJun 节点的 JSON 配置结构改成 DS 要求的格式。DS 的 ChunJunParameters 期望的 jobContent 结构是{ content: [ { reader: { name: mysqlreader, parameter: {} }, writer: { name: mysqlwriter, parameter: {} } } ], setting: { speed: { bytes: 0, channel: 1 } } }注意这里的content数组直接位于 JSON 根路径而不是嵌套在job下面。这也是 DS 内部用了自己的一套参数解析并不是直接透传给 ChunJun。不过为了让这份配置在 ChunJun 原生执行时也能正常使用我做了兼容处理DS 节点里填写 DS 要求的结构在真正下发到 ChunJun 引擎时由 DS 的 ChunJunTaskChannel 做格式转换。DS 的这个转换逻辑在ChunJunTask.java里它会读取 parameters 里的 deployMode、mainJar、others 等字段拼装 ChunJun 的启动参数同时把 jobContent 原样写入临时 JSON 文件。也就是说DS 要的 jobContent 是它内部解析用的格式而 ChunJun 运行时需要的仍然是完整 job 结构。经过实测DS 3.1.9 中只要 jobContent 满足“根路径包含 content 数组”这个条件DS 就能把 content 内容转换成 ChunJun 的 JobGraph 并下发执行。我的最终配置改为{ content: [ { reader: { name: mysqlreader, parameter: { username: root, password: 123456, column: [*], connection: [{ jdbcUrl: [jdbc:mysql://localhost:3306/test], table: [source_table] }] } }, writer: { name: mysqlwriter, parameter: { username: root, password: 123456, writeMode: insert, column: [*], connection: [{ jdbcUrl: jdbc:mysql://localhost:3306/test, table: [target_table] }] } } } ], setting: { speed: { channel: 1, bytes: 0 } } }修改配置后保存 ChunJun 任务成功不再报空指针。随后我触发了一次工作流运行任务也能正常跑通问题初步解决。3.2 root 原因延伸插件依赖包缺失导致的保存失败JSON 结构问题修复后我顺手也复盘了一下团队的另一个环境因为那个环境的 DS 里ChunJun 任务的保存失败表现完全不同——不是空指针而是ClassNotFoundException报错指向com.dtstack.chunjun.Main。这个环境是最近通过 Docker 方式部署的 DS没有手动往 worker 节点的 lib 目录放 ChunJun 相关依赖。这个问题其实也非常典型。DS 的 ChunJun 任务节点在任务真正提交执行时Worker 上必须有 ChunJun 的执行入口类和相关依赖。如果在 DS 的安装目录里没有配置 chunjun 插件依赖包任务保存时虽然不会失败但任务运行时一定会失败而如果你的 Worker 节点和 API-Server 混布且某些扩展包的缺失会影响 API-Server 的类加载那就可能在保存阶段就暴露问题。解决方案是在 DS 的安装目录下找到libs或plugins目录把 ChunJun 发行包里的chunjun-core.jar、chunjun-mysql.jar等依赖放进去。比较稳妥的做法是在每台 Worker 节点上部署 ChunJun 发行包比如 /opt/chunjun 目录在 DS 的 worker 配置里把 ChunJun 需要的依赖 jar 放到dolphinscheduler-worker的 lib 目录下或者在任务节点的“其他参数”中指定-Dchunjun.libjars路径让 Worker 动态加载。这里可以关联到很多团队用 Dockerfile 封装 DS 镜像时的一个共同痛点只把 DS 本体打进镜像ChunJun 依赖忘加或者加错路径结果换一台机器部署就炸。建议在做镜像时直接把 ChunJun 依赖打进同一个镜像或者在启动脚本里固定CHUNJUN_HOME环境变量。3.3 数据库字段长度与字符集问题还有一次比较隐蔽的保存失败发生在 MySQL 元数据库里。DS 的任务定义表命名是t_ds_task_definition其中有一个字段task_params用于存储任务参数类型是text但有些用户的场景里 ChunJun 的配置特别长尤其是包含大量字段映射的同步任务JSON 文本超过 64KB 时text 字段就存不下了保存时直接报数据库异常。这种问题的典型报错是Data truncation: Data too long for column task_params at row 1解决办法有两种调大字段类型把task_params从text改成longtext执行ALTER TABLE t_ds_task_definition MODIFY COLUMN task_params LONGTEXT;注意备份和停机窗口在程序层面控制 ChunJun 任务 JSON 的长度拆分任务避免一个任务节点里塞下所有逻辑。在我的经验里第二种方式更推荐。因为一个 ChunJun 任务节点动辄几百行的 JSON本身可读性就很差出了问题也不好排查。把它拆成多个子任务配合 DS 的依赖关系编排反而更清晰稳定。3.4 排查保存失败时常用的几个命令套路排查过程中除了看日志我还习惯了用几条命令快速缩小范围。如果你的问题不是 JSON 结构而是异常信息不明确可以这样操作首先找到 API-Server 日志tail -f /opt/dolphinscheduler/logs/dolphinscheduler-api.log | grep -i error其次定位到具體任务 ID 去查详细日志。DS 的 API-Server 日志一般会打印任务定义 ID拿到这个 ID 后再到t_ds_task_definition表里查看 task_params 字段的实际情况。SELECT id, name, task_type, task_params FROM t_ds_task_definition WHERE id 12345;然后再确认工作流定义 ID 对应的 DAG 结构是否完整SELECT * FROM t_ds_process_task_relation WHERE process_definition_code xxx;这套组合拳打下来基本能把“前端报保存失败”这个大问题拆解成“参数校验失败”“数据库写入失败”“依赖缺失失败”三个小方向再逐个击破。4. 常见问题诊断速查表与避坑经验4.1 诊断速查表我把这次排查和之前遇到过的同类问题整理成了一张速查表遇到保存失败可以直接对着排查异常特征可能原因处理方式NullPointerExceptionat ChunJunParametersjobContent JSON 根路径缺少 content 数组调整 JSON 结构把 content 提到根路径ClassNotFoundException: com.dtstack.chunjun.MainWorker 缺少 ChunJun 依赖包把 ChunJun 发行包 jar 放到 worker lib 目录或配置依赖路径Data too long for column task_params任务参数超过 text 字段长度上限修改字段为 longtext或拆分任务节点IllegalArgumentException: deployMode must not be emptyChunJun 节点未选择部署模式检查节点的“部署模式”参数必须选择 local/yarn/per-job 等JSON parse error任务参数中有多余逗号或非法字符用在线 JSON 校验工具先过一遍格式NoSuchMethodErrorDS 与 ChunJun 版本不匹配统一 DS 和 ChunJun 版本或更换兼容版本组合前端提示保存失败但日志无异常浏览器缓存或前端组件版本与后端不一致清理浏览器缓存强制刷新页面确认前后端版本一致这张表只是起点实际项目里肯定还有其他更个性化的场景但排查思路是通用的先日志定位异常类型再确认是哪一层抛出来的最后再针对性地处理。4.2 一个容易忽视的细节任务节点名称与标识还有一个细节也值得单独拿出来说DS 里保存 ChunJun 任务时任务节点的 name 字段如果包含特殊字符比如中文括号、百分号或者超出 255 个字符也会在保存阶段失败。这个问题的报错往往不太明确前端可能看到的是“保存失败”后端日志则是Data truncation或SQLException。我遇到过最离奇的一次是任务名称里有一个全角的空格看起来和普通空格一模一样但数据库写入时触发了字符集校验导致保存失败。排查了很久最后把任务名称复制出来逐个字符比对才发现。所以如果你的 ChunJun 任务一直保存失败且日志里没有明显的 Java 异常可以顺手检查一下任务名称和项目名称里有没有特殊字符尽量不要用 emoji、全角符号、超长字符。4.3 资源中心引用路径不存在也会导致保存失败还有一种情况是ChunJun 任务节点里引用了资源中心的 jar 包或文件比如你用资源中心管理了 ChunJun 的驱动包然后在节点的“自定义模板”里写了${resourceName}这样的占位符。如果你在资源中心里删除了这个文件或者路径写错了保存时 DS 也会做一次资源校验校验不通过直接报失败。这种情况下的日志通常会出现resource does not exist或类似的提示。处理方式很简单去“资源中心”确认文件是否存在然后检查任务节点里的资源引用路径是否与资源中心里的路径完全一致注意大小写。DS 的资源引用是区分大小写的这一点经常被忽略。4.4 复制粘贴 JSON 时出现的隐藏字符坑我最后再补一个实战中特别容易踩的坑从微信、飞书或在线文档里复制 ChunJun 的 JSON 配置时粘贴到 DS 的任务参数里经常会带入零宽空格或不可见字符。这些字符在 JSON 解析时会导致IllegalStateException或MalformedJsonException报错内容会指向某个奇怪的字符位置。遇到这种情况不要直接盯着 JSON 看先用十六进制模式查看粘贴内容或者把内容粘贴到一个纯文本编辑器里把不可见字符显示出来再手动清理一遍。还有一个更快的办法用 Python 一键清洗比如sed s/\xe2\x80\x8b//g chunjun.json chunjun-clean.json或者用 Pythonwith open(chunjun.json, r, encodingutf-8) as f: content f.read() content content.replace(\u200b, ).replace(\u200c, ).replace(\u200d, ) with open(chunjun-clean.json, w, encodingutf-8) as f: f.write(content)我个人的习惯是凡是准备贴到 DS 里的 JSON都先经过一步清洗再提交省得时不时被这种隐形字符坑一下。5. 延伸思考从“保存成功”到“稳定运行”的几条建议5.1 验证保存成功只是第一步推荐加一个“试运行”检查ChunJun 任务保存成功并不代表任务运行不会出问题。DS 在保存任务时只做了参数合法性的初步校验真正的运行期校验比如目标表是否存在、连接 MongoDB 的认证方式是否正确、Flink 集群是否有资源都会在运行阶段才暴露。所以我的建议是每新建一个 ChunJun 任务节点保存通过后最好先单独触发一次任务运行确认数据同步链路跑通再把工作流整体的调度打开。不要一步到位直接上线尤其是改动了 reader 或 writer 的字段映射时最好先在测试环境做全量验证。即使是线上环境也要预留出试运行的时间窗口避免因为一次保存成功就掉以轻心。5.2 注意 DS 与 ChunJun 的版本兼容矩阵我这次踩的 JSON 校验问题本质上就是 DS 3.1.9 和 ChunJun 新版本搭配时的兼容性问题。实际上DS 官方文档里对 ChunJun 的版本支持是有说明的不同 DS 版本对 ChunJun 的嵌入方式和参数要求不同。我整理了一下当前主流组合的参考建议DolphinScheduler 版本ChunJun 版本兼容性说明3.0.x1.1.0较稳定JSON 校验较宽松3.1.0 - 3.1.41.1.0功能变化不大可正常使用3.1.5 - 3.1.91.1.0校验加强content 必须位于根路径3.2.x1.1.1注意新版本类名变化建议先验证当然这个表格只能作为参考真正落地的版本组合一定要以你自己的测试结果为准。升级 DS 或 ChunJun 时我会先在一台测试机器上完整跑一遍“创建任务 - 保存 - 运行 - 数据校验”的流程再决定是否全量升级。5.3 善用 DS 的任务插件机制必要时可二次开发如果你的团队对 ChunJun 任务的依赖特别深而且受够了 DS 内置的 JSON 校验规则其实还有一个更治本的方案基于 DS 的 SPI 机制自己实现一个自定义任务插件直接使用你期望的 JSON 解析方式和参数结构。DS 的任务插件机制并不复杂核心就是继承AbstractTask然后实现TaskChannelFactory再通过 SPI 的方式注册到 DS 里。这样你可以在自己的插件里做完整的 JSON 解析和校验甚至把 ChunJun 的参数组装逻辑都包进去完全摆脱内置插件的限制。不过这个方案对开发和维护成本有一定要求适合团队里有专门的大数据平台开发人员的情况。如果只是偶尔用一下 ChunJun内置插件加一个“JSON 结构修正”的操作完全够用了。最后的实操体会这次定位和修复 ChunJun 任务保存失败我最大的感受是在开源调度系统里文档提示和代码实现往往存在滞后遇到问题不能只靠猜一定要顺着日志往源码里挖。DS 的源码结构还算清晰ds-rpc、ds-service、ds-task-plugin都能快速定位到问题类。只要你愿意花时间看那一两段报错对应的代码排查效率会高很多。另外关于 ChunJun 任务 JSON 的格式问题我现在养成了一个习惯在本地定义一个标准的 JSON 模板每次新建任务节点时直接复制模板再改字段而不是手写。这样可以极大降低因为少了一个字段或者嵌套层级不对导致的保存失败概率。说白了折腾过一次够了能靠工具和模板规避的坑就不要靠记忆硬扛。希望这篇文章能把你在 DolphinScheduler 工作流里配置 ChunJun 任务时可能遇到的保存失败问题从“玄学报错”变成“有据可查的系统问题”。如果你在实际排查中还有不一样的报错信息欢迎带着日志数据再来交流说不定你的场景又能补全一张排查记录。
