news 2026/9/23 20:23:13

Apache DolphinScheduler 常见问题实战指南：服务架构、并发调度与故障排查全解析

作者头像

张小明

前端开发工程师

1.2k 24
文章封面图
Apache DolphinScheduler 常见问题实战指南：服务架构、并发调度与故障排查全解析
  • 任务调度
  • 大数据
  • 后端
  • 前端

【免费下载链接】dolphinscheduler

Apache DolphinScheduler is the modern data orchestration platform. Agile to create high performance workflow with low-code

项目地址：https://gitcode.com/gh_mirrors/do/dolphinscheduler
点击查看免费下载

Apache DolphinScheduler 是一款面向现代数据编排场景的低代码工作流调度平台。官方 FAQ 文档沉淀了大量来自社区一线的真实问题，涵盖服务架构与部署规划、任务执行机制、并发调度配置、高可用容错、网络与数据库调优、版本升级等主题。本文以该 FAQ 为骨架，结合当前仓库中的源码与配置逐条展开讲解，帮助你快速定位并解决实际运维与二次开发中最常见的疑难问题。

说明：FAQ 中的部分条目源于 1.x / 2.x 历史版本，文中均保留了版本前提标注；当前仓库（3.x 主线）的配置形态（如application.yaml、application.properties、common.properties）会与旧版本略有差异，使用时请以你实际部署的版本为准。

一、项目与服务架构

1.1 项目名称与五个核心服务

项目全称为DolphinScheduler。整体由 5 个服务加 1 个前端组成，各服务职责如下：

服务说明
MasterServer主要负责 DAG 的切分和任务状态的监控
WorkerServer / LoggerServer主要负责任务的提交、执行和任务状态的更新；LoggerServer 用于 Rest Api 通过 RPC 查看日志
ApiServer提供 Rest Api 服务，供 UI 进行调用
AlertServer提供告警服务
UI前端页面展示

从当前仓库的模块划分可以印证这一职责边界：dolphinscheduler-master 负责工作流（DAG）的解析、分发与状态轮询，dolphinscheduler-worker 负责任务的实际提交与执行，dolphinscheduler-api 提供 REST API，dolphinscheduler-alert 承载各类告警插件（email、dingtalk、feishu、webexteams 等）。

由于服务数量较多，单机部署建议至少 4 核 16G 以上内存。若仅有一个节点，各服务只能部署在同一台机器上；生产环境建议使用 3 节点以获得更好的稳定性，且尽量让 Master / Worker / Api 分别落在不同节点上。DolphinScheduler 自身对系统资源占用并不高，具体机器数量取决于你的业务任务量，建议多做压测再确定规模。

1.2 支持的操作系统与运行环境

理论上只有 Worker 必须运行在 Linux 上（任务通过sudo -u tenant以租户身份执行），其他服务可以运行在 Windows 上，但仍推荐统一部署在 Linux 环境。生产环境的部署形态包括裸机脚本部署（见 script/dolphinscheduler-daemon.sh）、Docker Compose、Kubernetes Helm 以及 Terraform 等多种方式。

官方同时提供 Docker 镜像与 Dockerfile 供容器化部署使用；需要注意MySQL JDBC 驱动因许可证与 Apache v2 不兼容，不会被打入 Docker 镜像，使用 MySQL 作为元数据库时需要自行处理驱动。

1.3 支持的邮箱告警

系统支持绝大多数邮箱：qq、163、126、139、outlook、aliyun 等，且支持TLS 和 SSL 协议，可在 DolphinScheduler 的 UI 中直接配置。详细配置步骤参见 如何配置邮箱告警，其告警实现位于 dolphinscheduler-alert-email。

二、任务执行机制

2.1 如何指定机器运行任务（Worker 分组）

  • 1.2 及以前版本：使用管理员创建 Worker 分组，在流程定义启动时可指定 Worker 分组，也可以在任务节点上指定 Worker 分组。若未指定则使用Default分组，Default 表示从集群中所有 Worker 里随机选取一台进行任务提交与执行。
  • 1.3 版本起：可以在 worker 配置文件中为每个 Worker 设置所属分组。

关于"Worker 分组管理页面无按钮"的问题：1.3.0 版本起为了支持 k8s，Pod 的 IP 会动态变化，无法在 UI 上静态配置分组，因此改为在worker.properties（新版为worker 配置节）中配置分组名。当前仓库的 dolphinscheduler-worker/src/main/resources/application.yaml 中提供了worker.host-weight、worker.tenant-config等分发相关配置，Worker 通过注册中心上报自身信息供 Master 分发任务。

