DolphinScheduler Telegram 告警插件参数配置、发送链路与源码级实践指南【免费下载链接】dolphinschedulerApache DolphinScheduler is the modern data orchestration platform. Agile to create high performance workflow with low-code项目地址: https://gitcode.com/GitHub_Trending/dol/dolphinscheduler本篇技术指南围绕 Apache DolphinScheduler 的 Telegram 告警插件展开完整讲解在告警实例管理中创建 Telegram 告警实例所需的全部参数与含义并结合仓库内dolphinscheduler-alert-telegram插件的源码与测试用例深入剖析其 WebHook 请求构造、消息体格式、代理机制与响应处理逻辑。读完本文你将能够在 DolphinScheduler 中独立完成 Telegram 告警的配置与排障并理解其底层实现原理。一、Telegram 告警插件概述Telegram 是 DolphinScheduler 众多告警插件中的一员位于告警插件模块 dolphinscheduler-alert-telegram。它的作用是当工作流或任务状态发生变化成功、失败或全部状态时DolphinScheduler 通过 Telegram Bot 向指定的频道或群聊推送一条告警消息。使用方式非常直接进入告警实例管理模块点击创建告警实例在插件下拉框中选择Telegram按需填写下方配置项并保存即可。随后在任何工作流或任务定义中将告警组关联到该告警实例即可实现告警推送。告警实例的创建与展示效果如下图所示该配置表单由插件工厂类 TelegramAlertChannelFactory.java 通过 SPI 机制声明AutoService(AlertChannelFactory.class)并注册到系统其name()返回Telegram即告警实例管理界面中插件下拉框展示的名称。二、参数配置详解下表完整列出了 Telegram 告警插件的全部配置参数及其说明参数说明WebHook使用机器人发送消息时的 WebHook 地址。botToken创建 Telegram 机器人后获取的访问令牌Access Token。chatId订阅的 Telegram 频道Channel或群聊 ID即消息接收方。parseMode消息解析类型支持txt、markdown、markdownV2、html。EnableProxy是否启用代理服务器默认不启用。Proxy代理服务器地址。Port代理服务器端口。User代理服务器认证用户名。Password代理服务器认证密码。2.1 必填项与输入校验从 TelegramAlertChannelFactory.java 的params()方法可以看出各字段的校验与形态约束WebHook、botToken、chatId 均为必填项三个输入框都通过Validate.newBuilder().setRequired(true)声明为必填未填写时前端表单会拦截提交。parseMode 为下拉选择可选值在 TelegramAlertConstants.java 中定义为Txt、Markdown、MarkdownV2、Html四个枚举常量默认值为Txt也是必填项。文档描述中的小写形式txt/markdown/markdownV2/html与源码中存储的首字母大写枚举值Txt/Markdown/MarkdownV2/Html一一对应。EnableProxy 为单选按钮可选YES/NO默认NO即布尔值false。Port 为数字输入框通过InputNumberParam声明校验类型为DataType.NUMBER只能填写数字。Password 输入框类型为password在页面上以密文形式展示避免代理认证密码明文泄露。Proxy、User、Password 为非必填仅在启用代理时才有实际意义。2.2 WebHook 与默认推送地址的关联WebHook 参数在发送链路中扮演核心角色。在 TelegramSender.java 的构造函数中可以看到当用户不填写 WebHook时插件会自动使用默认推送地址https://api.telegram.org/bot{botToken}/sendMessage常量定义见 TelegramAlertConstants.java并把其中的{botToken}占位符替换为实际填写的 botToken当用户填写了自定义 WebHook时插件仍会对其执行url.replace({botToken}, botToken)也就是说自定义 WebHook 中如果包含{botToken}占位符同样会被替换为机器人令牌。这一设计意味着 WebHook 有两种使用形态直接使用 Telegram 官方sendMessage接口或使用自定义的转发服务地址。三、发送链路与消息体结构3.1 一次告警的完整调用链一次 Telegram 告警的调用链非常清晰从入口到发送仅经过两层TelegramAlertChannel.java 的process(AlertInfo info)是告警入口先检查alertParams是否为空为空则直接返回失败随后取出AlertData包含告警标题与内容构造TelegramSender并调用sendMessage(data)。TelegramSender.sendMessage() 负责真正发送调用sendInvoke(title, content)发起 HTTP POST 请求并将 Telegram 服务端的响应解析为AlertResult成功或失败返回给上层。3.2 HTTP POST 请求体结构DolphinScheduler 构造的 HTTP POST 请求为 JSON 格式Content-Type 为application/json见 TelegramSender.java。告警消息体结构如下{ text: [{\projectId\:1,\projectName\:\p1\,\owner\:\admin\,\processId\:35,\processDefinitionCode\:4928367293568,\processName\:\s11-3-20220324084708668\,\taskCode\:4928359068928,\taskName\:\s1\,\taskType\:\SHELL\,\taskState\:\FAILURE\,\taskStartTime\:\2022-03-24 08:47:08\,\taskEndTime\:\2022-03-24 08:47:09\,\taskHost\:\192.168.1.103:1234\,\logPath\:\\}], chat_id: chat id number }从消息体可以看到 DolphinScheduler 向 Telegram 推送的内容组织方式text字段是告警正文内容为任务/工作流相关信息的 JSON 字符串以字符串形式内嵌包含projectId、projectName、owner、processId、processName、taskCode、taskName、taskType、taskState、taskStartTime、taskEndTime、taskHost、logPath等字段便于在 Telegram 客户端直接查看失败任务的关键上下文chat_id字段对应配置中的 chatId指定消息推送到哪个频道或群聊。3.3 parseMode 对请求体的影响消息体的实际构造逻辑位于 TelegramSender.buildMsgJsonStr()chat_id始终写入仅当 parseMode不是Txt即配置为 Markdown、MarkdownV2 或 Html时才会额外写入parse_mode字段text始终写入告警内容。换句话说默认的Txt模式发送的是纯文本消息不携带parse_mode只有选择 Markdown 或 HTML 等富文本模式时才会通知 Telegram 服务端按对应语法解析text此时可在告警内容中使用粗体、链接、代码块等格式参考 TelegramSenderTest.java 中 Markdown 代码块与 HTML 粗体内容的发送用例。3.4 响应处理与失败判定发送完成后插件解析 Telegram 服务端返回的 JSON 响应TelegramSender.parseRespToResult()响应为空 → 判定失败消息为 telegram server resp is empty响应无法解析 → 判定失败响应中ok字段为true→ 发送成功ok为false时插件会把服务端返回的error_code与description拼入失败消息方便定位 token 无效、chatId 错误等具体原因响应模型见TelegramSendMsgResponse内部类对应字段为ok、error_code、description、result。此外HTTP 客户端启用了统一的重试策略HttpServiceRetryStrategy.retryStrategy见 TelegramSender.java在网络异常等可重试场景下会自动重试提升告警送达的可靠性。四、代理Proxy机制当 DolphinScheduler 所在网络无法直连 Telegram 服务例如处于受限内网环境时可通过代理转发告警请求。代理配置的启用与解析逻辑位于 TelegramSender.java 与 TelegramSender.java当EnableProxy配置为true时插件才会解析Proxy代理地址、Port端口数字类型、User与Password若同时配置了 User 与 Password则使用带认证的代理客户端getProxyClient基于 Apache HttpClient 的CredentialsProvider与UsernamePasswordCredentials若未配置认证信息则使用默认客户端仅通过RequestConfig设置HttpHost(proxy, port)实现代理转发未启用代理时走直连路径getDefaultClient。简而言之只有开启 EnableProxy 后Proxy/Port/User/Password 四个字段才会生效代理是否需要认证由 User/Password 是否填写决定。五、测试用例对配置正确性的验证仓库中的测试用例 TelegramSenderTest.java 从配置层面验证了插件的健壮性可作为实际排障的参考无效 botTokentestSendMessageFailByParamToken填入错误的令牌后发送断言结果为失败说明错误的 Token 会被 Telegram 服务端拒绝无效 chatIdtestSendMessageFailByChatId填入非法频道 ID 后发送断言结果为失败默认 Txt 模式testSendMessage使用标准配置Txt 解析模式发送普通文本内容Markdown 模式testSendMessageByMarkdown发送 Python 代码块内容验证 Markdown 解析模式下的消息发送HTML 模式testSendMessageByHtml发送bbold/b加粗内容验证 HTML 解析模式下的消息发送。以上用例通过BeforeEach initConfig()初始化webHook、botToken、chatId、parseMode四个核心参数与告警实例表单的字段一一对应。这些用例说明在真实环境中如果告警一直失败应优先检查 botToken 是否有效、chatId 是否正确以及 parseMode 与消息内容的格式是否匹配。六、注意事项与参考资料注意事项WebHook 兼容性无论是使用 Telegram 官方sendMessage地址还是自定义 WebHook 服务目标地址都必须能够接收并处理 DolphinScheduler 构造的上述 JSON 请求体包含text与chat_id字段。如果使用自定义服务转发请确保其透传或正确消费该结构否则告警将无法正常送达。消息格式选择若选择 Markdown/MarkdownV2/HTML 解析模式告警正文必须符合对应语法规范否则 Telegram 服务端会返回解析错误纯文本需求建议使用默认的Txt模式。代理适用场景仅当 DolphinScheduler 服务所在环境无法直连 Telegram API 时才需要启用代理启用后需确保 Proxy 地址与 Port 可达并视代理服务器要求填写 User/Password。参考资料本文所涉配置项与发送逻辑的完整定义可进一步查阅以下仓库文件插件参数常量TelegramParamsConstants.java告警常量与默认推送地址TelegramAlertConstants.java告警通道入口与发送实现TelegramAlertChannel.java、TelegramSender.java插件表单与参数声明TelegramAlertChannelFactory.java发送行为测试TelegramSenderTest.java关于 Telegram Bot 的申请方式通过 BotFather 创建机器人并获取 Token、频道创建、以及sendMessage接口的字段规范请以 Telegram 官方 Bot 文档为准对应本文消息体与默认推送地址所遵循的官方 API 约定。【免费下载链接】dolphinschedulerApache DolphinScheduler is the modern data orchestration platform. Agile to create high performance workflow with low-code项目地址: https://gitcode.com/GitHub_Trending/dol/dolphinscheduler创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 DolphinScheduler Telegram 告警插件：参数配置、发送链路与源码级实践指南
DolphinScheduler Telegram 告警插件参数配置、发送链路与源码级实践指南【免费下载链接】dolphinschedulerApache DolphinScheduler is the modern data orchestration platform. Agile to create high performance workflow with low-code项目地址: https://gitcode.com/GitHub_Trending/dol/dolphinscheduler本篇技术指南围绕 Apache DolphinScheduler 的 Telegram 告警插件展开完整讲解在告警实例管理中创建 Telegram 告警实例所需的全部参数与含义并结合仓库内dolphinscheduler-alert-telegram插件的源码与测试用例深入剖析其 WebHook 请求构造、消息体格式、代理机制与响应处理逻辑。读完本文你将能够在 DolphinScheduler 中独立完成 Telegram 告警的配置与排障并理解其底层实现原理。一、Telegram 告警插件概述Telegram 是 DolphinScheduler 众多告警插件中的一员位于告警插件模块 dolphinscheduler-alert-telegram。它的作用是当工作流或任务状态发生变化成功、失败或全部状态时DolphinScheduler 通过 Telegram Bot 向指定的频道或群聊推送一条告警消息。使用方式非常直接进入告警实例管理模块点击创建告警实例在插件下拉框中选择Telegram按需填写下方配置项并保存即可。随后在任何工作流或任务定义中将告警组关联到该告警实例即可实现告警推送。告警实例的创建与展示效果如下图所示该配置表单由插件工厂类 TelegramAlertChannelFactory.java 通过 SPI 机制声明AutoService(AlertChannelFactory.class)并注册到系统其name()返回Telegram即告警实例管理界面中插件下拉框展示的名称。二、参数配置详解下表完整列出了 Telegram 告警插件的全部配置参数及其说明参数说明WebHook使用机器人发送消息时的 WebHook 地址。botToken创建 Telegram 机器人后获取的访问令牌Access Token。chatId订阅的 Telegram 频道Channel或群聊 ID即消息接收方。parseMode消息解析类型支持txt、markdown、markdownV2、html。EnableProxy是否启用代理服务器默认不启用。Proxy代理服务器地址。Port代理服务器端口。User代理服务器认证用户名。Password代理服务器认证密码。2.1 必填项与输入校验从 TelegramAlertChannelFactory.java 的params()方法可以看出各字段的校验与形态约束WebHook、botToken、chatId 均为必填项三个输入框都通过Validate.newBuilder().setRequired(true)声明为必填未填写时前端表单会拦截提交。parseMode 为下拉选择可选值在 TelegramAlertConstants.java 中定义为Txt、Markdown、MarkdownV2、Html四个枚举常量默认值为Txt也是必填项。文档描述中的小写形式txt/markdown/markdownV2/html与源码中存储的首字母大写枚举值Txt/Markdown/MarkdownV2/Html一一对应。EnableProxy 为单选按钮可选YES/NO默认NO即布尔值false。Port 为数字输入框通过InputNumberParam声明校验类型为DataType.NUMBER只能填写数字。Password 输入框类型为password在页面上以密文形式展示避免代理认证密码明文泄露。Proxy、User、Password 为非必填仅在启用代理时才有实际意义。2.2 WebHook 与默认推送地址的关联WebHook 参数在发送链路中扮演核心角色。在 TelegramSender.java 的构造函数中可以看到当用户不填写 WebHook时插件会自动使用默认推送地址https://api.telegram.org/bot{botToken}/sendMessage常量定义见 TelegramAlertConstants.java并把其中的{botToken}占位符替换为实际填写的 botToken当用户填写了自定义 WebHook时插件仍会对其执行url.replace({botToken}, botToken)也就是说自定义 WebHook 中如果包含{botToken}占位符同样会被替换为机器人令牌。这一设计意味着 WebHook 有两种使用形态直接使用 Telegram 官方sendMessage接口或使用自定义的转发服务地址。三、发送链路与消息体结构3.1 一次告警的完整调用链一次 Telegram 告警的调用链非常清晰从入口到发送仅经过两层TelegramAlertChannel.java 的process(AlertInfo info)是告警入口先检查alertParams是否为空为空则直接返回失败随后取出AlertData包含告警标题与内容构造TelegramSender并调用sendMessage(data)。TelegramSender.sendMessage() 负责真正发送调用sendInvoke(title, content)发起 HTTP POST 请求并将 Telegram 服务端的响应解析为AlertResult成功或失败返回给上层。3.2 HTTP POST 请求体结构DolphinScheduler 构造的 HTTP POST 请求为 JSON 格式Content-Type 为application/json见 TelegramSender.java。告警消息体结构如下{ text: [{\projectId\:1,\projectName\:\p1\,\owner\:\admin\,\processId\:35,\processDefinitionCode\:4928367293568,\processName\:\s11-3-20220324084708668\,\taskCode\:4928359068928,\taskName\:\s1\,\taskType\:\SHELL\,\taskState\:\FAILURE\,\taskStartTime\:\2022-03-24 08:47:08\,\taskEndTime\:\2022-03-24 08:47:09\,\taskHost\:\192.168.1.103:1234\,\logPath\:\\}], chat_id: chat id number }从消息体可以看到 DolphinScheduler 向 Telegram 推送的内容组织方式text字段是告警正文内容为任务/工作流相关信息的 JSON 字符串以字符串形式内嵌包含projectId、projectName、owner、processId、processName、taskCode、taskName、taskType、taskState、taskStartTime、taskEndTime、taskHost、logPath等字段便于在 Telegram 客户端直接查看失败任务的关键上下文chat_id字段对应配置中的 chatId指定消息推送到哪个频道或群聊。3.3 parseMode 对请求体的影响消息体的实际构造逻辑位于 TelegramSender.buildMsgJsonStr()chat_id始终写入仅当 parseMode不是Txt即配置为 Markdown、MarkdownV2 或 Html时才会额外写入parse_mode字段text始终写入告警内容。换句话说默认的Txt模式发送的是纯文本消息不携带parse_mode只有选择 Markdown 或 HTML 等富文本模式时才会通知 Telegram 服务端按对应语法解析text此时可在告警内容中使用粗体、链接、代码块等格式参考 TelegramSenderTest.java 中 Markdown 代码块与 HTML 粗体内容的发送用例。3.4 响应处理与失败判定发送完成后插件解析 Telegram 服务端返回的 JSON 响应TelegramSender.parseRespToResult()响应为空 → 判定失败消息为 telegram server resp is empty响应无法解析 → 判定失败响应中ok字段为true→ 发送成功ok为false时插件会把服务端返回的error_code与description拼入失败消息方便定位 token 无效、chatId 错误等具体原因响应模型见TelegramSendMsgResponse内部类对应字段为ok、error_code、description、result。此外HTTP 客户端启用了统一的重试策略HttpServiceRetryStrategy.retryStrategy见 TelegramSender.java在网络异常等可重试场景下会自动重试提升告警送达的可靠性。四、代理Proxy机制当 DolphinScheduler 所在网络无法直连 Telegram 服务例如处于受限内网环境时可通过代理转发告警请求。代理配置的启用与解析逻辑位于 TelegramSender.java 与 TelegramSender.java当EnableProxy配置为true时插件才会解析Proxy代理地址、Port端口数字类型、User与Password若同时配置了 User 与 Password则使用带认证的代理客户端getProxyClient基于 Apache HttpClient 的CredentialsProvider与UsernamePasswordCredentials若未配置认证信息则使用默认客户端仅通过RequestConfig设置HttpHost(proxy, port)实现代理转发未启用代理时走直连路径getDefaultClient。简而言之只有开启 EnableProxy 后Proxy/Port/User/Password 四个字段才会生效代理是否需要认证由 User/Password 是否填写决定。五、测试用例对配置正确性的验证仓库中的测试用例 TelegramSenderTest.java 从配置层面验证了插件的健壮性可作为实际排障的参考无效 botTokentestSendMessageFailByParamToken填入错误的令牌后发送断言结果为失败说明错误的 Token 会被 Telegram 服务端拒绝无效 chatIdtestSendMessageFailByChatId填入非法频道 ID 后发送断言结果为失败默认 Txt 模式testSendMessage使用标准配置Txt 解析模式发送普通文本内容Markdown 模式testSendMessageByMarkdown发送 Python 代码块内容验证 Markdown 解析模式下的消息发送HTML 模式testSendMessageByHtml发送bbold/b加粗内容验证 HTML 解析模式下的消息发送。以上用例通过BeforeEach initConfig()初始化webHook、botToken、chatId、parseMode四个核心参数与告警实例表单的字段一一对应。这些用例说明在真实环境中如果告警一直失败应优先检查 botToken 是否有效、chatId 是否正确以及 parseMode 与消息内容的格式是否匹配。六、注意事项与参考资料注意事项WebHook 兼容性无论是使用 Telegram 官方sendMessage地址还是自定义 WebHook 服务目标地址都必须能够接收并处理 DolphinScheduler 构造的上述 JSON 请求体包含text与chat_id字段。如果使用自定义服务转发请确保其透传或正确消费该结构否则告警将无法正常送达。消息格式选择若选择 Markdown/MarkdownV2/HTML 解析模式告警正文必须符合对应语法规范否则 Telegram 服务端会返回解析错误纯文本需求建议使用默认的Txt模式。代理适用场景仅当 DolphinScheduler 服务所在环境无法直连 Telegram API 时才需要启用代理启用后需确保 Proxy 地址与 Port 可达并视代理服务器要求填写 User/Password。参考资料本文所涉配置项与发送逻辑的完整定义可进一步查阅以下仓库文件插件参数常量TelegramParamsConstants.java告警常量与默认推送地址TelegramAlertConstants.java告警通道入口与发送实现TelegramAlertChannel.java、TelegramSender.java插件表单与参数声明TelegramAlertChannelFactory.java发送行为测试TelegramSenderTest.java关于 Telegram Bot 的申请方式通过 BotFather 创建机器人并获取 Token、频道创建、以及sendMessage接口的字段规范请以 Telegram 官方 Bot 文档为准对应本文消息体与默认推送地址所遵循的官方 API 约定。【免费下载链接】dolphinschedulerApache DolphinScheduler is the modern data orchestration platform. Agile to create high performance workflow with low-code项目地址: https://gitcode.com/GitHub_Trending/dol/dolphinscheduler创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考