Apache DolphinScheduler Script 告警插件实战：用 Shell 脚本接管告警通知-育师

Apache DolphinScheduler Script 告警插件实战：用 Shell 脚本接管告警通知

【免费下载链接】dolphinschedulerApache DolphinScheduler is the modern data orchestration platform. Agile to create high performance workflow with low-code项目地址: https://gitcode.com/GitHub_Trending/dol/dolphinscheduler

Script 告警插件是 Apache DolphinScheduler 告警体系中最灵活的扩展点之一，它允许你把告警的标题、内容与自定义参数透传给一台服务器上的 Shell 脚本，由脚本自行完成通知动作（如调用内部消息网关、钉钉/飞书 Webhook 之外的自建接口、运维工单系统等）。读完本文，你将掌握在告警实例管理中配置 Script 插件的完整方法、三个核心参数的语义与约束，以及从 ScriptSender 到ProcessBuilder的底层执行链路和安全校验逻辑。

Script 插件是什么

当内置的 Email、DingTalk、FeiShu、WeChat 等告警渠道都无法满足你的通知需求时，DolphinScheduler 允许你启用Shell script方式告警：在「告警实例管理」中新建一个告警实例，选择Script插件即可。插件本身不做任何推送动作，而是把你预先部署在 DolphinScheduler 服务端机器上的.sh脚本拉起来执行，执行结果（退出码）直接决定本次告警的成败。

该插件位于仓库的 dolphinscheduler-alert-script 模块，通过@AutoService(AlertChannelFactory.class)注册为名为Script的告警通道（见 ScriptAlertChannelFactory.java），被打包为alert.script插件随告警服务加载。

参数配置详解

在告警实例管理中选择Script插件后，需要配置三个参数。下表为官方文档给出的参数说明：

Parameter	Description
User Params	User defined parameters will pass to the script.
Script Path	The file location path in the server, only support .sh file
Type	Support`Shell`script.

结合插件源码中的参数定义（ScriptAlertChannelFactory.java 与 ScriptParamsConstants.java），可以进一步明确每个参数的底层语义：

User Params（用户自定义参数）

内部参数名为userParams，非必填，可留空。
该值会在执行时原样透传给脚本的-p选项，供脚本内的自定义逻辑使用。
在源码中它经StringUtils.isNotBlank判空处理，空值会被替换为空字符串，不会导致 NPE（对应测试用例testUserParamsNPE）。

Script Path（脚本路径）

内部参数名为path，必填，是脚本在服务端机器上的文件绝对路径。
仅支持.sh文件：源码中executeShellScript会先校验scriptPath.endsWith(".sh")，否则直接返回失败信息shell script is invalid, only support .sh file。
执行前还会依次校验文件存在（exists()）且是普通文件（isFile()），任一不满足即告警失败。
该插件不支持 Windows，在 Windows 操作系统上执行会直接返回shell script not support windows os。

Type（脚本类型）

内部参数名为type，必填，为单选（Radio）控件。
目前仅支持SHELL一种类型，对应枚举 ScriptType.java 中的SHELL(0, "SHELL")。
源码中预留了扩展位：若传入非 SHELL 类型，会走sendScriptAlert的兜底分支，返回script type error；注释也提示未来可在该处扩展 Python 等其他类型脚本。

脚本如何被调用：底层执行链路

配置好告警实例后，每当产生告警，ScriptAlertChannel.process 会取出AlertData的标题（title）与内容（content），连同告警实例参数一并交给ScriptSender。ScriptSender组装出的实际命令是：

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

即：你的脚本会被要求支持三个命令行选项，-t传入告警标题、-c传入告警正文、-p传入用户自定义参数。仓库测试目录中的示例脚本 scriptExample.sh 给出了标准写法——用getopts t:c:p:解析这三个参数，然后写入你自己的业务逻辑：

#!/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

脚本的退出码直接决定告警结果：ProcessUtils.executeScript通过ProcessBuilder启动子进程，process.waitFor()返回的退出码为0时告警成功（send script alert msg success），非 0 时告警失败（send script alert msg error,exitCode is N）。上述示例脚本中，当标题为error msg title时返回退出码 12，用来模拟告警失败场景。

执行期间，子进程的标准输出与标准错误流分别由两个 StreamGobbler 线程异步消费，避免缓冲区写满导致进程阻塞，输出内容记录到告警服务日志中，便于排查脚本执行问题。

安全与权限注意事项（官方 Note）

官方文档明确列出两点注意事项，结合源码可以理解其背后的机制：

考虑脚本文件相对于执行租户的访问权限：脚本以 DolphinScheduler 服务进程（告警服务）所在租户/用户的权限执行，因此必须确保该运行账号对脚本文件具备读取与执行权限，否则脚本可能因权限不足而无法运行。
平台不校验脚本内容与是否被篡改：告警插件会原样执行对应的 Shell 脚本，平台不会审查脚本内容，也不会校验脚本是否被恶意篡改。因此必须高度信任该脚本，并信任使用该功能的用户不会滥用此能力。从安全角度，这也是一个高权限入口，应仅授权给可信的运维人员配置。
（源码层面的补充）注入防护：虽然脚本内容不受平台审查，但平台对传入脚本的参数做了注入防护。在 ScriptSender.executeShellScript 中，若userParams、title、content任一包含单引号'，会被判定为非法参数而拒绝执行（防止拼接命令时的单引号逃逸注入）。对应的单元测试testScriptSenderInjectionTest用' ; calc.exe ; '验证了该拦截逻辑（见 ScriptSenderTest.java）。

典型使用步骤

在 DolphinScheduler 服务端机器上编写并放置你的告警脚本（.sh），确保脚本可执行、运行账号有权限访问。
进入「安全中心 → 告警实例管理」（不同版本菜单位置略有差异），点击「创建告警实例」。
告警插件类型选择Script，依次填写：
- Script Path：脚本在服务端的绝对路径（如/opt/alert/notify.sh）；
- User Params：需要透传给脚本的自定义参数（可选，如业务方标识、机器人 Token 等）；
- Type：选择SHELL。
保存后，在需要使用该通知方式的工作流或告警组中引用该告警实例。
触发一次告警验证：告警成功后可在告警历史中看到成功记录；失败时可根据退出码与StreamGobbler记录的脚本输出日志排查原因。

验证与测试

插件模块自带完整的单元测试（ScriptSenderTest.java），覆盖了以下关键场景，也可作为你理解插件行为的参考：

正常执行：普通标题 + 内容，脚本退出码为 0，告警成功；
失败语义：标题为error msg title时脚本返回 12，告警失败；
注入防护：用户参数包含单引号注入串时被拒绝，告警失败；
空值健壮性：userParams为 null 时仍可正常执行；path为 null 或非法路径时返回对应错误信息；
类型异常：type 为 null 时返回失败。

小结

Script 插件是 DolphinScheduler 告警体系的"万能适配器"：-t、-c、-p三个选项让标准告警数据与自定义参数能够无侵入地进入你的自有脚本，退出码即告警结果的设计让脚本状态与告警状态严格对齐。配置时请务必记住官方 Note 的两点要求——确保执行租户具备脚本访问权限，并高度信任脚本本身。若需查阅插件完整实现，可深入 dolphinscheduler-alert-script 源码目录与告警插件聚合模块继续研究。

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