2.2 Shell 任务的完整执行链路

一个 Shell 任务在 DolphinScheduler 中是如何运行的？FAQ 给出了三个关键点：

  1. 在哪里执行：可指定某个 Worker 运行任务——在安全中心创建 Worker 分组，任务即可发送到指定 Worker；若一个分组含多台服务器，具体由哪台执行由调度决定，存在随机性。
  2. 脚本从哪来：不推荐直接引用服务器上的 Shell 文件路径（涉及权限问题）。建议使用资源中心的存储功能，在 Shell 编辑器中引用资源；系统会先将脚本下载到执行目录。若任务依赖资源中心文件，Worker 通过hdfs dfs -get从 HDFS 拉取资源文件，然后在/tmp/escheduler/exec/process目录下运行任务（该路径可在安装时自定义）。
  3. 以谁的身份执行：任务通过sudo -u ${tenant}以租户身份执行，租户是一个真实的 Linux 用户。

围绕第 3 点，FAQ 还专门回答了"任务被杀时其子进程如何清理"：Worker 任务会通过sudo -u tenant sh xxx.command生成子进程，DolphinScheduler 在 1.0.4 版本起加入 kill 任务能力，会一并杀掉任务产生的所有子进程。当前仓库中 dolphinscheduler-common/src/main/resources/common.properties 的sudo.enable=true即控制是否以sudo方式切换执行用户。

2.3 如何新增一台 Worker 服务器

  1. 创建部署用户并配置 hosts 映射（参考集群部署文档的环境准备章节）；
  2. 配置 hosts 映射与 ssh 免密访问，并修改目录权限；
  3. 从已部署好的 Worker 服务器上拷贝部署目录；
  4. 进入bin目录启动 Worker：
./dolphinscheduler-daemon.sh start worker-server

2.4 队列（Queue）的使用：用户队列与租户队列

DolphinScheduler 的队列可以在用户或租户上配置，用户指定的队列优先级高于租户队列。例如为 MR 任务指定队列，通过mapreduce.job.queuename指定，MR 采用如下方式读取：

Configuration conf = new Configuration(); GenericOptionsParser optionParser = new GenericOptionsParser(conf, args); String[] remainingArgs = optionParser.getRemainingArgs();

如果是 Spark 任务，则通过--queue方式指定队列。

2.5 任务优先级与失败策略

DolphinScheduler 同时支持流程优先级和任务优先级，共五级：HIGHEST、HIGH、MEDIUM、LOW、LOWEST。既可以设置不同流程实例之间的优先级，也可以设置同一流程实例中不同任务实例的优先级。

当前置任务失败时，后续任务是否继续执行由启动工作流时的"任务失败策略"决定：可选择continue（继续）或failure（失败即停）。

2.6 启动流程定义的几种方式

  1. 在流程定义列表中点击"启动"按钮；
  2. 为流程定义添加定时器，由调度触发启动；
  3. 在流程定义的查看/编辑 DAG 页面，右键任意任务节点选择"启动流程定义"；
  4. 编辑 DAG 时，可将部分任务的运行标志设为禁止运行，流程定义启动时，这些节点对应的连线会从 DAG 中移除。

三、并发与调度配置

3.1 流程并发、任务并发与 DAG 最大并发数

FAQ 以 1.2.1 版本的配置为例，解释了"并发数"的真实含义：

master.properties # 控制 master 节点上工作流的最大并行数 master.exec.threads=100 # 控制每个工作流中并行任务的最大数量 master.exec.task.number=20 worker.properties # 控制 worker 节点上任务的最大并行数 worker.exec.threads=100

DAG 支持的最大并发 100，并不是说同时生成 100 个工作流实例去并发运行——它分别表示 Master 侧工作流并行上限、单工作流内并行任务上限、Worker 侧任务并行上限。在当前仓库 3.x 主线中，这些参数已迁移到 master application.yaml（master.pre-exec-threads: 10、master.exec-threads: 100）与 worker application.yaml（worker.exec-threads: 100）中，同时新增了server-load-protection负载保护（CPU、内存、磁盘阈值默认 0.7）等能力，源码中可见其并行控制语义与 FAQ 描述一致。

