任务调度 Dolphin Scheduler

第一章：DolphinScheduler 概述

1.1 什么是 DolphinScheduler

概念名称	说明	注意事项
DolphinScheduler	一个分布式、易扩展的可视化工作流任务调度系统，原名 EasyScheduler，由 Apache 孵化并开源。专注于大数据任务编排，支持多种任务类型（Shell、SQL、Spark 等），通过 DAG（有向无环图）方式定义任务依赖关系。	不是传统 Cron 工具的替代品，而是面向复杂数据流水线的调度平台，适合企业级批量任务管理。
开源协议	Apache License 2.0，允许自由使用、修改和分发。	商用需遵守开源协议，注意衍生作品的版权标注。
核心目标	解决任务依赖复杂、调度不稳定、运维困难等问题，提供高可用、可监控、可追溯的任务执行能力。	强调”任务编排”而非”定时触发”，更注重流程完整性与容错机制。

1.2 核心特性与优势

特性名称	说明	注意事项
分布式调度	支持 Master/Worker 架构，任务在 Worker 节点执行，Master 负责调度协调，可水平扩展。	需依赖 ZooKeeper 实现 Master 高可用和 Worker 注册发现。
可视化 DAG 编排	通过 Web UI 拖拽方式构建任务依赖关系，直观展示执行流程。	初学者需理解 DAG 原理，避免循环依赖。
多种任务类型支持	内置 Shell、SQL、Spark、Flink、Python、HTTP、DataX 等任务类型，满足大数据生态需求。	某些任务需额外配置环境路径或客户端（如 Spark-submit）。
高可用（HA）	Master 和 Worker 均支持多节点部署，故障自动转移。	需正确配置 ZooKeeper 集群，避免脑裂问题。
灵活调度策略	支持 Cron 表达式、手动触发、补数（backfill）、依赖触发等多种调度方式。	Cron 表达式需符合 Quartz 格式（6 或 7 位）。
参数化执行	支持全局参数、局部参数、运行时参数传递，提升工作流复用性。	参数类型分为 VALUE 和 DATE，后者支持日期函数（如 $[yyyyMMdd]）。
告警通知机制	支持邮件、短信、钉钉、企业微信、飞书等多种通知方式，任务失败可及时告警。	需提前配置告警组和通知模板，测试连通性。
多租户资源隔离	通过租户（Tenant）机制隔离操作系统用户和资源，确保任务运行安全。	租户需绑定系统用户，Worker 节点上该用户必须存在且有执行权限。

1.3 适用场景与典型用户

场景/用户类型	说明	注意事项
数据仓库 ETL 流程	定时抽取、清洗、加载数据，如从 MySQL 同步到 Hive，再跑 Spark 任务。	需结合 DataX 或 Sqoop 任务类型实现数据迁移。
机器学习流水线	训练前数据准备 → 模型训练（Python/Spark）→ 模型评估 → 结果写入数据库。	可通过 Python 任务调用 sklearn/pytorch 等框架。
日报/周报自动化	每日凌晨自动执行 SQL 统计任务，生成报表并邮件发送。	需配置邮件告警模板，结合 SQL 任务的”查询结果通知”功能。
运维自动化脚本调度	定时清理日志、备份文件、检查服务状态等 Shell 脚本统一管理。	注意脚本退出码（exit code），非 0 视为失败。
互联网公司数据中台	作为统一调度平台，整合多个业务线的数据任务，实现集中监控。	需合理划分项目、租户和权限，避免权限混乱。
典型用户	数据工程师、ETL 开发者、运维工程师、数据分析师、AI 工程师。	非技术人员可通过查看任务日志了解执行状态，但不能修改工作流。

1.4 架构概览（Master/Worker/Alert/Api Server等角色）

组件名称	说明	注意事项
Master Server	负责工作流解析、任务调度、DAG 编排、任务分发，是调度核心。	多 Master 通过 ZooKeeper 选举主节点，避免单点故障。
Worker Server	接收 Master 分配的任务，执行具体任务脚本或程序，上报执行状态。	Worker 按租户（Tenant）分配任务，需确保系统用户存在且有权限。
API Server	提供 RESTful API 接口，供前端 Web UI 或外部系统调用。	所有操作（如启动工作流）最终都通过 API Server 处理。
Alert Server	处理告警事件，根据配置将任务失败等信息发送到邮件、钉钉等渠道。	需单独配置告警插件和通知组，支持自定义告警脚本。
Frontend (Web UI)	基于 Vue 的前端界面，用于可视化操作和监控任务。	可独立部署，通过 Nginx 反向代理连接后端 API。
ZooKeeper	用于 Master/Worker 的注册与发现、高可用选举、任务状态协调。	生产环境建议部署 3 节点以上 ZooKeeper 集群。
Database (MySQL/PostgreSQL)	存储元数据，如用户、项目、工作流定义、执行实例、日志等。	初始化需执行 dolphinscheduler-*-create.sql 脚本建表。
Logger Server	收集 Worker 执行日志，写入本地文件或 HDFS（可选）。	日志路径通常为 logs/workflow/ 目录下，按实例 ID 存储。

第二章：环境准备与安装部署

2.1 环境依赖要求（JDK、MySQL、ZooKeeper等）

依赖项	版本要求	说明	注意事项
JDK	1.8+（推荐 OpenJDK 或 Oracle JDK）	DolphinScheduler 使用 Java 开发，所有节点均需安装 JDK。	必须配置 JAVA_HOME 环境变量，且版本为 64 位。
MySQL	5.7 或 8.0	作为元数据库存储系统信息，API Server 和 Master 需连接。	需创建独立数据库（如 dolphinscheduler）并授权用户远程访问。
PostgreSQL	9.4+	可替代 MySQL 作为元数据库（社区版支持）。	配置时需修改 application-dao.yml 中的数据库类型和驱动。
ZooKeeper	3.4.6+（推荐 3.5+）	用于 Master/Worker 的注册发现与高可用协调。	建议独立部署集群，避免与 Hadoop 共用导致性能瓶颈。
传输工具	rsync、ssh（免密登录）	用于节点间文件同步和远程命令执行。	所有 Worker 节点需配置与 Master 的 SSH 免密登录。
操作系统	Linux（CentOS、Ubuntu 等）	支持主流 Linux 发行版，不推荐 Windows 部署生产环境。	用户需有 sudo 权限或能切换到目标租户用户。

2.2 单机模式部署步骤

步骤	操作命令/说明	注意事项
1. 下载安装包	wget https://downloads.apache.org/dolphinscheduler/1.3.9/apache-dolphinscheduler-1.3.9-bin.tar.gz	选择稳定版本，建议从 Apache 官网下载。
2. 解压文件	tar -zxvf apache-dolphinscheduler-1.3.9-bin.tar.gz -C /opt/	解压路径避免中文和空格。
3. 创建数据库	CREATE DATABASE dolphinscheduler DEFAULT CHARACTER SET utf8mb4;	推荐使用 utf8mb4 支持 emoji。
4. 修改数据库配置	编辑 conf/application-dao.yml，设置 datasource.url, username, password	确保网络可达，测试连接可用。
5. 初始化数据库	sh script/create-dolphinscheduler.sh	自动执行建表脚本，输出无错误即成功。
6. 修改运行用户	编辑 conf/config/install_config.conf，设置 ips="127.0.0.1" masters="127.0.0.1" workers="127.0.0.1" installPath="/opt/dolphinscheduler" deployUser="ds"	deployUser 必须是系统已存在用户，且有写权限。
7. 执行部署脚本	sh script/deploy.sh	脚本自动复制文件、创建软链接、启动服务。
8. 验证服务	jps 查看是否有 MasterServer、WorkerServer、ApiApplicationServer	若无进程，检查 logs/ 目录下对应日志文件。

2.3 集群模式部署指南

