> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flashduty.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Wormly 告警集成

> 通过联系人的 Webhook 通道将 Wormly 主机的宕机、升级和恢复通知同步到 Flashduty On-call。

通过 Wormly 联系人（Contact）的 Webhook 通道，把主机（Host）的故障和恢复通知同步到 Flashduty On-call。每个 Wormly 主机对应一条 Flashduty 告警：主机故障时触发，持续故障期间按告警组的升级级别重复发送的通知合并到同一条告警，主机恢复时关闭这条告警。

<div className="hide">
  ## 在 Flashduty On-call

  ***

  您可通过以下两种方式获取集成推送地址，任选其一即可。

  ### 使用专属集成

  1. 进入 Flashduty 控制台，选择 **协作空间**，打开一个协作空间
  2. 选择 **配置** → **集成数据** → **专属集成**，点击 **新增一个集成**
  3. 选择 **Wormly**，点击 **保存**
  4. 打开生成的集成卡片，复制 **推送地址**

  ### 使用共享集成

  1. 进入 Flashduty 控制台，选择 **集成中心 → 告警事件**
  2. 选择 **Wormly**，填写集成名称
  3. 配置默认路由并选择协作空间；创建后可在 **路由** 中增加更多规则
  4. 点击 **保存**，复制生成的 **推送地址**
</div>

## 在 Wormly 中配置

***

<Steps>
  <Step title="创建 Webhook 联系人">
    1. 登录 Wormly，进入 **Contacts**，点击 **Create New Contact**
    2. 通道选择 **Webhook**
    3. 将 Flashduty 集成的完整推送地址粘贴到 URL 字段
    4. Webhook 类型选择 JSON 格式（`JSON` 或 `JSON - multipart/form encoding` 均可，Flashduty 两种都能解析；不要选择 XML 和 Serialized PHP）
    5. 保存
  </Step>

  <Step title="在告警组中启用该联系人">
    在 **Alert Groups** 中编辑需要接入的告警组，把刚创建的联系人加入相应的升级级别（Escalation Level）。一个告警组可以被多个主机使用。
  </Step>

  <Step title="验证生命周期">
    让一个被监控的主机真正故障（例如临时把监控地址指向一个不可访问的端口），确认 Flashduty 收到活动告警；再恢复目标，确认原告警恢复。
  </Step>
</Steps>

<Note>
  Wormly 要求接收端与被监控的服务器不在同一台服务器上，请求超时时间为 5 秒。Flashduty 的推送地址满足这一要求。
</Note>

## 推送内容

***

Wormly 每次通知发送一个 JSON 对象，Flashduty 直接解析，无需配置模板：

| 字段 | 含义 | 在 Flashduty 中 |
| :- | :- | :- |
| `hostid` | Wormly 主机 ID | Alert Key，标签 `host_id` |
| `name` | 主机名称 | 告警标题，标签 `check`、`host` |
| `isrecovery` | `0` 表示故障，`1` 表示已从之前的故障中恢复 | 触发或恢复 |
| `downtime` | 主机已宕机的秒数 | 标签 `downtime_seconds`，写入描述 |
| `alertlevel` | 当前升级级别 ID | 标签 `alert_level` |
| `alertlevel_name` | 当前升级级别名称 | 标签 `alert_level_name`，写入描述 |
| `failedsensors` | 未通过检查的传感器数组，元素含 `type`、`sensorid`、`message` | 标签 `sensor_types`、`sensor_ids`，错误信息写入描述 |

告警标题使用主机名称；主机名称为空时使用 `Wormly host <hostid>`。请求既可以是 JSON 请求体，也可以是把 JSON 放在表单字段 `wormlyalert` 中的 urlencoded 或 multipart 表单。

## Alert Key

***

Flashduty 使用 `hostid` 作为 Alert Key。Wormly 文档将它定义为触发告警的 Wormly 主机的唯一 ID。同一个主机的故障、升级重复通知和恢复通知携带相同的 `hostid`，因此会落在同一条告警上；不同主机即使名称相同，也会生成不同的告警。修改主机名称、升级级别或传感器不会改变 Alert Key。

请求缺少 `hostid` 时，Flashduty 会返回参数错误，因为无法可靠地把恢复通知关联到原告警。

## 状态和告警等级

***

Wormly 的通知不区分告警等级，`alertlevel` 表示升级步骤而不是严重程度，Flashduty 对所有故障统一按 Critical 处理。

| Wormly `isrecovery` | Flashduty 状态或等级 |
| :- | :- |
| `0` | Critical |
| `1` | 恢复，原等级为 Critical |

`isrecovery` 缺失或不是 `0`、`1` 的请求会被拒绝，避免把无法判断状态的请求写入错误的告警生命周期。

## 常见问题

***

<AccordionGroup>
  <Accordion title="持续故障时会产生多条 Flashduty 告警吗？">
    不会。主机持续故障期间，告警组每次升级发出的通知都带相同的 `hostid`，会合并到同一条告警中。同一主机上多个传感器同时失败时，Wormly 在一条通知中列出它们，Flashduty 仍然是一条告警。
  </Accordion>

  <Accordion title="联系人的测试按钮会创建告警吗？">
    联系人表单中的 **Send Test** 按钮总是发送一条带示例 `hostid`（`5112`）的故障通知，因此会创建一条以 `5112` 为 Alert Key 的告警。测试之后不会有恢复通知，请在 Flashduty 中手动关闭这条告警。不含任何已知字段的空 JSON 对象会被直接确认，不创建告警。
  </Accordion>

  <Accordion title="可以把 Wormly 的 XML 或 Serialized PHP 格式发过来吗？">
    不可以。Flashduty 只解析 JSON 格式，请在 Wormly 的 Webhook 类型中选择 JSON。
  </Accordion>
</AccordionGroup>

## 排查问题

***

* **Wormly 推送失败**：确认 URL 是完整的推送地址，且包含 `integration_key`
* **Flashduty 返回参数错误**：确认 Webhook 类型是 JSON，且请求中的 `hostid`、`isrecovery` 非空
* **告警没有恢复**：确认恢复通知会发送到同一个联系人，Wormly 会在主机恢复后通知所有收到过故障通知的接收方

字段说明请参阅 Wormly 官方文档 [Webhook / HTTP Alert Channel](https://www.wormly.com/help/channels/http-rpc)。