3.2 定时相关的三个"坑"

  1. 不要设置为每秒执行：设置定时时，若第一段（* * * * * ? *）设为*，意味着每秒执行一次。调度系统不支持秒级频率任务，设置秒级任务可能直接导致系统崩溃。1.1.0 版本之后会提供"最近调度时间列表"辅助排查。
  2. 定时有生效时间范围：若定时任务的开始与结束时间相同，则该定时无效；若结束时间早于当前时间，定时很可能被自动删除。
  3. 定时任务无法上线：创建定时任务并写入t_scheduler_schedules表后，点击"上线"无反应并锁表，可将表中release_state字段置为1使任务显示上线状态。注意：DS 1.2 以上版本表名为t_ds_schedules，其他版本为t_scheduler_schedules。

3.3 系统变量时间参数

常用的系统内置时间参数（如${system.biz.date}、${system.biz.curdate}等）及其用法，完整说明见 系统内置参数文档。这些参数在工作流启动时按当前调度时间计算，是构建"按天/按小时增量同步"类任务的核心工具。

四、任务依赖设计

4.1 任务依赖的几种实现

FAQ 明确了两类任务依赖实现：

  1. DAG 内的任务依赖：由 DAG 切分时的**入度（零度）**关系决定，即下游任务依赖其所有上游任务完成；
  2. 任务依赖节点（DEPENDENT）：用于实现跨流程的任务或流程依赖，详细设计参见 任务结构设计文档。

注意：不支持跨项目的流程或任务依赖。

4.2 DEPENDENT 任务节点到底是什么

DEPENDENT 任务节点实际上没有可执行脚本，它只用来配置数据周期的依赖逻辑，并在其后挂接任务节点来实现任务的周期依赖。从源码看，依赖判定逻辑集中在 DependentExecute.java（依赖项列表 +AND/OR关系组合判定），配套的数据模型包括 DependentItem、DependentTaskModel，并有 DependentTaskTest 等测试用例验证。

4.3 工作流依赖（Workflow Dependency）的判定规则

工作流依赖目前按自然日判定：

  • 上月末：判定时间取工作流 A 的 start_time / 调度时间，落在'2019-05-31 00:00:00'与'2019-05-31 23:59:59'之间；
  • 上月：判定 1 号到月末每一天都有一个 A 实例成功完成；
  • 上周：上周 7 天每天都有完成的 A 实例；
  • 前两天：判定昨天和前天，两天都必须有完成的 A 实例。

五、高可用与故障容错

5.1 多 Master、多 Worker 场景下的容错

Master 同时监控 Master 与 Worker 服务：

  1. Master 服务丢失：其他 Master 会接管宕机 Master 的流程，继续监控 Worker 任务状态；
  2. Worker 服务丢失：Master 监控到 Worker 消失后，若该 Worker 上有 Yarn 任务，会重试 Kill Yarn 任务。

详细设计见 架构设计文档。

5.2 Master 与 Worker 部署在同一台机器的容错限制

1.0.3 版本只实现了 Master 启动过程的容错，未实现 Worker 容错——即 Worker 挂掉时若无 Master 存在，该流程会出现问题。该缺陷计划在 1.1.0 中修复（增加 Master 与 Worker 启动容错）。如需手动修复，需要将跨重启期间被丢弃的、正在运行的 Worker 任务置为失败状态，再从失败节点恢复流程。

5.3 手动启动或调度后没有生成流程实例

  1. 通过jps确认 MasterServer 服务是否存在，或在服务监控中直接查看 zk 里是否存在 master 服务；
  2. 若 Master 存在，检查命令状态统计或t_ds_error_command表是否有新记录；若有新记录，重点查看 message 字段定位失败原因。

5.4 任务状态一直停留在"提交成功"

按如下顺序排查：

  1. 通过jps确认 WorkerServer 服务是否存在，或查看服务监控中 zk 里是否存在 worker 服务；
  2. 若 WorkerServer 正常，需检查MasterServer 是否把任务放入 zk 队列——查看 MasterServer 日志与 zk 队列，判断任务是否阻塞在 Master；
  3. 若以上均无问题，定位是否指定了 Worker 分组，但该分组下没有在线的机器。

5.5 Master / Worker 运行数天后异常停止

典型原因是Zookeeper 会话超时设置过短（仅 0.3 秒）。修改zookeeper.properties（新版为registry.zookeeper配置节）：

