Apache DolphinScheduler Script 脚本告警插件使用指南：参数配置、执行原理与安全防护-育师

任务调度
大数据
后端
前端

【免费下载链接】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 告警插件体系中的Script（Shell 脚本）插件为核心，讲解如何在告警实例管理中创建脚本告警实例、配置脚本路径与自定义参数，并结合仓库源码剖析脚本执行器（ScriptSender）的完整调用链、命令行参数约定与命令注入防护机制。读完本文，你将掌握用 Shell 脚本接入任意自定义告警通道（如自研通知系统、企业内部 IM、监控平台 Webhook 等）的完整实战方案。

一、Script 插件能做什么

在 DolphinScheduler 中，告警是任务流运行状态（成功 / 失败）触发的下游动作。内置的告警插件目录覆盖了 DingTalk、企业微信、飞书、邮件、HTTP 等常见通道，但真实生产环境往往存在内置插件覆盖不到的自定义通知渠道。Script 插件正是为这类场景设计的"万能出口"：

把告警标题与内容作为命令行参数，交给用户指定的 Shell 脚本处理；
脚本内可以自由对接内部短信网关、自研 IM、工单系统、监控平台 API 等任意服务；
通过脚本的退出码（exit code）反馈告警发送是否成功，进而决定该条告警记录的最终状态。

从源码结构看，Script 插件位于 dolphinscheduler-alert-script 模块，核心实现由ScriptAlertChannelFactory（插件工厂）、ScriptAlertChannel（告警通道）、ScriptSender（脚本执行器）、ProcessUtils（进程工具）、StreamGobbler（输出流消费线程）和ScriptType（脚本类型枚举）六个类构成。

二、创建告警实例：配置步骤与字段说明

如需使用Shell脚本进行告警，请在告警实例管理中创建告警实例，并选择Script插件。以下为Script的配置示例：

2.1 参数配置表

参数	说明
用户参数（User Params）	用户自定义的参数，将作为`-p`参数传入脚本执行；非必填
脚本路径（Script Path）	脚本在服务器上的文件位置，只支持`.sh`后缀的文件；必填
脚本类型（Type）	目前支持`Shell`脚本（单选，默认且仅提供`SHELL`选项）；必填

从 ScriptAlertChannelFactory.java 可以看出三个字段在代码侧的完整定义：

userParams：InputParam类型，required=false，占位提示为 "Customized Params"，允许留空；
path：InputParam类型，required=true，源码注释明确说明"需要校验文件类型与文件是否存在"；
type：RadioParam单选参数，目前唯一可选项来自 ScriptType.java 枚举中的SHELL(0, "SHELL")。

三个字段的配置键名定义在 ScriptParamsConstants.java 中，分别是type、path、userParams，它们在执行期会被组装进参数 Map 传给ScriptSender。

2.2 告警实例的完整填写项

参照配置界面截图，一个完整的告警实例通常还包含以下通用字段（与插件参数配合使用）：

告警实例名称（Alarm instance name）：必填，为该实例起一个可辨识的名称，如script001；
选择插件（Select plugin）：必填，选中Script；
告警类型（Warning Type）：必填，单选success/failure/all，决定任务成功、失败或全部情况下触发该脚本告警；
用户参数（User Params）：可选，按脚本约定格式填写，例如--to=admin@example.com --subject=DolphinScheduler Alert；
脚本路径（Script Path）：必填，填写服务器上可执行脚本的绝对路径，例如/home/script.sh；
脚本类型（Type）：必填，选中SHELL。

2.3 注意事项

请注意脚本的读写权限与执行租户的关系。脚本告警实际运行在 Alert Server 所在宿主机上，以执行告警的租户身份调用/bin/sh，因此必须保证：

脚本文件对该执行用户具备可读（必要时可执行）权限；
脚本内部需要读写的外部文件、日志目录、凭据文件等，同样要授予对应租户合理的访问权限；
若脚本需要调用外部命令或网络接口，需确认执行环境（PATH、代理、DNS）对该租户可用。

三、脚本的执行约定：命令行参数与退出码

3.1 参数传递协议

从 ScriptSender.java 可以看到，插件实际构造的命令为：

/bin/sh -c "<scriptPath> -t '<title>' -c '<content>' -p '<userParams>'"

即脚本固定接收三个短参数：

参数	含义
`-t`	告警标题（title），来自告警数据
`-c`	告警内容（content），来自告警数据
`-p`	用户自定义参数（userParams），来自告警实例配置

仓库自带的示例脚本 scriptExample.sh 演示了标准的参数解析骨架，可作为编写自有脚本的模板：

#!/bin/bash while getopts t:c:p: opts; do case $opts in t) t=$OPTARG ;; c) c=$OPTARG ;; p) p=$OPTARG ;; ?) ;; esac done # Write your specific logic here # Set the exit code according to your execution result, and alert needs to use it # to judge the status of this alarm result if [ "$t" = "error msg title" ]; then exit 12 fi exit 0

3.2 退出码决定告警结果