配置项	说明	注意事项
节点规划	Master 节点：2 台（高可用）；Worker 节点：≥2 台（按负载分配）；公共节点：ZooKeeper、MySQL、API Server（可共用）	API Server 可部署在 Master 节点上，也可独立部署。
SSH 免密配置	在部署机上执行：ssh-keygen -t rsa，ssh-copy-id user@master1，ssh-copy-id user@worker1 ...	所有节点之间需互相免密，包括自己到自己。
install_config.conf 配置示例	ips="master1,master2,worker1,worker2"，masters="master1,master2"，workers="worker1:default,worker2:default"，zooQuorum="zk1:2181,zk2:2181,zk3:2181"，dbtype="mysql"，dbname="dolphinscheduler"	workers 后可指定租户分组，default 为默认组。
部署命令	sh script/deploy.sh	脚本会通过 SSH 将文件分发到各节点并启动服务。
高可用验证	停止一台 Master，观察另一台是否接管调度任务	查看 ZooKeeper 中 /dolphinscheduler/masters 节点变化。
资源隔离	通过租户（Tenant）绑定不同系统用户，实现 Worker 上的任务隔离	确保每个租户对应的系统用户在所有 Worker 上存在。

2.4 初始化数据库与配置文件详解

配置文件	关键配置项	说明	注意事项
conf/application-dao.yml	spring.datasource.url、spring.datasource.username、spring.datasource.password	数据库连接信息	生产环境建议使用专用账号，限制权限。
conf/application-master.yml	master.exec.threads=100、master.exec.task.num=20、master.dispatch.task.num=10	Master 线程池与任务调度参数	根据 CPU 核数调整，避免过载。
conf/application-worker.yml	worker.exec.threads=100、worker.max.cpu.load.avg=-1、worker.reserved.memory=0.3	Worker 执行线程与资源限制	reserved.memory 表示保留内存比例（GB），-1 表示不限制。
conf/application-api.yml	server.port=12345、logging.level.org.apache.dolphinscheduler=INFO	API Server 端口与日志级别	可通过 Nginx 代理对外暴露 80/443 端口。
conf/config/install_config.conf	resource.storage.type=NONE、data.basedir.path=/tmp/dolphinscheduler、tenant.auto.create=true	安装时的全局配置	data.basedir.path 是任务工作目录，需保证磁盘空间充足。
conf/worker.properties（旧版本）	worker.group=default、worker.max.cpuload.avg=-1	Worker 分组与负载控制	新版本使用 application-worker.yml 替代。

2.5 启动与验证服务状态