zookeeper.session.timeout=60000 zookeeper.connection.timeout=30000

当前仓库 master application.yaml 中对应配置为registry.zookeeper.session-timeout: 60s、connection-timeout: 15s，语义一致。

5.6 数据库延迟导致任务显示一直 running

当 DB 延迟、日志显示 task instance 为 null 时，界面会出现某些任务一直 running 的问题。1.2.1 版本已修复；1.2.1 以下版本可按以下步骤手工恢复：

1. 清理 zk 中 /dolphinscheduler/task_queue 路径下的任务队列 2. 将该任务状态改为 failed（整数值：6） 3. 通过"从失败恢复"重新运行工作流

5.7 Zookeeper 中 master znode 的 IP 是 127.0.0.1

若 zk 中注册的 master/worker 地址是127.0.0.1而非期望的内网 IP（eth0/eth1），且可能看不到任务日志，通常是/etc/hosts解析问题。修复步骤：

# 1, 确认 hostname $ hostname hadoop1 # 2, 查看 hostname -i 解析结果 $ hostname -i 127.0.0.1 10.3.57.15 # 3, 编辑 /etc/hosts，把 hadoop1 从 127.0.0.1 记录中删除 $ cat /etc/hosts 127.0.0.1 localhost 10.3.57.15 ds1 hadoop1 # 4, 再次确认 $ hostname -i 10.3.57.15

根因：hostname返回服务器主机名，hostname -i返回/etc/hosts中匹配的所有 IP。DolphinScheduler 取hostname -i返回的第一条记录，因此只要保证hostname能解析出正确的内网 IP 即可修复。社区也建议使用配置文件或 znode 中指定的 IP 而非依赖/etc/hosts。

六、网络与 IP 地址获取

6.1 运行期间 IP 地址获取错误

Master 与 Worker 向 Zookeeper 注册时，会以ip:port形式创建相关信息。若 IP 获取错误，先检查网络信息（Linux 下可用ifconfig查看），如下图所示：

DolphinScheduler 提供了三种网卡获取策略：

  • default：优先使用内网网卡获取 IP，失败后使用外网网卡，全部失败则使用第一个可用网卡地址；
  • inner：只使用内网网卡获取 IP，失败抛出异常；
  • outer：只使用外网网卡获取 IP，失败抛出异常。

修改common.properties中的配置：

# network IP gets priority, default: inner outer # dolphin.scheduler.network.priority.strategy=default

如需从指定网卡获取 IP，修改common.properties的dolphin.scheduler.network.interface.preferred。例如从网卡eth1获取：

dolphin.scheduler.network.interface.preferred=eth1

配置修改后重启服务生效。若 IP 仍不正确，可下载dolphinscheduler-netutils.jar到机器上执行java -jar target/dolphinscheduler-netutils.jar，将输出反馈给社区开发者。

从源码看，这套逻辑实现在 NetUtils.java 中：findSuitableNetworkInterface()会先按dolphin.scheduler.network.interface.preferred指定网卡，再通过dolphin.scheduler.network.interface.restrict（默认docker0）排除虚拟网卡，最后由filterByNetworkPriority()依据dolphin.scheduler.network.priority.strategy（default/inner/outer 三态）过滤，并优先选取可达（isReachable(100)）的 IPv4 地址。当前 common.properties 中对应的默认值即为上述描述。

6.2 多 YARN 集群部署

通过在不同 YARN 集群部署不同 Worker 即可实现多集群支持，以 AWS EMR 为例：

  1. 在 EMR 集群的 master 节点上部署 WorkerServer；
  2. 将conf/common.properties中的yarn.application.status.address改为当前 EMR 的 yarn 地址；
  3. 执行bin/dolphinscheduler-daemon.sh start worker-server启动 WorkerServer。

当前仓库 common.properties 中对应的 YARN 配置项包括yarn.application.status.address=http://ds1:%s/ws/v1/cluster/apps/%s与yarn.job.history.status.address，多 RM 场景可配置yarn.resourcemanager.ha.rm.ids。

七、内存与资源告警

7.1 Master / Worker 报资源不足告警

当 Master 或 Worker 报如下告警时，可将master.properties中的master.reserved.memory调小（如0.1），或把worker.properties中的worker.reserved.memory调小（如0.1）。该参数表示预留内存比例，调小后可降低触发保护的门槛。新版中对应server-load-protection下的内存使用率阈值（如 worker application.yaml 的max-system-memory-usage-percentage-thresholds: 0.7）。

