Apache 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 告警实例、理解 WebHook / botToken / chatId / parseMode 等全部配置项的含义并结合当前仓库中dolphinscheduler-alert-telegram模块的源码实现深入剖析消息的组装、发送与响应解析的底层机制。读完本文你将能够独立完成 Telegram 告警通道的接入、排障并理解该插件在 DolphinScheduler 告警插件体系中的运行方式。一、插件定位与适用场景Telegram 告警插件是 Apache DolphinScheduler 告警插件体系中的一个标准告警通道。当工作流Workflow或任务Task发生状态变化成功、失败时DolphinScheduler 的告警服务会将告警内容通过 Telegram Bot API 推送到指定的 Telegram 频道或会话中适合依赖 Telegram 进行即时消息通知的团队。该插件的完整代码位于 dolphinscheduler-alert/dolphinscheduler-alert-plugins/dolphinscheduler-alert-telegram 模块通过AutoService(AlertChannelFactory.class)注解注册进告警插件体系见 TelegramAlertChannelFactory.java与邮件、钉钉、飞书、企业微信等插件并列统一以告警实例的形式在安全中心配置和复用。二、接入前置准备申请 Bot 与获取 ChatId在 DolphinScheduler 中配置前需要先完成两项 Telegram 侧的准备工作创建机器人并获取 Bot Token通过 Telegram 官方提供的 BotFather 机器人创建自己的 Bot创建完成后会获得一个访问令牌Bot Token。Bot Token 是调用 Telegram Bot API 的身份凭证在插件的botToken配置项中使用。确定消息接收方 ChatIdTelegram 告警消息通过chat_id参数指定接收方可以是私人会话、群组或频道。需要将 Bot 添加到目标频道/群组并获取对应的 ChatId频道/群组的 ID 通常为负数例如-100xxxxxxxxxx。说明原文档中附带的 Telegram 官方 Bot、API、SendMessage 文档链接请通过 Telegram 官方渠道查阅此处不再赘述。三、创建 Telegram 告警实例在 DolphinScheduler Web UI 中进入安全中心 → 告警实例管理模块点击创建告警实例告警实例名称填写一个可辨识的名称如图中示例alert_telegram选择插件下拉选择Telegram告警类型通过单选按钮选择success、failure或all默认all用于指定触发告警的任务状态类型填写下方 Telegram 专属配置项点击确认保存。告警实例创建完成后即可在工作流定义或告警组中被引用当任务/工作流状态匹配告警类型时自动触发 Telegram 消息推送。四、Telegram 插件参数详解Telegram 插件的全部 9 个参数由 TelegramAlertChannelFactory.java 中的params()方法定义参数名常量统一维护在 TelegramParamsConstants.java 中。测试 TelegramAlertChannelFactoryTest.java 也验证了插件参数数量为 9 个。参数名类型是否必填默认值说明WebHook输入框是无使用 Telegram 机器人发送消息的 WebHook 地址其中可包含{botToken}占位符botToken输入框是无创建 Telegram 机器人时获取的访问令牌chatId输入框是无订阅接收告警的 Telegram 频道/会话 IDparseMode下拉选择是Txt消息解析类型支持Txt、Markdown、MarkdownV2、HtmlIsEnableProxy单选否falseNO是否开启代理选项为 YES / NOProxy输入框否无代理地址仅在启用代理时生效Port数字输入框否无代理端口仅在启用代理时生效User输入框否无代理鉴权用户名代理需要认证时填写Password输入框password 类型否无代理鉴权密码代理需要认证时填写从源码可以确认几个关键细节必填项校验webHook、botToken、chatId、parseMode四个参数均通过Validate.newBuilder().setRequired(true)标记为必填见 TelegramAlertChannelFactory.java其中webHook、botToken、chatId还带有输入提示占位符而代理相关的 5 个参数均为非必填。Parse Mode 选项下拉选项直接来自常量类 TelegramAlertConstants.java即Txt、Markdown、MarkdownV2、Html默认选中Txt。代理开关默认关闭IsEnableProxy通过单选参数YES/NO呈现setValue(STRING_FALSE)表明默认值为否见 TelegramAlertChannelFactory.java。密码脱敏Password参数通过setType(password)声明为密码输入框见 TelegramAlertChannelFactory.java。五、WebHook 的两种用法与消息体结构5.1 WebHook 地址的处理逻辑虽然webHook在表单中为必填项但源码中对其做了兼容处理。TelegramSender.java 的构造函数逻辑如下若webHook为空则回退到默认地址https://api.telegram.org/bot{botToken}/sendMessage无论使用默认地址还是用户自定义地址都会将 URL 中的{botToken}占位符替换为实际配置的 botToken默认地址常量定义在 TelegramAlertConstants.java 中。这意味着标准用法下只需正确填写 botTokenWebHook 可以直接使用官方默认地址也可以填写自定义的 WebHook例如自建 Bot API 代理网关。5.2 请求 Body 的 JSON 结构发送告警时插件通过 HTTP POST 请求向 Telegram 推送消息请求体由 TelegramSender.buildMsgJsonStr() 构建核心字段为{ chat_id: 实际配置的 chatId, parse_mode: 非 Txt 模式时才会携带取值 Markdown/MarkdownV2/Html, text: 告警内容 }其中text字段承载的就是 DolphinScheduler 告警服务生成的告警正文一个典型的工作流任务失败告警内容如下与告警数据序列化后的 JSON 字符串一致{ 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 }从源码实现看text内容实际来自AlertData.getContent()而AlertData.getTitle()如测试中的[telegram alert] test title会写入日志用于追踪见 TelegramSender.java 与sendInvoke中的日志记录。注意如果用户配置的是自定义 WebHook非 Telegram 官方 Bot API 端点则要求该 WebHook 能够接收并处理与上述结构一致的 HTTP POST 请求 Body否则消息无法被正确解析和投递。5.3 parseMode 的语义当选择Txt时请求体中不会携带parse_mode字段见 TelegramSender.isTextParseMode()当选择Markdown、MarkdownV2或Html时会将对应取值写入parse_mode字段Telegram 端按相应语法渲染消息正文中的格式标记。测试 TelegramSenderTest.java 分别覆盖了 Markdown代码块内容与 HTMLbbold/b两种解析模式下的发送场景。六、代理配置说明当运行环境无法直接访问 Telegram 服务如国内网络环境可以开启代理将Enable Proxy设为YES界面会动态展开代理相关字段填写Proxy代理地址与Port代理端口若代理需要鉴权再填写User与Password。源码中代理逻辑集中在 TelegramSender.java 与代理客户端构建方法getProxyClient、getProxyConfig仅当IsEnableProxy为true时才会读取并解析端口Integer.parseInt、代理地址、用户与密码若填写了用户与密码则通过 Apache HttpClient 的CredentialsProvider构建带基础认证的客户端否则使用默认客户端请求级配置RequestConfig中通过HttpHost(proxy, port)设置代理未开启代理时直接使用默认 HttpClient二者均挂载了HttpServiceRetryStrategy重试策略来自告警 API 模块见 dolphinscheduler-alert/dolphinscheduler-alert-plugins/dolphinscheduler-alert-api 中的HttpServiceRetryStrategy。七、源码级消息发送调用链从告警触发到 Telegram 消息落地的完整调用链如下告警服务将告警内容与告警实例参数封装为AlertInfoTelegramAlertChannel.process() 校验告警参数非空后构造TelegramSender并调用sendMessage(alertData)sendMessage调用sendInvoke发送 HTTP POST请求 Content-Type 为application/json、编码 UTF-8Body 即上文的 JSON 结构见 TelegramSender.buildHttpPost读取 Telegram 服务端响应后由parseRespToResult解析返回 JSON字段包括ok、error_code、description、result映射见内部类TelegramSendMsgResponse并据此生成AlertResult成功或携带 error_code/description 的失败信息任何异常网络、超时、参数错误等都会被捕获并包装为send telegram alert fail. 原因的失败结果同时记录 warn 级别日志见 TelegramSender.java。测试 TelegramSenderTest.java 验证了三个典型失败场景错误的 botTokentestSendMessageFailByParamToken、错误的 chatIdtestSendMessageFailByChatId、以及正常参数下的发送因测试环境无真实 Telegram 服务统一断言success false这为接入后的排障提供了参考——当告警发送失败时可优先检查 botToken 与 chatId 是否有效、目标环境能否连通 Telegram API。八、接入常见问题排查现象排查方向告警发送失败提示telegram server error_code ... description ...查看告警服务日志中的返回报文error_code 401通常为 botToken 无效400多为 chatId 错误或 parseMode 下正文格式不合法消息能发出但未渲染格式确认 parseMode 选择的是Markdown/MarkdownV2/Html且正文语法与所选模式匹配Txt模式下 Telegram 不会渲染任何格式标记网络不可达在服务器上测试到https://api.telegram.org的连通性必要时开启插件代理Enable Proxy YES并填写代理地址、端口及鉴权信息使用了自定义 WebHook 收不到消息确认自定义端点能正确处理插件 POST 的 JSON Bodytextchat_id非 Txt 模式下还包含parse_mode通过本文的配置指引与源码级原理说明你可以快速在 Apache 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考