操作	命令	说明	注意事项
启动所有服务	sh bin/start-all.sh	启动 Master、Worker、API Server	仅适用于单机或已部署的集群。
停止所有服务	sh bin/stop-all.sh	安全停止所有进程	建议在维护时使用。
单独启动 Master	sh bin/dolphinscheduler-daemon.sh start master-server	用于故障恢复或调试	查看 logs/master-server/*.log 确认启动成功。
单独启动 Worker	sh bin/dolphinscheduler-daemon.sh start worker-server	—	确保 ZooKeeper 已连接。
单独启动 API Server	sh bin/dolphinscheduler-daemon.sh start api-server	—	启动后可通过 curl http://localhost:12345/dolphinscheduler/doc.html 查看 API 文档。
查看进程	jps	输出应包含：MasterServer、WorkerServer、ApiApplicationServer	若缺失某进程，检查对应日志文件。
查看日志	tail -f logs/master-server/master-server.log	实时观察错误信息	常见错误：数据库连接失败、ZooKeeper 超时、端口占用。
Web UI 登录	浏览器访问 http://<ip>:12345/dolphinscheduler/ui，默认账号：admin / 密码：dolphinscheduler	首次登录建议修改密码	若无法访问，检查防火墙或 Nginx 配置。

第三章：Web UI 快速入门

3.1 登录与初始界面介绍

元素名称	说明	注意事项
登录地址	默认为 http://<api-server-ip>:12345/dolphinscheduler/ui	确保 API Server 正常运行且端口开放
默认账号密码	用户名：admin；密码：dolphinscheduler	首次登录后建议立即修改密码
主界面布局 - 顶部导航栏	包含”项目管理”、“资源中心”、“安全中心”、“监控中心”、“个人中心”等模块入口	不同角色权限显示不同菜单项
主界面布局 - 左侧菜单	在”项目管理”中，可切换不同项目，查看工作流定义与实例	仅当前用户有权限的项目可见
主界面布局 - 中央区域	展示任务 DAG 图、执行日志、调度记录等核心信息	支持缩放、拖拽、节点右键操作
多语言支持	支持中文和英文界面切换（右上角语言选择）	国际化仍在完善中，部分提示仍为英文
退出登录	右上角点击头像 → “退出登录”	推荐操作，避免会话泄露

3.2 用户、项目、租户的基本概念

概念	说明	注意事项
用户（User）	系统登录者，拥有唯一用户名和密码，可分配角色（Admin、普通用户等）	Admin 用户可管理其他用户，普通用户只能操作所属项目
项目（Project）	工作流的容器，用于组织和隔离任务流程。每个项目包含工作流定义、任务实例、UDF 函数等	用户需被授权才能加入项目，权限分为：管理员、项目经理、开发员、运维员、访客
租户（Tenant）	对应操作系统用户，用于 Worker 节点上执行任务的身份隔离。任务在哪个租户下运行，就以该系统用户身份执行	租户必须提前在所有 Worker 节点创建，否则任务无法启动
角色（Role）	控制用户权限，如安全管理、项目创建、告警配置等	自定义角色需谨慎赋权，避免越权操作
资源中心	存储脚本、JAR 包等共享资源的目录，可绑定到项目	资源上传后可在 Shell、Spark 等任务中引用

3.3 创建第一个工作流任务

操作步骤	说明	注意事项
1. 进入项目	点击”项目管理” → 选择或创建一个项目	若无项目，需先由 Admin 或自己创建
2. 创建工作流	点击”工作流定义” → “创建工作流”按钮	弹出 DAG 编辑器界面
3. 添加任务节点	从左侧任务类型栏拖拽”Shell”任务到画布	可重命名节点，如”echo_hello”
4. 编辑任务内容	双击节点 → 在”脚本”框输入：echo "Hello DolphinScheduler"	脚本支持变量，如 ${start_time}
5. 设置租户	在”运行标志”下方选择已有租户（如 tenant_ds）	必须选择，否则提交时报错
6. 连接节点（单节点无需连接）	使用鼠标从一个节点拖线到另一个节点建立依赖	DAG 不允许环路
7. 保存工作流	点击右上角”保存”图标，填写名称（如”first_workflow”）	保存后可在”工作流定义”列表看到

3.4 手动执行与查看日志

操作	说明	注意事项
手动启动工作流	在”工作流定义”列表中，找到目标工作流 → 点击”上线” → “运行”按钮	必须先上线才能运行
查看执行实例	跳转至”工作流实例”页签，查看刚触发的实例状态	状态包括：正在运行、成功、失败、停止等
查看任务日志	点击实例中的具体任务节点 → “查看日志”	日志实时刷新，包含标准输出和错误信息
日志关键字搜索	在日志窗口使用 Ctrl+F 搜索关键词（如”error”）	建议开启”自动滚动”跟踪最新输出
终止任务	右键任务节点 → “停止”	仅对正在运行的任务有效，底层调用 kill -9
查看重试情况	若配置了失败重试，可在日志中看到多次尝试记录	重试间隔默认 1 分钟
下载日志文件	点击”下载日志”按钮，保存本地分析	日志路径通常为 /tmp/dolphinscheduler/logs/

3.5 常见操作快捷方式

操作	快捷方式 / 技巧	说明	注意事项
刷新页面数据	F5 或 Ctrl+R	适用于实例状态未更新时手动刷新	避免频繁刷新影响性能
全屏 DAG 图	点击 DAG 编辑器右上角”全屏”图标	更清晰查看复杂流程	ESC 键退出全屏
节点复制粘贴	选中节点 → Ctrl+C → Ctrl+V	提高重复结构构建效率	粘贴后需重新配置脚本和参数
批量删除节点	Shift+拖拽框选多个节点 → Delete 键	快速清理无效节点	删除不可撤销，请确认
快速查找节点	在 DAG 图上方搜索框输入节点名称	适用于大型工作流	支持模糊匹配
查看上下游依赖	右键节点 → “查看上游” / “查看下游”	分析任务影响范围	便于调试依赖逻辑
导出/导入工作流	”更多操作” → “导出” JSON 文件	实现跨环境迁移或备份	导入时注意数据源和资源路径一致性

第四章：任务类型详解

4.1 Shell 任务

参数名称	语法	用途	示例	注意事项
脚本内容	直接输入 Shell 命令或脚本片段	执行 Linux 命令或调用本地脚本	#!/bin/bash、date、echo "Running as ${USER}"	使用 #!/bin/bash 明确解释器；支持变量注入
运行标志	NORMAL / FORBIDDEN / DISABLED	控制任务是否参与调度	NORMAL（正常执行）	FORBIDDEN 表示跳过，但仍计入 DAG
失败策略	继续 / 结束流程	定义任务失败后是否中断整个工作流	建议关键任务设为”结束流程"	"继续”可用于非关键通知类任务
超时设置	数值 + 单位（分/小时）	防止任务无限挂起	超时时间：30 分钟	超时后自动 kill 进程并标记失败
自定义参数	KEY=VALUE 形式添加	注入环境变量或脚本参数	key: input_path, value: /data/input/${yyyyMMdd}	可在脚本中通过 ${input_path} 引用

4.2 SQL 任务（支持多数据源）

参数名称	语法	用途	示例	注意事项
数据源类型	MySQL / PostgreSQL / Oracle / SQLServer / Hive / Spark 等	选择目标数据库类型	选择：MySQL	需提前在”数据源中心”配置连接信息
数据源	下拉选择已注册的数据源	指定连接实例	datasource_mysql_01	测试连通性确保可用
SQL 脚本	输入标准 SQL 语句	执行查询或更新操作	SELECT count(*) FROM logs WHERE dt='${dt}'	支持多条语句，分号分隔
查询结果处理	不处理 / 写入表 / 发送告警	定义 SELECT 结果的后续动作	发送告警：将结果通过邮件通知	仅 SELECT 语句产生结果
分页记录数	整数（如 100）	控制返回结果行数	100	避免大数据量阻塞
自定义参数	KEY=VALUE	传递动态值	dt=$[yyyy-MM-dd]	支持日期函数解析
PreparedStatement	开启/关闭	是否预编译 SQL	开启可防止注入	UPDATE/DELETE 推荐开启

4.3 Spark 任务

参数名称	语法	用途	示例	注意事项
主程序包	选择已上传的 JAR 文件（资源中心）	指定 Spark 应用主 Jar 包	spark-etl-1.0.jar	必须先上传至资源中心
主类名	com.example.MainClass	指定 main 方法所在类	com.etl.DataProcessor	类路径必须正确
部署模式	local / client / cluster	Spark 运行模式	cluster（生产推荐）	cluster 模式 Driver 在集群运行
Spark 版本	1.x / 2.x / 3.x	匹配集群实际版本	3.1.2	版本不一致可能导致兼容问题
命令行参数	--input hdfs://... --output /out	传递给 main 方法的 args	--mode=prod --batchId=123	多参数空格分隔
Driver/Core 资源	driver-memory, executor-cores 等	设置资源配额	--driver-memory 2g --num-executors 4	根据集群资源合理配置
自定义参数	spark.conf.key=value	添加 SparkConf 配置	spark.sql.adaptive.enabled=true	高级调优选项

4.4 Flink 任务

参数名称	语法	用途	示例	注意事项
Flink 脚本类型	Java/Scala/PYTHON	选择程序语言	JAVA	PYTHON 需启用 PyFlink
程序包	上传或选择已有的 JAR/Python 文件	指定作业代码	flink-job-1.0.jar	支持远程 HDFS 路径
主类名	org.apache.flink.WordCount	Java/Scala 程序入口类	com.streaming.RealTimeJob	必须是 public class
部署模式	local / remote / yarn-per-job / yarn-session	运行模式	yarn-per-job（推荐）	生产环境避免 local 模式
Flink 配置参数	parallelism, checkpointInterval 等	调优参数	-p 4 --checkpointing 60000	参考 Flink CLI 参数格式
JobManager 地址	host:port	remote 模式需指定	jobmanager-host:8081	仅 remote 模式需要
YARN 队列	default / prod_queue	指定资源队列	prod_queue	需 YARN 集群支持队列划分

4.5 Python 任务

参数名称	语法	用途	示例	注意事项
Python 脚本	直接编写或引用外部 .py 文件	执行 Python 逻辑	print("Hello")、import pandas as pd	确保 Worker 节点安装所需库
脚本类型	内联脚本 / 脚本文件	选择输入方式	内联脚本适合简单逻辑	文件方式便于复用
Python 命令路径	python / python3 / /usr/bin/python3.8	指定解释器路径	/opt/venv/bin/python	若使用虚拟环境需写完整路径
依赖包管理	手动安装或打包 venv	确保第三方库可用	pip install pandas	建议将依赖打包进 zip 并上传
命令行参数	--arg1 val1 --arg2 val2	传参给脚本	sys.argv 获取参数	使用 argparse 解析更规范
自定义参数	KEY=VALUE	注入环境变量	env: ENV=prod	脚本中通过 os.getenv('ENV') 读取

4.6 HTTP 任务

参数名称	语法	用途	示例	注意事项
请求方法	GET / POST / PUT / DELETE	指定 HTTP 动作	POST	根据接口文档选择
URL	https://api.example.com/v1/data	目标接口地址	https://hooks.slack.com/services/...	支持变量替换，如 ${token}
请求头	Content-Type: application/json	添加 Header	Authorization: Bearer ${access_token}	多个头换行输入
请求体	JSON 或 Form-data	POST/PUT 数据内容	{"name": "test"}	JSON 需合法格式
超时时间	毫秒数（如 5000）	设置连接与读取超时	3000 ms	防止长时间阻塞
成功状态码	200 / 2xx / 自定义	判断请求是否成功	200,201	多个码逗号分隔
认证方式	NONE / BASIC / BEARER	身份验证机制	BEARER token=abc123	安全敏感信息建议用参数传递

4.7 Sub-Process 任务

参数名称	语法	用途	示例	注意事项
子工作流	从下拉框选择已有工作流定义	调用另一个完整工作流	workflow_data_import	子流程独立调度与记录
等待子流程	是 / 否	是否阻塞等待完成	是（常用）	“否”表示异步触发
传递参数	KEY=VALUE	向子流程传递上下文	parent_id=${processId}	子流程需定义对应全局参数
失败策略	继续 / 结束流程	子流程失败后的处理	关键流程建议”结束流程”	可实现异常传播
超时控制	数值 + 单位	防止子流程长期不结束	2 小时	超时后自动终止子实例

4.8 Condition 分支任务

条件表达式	语法	用途	示例	注意事项
SUCCESS	node_name == 'SUCCESS'	判断前驱任务是否成功	A == 'SUCCESS'	支持节点别名
FAILURE	node_name == 'FAILURE'	判断是否失败	B == 'FAILURE'	可触发告警分支
ALL_FAILURE	ALL_STATUS == 'FAILURE'	所有上游都失败才走此分支	ALL_STATUS == 'FAILURE'	用于兜底处理
ELSE	ELSE	默认分支，当前面都不满足时执行	ELSE	必须放在最后
多条件组合	&& / ||	逻辑与或	(A=='SUCCESS') || (B=='SUCCESS')	括号控制优先级
输出分支	Left / Right / Else	分支连接不同下游任务	Left → 发送成功通知；Right → 发送失败告警	DAG 必须显式连线

4.9 Depend 依赖任务

参数名称	语法	用途	示例	注意事项
依赖工作流	选择项目内的其他工作流	定义跨工作流依赖	project_etl_daily	必须在同一项目
依赖周期	TODAY / YESTERDAY / LAST_1_DAYS 等	时间维度匹配	YESTERDAY	用于按天补数场景
依赖状态	SUCCESS / ANY	要求的状态	SUCCESS	建议关键依赖设为 SUCCESS
自定义表达式	${dag.offset(1)}==SUCCESS	高级依赖判断	${dag.offset(-1)}==SUCCESS	offset(-1) 表示前一天实例
检查间隔	1m / 5m / 10m	轮询频率	5 分钟	频繁检查增加 DB 压力
超时时间	最长等待时间	防止无限等待	2 小时	超时后可配置失败策略

4.10 Stored Procedure 存储过程任务

参数名称	语法	用途	示例	注意事项
数据源	选择支持存储过程的数据库	如 MySQL、Oracle	ds_oracle_proc	必须支持 CALL 语法
存储过程名	procedure_name(?, ?)	调用带参过程	calc_monthly_report(?, ?)	? 为占位符
参数类型	IN / OUT / INOUT	定义参数方向	IN: date_str, OUT: result_code	多数为 IN 类型
参数值	具体值或变量	传入实际参数	$[yyyy-MM-dd], 100	支持表达式解析
调用语法	{call proc_name(?,?)}	标准 JDBC 调用格式	{call backup_data(?,?)}	必须符合 JDBC 规范
返回处理	忽略 / 写日志 / 告警	如何处理 OUT 参数	写日志：result_code=${result_code}	OUT 参数可在后续任务引用

4.11 MR（MapReduce）任务

参数名称	语法	用途	示例	注意事项
主类名	com.hadoop.WordCount	MapReduce 程序入口	com.etl.UserBehaviorMR	必须打包进 Jar
程序包	上传 Hadoop Jar 包	包含 Mapper/Reducer 类	etl-job-2.0.jar	支持 HDFS 路径
Hadoop 配置	core-site.xml, hdfs-site.xml	指定集群配置文件	自动加载 $HADOOP_CONF_DIR	确保 Worker 节点配置正确
命令行参数	/input /output	传递给 ToolRunner 的 args	/raw/logs/$[yyyyMMdd] /dw/fact/user	路径需存在且可读写
队列名称	default / etl_queue	YARN 队列分配	etl_queue	需集群支持资源队列
任务优先级	LOW / NORMAL / HIGH	调度优先级	NORMAL	HIGH 可能抢占资源
故障重试	1~4 次	任务失败自动重试次数	2 次	Hadoop 本身也有重试机制，避免叠加过多

4.12 DataX 数据同步任务

参数名称	语法	用途	示例	注意事项
DataX JSON 模板	标准 DataX 作业配置	定义读写插件与字段映射	{ "job": { "content": [...] } }	必须符合 DataX Schema
reader.name	mysqlreader / hdfsfiler	源端读取插件	mysqlreader	插件名必须正确
writer.name	mysqlwriter / hdfswriter	目标写入插件	hdfswriter	注意目标格式（text/orc）
数据源配置	jdbcUrl, username, password	数据库连接信息	jdbc:mysql://host:3306/db	建议使用数据源管理功能
字段映射	column: ["id", "name"]	指定同步字段	支持常量和表达式	如 {value: "fixed", type: "string"}
通道数	channel: 3	并发读写线程数	channel: 5	根据源库负载调整
脏数据限制	record: 100, percentage: 0.05	容忍错误记录数	record: 10, percentage: 0.1	超过则任务失败
Pre/Post SQL	执行前置或后置 SQL	清理或统计	preSql: ["truncate table tmp"]	可用于事务控制

第五章：工作流设计与调度机制

5.1 DAG 有向无环图原理

概念名称	说明	注意事项
DAG（Directed Acyclic Graph）	有向无环图，DolphinScheduler 的核心任务编排模型，用节点表示任务，边表示依赖关系	不允许存在循环依赖（如 A→B→C→A），否则无法调度
节点（Node）	代表一个具体任务，如 Shell、SQL、Spark 等类型	每个节点有唯一名称和运行配置
边（Edge）	表示任务之间的执行顺序依赖，前驱任务成功后，后继任务才能启动	依赖关系是”成功才执行”，失败默认中断流程（可配置）
入度与出度	入度：指向该节点的边数；出度：从该节点出发的边数	入度为 0 的节点为起始节点，出度为 0 的为终止节点
拓扑排序	系统根据 DAG 自动计算任务执行顺序，确保依赖满足	排序结果决定任务分发时机
并行分支	多个任务无依赖关系时可并行执行，提升效率	受 Worker 资源和任务队列限制
子 DAG	通过 Sub-Process 任务实现嵌套流程，提高复用性	子流程独立调度、记录日志

5.2 节点间的依赖关系设置

依赖类型	配置方式	用途	示例	注意事项
顺序依赖	鼠标从任务 A 拖线到任务 B	B 在 A 成功后执行	A → B → C	最常见模式
多前驱依赖	多个任务连接到同一任务	所有前驱必须成功，后继才执行	A→C, B→C，则 C 等 A 和 B 都成功	用于合并分支
条件分支	使用 Condition 任务判断状态	根据前驱结果走不同路径	A 成功 → 发邮件；A 失败 → 发告警	需配合 Condition 节点
手动依赖	不连线，通过 Depend 任务跨工作流依赖	实现项目间或周期性依赖	工作流 B 依赖工作流 A 昨天的成功实例	用于跨日调度场景
广播依赖	一个任务成功触发多个下游	一对多通知或分发	A → B, A → C, A → D	可并行执行 B/C/D
可选依赖	设置”失败继续”策略	前驱失败不影响后继执行	B 不依赖 A 的状态	用于非关键任务

5.3 全局参数与局部参数

参数类型	配置位置	语法	用途	示例	注意事项
全局参数	工作流定义页面 → “全局参数”按钮	${param_name}	整个工作流共享的变量	${bizdate}, ${region}	在任务中通过 ${} 引用
局部参数	单个任务节点 → “自定义参数”	${param_name}	仅当前任务使用的变量	${inputpath}, ${thread_num}	优先级高于全局参数
参数类型 - VALUE	手动输入固定值	类型选择 VALUE	静态配置	VALUE: prod	不支持函数解析
参数类型 - DATE	使用日期函数动态生成	类型选择 DATE	动态时间戳	DATE: $[yyyy-MM-dd]	支持偏移，如 $[yyyyMMdd-1] 表示昨天
内置参数	系统自动提供	${startTime}${endTime} 等	获取运行上下文	${scheduleTime}	常用于日志标记
参数传递	子流程通过 Sub-Process 任务传参	KEY=VALUE 形式	上下文传递	parent_id=${processId}	子流程需预先定义同名参数
参数优先级	局部 > 全局 > 内置	相同名称时覆盖规则	若局部和全局都有 ${env}，取局部值	建议命名区分作用域

5.4 工作流定时调度配置（Cron 表达式）

配置项	说明	示例	注意事项
Cron 表达式格式	秒 分 时 日 月 周 年（年可选）	0 0 2 * * ?	DolphinScheduler 使用 Quartz 格式
秒字段	0-59	0/30 表示每30秒一次	通常设为 0
分字段	0-59	0/15 表示每15分钟	支持范围（10-20）和通配符（*）
时字段	0-23	2 表示凌晨2点	2 表示 02:00
日字段	1-31	? 表示不指定（与周互斥）	避免与周同时指定具体值
月字段	1-12 或 JAN-DEC	* 表示每月	JAN 表示1月
周字段	1-7 或 SUN-SAT	? 表示不指定（与日互斥）	1=SUN, 2=MON…7=SAT
年字段	可选，如 2025	* 表示每年	通常省略
常见表达式	每日凌晨2点	0 0 2 * * ?	推荐用于 ETL 任务
常见表达式	每小时整点	0 0 * * * ?	适用于实时性要求高的任务
常见表达式	工作日9点	0 0 9 ? * MON-FRI	MON-FRI 表示周一至周五
验证工具	Web UI 提供”下一次触发时间”预览	输入后自动计算	避免错误调度
时区问题	默认使用服务器时区（建议 UTC+8）	避免跨时区混乱	生产环境统一设置时区

5.5 手动触发与补数操作

操作类型	配置方式	用途	示例	注意事项
手动运行	”工作流定义” → 选择工作流 → “上线” → “运行”	临时触发一次执行	调试或紧急处理	必须先上线才能运行
补数（Backfill）	“补数”按钮 → 选择日期范围	重新执行历史时间段的任务	补 2025-09-01 至 2025-09-10 的数据	用于修复数据或修复失败任务
补数模式	串行 / 并行	控制补数实例的执行方式	并行：最多同时运行 N 个	并行可能压垮数据库
补数参数覆盖	可修改全局参数值	覆盖原始调度参数	将 ${env} 从 prod 改为 test	用于测试修复逻辑
强制运行	忽略依赖直接启动	跳过前驱任务	仅用于调试	生产慎用
查看补数实例	”工作流实例”中筛选”补数”类型	监控补数进度	支持暂停、停止	补数实例独立记录
补数并发控制	在”补数设置”中限制并发数	防止资源过载	最大并发：3	根据集群负载调整

5.6 并行执行与串行执行控制

控制方式	配置方法	说明	示例	注意事项
DAG 结构控制	多任务无依赖则并行	系统自动并行调度	A → C, B → C，则 A 和 B 并行	受 Worker 资源限制
任务组（Task Group）	设置任务组名称和并发数	限制同类任务并发	组名：etl_group，并发：2	需提前在系统配置启用
并行分支	多个下游任务同时启动	提升吞吐	A → B, A → C, A → D	B/C/D 并行执行
串行化依赖	显式添加顺序依赖	强制按序执行	A → B → C	用于资源竞争场景
Worker 资源限制	worker.exec.threads 配置	控制单 Worker 最大并发	默认 100	根据 CPU 核数调整
Master 分发策略	master.dispatch.task.num	控制任务分发频率	避免瞬时高峰	通常保持默认
失败重试间隔	重试间隔时间（分钟）	避免密集重试	间隔：5 分钟	可防止雪崩
手动暂停/恢复	在”任务实例”中暂停队列	临时控制执行节奏	运维窗口期暂停	恢复后继续调度

第六章：系统管理与安全

6.1 用户与角色权限管理

概念	说明	注意事项
用户（User）	系统登录实体，有用户名、密码、邮箱、手机号	支持 LDAP/AD 集成（需配置）
角色（Role）	权限集合，分为系统角色和项目角色	系统角色：Admin、普通用户等；项目角色：管理员、开发员、运维员、访客
系统角色 - Admin	拥有所有权限，可管理用户、租户、告警、项目等	仅分配给运维人员
系统角色 - 普通用户	可创建项目、上传资源、定义工作流	默认权限较低，需授权访问项目
项目角色 - 管理员	可管理项目内所有资源和成员	可添加/删除成员
项目角色 - 开发员	可创建、编辑工作流定义	不能上线或运行
项目角色 - 运维员	可上线、运行、补数、查看日志	不能修改工作流定义
项目角色 - 访客	只读权限，仅能查看	适用于审计或监控人员
权限分配	用户 → 角色 → 项目	一个用户可在多个项目有不同角色
用户锁定	连续失败登录多次后自动锁定	默认 5 次

6.2 租户管理与资源隔离

配置项	说明	示例	注意事项
租户名称	唯一标识符，对应系统用户	tenant_ds	建议命名清晰
系统用户	操作系统级用户名	ds_user	必须在所有 Worker 节点存在
创建租户	安全中心 → 租户管理 → 创建	输入租户名和系统用户	系统自动创建用户（若未启用自动创建需手动添加）
自动创建用户	tenant.auto.create=true	自动调用 useradd 创建系统用户	需部署机有 sudo 权限
资源隔离	不同租户任务以不同系统用户运行	ds_user1 和 ds_user2 互不影响	防止越权访问文件
文件权限	任务日志、临时文件按租户隔离	/tmp/dolphinscheduler/tenant_ds/	确保目录可写
资源组（Worker Group）	租户可绑定到特定 Worker 组	default / high_priority	实现物理资源隔离
删除租户	必须先解除所有任务关联	否则无法删除	建议归档后删除

6.3 数据源管理（MySQL、PostgreSQL、Hive 等）

数据源类型	配置参数	示例	注意事项
MySQL	主机、端口、数据库名、用户名、密码、JDBC URL	jdbc:mysql://192.168.1.10:3306/dw	建议使用专用账号，限制 IP
PostgreSQL	同上，驱动不同	jdbc:postgresql://host:5432/db	支持 SSL 连接
Oracle	SID 或 Service Name	jdbc:oracle:thin:@host:1521:ORCL	注意驱动版本兼容性
SQL Server	使用 jtds 或 mssql-jdbc	jdbc:sqlserver://host:1433;DatabaseName=test	需开启 TCP/IP
Hive	支持 HiveServer2	jdbc:hive2://host:10000/default	需 Kerberos 认证（如启用）
Spark	Thrift Server 连接	jdbc:hive2://host:10001/default	实际走 Hive 协议
测试连接	点击”测试连接”按钮	验证网络和凭证	必须成功才能保存
数据源共享	可设置为”公共”或”私有”	公共：所有项目可用	私有仅创建者所在项目可用
密码加密	存储时自动加密	AES 或 SM3 算法	不以明文存储

6.4 告警组与通知渠道配置（Email、SMS、DingTalk、WeChat）

通知类型	配置参数	示例	注意事项
Email	SMTP 服务器、端口、发件人、用户名、密码	smtp.gmail.com:587	需开启 SMTP 服务
短信（SMS）	第三方平台 API 密钥	阿里云 SMS、腾讯云 SMS	需申请模板和签名
钉钉（DingTalk）	Webhook URL + 自定义关键词	https://oapi.dingtalk.com/robot/send?access_token=xxx	必须设置”加签”或关键词
企业微信（WeChat Work）	应用 Webhook	https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxx	支持 Markdown
飞书（Lark）	飞书群机器人 Webhook	https://open.feishu.cn/open-apis/bot/v2/hook/xxx	支持富文本
告警组	包含多个通知方式的集合	group_prod_alert	可绑定到工作流或任务
告警模板	自定义消息内容	任务失败：${taskName} at ${time}	支持变量注入
失败告警触发	在任务或工作流中启用”失败告警”	勾选”失败时通知”	可指定告警组
告警去重	避免短时间内重复发送	配置冷却时间（如 30 分钟）	防止告警风暴

6.5 安全配置（HTTPS、访问控制、Token 管理）

配置项	配置方式	说明	注意事项
HTTPS 启用	配置 Nginx 或 Tomcat SSL	前端反向代理启用 HTTPS	推荐生产环境使用
访问控制（IP 白名单）	通过 Nginx 或防火墙限制	allow 192.168.1.0/24	限制 API 和 Web 访问来源
Token 认证	用于 API 调用身份验证	请求头添加 X-Access-Token: xxx	Token 在”安全中心”生成
Token 过期时间	默认 30 天	可配置 token.expire.time	建议定期轮换
用户密码策略	最小长度、复杂度、过期时间	默认无强制策略	可通过 LDAP 统一管理
操作审计日志	记录用户关键操作（如删除工作流）	日志位于 logs/api-server/	用于安全审计
敏感信息加密	数据库密码、API Key 等	使用 AES 加密存储	密钥管理需安全
CSRF 防护	启用 anti-forgery token	默认开启	防止跨站请求伪造

第七章：高可用与监控运维

7.1 Master/Worker 高可用机制

组件	实现机制	配置要点	注意事项
Master 高可用	基于 ZooKeeper 选举主节点，多个 Master 实例中仅一个 Active，其余 Standby	在 conf/master.properties 中配置 zk.quorum=zk1:2181,zk2:2181,zk3:2181	所有 Master 节点需能连接 ZooKeeper 集群
Worker 高可用	无主从之分，所有 Worker 注册到 ZooKeeper，Master 随机或按负载分发任务	在 conf/worker.properties 中设置 worker.group=default	故障 Worker 自动下线，任务由其他 Worker 接管
故障转移（Failover）	Master 宕机后，ZooKeeper 触发重新选举，新 Master 恢复调度	确保 master.server.max.idle.time 设置合理（默认 30s）	网络抖动可能导致误判，建议调大超时时间
任务容错	任务失败可配置重试次数，或由其他 Worker 重新执行	在任务节点设置”失败重试”策略	重试间隔避免过短导致雪崩
多租户隔离	不同租户任务在不同系统用户下运行，防止资源争抢	租户绑定操作系统用户	确保 Worker 节点上用户存在且权限正确
心跳检测	Master/Worker 每隔一定时间向 ZooKeeper 发送心跳	heartbeat.interval 默认 5s	网络延迟过高可能导致假死

7.2 ZooKeeper 在集群中的作用

功能	说明	配置文件	注意事项
Master 选举	利用 ZNode 临时节点和 Watcher 机制实现主节点选举	conf/master.properties，zk.quorum=...	建议部署奇数个节点（3/5/7）
Worker 注册发现	Worker 启动时在 /workers 路径创建临时节点	conf/worker.properties	Master 通过监听该路径感知 Worker 状态
分布式锁	协调多个 Master 对任务调度的并发访问	内部机制，无需手动配置	避免长时间持有锁
配置管理	可集中存储部分动态配置（如队列状态）	非主要用途，DolphinScheduler 主要用 DB 存储配置	建议仍以数据库为准
状态协调	记录任务实例状态变更，确保一致性	用于 Master 故障恢复时重建上下文	日志与 ZK 状态应一致
会话超时	sessionTimeout 参数控制连接有效性	zookeeper.session.timeout=60000（单位 ms）	设置过短易误判宕机，过长恢复慢
监控命令	echo stat | nc zk_host 2181	命令行工具	用于排查连接问题

7.3 日志路径与日志分析技巧

日志类型	默认路径	内容说明	分析技巧	注意事项
Master 日志	logs/master-server/master-server.log	调度决策、任务分发、ZK 连接状态	搜索关键词：Scheduling, Dispatch, Failed	关注调度延迟和分发失败
Worker 日志	logs/worker-server/worker-server.log	任务拉取、执行启动、资源分配	搜索：Executing task, Process start failed	检查脚本路径、权限、环境变量
API Server 日志	logs/api-server/api-server.log	用户请求、认证、REST 接口调用	搜索：HTTP 500, Unauthorized, SQLException	排查登录失败或接口错误
任务实例日志	logs/task/{taskInstanceId}.log	具体任务的标准输出和错误输出	搜索：ERROR, Exception, exit code	Shell 任务非 0 退出码即失败
前端日志	浏览器 F12 Console	Web UI 交互错误、JS 异常	查看网络请求是否 404/500	常见于跨域或 Token 过期
日志轮转	按天分割，保留 30 天	使用 logback 配置	可通过 logback-spring.xml 修改策略	避免磁盘写满
日志级别调整	INFO / DEBUG / WARN	修改 application-*.yml 中 logging.level	DEBUG 级别日志量大，仅调试时开启

7.4 系统监控指标（CPU、内存、队列积压等）

指标类别	监控项	正常范围	异常表现	建议监控方式
CPU 使用率	Master/Worker 进程 CPU 占用	< 70%	持续 > 90% 可能导致调度延迟	Prometheus + Grafana
内存使用	JVM Heap 使用（Xmx）	< 80%	OOM 或频繁 GC	jstat -gc pid，或 JMX 导出
线程池积压	Master 待处理任务队列长度	< 100	队列持续增长表示消费不及	查看 master.dispatch.task.num 相关日志
ZooKeeper 连接	ZK 会话数、延迟	延迟 < 100ms	超时或断连影响 HA	echo stat | nc zk 2181
数据库连接	MySQL 活跃连接数	< 最大连接数 80%	连接耗尽导致 API 失败	show processlist;
任务执行延迟	从调度时间到实际启动的时间差	< 5s	显著延迟可能 Worker 资源不足	查看任务实例”开始时间”与”计划时间”
磁盘空间	日志目录所在分区	> 20% 剩余	写入失败导致任务异常	df -h 定期检查
网络带宽	节点间数据传输	无持续打满	影响大文件同步或日志上传	sar -n DEV 1 3

7.5 故障排查常见问题清单

问题现象	可能原因	排查步骤	解决方案
Master 无法启动	数据库连接失败、端口占用、ZK 不可达	1. 查看 master-server.log 2. telnet 检查 DB/ZK 连通性 3. netstat 检查 5678 端口	修复网络、修改配置、释放端口
Worker 未注册	SSH 免密失败、租户用户不存在、ZK 问题	1. 查看 worker-server.log 2. 手动 su - tenant_user 测试 3. 检查 sshd 服务	配置免密、创建系统用户、重启 sshd
任务卡在”正在运行”	脚本死循环、超时设置过大、进程未上报状态	1. 查看任务日志是否有输出 2. ps 查找对应进程 3. kill 后观察是否恢复	设置合理超时、优化脚本逻辑
工作流不触发	Cron 表达式错误、未上线、补数冲突	1. 检查”下一次执行时间”预览 2. 确认工作流状态为”上线” 3. 查看 master 调度日志	修正 Cron、上线工作流
SQL 任务连接失败	数据源配置错误、网络不通、驱动缺失	1. 在”数据源中心”测试连接 2. telnet host port 3. 检查 lib 目录是否有驱动 jar	修正 IP/端口、添加 jdbc 驱动
日志无法查看	Logger Server 未启动、路径权限不足	1. 查看 logger-server.log 2. 检查 logs/task/ 目录权限	启动 logger 服务、chmod 755
Web UI 加载慢	网络延迟、API 响应慢、浏览器缓存	1. F12 查看 Network 请求耗时 2. 检查 api-server.log 是否有慢查询	优化网络、升级硬件、清理缓存

第八章：API 接口编程与集成

8.1 REST API 基础认证方式（Token）

参数	说明	示例	注意事项
认证方式	Bearer Token	请求头：X-Access-Token: abcdefghijklmnopqrstuvwx	Token 在”安全中心”生成
获取 Token	通过用户密码调用登录接口获取	POST /login，{"userName": "admin", "userPassword": "dolphinscheduler"}	返回 JSON 包含 token 字段
Token 有效期	默认 30 天	可配置 token.expire.time=2592000（秒）	过期需重新登录获取
使用方式	所有 API 请求必须携带 Token	curl -H "X-Access-Token: abc..." http://api:12345/projects	否则返回 401 Unauthorized
权限控制	Token 绑定用户角色，决定可访问资源	admin 的 token 权限最高	避免泄露
多租户支持	Token 自动关联用户所属租户	无需额外传参	任务提交自动使用用户默认租户
安全建议	HTTPS 传输、定期轮换、最小权限原则	生产环境禁用明文 HTTP	可结合 LDAP 统一认证

8.2 项目管理相关 API

API 接口	请求方式	参数	用途	示例
创建项目	POST /projects	projectName, description	新建一个项目容器	POST /projects?projectName=my_project&description=ETL
查询项目列表	GET /projects	pageSize, pageNo	获取用户有权限的项目	GET /projects?pageSize=10&pageNo=1
删除项目	DELETE /projects/{projectId}	projectId	删除指定项目（需管理员权限）	DELETE /projects/5
项目详情	GET /projects/{projectId}	projectId	查看项目基本信息	GET /projects/5
添加项目成员	POST /project-users	projectId, userId, perm	将用户加入项目并赋权	POST /project-users?projectId=5&userId=10&perm=3
移除成员	DELETE /project-users/{relationId}	relationId	解除用户与项目的关联	DELETE /project-users/20

8.3 工作流定义操作 API

API 接口	请求方式	参数	用途	示例
创建工作流	POST /projects/{projectId}/workflow-definition	name, json (DAG 结构)	提交一个新的 DAG 定义	POST /projects/5/workflow-definition?name=test_wf&json={...}
上线工作流	PUT /projects/{projectId}/wf-instance/publish	workflowDefinitionCode, state=publish	将工作流设为可调度状态	PUT /projects/5/wf-instance/publish?workflowDefinitionCode=100&state=publish
下线工作流	PUT ... state=unpublish	同上	停止调度，禁止手动运行	state=unpublish
查询工作流列表	GET /projects/{pid}/workflow-definition	searchVal, pageSize, pageNo	模糊查找工作流	GET /projects/5/workflow-definition?searchVal=etl
获取工作流详情	GET /projects/{pid}/workflow-definition/{code}	code	查看 DAG 结构和参数	GET /projects/5/workflow-definition/100
导出工作流	GET /projects/{pid}/export-workflow-def	workflowDefinitionCode	下载 JSON 文件备份	GET /projects/5/export-workflow-def?workflowDefinitionCode=100
导入工作流	POST /projects/{pid}/import-workflow-def	file (JSON)	从文件恢复工作流	POST /projects/5/import-workflow-def

8.4 工作流实例控制 API

API 接口	请求方式	参数	用途	示例
手动启动工作流	POST /projects/{pid}/executors/start	workflowDefinitionCode	触发一次执行	POST /projects/5/executors/start?workflowDefinitionCode=100
停止工作流实例	POST /projects/{pid}/executors/stop	workflowInstanceId	终止正在运行的实例	POST /projects/5/executors/stop?workflowInstanceId=200
补数操作	POST /projects/{pid}/batch-execution	mode=backfill, start, end, codes	批量重跑历史实例	mode=backfill&start=20250901&end=20250910&codes=100
查询实例列表	GET /projects/{pid}/executors/query	startDate, endDate, state	按条件筛选实例	GET /projects/5/executors/query?state=SUCCESS&startDate=2025-09-01
实例详情	GET /projects/{pid}/executors/{instanceId}	instanceId	查看 DAG 执行状态和耗时	GET /projects/5/executors/300
查看实例日志	GET /projects/{pid}/executors/log	taskInstanceId, skipLineNum, limit	分页获取任务日志	GET /projects/5/executors/log?taskInstanceId=400&skipLineNum=0&limit=1000

8.5 任务实例查询 API

API 接口	请求方式	参数	用途	示例
查询任务实例	GET /projects/{pid}/task-instances	workflowInstanceId, taskName, state	查找特定任务实例	GET /projects/5/task-instances?workflowInstanceId=300&state=RUNNING
任务实例详情	GET /tasks/{taskInstanceId}	taskInstanceId	获取任务配置和执行信息	GET /tasks/400
重跑任务	POST /projects/{pid}/task-instances/{id}/repeat	id, executeType	重新执行失败任务	POST /projects/5/task-instances/400/repeat?executeType=REPEAT_RUNNING
停止单个任务	POST /projects/{pid}/task-instances/{id}/stop	id	终止正在运行的任务	POST /projects/5/task-instances/400/stop
替代运行	POST .../replace-by-node	id, node	用指定节点替代当前任务继续	调试图形分支时使用

8.6 数据源操作 API

API 接口	请求方式	参数	用途	示例
创建数据源	POST /datasource/create	name, type, connectionParams(json)	添加新的数据库连接	POST /datasource/create?name=mysql_prod&type=MYSQL&connectionParams={"host":"h","port":3306,"database":"db"}
查询数据源列表	GET /datasource/list	type, searchVal, pageNo, pageSize	获取可用数据源	GET /datasource/list?type=MYSQL&pageNo=1&pageSize=10
测试连接	POST /datasource/connect	type, connectionParams	验证连接可用性	用于前端”测试连接”功能
更新数据源	PUT /datasource/update	id, name, connectionParams	修改已有数据源配置	PUT /datasource/update?id=10&name=new_name
删除数据源	DELETE /datasource/delete	id	移除数据源（需无任务引用）	DELETE /datasource/delete?id=10
获取数据源详情	GET /datasource/{id}	id	查看具体配置信息	GET /datasource/10

8.7 用户与权限管理 API

API 接口	请求方式	参数	用途	示例
创建用户	POST /users	userName, userPassword, email, phone	新增系统用户	POST /users?userName=john&userPassword=123&email=john@company.com
查询用户列表	GET /users	searchVal, pageNo, pageSize	查找用户	GET /users?searchVal=admin&pageNo=1
更新用户信息	PUT /users/{userId}	email, phone, state	修改邮箱、手机号、启用/禁用	PUT /users/5?email=new@com.com&state=1
重置密码	PUT /users/{userId}/password	oldPassword, newPassword	用户自行修改密码	需提供旧密码验证
获取当前用户	GET /users/get-user-info	（无）	获取 Token 对应的用户信息	GET /users/get-user-info
分配角色	POST /user/role/save	userId, roleId	将角色赋予用户	POST /user/role/save?userId=5&roleId=2

8.8 告警组与通知 API

API 接口	请求方式	参数	用途	示例
创建告警组	POST /alert-group/create	groupName, alertInstanceIds	定义通知接收组	POST /alert-group/create?groupName=prod_alert&alertInstanceIds=1,2,3
查询告警组	GET /alert-group/list	pageNo, pageSize	获取所有告警组	GET /alert-group/list?pageNo=1&pageSize=10
更新告警组	PUT /alert-group/update	id, groupName, alertInstanceIds	修改组内通知方式	PUT /alert-group/update?id=5&groupName=new_grp
删除告警组	DELETE /alert-group/delete	id	移除告警组	DELETE /alert-group/delete?id=5
创建告警实例	POST /alert-plugin-instance/create	pluginType, instanceParams(json)	添加钉钉、邮件等通知渠道	pluginType=EMAIL&instanceParams={"smtpHost":"smtp.ex.com"}
查询告警实例	GET /alert-plugin-instance/list	pluginType	获取已配置的通知方式	GET /alert-plugin-instance/list?pluginType=DINGTALK

第九章：高级特性与最佳实践

9.1 参数传递与运行时变量解析

参数类型	语法格式	解析时机	示例	注意事项
全局参数	${param_name}	工作流启动时解析	${biz_date}, ${env}	可在任务中直接使用
局部参数	${param_name}	任务执行前解析	${input_path=/data/in}	优先级高于全局参数
内置系统参数	${system_param}	调度系统自动注入	${scheduleTime}, ${startTime}, ${endTime}	常用于日志标记和分区写入
日期函数表达式	$[yyyy-MM-dd]	运行时动态计算	$[yyyy-MM-dd-7] 表示 7 天前	支持 +/- 偏移
日期偏移	$[yyyyMMdd-1]	运行时动态计算	$[yyyyMMdd-1] 表示昨天	—
Shell 脚本传参	使用 param=xxx 形式传递	子流程或命令行调用时	sh etl.sh date=${biz_date}	需脚本内接收 $1
上游任务输出捕获	通过 set variable=value 输出	任务结束时写入上下文	在 Shell 中 echo "SET_OUTPUT:region=shanghai"	下游用 ${region} 引用
动态 SQL 参数	在 SQL 节点中使用 ${}	执行前替换	INSERT INTO t VALUES('${user}', ${id});	防止 SQL 注入需校验输入
子流程参数映射	Sub-Process 任务中设置 KEY=VALUE	子流程启动前绑定	parent_id=${processId}	子流程需预定义同名参数

9.2 工作流版本管理策略

策略	说明	实现方式	优点	缺点
手动导出备份	定期将工作流导出为 JSON 文件	Web UI → 导出功能	简单直观，便于归档	易遗漏，无差异对比
Git 版本控制	将导出的 JSON 提交到 Git 仓库	使用 CI/CD 脚本自动提交	支持 diff、回滚、分支管理	需集成外部系统
命名版本号	在工作流名称后加 -v1, -v2	如 etl_user_data-v3	快速识别版本	不支持自动切换
灰度上线	新版本先复制为测试工作流，验证后再替换主流程	复制 → 修改 → 上线 → 切流量	降低生产风险	需人工操作
API 自动化管理	使用 /export-workflow-def + /import-workflow-def 接口	脚本定期备份或发布	可集成进 DevOps 流程	需编写维护脚本
版本快照	DolphinScheduler 社区版无内置版本，企业版可能支持	—	—	建议自行实现快照机制
回滚机制	从 Git 或备份文件重新导入旧版本	curl -X POST ... /import	故障时快速恢复	需确保参数一致性

9.3 失败重试机制与容错设计

配置项	说明	示例值	注意事项
重试次数	任务失败后自动重试的次数	0, 1, 3, 5	I/O 类任务建议设 2~3 次
重试间隔	每次重试之间的等待时间（分钟）	5, 10, 30	避免密集重试压垮服务
重试策略	条件触发重试	失败重试 / 异常重试	可结合告警通知
容错任务	设置”失败继续”标志	在任务节点勾选”失败继续”	用于非关键路径任务
条件分支容错	使用 Condition 节点判断状态	A 成功 → B；A 失败 → C（补偿任务）	实现事务性语义
超时中断	设置任务最大执行时间	3600 秒（1小时）	防止长时间卡住资源
补偿任务	失败后执行清理或通知	发送告警、回滚数据	提高系统健壮性
断路器模式	（需自定义）连续失败 N 次暂停调度	结合外部监控系统实现	防止雪崩效应

9.4 跨项目任务调用与共享

方式	实现机制	配置方法	适用场景	注意事项
Depend 依赖任务	跨项目依赖上一个周期的成功实例	添加 Depend 节点，选择目标项目和工作流	项目间 ETL 依赖	仅支持按调度周期依赖
Sub-Process 调用	在当前工作流中嵌套执行其他项目的子流程	添加 Sub-Process 节点，选择目标项目和工作流	复用通用逻辑（如清洗）	目标工作流必须上线
公共数据源	创建”公共”类型的数据源	数据源中心 → 创建 → 设为”公共”	多项目共享数据库连接	需统一权限管理
资源文件共享	上传 UDF 或脚本为”公共”资源	资源中心 → 上传 → 公共资源	共享 Hive UDF、Shell 工具	需注意版本兼容
API 远程触发	使用 REST API 启动其他项目的工作流	POST /projects/{pid}/executors/start	动态触发、条件调用	需 Token 认证
全局参数传递	通过 Sub-Process 显式传递参数	KEY=VALUE 映射	上下文传递（如日期）	接收方需定义同名参数
权限控制	用户需有目标项目的访问权限	在目标项目中添加该用户为成员	否则无法查看或调用	建议最小权限原则

9.5 性能调优建议（线程池、任务队列等）

调优项	配置参数	推荐值	作用	注意事项
Master 分发线程数	master.dispatch.task.num	50 ~ 200	控制任务分发速度	过大会导致 DB 压力高
Worker 执行线程数	worker.exec.threads	CPU 核数 × 2	并行执行本地任务	避免过多线程争抢资源
ZooKeeper 会话超时	zookeeper.session.timeout	60000 ms（1分钟）	防止网络抖动误判宕机	过短易频繁切换主节点
任务心跳间隔	task.executor.heartbeat.interval	10s	保持任务活跃状态上报	过长可能导致假死
日志批量刷盘	logback.appender.file.bufferSize	8KB ~ 64KB	提升日志写入性能	生产环境建议开启缓冲
数据库连接池	spring.datasource.hikari.maximum-pool-size	20 ~ 50	提高并发查询能力	需匹配 MySQL max_connections
缓存启用	spring.redis.open=true	true	加速元数据读取	建议搭配 Redis 使用
JVM 堆内存	-Xms4g -Xmx4g	根据机器内存设置	避免频繁 GC	Master/Worker 建议独立部署
磁盘 IO 优化	使用 SSD 存储日志和临时文件	—	减少 I/O 等待	特别是 Spark/Hive 任务

9.6 与 CI/CD 集成自动化发布

阶段	工具/方式	实现方式	示例	注意事项
代码管理	Git（GitHub/GitLab）	将工作流 JSON 文件纳入版本控制	etl_workflow_v1.json	建议按项目/模块分类存储
构建触发	Jenkins / GitLab CI	监听 Git Push 事件	webhook 触发构建	需配置安全令牌
自动化测试	Shell 脚本 / Python	验证工作流结构合法性	JSON Schema 校验	可模拟参数运行
自动发布	REST API 调用	使用 /import-workflow-def 接口	curl -X POST ... -F file=@wf.json	需携带有效 Token
环境隔离	多套 DolphinScheduler 环境	dev → test → prod	不同环境对应不同集群	配置参数差异化（如 ${env}）
回滚机制	Git revert + 重新导入	回退到上一版本并发布	git revert HEAD && make deploy	需记录发布历史
审批流程	Jenkins Manual Step / MR Review	人工确认后才发布到生产	”是否继续部署生产？“	关键任务建议人工审核
发布报告	邮件 / 钉钉通知	发送成功/失败消息	”工作流 etl_user 已部署至 PROD”	包含版本号和变更内容

第十章：扩展开发与源码解析（可选）

10.1 自定义任务类型开发

步骤	说明	关键类/接口	注意事项
1. 继承 TaskExecutionContext	封装任务运行上下文	org.apache.dolphinscheduler.plugin.task.api.TaskExecutionContext	获取参数、环境信息
2. 实现 TaskPluginDelegate	定义任务执行入口	org.apache.dolphinscheduler.plugin.task.api.TaskPluginDelegate	核心执行逻辑
3. 创建 TaskDefinition	定义任务配置模型	TaskDefinition	包含参数、资源、超时等
4. 编写 TaskProcessor	处理任务生命周期	TaskProcessor	启动、监控、终止
5. 打包为 JAR 插件	放入 plugins/task/ 目录	如 dolphinscheduler-task-custom-1.0.jar	需符合 SPI 规范
6. 重启 Worker	加载新任务类型	—	Master 不需要重启
7. Web UI 支持	前端添加任务图标和表单	Vue 组件开发	非必须，可用 API 调用
示例任务	Python 脚本任务、Flink SQL 任务、Kafka 生产者任务等	—	可复用现有进程执行器

10.2 插件机制与扩展点说明

扩展点	用途	实现方式	示例
任务插件（Task Plugin）	支持新类型任务（如 Flink, Kubernetes）	实现 TaskPluginDelegate 接口	自定义 AI 训练任务
告警插件（Alert Plugin）	新增通知渠道（如 Feishu, Slack）	实现 AlertChannelPlugin	企业微信机器人
数据源插件	支持新型数据库连接	实现 DataSourceChannel	Doris、StarRocks
资源存储插件	切换资源存储后端（HDFS, S3）	实现 ResourceStoragePlugin	AWS S3 存储脚本
认证插件	集成 LDAP、OAuth2、JWT	实现 AuthenticationProvider	单点登录（SSO）
日志插件	自定义日志收集方式（ELK, Loki）	实现 LoggerPlugin	推送到 Kafka 进行分析
SPI 机制	Java Service Provider Interface	META-INF/services/ 下注册实现类	工业标准插件机制
热加载	插件放入目录后自动识别	无需重启核心服务	仅 Worker 需重启

10.3 核心模块源码结构分析

模块	主要功能	关键包路径	说明
API Server	提供 REST 接口、用户认证、元数据管理	org.apache.dolphinscheduler.api	Spring Boot 应用，处理 HTTP 请求
Master Server	调度决策、DAG 解析、任务分发	org.apache.dolphinscheduler.server.master	基于 Quartz 和 ZooKeeper 实现 HA
Worker Server	任务执行、资源调度、状态上报	org.apache.dolphinscheduler.server.worker	实际 fork 子进程运行 Shell/SQL 等
Common	公共工具类、实体、常量	org.apache.dolphinscheduler.common	跨模块共享代码
Alert	告警发送、渠道管理、事件监听	org.apache.dolphinscheduler.alert	支持邮件、短信、IM
Plugin	插件框架与各类插件实现	org.apache.dolphinscheduler.plugin	任务、告警、数据源等扩展
DAO	数据访问层，操作 PostgreSQL/MySQL	org.apache.dolphinscheduler.dao	MyBatis 实现
RPC	节点间通信协议（Netty）	org.apache.dolphinscheduler.remote	Master 与 Worker 通信基础

10.4 编译与调试环境搭建

步骤	操作	命令/工具	注意事项
1. 获取源码	Clone 官方仓库	git clone https://github.com/apache/dolphinscheduler.git	建议使用最新稳定分支
2. 安装 JDK	Java 8 或 11	java -version	Maven 编译依赖
3. 安装 Maven	构建工具	mvn -v	用于打包
4. 编译项目	执行构建	mvn clean install -Dmaven.test.skip=true	跳过测试加快编译
5. 导入 IDE	IntelliJ IDEA / Eclipse	File → Open → pom.xml	等待依赖下载完成
6. 配置数据库	初始化 MySQL/PostgreSQL	sh script/create-dolphinscheduler.sql	修改 application-dao.yml 连接信息
7. 启动服务	分别运行各模块	./bin/start.sh master-server、./bin/start.sh worker-server	可单节点调试
8. 调试模式	添加远程调试参数	-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=5005	使用 IDEA 远程调试
9. 日志定位	查看 logs/ 目录	tail -f logs/master-server.log	快速发现问题
10. 单元测试	运行测试用例	mvn test	验证修改正确性