八、install.sh 安装脚本注意事项

FAQ 特别提醒安装脚本install.sh中的几个易错点：

  1. 若替换变量包含特殊字符，使用\转义字符进行转义；
  2. installPath="/data1_1T/dolphinscheduler"，该目录不能与当前执行一键安装的 install.sh 所在目录相同；
  3. deployUser="dolphinscheduler"，部署用户必须具有 sudo 权限，因为 Worker 通过sudo -u tenant sh xxx.command执行；
  4. monitorServerState="false"控制是否启动服务监控脚本，默认不启动；若启动，则每 5 分钟监控 master 和 worker 服务，机器宕机时自动重启；
  5. hdfsStartupSate="false"控制是否启用 HDFS 资源上传功能，默认不启用；不启用则资源中心不可用。启用时需在conf/common/hadoop/hadoop.properties中配置resource.hdfs.fs.defaultFS与 yarn 配置；若使用 namenode HA，还需将core-site.xml和hdfs-site.xml拷贝到 conf 根目录。注意：1.0.x 版本不会自动创建 HDFS 根目录，需要自行创建，且部署用户需具备 hdfs 操作权限。

8.1 租户与资源中心的关系

HDFS 启动前创建的租户无法正常使用资源中心：因为 HDFS 未启动时创建的租户，其租户目录不会注册到 HDFS 中，后续资源操作会报错。当前仓库 common.properties 中的resource.storage.type（LOCAL/HDFS/S3/OSS/GCS/ABS/OBS）与resource.storage.upload.base.path即资源中心存储相关配置。

九、数据库相关

9.1 使用 MySQL 替代 PostgreSQL

FAQ 给出了两步配置：

  1. 编辑项目根目录的 maven 配置文件，去掉 mysql 驱动的testscope，使其可被加载：
<dependency> <groupId>mysql</groupId> <artifactId>mysql-connector-java</artifactId> <version>${mysql.connector.version}</version> <scope>test</scope> </dependency>
  1. 编辑application-dao.properties与quzrtz.properties配置使用 mysql 驱动。

默认使用 PostgreSQL 驱动同样是出于许可证原因。在当前仓库 3.x 中，数据库切换改为 Spring profile 方式：默认激活postgresql，切换 MySQL 时激活mysqlprofile，见 master application.yaml 末尾的spring.config.activate.on-profile: mysql配置块。

9.2 更新流程定义报错：Duplicate key TaskDefinition

DS 2.0.4（2.0.0-alpha 之后）之前，版本切换可能导致t_ds_process_task_relation_log、t_ds_task_definition_log中出现重复键，使更新工作流失败。可参照如下 SQL 删除重复数据（操作前务必备份原始数据）：

DELETE FROM t_ds_process_task_relation_log WHERE id IN ( SELECT x.id FROM ( SELECT aa.id FROM t_ds_process_task_relation_log aa JOIN ( SELECT a.process_definition_code ,MAX(a.id) as min_id ,a.pre_task_code ,a.pre_task_version ,a.post_task_code ,a.post_task_version ,a.process_definition_version ,COUNT(*) cnt FROM t_ds_process_task_relation_log a JOIN ( SELECT code FROM t_ds_process_definition GROUP BY code )b ON b.code = a.process_definition_code WHERE 1=1 GROUP BY a.pre_task_code ,a.post_task_code ,a.pre_task_version ,a.post_task_version ,a.process_definition_code ,a.process_definition_version HAVING COUNT(*) > 1 )bb ON bb.process_definition_code = aa.process_definition_code AND bb.pre_task_code = aa.pre_task_code AND bb.post_task_code = aa.post_task_code AND bb.process_definition_version = aa.process_definition_version AND bb.pre_task_version = aa.pre_task_version AND bb.post_task_version = aa.post_task_version AND bb.min_id != aa.id )x ) ; DELETE FROM t_ds_task_definition_log WHERE id IN ( SELECT x.id FROM ( SELECT a.id FROM t_ds_task_definition_log a JOIN ( SELECT code ,name ,version ,MAX(id) AS min_id FROM t_ds_task_definition_log GROUP BY code ,name ,version HAVING COUNT(*) > 1 )b ON b.code = a.code AND b.name = a.name AND b.version = a.version AND b.min_id != a.id )x ) ;

