Apache DolphinScheduler自定义告警插件：HTTP回调与脚本集成
项目地址: https://gitcode.com/gh_mirrors/dolp/dolphinscheduler 在数据工作流调度中，及时可靠的告警机制是保障系统稳定性的关键环节。Apache DolphinScheduler（分布式工作流调度系统）提供了灵活的告警插件机制，支持通过HTTP回调和脚本执行等方式将任务状态通知传递到外部系统。本文将详细介绍如何基于官方插件框架实现这两种告警方式，并提供完整的集成指南。
告警插件架构概述
DolphinScheduler的告警系统基于插件化架构设计，核心接口为AlertChannel，所有告警实现类需遵循此标准接口。该接口定义在dolphinscheduler-alert/dolphinscheduler-alert-api/src/main/java/org/apache/dolphinscheduler/alert/api/AlertChannel.java中，仅包含一个核心方法：
public interface AlertChannel {
AlertResult process(AlertInfo alertInfo);
}
插件实现需通过AlertChannelFactory创建具体实例，框架会自动扫描classpath中的实现类并完成注册。这种设计使得新增告警方式无需修改核心代码，只需开发独立的插件模块即可。
HTTP回调告警实现
HTTP告警插件允许将任务状态变更以HTTP请求形式发送到指定的外部服务端点，适用于与监控系统、通知平台或自定义业务系统集成。
核心实现类
HTTP告警通道的具体实现位于dolphinscheduler-alert/dolphinscheduler-alert-plugins/dolphinscheduler-alert-http/src/main/java/org/apache/dolphinscheduler/plugin/alert/http/HttpAlertChannel.java，核心代码如下：
public final class HttpAlertChannel implements AlertChannel {
@Override
public AlertResult process(AlertInfo alertInfo) {
AlertData alertData = alertInfo.getAlertData();
Map<String, String> paramsMap = alertInfo.getAlertParams();
if (null == paramsMap) {
return new AlertResult("false", "http params is null");
}
return new HttpSender(paramsMap).send(alertData.getContent());
}
}
该实现通过HttpSender类处理实际的HTTP请求发送，支持配置请求URL、方法、头信息等参数。插件工厂类HttpAlertChannelFactory负责创建通道实例并声明所需参数：
@AutoService(AlertChannelFactory.class)
public final class HttpAlertChannelFactory implements AlertChannelFactory {
@Override
public List<PluginParams> params() {
List<PluginParams> pluginParams = new ArrayList<>();
pluginParams.add(new PluginParams("url", "HTTP请求地址", true));
pluginParams.add(new PluginParams("method", "请求方法(GET/POST)", false, "POST"));
pluginParams.add(new PluginParams("headers", "请求头信息(JSON格式)", false));
return pluginParams;
}
@Override
public AlertChannel create() {
return new HttpAlertChannel();
}
}
配置与使用
在DolphinScheduler Web UI中配置HTTP告警时，需提供以下关键参数：
| 参数名 | 说明 | 是否必填 |
|---|---|---|
| url | 接收告警的HTTP服务端点 | 是 |
| method | HTTP请求方法，支持GET/POST | 否，默认POST |
| headers | 请求头信息，JSON格式 | 否 |
| timeout | 超时时间(毫秒) | 否，默认3000 |
配置示例：
{
"url": "https://monitor.example.com/api/alerts",
"method": "POST",
"headers": {
"Content-Type": "application/json",
"Authorization": "Bearer xxxxx"
}
}
告警触发时，插件会自动构造包含任务信息的JSON请求体，格式如下：
{
"projectId": 1,
"processDefinitionId": 1001,
"processInstanceId": 10001,
"taskInstanceId": 100001,
"status": "FAILURE",
"content": "任务[数据同步]执行失败: 数据库连接超时",
"startTime": "2025-10-15 08:30:00",
"endTime": "2025-10-15 08:30:30"
}
脚本告警实现
脚本告警插件允许通过执行外部脚本文件处理告警信息，支持Bash、Python等任意可执行脚本，提供了极高的灵活性。
核心实现类
public final class ScriptAlertChannel implements AlertChannel {
@Override
public AlertResult process(AlertInfo alertinfo) {
AlertData alertData = alertinfo.getAlertData();
Map<String, String> paramsMap = alertinfo.getAlertParams();
if (null == paramsMap) {
return new AlertResult("false", "script params is null");
}
return new ScriptSender(paramsMap).sendScriptAlert(alertData.getTitle(), alertData.getContent());
}
}
脚本执行逻辑由ScriptSender类处理，支持配置脚本路径、执行参数和环境变量。工厂类ScriptAlertChannelFactory定义了所需参数：
public final class ScriptAlertChannelFactory implements AlertChannelFactory {
@Override
public List<PluginParams> params() {
List<PluginParams> pluginParams = new ArrayList<>();
pluginParams.add(new PluginParams("scriptPath", "脚本路径", true));
pluginParams.add(new PluginParams("scriptParams", "脚本参数", false));
return pluginParams;
}
}
脚本开发规范
脚本告警支持任意可执行文件，接收两个固定参数：告警标题和告警内容。以下是一个Python脚本示例（保存为/opt/dolphinscheduler/scripts/alert_handler.py）：
#!/usr/bin/env python3
import sys
import requests
# 接收告警标题和内容
title = sys.argv[1]
content = sys.argv[2]
# 发送到企业微信机器人
webhook = "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxxxx"
data = {
"msgtype": "text",
"text": {"content": f"[{title}]\n{content}"}
}
requests.post(webhook, json=data)
脚本需设置可执行权限：
chmod +x /opt/dolphinscheduler/scripts/alert_handler.py
在Web UI中配置脚本路径为/opt/dolphinscheduler/scripts/alert_handler.py，参数留空或根据需要添加额外参数。
插件开发与集成步骤
1. 创建插件模块
在dolphinscheduler-alert-plugins目录下创建新的插件模块，遵循命名规范dolphinscheduler-alert-<type>。以自定义HTTP插件为例，目录结构如下：
dolphinscheduler-alert-http/
├── src/
│ ├── main/
│ │ ├── java/org/apache/dolphinscheduler/plugin/alert/http/
│ │ │ ├── HttpAlertChannel.java
│ │ │ └── HttpAlertChannelFactory.java
│ │ └── resources/META-INF/services/
│ │ └── org.apache.dolphinscheduler.alert.api.AlertChannelFactory
│ └── test/
└── pom.xml
2. 实现核心接口
创建AlertChannel实现类处理具体告警逻辑，AlertChannelFactory类声明插件元信息和参数定义，并在META-INF/services目录下创建文件注册工厂类：
org.apache.dolphinscheduler.plugin.alert.http.HttpAlertChannelFactory
3. 打包与部署
执行Maven打包命令构建插件JAR：
mvn clean package -DskipTests -pl dolphinscheduler-alert/dolphinscheduler-alert-plugins/dolphinscheduler-alert-http
将生成的JAR文件复制到DolphinScheduler安装目录的alert-server/plugins目录下，重启alert-server服务即可完成加载。
常见问题与调试
参数验证失败
若告警日志中出现params is null错误，通常是由于未正确配置必填参数。检查Web UI中告警实例的参数配置，确保所有必填项均已提供。
脚本执行权限问题
若出现Permission denied错误，需确认脚本文件的所有者为DolphinScheduler运行用户（通常是dolphinscheduler），并已设置可执行权限。
HTTP请求失败
可通过以下步骤排查：
- 检查目标服务是否可从AlertServer节点访问
- 查看AlertServer日志（
logs/alert-server.log）获取详细错误信息 - 使用
curl命令测试HTTP端点连通性：
curl -X POST https://monitor.example.com/api/alerts -d "test"
总结
Apache DolphinScheduler的告警插件机制为用户提供了灵活的扩展能力，通过HTTP回调和脚本执行两种方式，可以轻松集成到各种通知系统中。本文详细介绍了这两种插件的实现原理和使用方法，用户可根据实际需求选择合适的集成方式，或基于插件框架开发自定义告警通道。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