ScriptSender在脚本执行完毕后读取进程退出码：

退出码为0：告警发送成功，返回send script alert msg success；
退出码非0：告警发送失败，返回send script alert msg error,exitCode is <n>。

因此脚本必须在结尾exit 0（发送成功）或exit 非 0（发送失败）之间做出明确选择，DolphinScheduler 会依据该结果更新告警记录状态，并在告警实例测试中给出直观反馈。

3.3 进程执行与输出流处理

脚本通过 ProcessUtils.java 中的ProcessBuilder启动子进程，并调用process.waitFor()同步等待脚本结束。为防止脚本输出内容过多导致标准输出 / 错误流的管道缓冲区阻塞，ProcessUtils会为输入流和错误流分别启动一个 StreamGobbler.java 线程持续消费并打印到告警服务日志，从而避免死锁、保证等待超时可控。脚本自身的 stdout/stderr 不会直接作为告警结果返回，排查问题时请关注 Alert Server 日志中的out put msg is ...输出。

四、执行链路与校验逻辑：从触发到结果

一次脚本告警的完整调用链如下：

告警触发后，ScriptAlertChannel.process(AlertInfo)被调用。该入口位于 ScriptAlertChannel.java，若参数 Map 为空会直接返回script params is empty的失败结果；
参数 Map 被封装为ScriptSender，调用sendScriptAlert(title, content)；
sendScriptAlert首先校验scriptType是否为SHELL（其余类型会返回script type error；源码注释预留了"可以在这里扩展 python 等其他脚本类型"的扩展点）；
进入executeShellScript后按顺序执行以下校验（见 ScriptSender.java）：
- 操作系统校验：Windows 环境直接返回shell script not support windows os，即该插件仅支持类 Unix 环境；
- 后缀校验：脚本路径必须以.sh结尾，否则返回shell script is invalid, only support .sh file；
- 存在性校验：文件必须存在，否则返回shell script not exist : <path>；
- 类型校验：路径必须是普通文件而非目录，否则返回shell script is not a file : <path>；
- 注入防护校验（详见下一节）；
构造/bin/sh -c命令并执行，依据退出码返回成功 / 失败结果。

五、安全设计：命令注入（RCE）防护

由于脚本告警的本质是把外部文本拼入 shell 命令执行，若不加约束极易产生命令注入漏洞。ScriptSender在构造命令前对标题、内容、用户参数三部分统一执行了单引号（'）黑名单校验（见 ScriptSender.java）：

if (userParams.contains("'")) { log.error("shell script illegal user params : {}", userParams); ... } if (title.contains("'")) { ... } if (content.contains("'")) { ... }

任一输入包含单引号，插件都会拒绝执行并记录shell script illegal ...日志。单引号是 shell 拼接场景下逃逸出参数边界的核心字符，拦截它即可阻断形如'; rm -rf /; '的注入载荷。这一点在单元测试 ScriptSenderTest.java 中有直接验证：testScriptSenderInjectionTest将用户参数设置为' ; calc.exe ; '，断言告警结果必然失败。

同文件中的其他测试用例还覆盖了：正常发送成功 / 失败（对应脚本示例中error msg title的分支）、用户参数为null时仍可成功（空参数不触发注入拦截）、路径为null或指向非.sh文件时失败等边界场景，可作为理解插件行为边界的参考。

六、常见问题排查清单

现象	可能原因	排查建议
告警结果提示`shell script not exist`	脚本路径填写错误或文件被删除	在 Alert Server 所在机器上确认路径存在
告警结果提示`only support .sh file`	路径后缀不是`.sh`	重命名为`.sh`后缀的脚本文件
告警结果提示`shell script illegal ...`	标题 / 内容 / 用户参数中包含单引号`'`	在脚本内改用双引号或转义方式处理含引号内容
告警结果提示`shell script not support windows os`	在 Windows 上运行 Alert Server	将脚本告警部署到 Linux 环境
脚本明明执行成功但告警仍失败	脚本未以`exit 0`结束	检查脚本尾部退出码
脚本输出丢失	输出仅写入 Alert Server 日志	检索日志中`out put msg is`关键字
脚本访问文件 / 网络被拒绝	执行租户权限不足	核对脚本读写权限与执行租户关系（见 2.3 节）

七、与告警插件体系的衔接

Script 插件是 DolphinScheduler 告警插件架构中的一员。插件工厂通过@AutoService(AlertChannelFactory.class)注解（见 ScriptAlertChannelFactory.java）实现 SPI 自动注册，插件名固定为Script。告警实例创建后，其配置会被持久化并在每次触发时随AlertInfo传入process()方法。若要进一步了解如何在告警实例管理中选择插件、配置告警组与测试告警，可参考告警插件用户指南（中文版见告警插件用户指南）。

综上，Script 插件通过"参数注入 + 退出码约定"这一极简协议，为 DolphinScheduler 提供了对接任意自定义通知系统的能力。在实际使用中，只需按本文给出的参数协议编写脚本、配置好路径与租户权限，即可将告警能力无缝扩展到内部业务系统。