9.3 使用 PostgreSQL 从 2.0.1 升级到 2.0.5 失败

执行如下 SQL 即可修复：

update t_ds_version set version='2.0.1';

9.4 任务实例提交多个 Yarn application 时总是失败

该问题已在 dev 分支修复（FAQ 中标注在 Requirement/TODO 列表），使用新版本即可避免。

十、前端与 API 常见问题

10.1 UI 无法正常登录

按顺序排查：

  1. 若为 node 启动，检查dolphinscheduler-ui下.env中的API_BASE是否为 Api Server 服务地址；
  2. 若通过install-dolphinscheduler-ui.sh以 nginx 启动，检查/etc/nginx/conf.d/dolphinscheduler.conf中的proxy_pass是否为 Api Server 服务地址；
  3. 若上述配置正确，则检查 Api Server 服务是否正常：
curl http://localhost:12345/dolphinscheduler/users/get-user-info

同时查看 Api Server 日志，若提示cn.dolphinscheduler.api.interceptor.LoginHandlerInterceptor:[76] - session info is null，说明 Api Server 服务正常； 4. 若以上均无问题，检查application.properties中的server.context-path 与 server.port 配置是否正确。

10.2 Swagger UI 地址

  • 3.1.0+ 版本：http://apiServerIp:apiServerPort/dolphinscheduler/swagger-ui/index.html
  • 1.2+ 版本：http://apiServerIp:apiServerPort/dolphinscheduler/doc.html
  • 其他更早版本：http://apiServerIp:apiServerPort/escheduler/doc.html

10.3 前端安装包缺少文件

若前端打包后页面报缺文件，通常是用户修改了 Api Server 配置文件中的apiServerContextPath项导致的；恢复为默认值即可解决。

10.4 上传较大文件被阻塞

  1. 编辑 nginx 配置文件，调大上传大小限制：
client_max_body_size 1024m;
  1. 若浏览器版本过旧，更新到最新版 Chrome。

10.5 创建 Spark 数据源点击"测试连接"时退回登录页

编辑 nginx 配置文件/etc/nginx/conf.d/escheduler.conf，增大代理超时时间：

proxy_connect_timeout 300s; proxy_read_timeout 300s; proxy_send_timeout 300s;

10.6 前端编译相关

Linux 下编译 node-sass 报 EACCESS: permission denied, mkdir xxxx：先单独安装npm install node-sass --unsafe-perm，再执行npm install。

下载 node-sass 二进制失败（如cannot download "https://github.com/sass/node-sass/releases/download/v4.13.1/darwin-x64-72_binding.node"）：

# 1, 进入 dolphinscheduler-ui 删除 node_modules 目录 sudo rm -rf node_modules # 2, 通过 npmmirror.com 安装 node-sass sudo npm uninstall node-sass sudo npm i node-sass --sass_binary_site=https://npmmirror.com/mirrors/node-sass/ # 3, 若第 2 步失败，重建 node-sass sudo npm rebuild node-sass

若不想每次下载该 node 二进制，可设置系统环境变量SASS_BINARY_PATH=/xxx/xxx/xxx/xxx.node。

10.7 Master 启动端口修改

修改application_master.properties，例如：

server.port=12345

十一、Python 相关

11.1 Python 任务指定 Python 版本

  • 1.0.3 之后版本：只需修改bin/env/dolphinscheduler_env.sh中的$PYTHON_LAUNCHER（注意是PYTHON_LAUNCHER，即 python 命令的绝对路径）：
export PYTHON_LAUNCHER=/bin/python/bin/python3

同时注意导出 PATH 时需要直接引用该变量：

export PATH=$HADOOP_HOME/bin:$SPARK_HOME/bin:$PYTHON_LAUNCHER:$JAVA_HOME/bin:$HIVE_HOME/bin:$PATH
  • 1.0.3 之前版本：Python 任务仅支持系统默认的 Python 版本，不支持指定 Python 版本。

11.2 pip install kazoo 报错是否必须安装

kazoo是 Python 连接 Zookeeper 使用的库，用于删除 Zookeeper 中的 master/worker 临时节点信息。如果是首次安装可以忽略该错误；1.3.0 之后 kazoo 不再需要，已由程序逻辑替代。

11.3 发行包中找不到 python-gateway-server

3.0.0-alpha 之后，Python gateway server 已集成进 ApiServer，启动 ApiServer 时 Python gateway 服务会随之启动。如需关闭，修改 ApiServer 配置api-server/conf/application.yaml中的python-gateway.enabled : false。

