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

# ntopng 告警集成

> 通过 ntopng 的 Webhook Endpoint 将主机、接口和流量告警的触发与释放事件同步到 Flashduty On-call。

通过 ntopng 的 Webhook Endpoint 将 ntopng 告警同步到 Flashduty On-call。ntopng 对主机、接口、网络等实体的告警会先发送 `engage`（触发），条件消失后发送 `release`（释放）；Flashduty 用同一个 Alert Key 关联这两条消息，触发时创建告警，释放时自动恢复。流量（Flow）告警只发送一次，没有释放消息。

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

  ***

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

  ### 使用专属集成

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

  ### 使用共享集成

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

## 在 ntopng 中配置

***

<Steps>
  <Step title="创建 Webhook Endpoint">
    1. 用管理员账号登录 ntopng
    2. 选择 **Notifications → Endpoints**，点击 **+**
    3. Endpoint 类型选择 **Webhook**，名称可填写 `Flashduty`
    4. 将 Flashduty 集成的完整推送地址（包含 `integration_key`）粘贴到 Webhook URL
    5. **Shared Secret**、**Username**、**Password** 留空即可。Flashduty 通过推送地址中的 `integration_key` 认证，不校验这几项；如果填写了 Shared Secret，它会出现在每条请求里，但不会写入 Flashduty 告警
  </Step>

  <Step title="创建 Recipient">
    1. 选择 **Notifications → Recipients**，点击 **+**
    2. 选择上一步创建的 `Flashduty` Endpoint，填写 Recipient 名称
    3. 将 **Notifications Type** 改为 **Alerts**。默认值是 **Active Scan Reports**，该类型不会发送告警，Flashduty 收不到任何事件
    4. 按需设置最低告警等级（Minimum Severity）、告警类别、实体类型和主机池，只有符合条件的告警才会发送
    5. 点击 **Check** 发送一次测试请求，再点击 **Add** 保存 Recipient
  </Step>

  <Step title="验证生命周期">
    触发一条主机告警（例如让某台主机触发 ntopng 的阈值检查），确认 Flashduty 收到活动告警；条件消失、ntopng 释放这条告警后，确认 Flashduty 中的告警自动恢复。
  </Step>
</Steps>

## Alert Key

***

ntopng 在 `engage` 和 `release` 消息里携带相同的接口 ID（`ifid`）、实体类型（`entity_id`）、实体值（`entity_val`）、告警类型（`alert_id`）和子类型（`subtype`），Flashduty 用这五项生成 Alert Key。ntopng 自身也用实体值、告警类型和子类型来区分已触发的告警。分值（`score`）、时间戳、主机名和检查周期会随消息变化，不参与 Alert Key。

流量（Flow）告警的 `action` 为 `store`，每条独立成为一条告警。同一条流因条件变化被 ntopng 重新发送时，Alert Key 保持不变：它由接口、告警类型、VLAN、客户端和服务端的 IP 与端口、协议以及流的首次出现时间生成。

`engage`、`release` 消息缺少 `alert_id`、`entity_id` 或 `entity_val` 时，Flashduty 会返回参数错误并指出字段名。

## 告警等级

***

ntopng 的告警等级由 `score` 决定，Flashduty 按下表映射。`score` 缺失或不是数字时按 Info 处理。

| ntopng `score` | ntopng 等级 | Flashduty 等级 |
| :- | :- | :- |
| 100 及以上 | Error、Critical、Emergency | Critical |
| 50 到 99 | Warning | Warning |
| 50 以下 | None、Info、Notice | Info |

## 恢复与测试

***

* **`release`**：按 Alert Key 关闭对应告警，并保留释放前的告警等级。
* **`store`（流量告警）和其他没有释放消息的告警**：不会自动恢复。请在 Flashduty 集成或协作空间中开启 **超时自动关闭**，建议设置为 24 小时。
* **Check 按钮**：ntopng 会发送一个 `version` 为 `0.2` 且 `alerts` 为空的请求。Flashduty 返回成功，并创建一条标题为 `ntopng test notification` 的 Info 告警，它使用独立的 Alert Key，不会与真实告警合并，也不会自动恢复，请手动关闭。

一个请求最多包含 10 条告警（ntopng 的单次发送上限）。Flashduty 为每条告警创建一个事件，并保持请求中的顺序。

## 排查问题

***

* **ntopng 提示发送失败**：确认 Webhook URL 完整，包含 `integration_key`，并且 ntopng 所在服务器能访问 `api.flashcat.cloud`。ntopng 在失败时会重试 3 次
* **Flashduty 返回参数错误**：检查请求体是否为 JSON，且每条 `engage`、`release` 告警都有 `alert_id`、`entity_id`、`entity_val`
* **告警没有恢复**：流量告警没有释放消息；其他告警需要 ntopng 先释放，请在 ntopng 的 **Alerts** 页面确认这条告警是否仍处于触发状态
* **收不到告警**：检查 Recipient 的最低告警等级、告警类别和实体过滤条件，以及 ntopng 是否启用了告警生成

更多说明请参阅 [ntopng 官方文档的 Endpoint 与 Recipient 章节](https://github.com/ntop/ntopng/blob/dev/doc/src/user_interface/shared/alerts/available_endpoints.rst)。