OneUptime Discord 集成实战:用内置工作流组件把事件推送到 Discord 频道
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
- 在 Discord 中打开目标频道,进入 Edit Channel → Integrations → Webhooks;
- 点击 New Webhook,给它命名(例如
OneUptime),选择消息落地频道,然后 Copy Webhook URL。
得到的 URL 形如 https://discord.com/api/webhooks/<id>/<token>,这正是组件元数据中给出的占位格式(见 Discord 组件定义 中 placeholder 字段)。
第 2 步 —— 存储 Webhook URL(可选但强烈建议)
- 在 OneUptime 中进入 Workflows → Global Variables → Create;
- 变量命名为
DISCORD_WEBHOOK_URL,粘贴 Webhook URL,并开启 Is Secret。
把 URL 放进全局变量有两个好处:跨工作流复用、轮换时只改一处。从组件定义看,webhook-url 参数本身被标记为 isSensitive: true(见 Common/Types/Workflow/Components/Discord.ts),也就是说即使直接粘贴,该字段也会按敏感信息处理;但集中到全局变量仍是文档推荐的更稳妥做法。
第 3 步 —— 搭建工作流
- 打开 Workflows → Create Workflow,命名如
Incidents → Discord,进入 Builder; - 添加一个 Incident 触发器,事件选择 On Create,并将节点重命名为
Incident; - 添加 Discord 组件(Send Message to Discord)并连接到触发器,配置两个必填参数:
- Discord Incoming Webhook URL:
{{variable.DISCORD_WEBHOOK_URL}}(也可以直接粘贴 URL); - Message Text:
🔴 New incident: {{Incident.title}}\n{{Incident.description}};
- Discord Incoming Webhook URL:
- 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,核心流程有四点值得注意:
- 参数校验:
text为空时直接抛BadDataException("Discord message not found")并走错误端口(L61-L63)。 - 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" 终止工作流。 - 禁用重定向:实际 POST 时显式设置
doNotFollowRedirects: true(L81-L87),注释里写得很直白——跟随重定向会把请求目标交还给控制该主机的人。 - 成败分流:请求返回
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数组。
延伸阅读
- 集成总览 — 入站/出站两大集成模式、密钥管理与各工具认证速查表;
- Telegram 集成 — 同样的出站思路在 Telegram 上的落地;
- 组件参考:Discord 组件元数据、执行实现、Webhook 域名锁定工具。
说明:本文以仓库中的 Discord 集成文档(da 版) 为主体骨架,操作步骤与 英文版文档 保持一致;源码部分对应 OneUptime 当前仓库的实际实现,适用于使用 Workflows 引擎(事件触发器 + 组件画布)的部署形态。