当前仓库 api application.yaml 中python-gateway配置节包含：enabled: false（默认关闭）、auth-token（公网部署时务必修改默认值）、gateway-server-address: 0.0.0.0、gateway-server-port: 25333、python-port: 25334以及连接/读取超时（0 表示永不超时）等，供 Python API 侧连接使用。

十二、缓存执行（Cache Execution）

如何判断某个任务在"缓存执行"时是否命中缓存、能否复用其他任务的运行结果？

对于标记为Cache Execution的任务，任务启动时会生成一个 cache key，该 key 由以下字段哈希而成：

  • 任务定义：任务实例对应的任务定义 id；
  • 任务版本：任务实例对应的任务定义版本；
  • 任务输入参数：包括上游节点传入的参数与全局参数、任务定义参数列表引用的参数，以及任务定义中使用${}引用的参数；
  • 环境配置：环境名称对应的实际配置内容，即安全中心 - 环境管理中的实际配置内容。

带缓存标识的任务运行时，会在数据库中查找是否存在相同 cache key 的数据：

  • 存在：复制任务实例并更新对应数据；
  • 不存在：任务照常运行，任务完成后将任务实例数据存入缓存。

若不再需要缓存，可在工作流实例中右键节点执行Clear cache（清除缓存），会清除当前版本下当前输入参数的缓存数据。

十三、版本发布、升级与编译

13.1 版本号规范与升级策略

Apache 项目的发布流程在邮件列表中完成，可订阅 DolphinScheduler 邮件列表接收发布通知；新版本发布时伴随 release note（变更日志）与针对上一版本的升级文档。

版本号格式为x.y.z：

  • x 增加：代表新架构版本；
  • y 增加：代表与之前的 y 版本不兼容，需要通过脚本或其他人工处理升级；
  • z 增加：代表 bug 修复，升级完全兼容，无需额外处理。

例外：1.0.2 升级到 1.0.1 不兼容（原文即如此标注），需要升级脚本。

13.2 dolphinscheduler-grpc 报错

在根目录执行：

mvn -U clean package assembly:assembly -Dmaven.test.skip=true

然后刷新整个项目。1.3 版本起不再使用 gRPC 通信，改为直接使用 netty。

13.3 Hive 1.1.0 + CDH 5.15.0 下 SQL Hive 任务连接报错

将 hive pom 依赖：

<dependency> <groupId>org.apache.hive</groupId> <artifactId>hive-jdbc</artifactId> <version>2.3.9</version> </dependency>

改为与集群版本匹配的：

<dependency> <groupId>org.apache.hive</groupId> <artifactId>hive-jdbc</artifactId> <version>1.1.0</version> </dependency>

13.4 流程定义与流程实例下线异常

1.0.4 之前的版本，可修改escheduler-api模块cn.escheduler.api.quartz包下的代码，对 job 不存在的情况做容错：

public boolean deleteJob(String jobName, String jobGroupName) { lock.writeLock().lock(); try { JobKey jobKey = new JobKey(jobName,jobGroupName); if(scheduler.checkExists(jobKey)){ logger.info("try to delete job, job name: {}, job group name: {},", jobName, jobGroupName); return scheduler.deleteJob(jobKey); }else { return true; } } catch (SchedulerException e) { logger.error(String.format("delete job : %s failed",jobName), e); } finally { lock.writeLock().unlock(); } return false; }

即先checkExists再删除，避免因任务不存在导致删除失败。

十四、其他高频问题

14.1 docker-compose 默认配置启动报 Zookeeper 错误

该问题已在 dev-1.3.0 修复，变更点包括：

  1. 在docker-compose.yml中为 Zookeeper 增加环境变量白名单；
  2. 将minLatency、avgLatency、maxLatency的数据类型从 int 改为 float。

当前仓库的 docker-compose.yml 与 docker-stack.yml 中均已配置：

ZOO_4LW_COMMANDS_WHITELIST: srvr,ruok,wchs,cons

14.2 配置 sudo 免密以收窄权限

当默认配置下 sudo 权限过大或无法申请 root 权限时，可将 dolphinscheduler 账号的 sudo 权限配置为普通用户范围内的用户管理器，限制指定用户在指定主机上运行指定命令。例如只允许 dolphinscheduler 操作 userA、userB、userC（这些用户用于多租户向大数据集群提交作业）：

