> ## 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.

# Peekaping 告警集成

> 通过 Webhook 通知渠道将 Peekaping 监控的宕机与恢复同步到 Flashduty On-call。

Peekaping 是开源的自托管监控系统。通过 Peekaping 的 Webhook 通知渠道（Notification Channel），可以把监控状态变化同步到 Flashduty On-call：监控宕机时在 Flashduty 触发告警，恢复时自动恢复。

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

  ***

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

  ### 使用专属集成

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

  ### 使用共享集成

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

## 在 Peekaping 中配置

***

需要 Peekaping 0.0.46 或更高版本，并使用有权限管理通知渠道和监控的账号登录。Peekaping 所在的服务器需要能访问 Flashduty 的推送地址。

<Steps>
  <Step title="创建 Webhook 通知渠道">
    1. 在 Peekaping 的 **通知渠道** 页面点击 **新建通知渠道**，**通知器类型** 选择 **Webhook**
    2. **POST 地址** 粘贴 Flashduty 集成的完整推送地址，地址中需包含 `integration_key`
    3. **请求体** 选择 **application/json**。`multipart/form-data` 和 `Custom` 两种格式 Flashduty 不支持
    4. 保存通知渠道
  </Step>

  <Step title="将通知渠道关联到监控">
    1. 打开需要告警的监控，在通知渠道中勾选上一步创建的渠道，保存
  </Step>

  <Step title="验证">
    1. 在通知渠道的编辑页面点击 **测试** 按钮，确认 Peekaping 显示发送成功。测试请求是 Peekaping 内置的固定内容（监控名称 `Test Monitor`），Flashduty 会为它创建一条独立的 Info 告警，不会与真实告警合并，也不会自动恢复，验证后请在 Flashduty 中手动关闭
    2. 让被监控的服务不可用，确认 Flashduty 出现 Critical 活动告警
    3. 服务恢复后，确认该告警自动恢复
  </Step>
</Steps>

## Alert Key

***

Flashduty 使用请求中的 `monitor.id`（监控 ID）作为 Alert Key。同一个监控宕机和恢复时的 `monitor.id` 相同，因此恢复会关闭对应的告警；`heartbeat.id` 每次心跳都不同，不参与 Alert Key。

监控名称、状态消息、时间等字段变化不会改变 Alert Key。请求中缺少 `monitor.id` 会被拒绝。`monitor.id` 只在同一个 Peekaping 实例内唯一，一个 Flashduty 集成请只接收一个 Peekaping 实例的推送。

## 状态和告警等级

***

| `heartbeat.status` | 含义 | Flashduty 处理 |
| :- | :- | :- |
| `0` | 宕机（Down） | 触发 Critical 告警 |
| `1` | 正常（Up） | 恢复 |
| `2` | 等待（Pending） | 忽略，不产生事件 |
| `3` | 维护（Maintenance） | 忽略，不产生事件 |

Peekaping 本身没有告警等级，宕机统一映射为 Critical。告警标题为监控名称，描述为心跳消息（例如 `TCP connection failed: ...`）。

## 标签

***

| 标签 | 来源 |
| :- | :- |
| `check` | `monitor.name`，监控名称 |
| `source` | 固定为 `peekaping` |
| `monitor_id` | `monitor.id` |
| `monitor_type` | `monitor.type`，例如 `http`、`tcp` |

监控的 `config`（包含主机、凭据等）和 `push_token` 不会进入标签或描述。

## 排查问题

***

* **Flashduty 返回参数错误**：确认 URL 完整且包含 `integration_key`，并确认通知渠道的 **请求体** 为 `application/json`；响应信息会指出缺少的字段
* **Peekaping 测试失败**：确认 Peekaping 所在服务器能访问 Flashduty 推送地址，并查看 Peekaping 日志中的 HTTP 状态码
* **告警没有恢复**：确认监控确实恢复到正常状态，并且通知渠道仍关联在该监控上
* **重复宕机通知**：若监控设置了重复通知间隔（Resend Interval），宕机期间会重复发送，Flashduty 按同一 Alert Key 合并到同一条告警


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.