OneUptime Discord 集成实战:用内置工作流组件把事件推送到 Discord 频道

原创2026-09-15 14:10:561,878 阅读
文章标签:可观测性后端运维前端云原生微服务AI Agent

OneUptime Discord 集成实战:用内置工作流组件把事件推送到 Discord 频道

本篇指南基于 OneUptime 官方文档(Discord Integration),讲解如何通过内置 Discord 工作流组件,把事件(Incident)的创建、确认与解决动态实时推送到指定 Discord 频道。你将掌握从创建 Webhook、配置密钥全局变量,到搭建并验证工作流的完整流程,并能对照源码理解该组件在执行时的参数校验、域名锁定(SSRF 防护)与成败分流机制。

集成模式:一条出站长链

Discord 集成是典型的**出站(outbound)**集成:OneUptime 通过 Discord 的 incoming webhook URL 向频道发消息,而不是 Discord 反向调用 OneUptime。官方文档给出的数据流如下:

OneUptime Incident → On Create  ──►  Discord component  ──►  message in your channel

即:事件触发器(On Create)→ Discord 组件 → 频道内收到消息。这一模式与 OneUptime 所有出站集成(Jira、PagerDuty、GitHub 等)共用同一套抽象:事件触发器 + API/专用组件 + 密钥变量,详见 集成总览。

第 1 步 —— 在 Discord 中创建 Webhook

  1. 在 Discord 中打开目标频道,进入 Edit Channel → Integrations → Webhooks;
  2. 点击 New Webhook,给它命名(例如 OneUptime),选择消息落地频道,然后 Copy Webhook URL。

得到的 URL 形如 https://discord.com/api/webhooks/<id>/<token>,这正是组件元数据中给出的占位格式(见 Discord 组件定义 中 placeholder 字段)。

第 2 步 —— 存储 Webhook URL(可选但强烈建议)

  1. 在 OneUptime 中进入 Workflows → Global Variables → Create;
  2. 变量命名为 DISCORD_WEBHOOK_URL,粘贴 Webhook URL,并开启 Is Secret。

把 URL 放进全局变量有两个好处:跨工作流复用、轮换时只改一处。从组件定义看,webhook-url 参数本身被标记为 isSensitive: true(见 Common/Types/Workflow/Components/Discord.ts),也就是说即使直接粘贴,该字段也会按敏感信息处理;但集中到全局变量仍是文档推荐的更稳妥做法。

第 3 步 —— 搭建工作流

  1. 打开 Workflows → Create Workflow,命名如 Incidents → Discord,进入 Builder;
  2. 添加一个 Incident 触发器,事件选择 On Create,并将节点重命名为 Incident;
  3. 添加 Discord 组件(Send Message to Discord)并连接到触发器,配置两个必填参数:
    • Discord Incoming Webhook URL:{{variable.DISCORD_WEBHOOK_URL}}(也可以直接粘贴 URL);
    • Message Text:🔴 New incident: {{Incident.title}}\n{{Incident.description}};
  4. Save 并启用工作流,然后手动创建一条测试事件——消息即出现在你的频道中。

组件的两个入参在源码中都有明确定义(Common/Types/Workflow/Components/Discord.ts):

参数 id 名称 类型 必填 说明
webhook-url Discord Incoming Webhook URL URL 是 标记为敏感信息(isSensitive: true)
text Message Text LongText 是 要发送到 Discord 的消息正文,支持模板变量

组件对外暴露 in 一个入端口和 success / error 两个出端口,执行结果另返回一个可选的 error 值,便于在后续节点判断投递是否失败。

备选方案 —— 用 API 组件直接调 Webhook

如果不想用专用组件,一个 API 块也能完成同样的事:

  • Method:POST
  • URL:{{variable.DISCORD_WEBHOOK_URL}}
  • Headers:Content-Type: application/json
  • Body:{ "content": "New incident: {{Incident.title}}" }

这条路线的价值在于:需要 Discord 更丰富的 embeds(富文本卡片)时,可以在 body 里追加 embeds 数组来构造卡片消息,而专用 Discord 组件目前只发送纯 content 文本(见下文源码分析)。

源码解析 —— Discord 组件到底做了什么

执行逻辑位于 SendMessageToChannel.ts,核心流程有四点值得注意:

  1. 参数校验:text 为空时直接抛 BadDataException("Discord message not found") 并走错误端口(L61-L63)。
  2. Webhook URL 域名锁定:组件并不直接信任 webhook-url 参数,而是先经 IncomingWebhookUtils.getPinnedWebhookUrl 校验,URL 必须落在 DISCORD_WEBHOOK_DOMAINS(discord.com 或 discordapp.com,且为 https)之上,否则以 "Discord Webhook URL must be an https URL on discord.com or discordapp.com" 终止工作流。
  3. 禁用重定向:实际 POST 时显式设置 doNotFollowRedirects: true(L81-L87),注释里写得很直白——跟随重定向会把请求目标交还给控制该主机的人。
  4. 成败分流:请求返回 HTTPErrorResponse 时走 error 端口并把错误信息放入返回值;成功则走 success 端口。

源码注释(IncomingWebhookUtils.ts)解释了"锁定"优于"黑名单"的原因:Slack / Discord / Microsoft Teams 这类聊天 webhook 组件的 webhook-url 参数由任意项目成员填写、还可由触发器数据模板化生成,属于与通用 API 组件相同的 SSRF 原语;而聊天 webhook 有明确的厂商域名可以锁定,锁定能防住 DNS rebinding、非标准 IP 写法与重定向绕过,且对自托管部署没有任何损失——自托管的 OneUptime 照样向官方 webhook 域名发消息。

实战技巧

  • 按严重级别过滤:在 Discord 块之前用 Conditions 节点对 {{Incident.incidentSeverity.name}} 做分支,只为特定严重级别的消息发帖,避免低级别事件刷屏。
  • 覆盖事件全生命周期:再建若干挂在 Incident → On Update 上的工作流,把确认(acknowledgement)与解决(resolution)也发到同一频道,形成"创建 → 确认 → 解决"的完整播报链。
  • 需要富文本时切换 API 组件:专用组件只支持 content 纯文本;想要 embeds 卡片就走上文给出的 API 组件方案,在 body 中补充 embeds 数组。

延伸阅读

说明:本文以仓库中的 Discord 集成文档(da 版) 为主体骨架,操作步骤与 英文版文档 保持一致;源码部分对应 OneUptime 当前仓库的实际实现,适用于使用 Workflows 引擎(事件触发器 + 组件画布)的部署形态。

登录后查看全文
oneuptime