echo 'dolphinscheduler ALL=(userA,userB,userC) NOPASSWD: NOPASSWD: ALL' >> /etc/sudoers sed -i 's/Defaults requirett/#Defaults requirett/g' /etc/sudoers

14.3 任务实例提交多个 Yarn application 失败

该缺陷已在 dev 分支修复，并使用新版本即可；若仍复现，请向社区提交 issue 并提供任务日志。

总结

以上内容完整覆盖了官方 FAQ 中的核心问答，并将其与当前仓库的源码与配置相互印证：服务职责可从 dolphinscheduler-master、dolphinscheduler-worker、dolphinscheduler-api 等模块结构确认；网络策略可追溯至 NetUtils.java 与 common.properties；并发语义可对照 master application.yaml 与 worker application.yaml；依赖判定可研读 DependentExecute.java。

建议在动手排查时遵循"先确认服务存在（jps / zk 监控）→ 再查库表状态（command / error_command / schedules）→ 最后看日志与配置"的路径，绝大多数问题都能在官方文档与上述源码中找到依据。若遇到 FAQ 尚未覆盖的新问题，欢迎在社区继续补充，官方 FAQ 也会持续收集沉淀。

  • 任务调度
  • 大数据
  • 后端
  • 前端

【免费下载链接】dolphinscheduler

Apache DolphinScheduler is the modern data orchestration platform. Agile to create high performance workflow with low-code

项目地址：https://gitcode.com/gh_mirrors/do/dolphinscheduler
点击查看免费下载

相关推荐

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

版权声明: 本文来自互联网用户投稿，该文观点仅代表作者本人，不代表本站立场。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。如若内容造成侵权/违法违规/事实不符，请联系邮箱：809451989@qq.com进行投诉反馈，一经查实，立即删除！
网站建设 2026/9/23 20:22:54

PDT团队KPI指标库搭建指南：从统一口径到落地避坑

简介&#xff1a;面向PDT&#xff08;产品开发团队&#xff09;绩效考核场景的KPI指标库文档&#xff0c;将财务、客户、内部业务三大维度的核心指标整理为可直接参考的评估体系。内容涵盖销售收入、毛利率、目标成本完成率、缺陷密度、问题解决率、NPD流程符合度、软件开发生产…

作者头像 李华
网站建设 2026/9/23 20:13:15

PyTorch人脸性别识别毕设：从数据划分到GUI部署的完整实战

简介&#xff1a;这份资源面向计算机相关专业的本科生与自学者&#xff0c;提供一套基于PyTorch实现人脸性别识别的完整课程设计或毕业设计参考方案。数据集涵盖白种人、黄种人、黑种人等多种族样本&#xff0c;并包含姿态、光照、年龄等干扰因素&#xff0c;需按40%、10%、50%…

作者头像 李华
网站建设 2026/9/23 20:12:36

为什么国内厂商卖的服务器配置低价格贵？

厂商典型配置价格&#xff08;月&#xff09;带宽/流量特点腾讯云轻量2核2G / 50-60GB SSD≈45-52元4-5Mbps&#xff0c;300-500GB流量国内访问优秀&#xff0c;稳定&#xff0c;备案方便阿里云轻量2核2G / 40-50GB SSD≈40-60元3-5Mbps生态最大&#xff0c;活动多百度智能云 B…

作者头像 李华
网站建设 2026/9/23 20:10:24

基于SpringBoot的家政服务系统：订单状态机与数据库设计实战解析

简介&#xff1a;面向Java后端学习者与毕业设计人群&#xff0c;这是一份基于SpringBoot的家政服务平台系统全套源码包&#xff0c;整合前端Vue页面、后端Java逻辑、数据库脚本及论文文档&#xff0c;可直接用于课程设计、大作业或工程实训&#xff0c;也可作为二次开发的基础工…

作者头像 李华
网站建设 2026/9/23 20:10:01

MMSE均衡器原理与工程实现：解决多径信道ISI问题

简介&#xff1a;本资源是一份面向通信工程与数字信号处理初学者的MATLAB实践教学包&#xff0c;聚焦多径信道下符号间干扰&#xff08;ISI&#xff09;的抑制问题&#xff0c;系统实现最小均方差&#xff08;MMSE&#xff09;均衡算法。压缩包共2个文件&#xff0c;均为MATLAB…

作者头像 李华