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

# 夜莺/Flashcat 集成

> 通过 Webhook 将夜莺（Nightingale / n9e）或 Flashcat 告警事件推送到 Flashduty，实现告警的触发与自动恢复

## 前置条件

***

<Tabs>
  <Tab title="在夜莺/Flashcat">
    * 您必须拥有修改 **系统配置 → 全局通知** 或 **告警管理 → 告警规则** 的权限
    * 您的夜莺 Server 必须能够访问域名 `api.flashcat.cloud`
  </Tab>

  <Tab title="在 Flashduty">
    * 您必须拥有 Flashduty 账户并具备创建集成的权限
    * 您需要提前创建好协作空间并配置分派策略
  </Tab>
</Tabs>

## 版本说明

***

<CardGroup cols={2}>
  <Card title="v8.0.0-beta.7+" icon="sparkles" href="#v8">
    推荐使用，支持在通知规则中直接配置协作空间，无需配置路由规则
  </Card>

  <Card title="v5 ~ v8.0.0-beta.6" icon="clock-rotate-left" href="#v5-v8">
    通过 Webhook 回调地址配置，需要在 Flashduty 中设置路由规则
  </Card>
</CardGroup>

## 在 Flashduty 获取推送地址

***

您可以通过以下两种方式获取推送地址，请根据您的需求选择。

### 方式一：专属集成（推荐）

当您不需要将告警事件路由到不同的协作空间时，优先选择此方式。

<Steps>
  <Step title="进入协作空间">
    登录 [Flashduty 控制台](https://console.flashcat.cloud)，选择 **协作空间**，进入目标空间的详情页面。
  </Step>

  <Step title="添加集成">
    选择 **集成数据** 标签页，点击 **添加一个集成**，选择 **夜莺/Flashcat** 集成类型，点击 **保存**。
  </Step>

  <Step title="获取推送地址">
    点击生成的集成卡片，复制 **推送地址** 备用。

    <Tip>
      点击 **编辑** 按钮，在 **控制台地址** 中输入夜莺控制台域名，Flashduty 将为新告警自动生成夜莺详情跳转链接。
    </Tip>
  </Step>
</Steps>

### 方式二：共享集成

当您需要根据告警事件的 Payload 信息将告警路由到不同的协作空间时，选择此方式。

<Steps>
  <Step title="进入集成中心">
    登录 [Flashduty 控制台](https://console.flashcat.cloud)，选择 **集成中心 → 告警事件**。
  </Step>

  <Step title="创建集成">
    选择 **夜莺/Flashcat** 集成，填写以下信息：

    * **集成名称**：为当前集成定义一个名称
    * **控制台地址**：（可选）输入夜莺控制台域名
  </Step>

  <Step title="配置路由规则">
    配置默认路由并选择对应的协作空间。您可以稍后在 **路由** 页面配置更多路由规则。
  </Step>

  <Step title="获取推送地址">
    点击 **保存** 后，复制生成的 **推送地址** 备用。
  </Step>
</Steps>

## 在夜莺/Flashcat 配置通知

***

<span id="v8" />

### v8.0.0-beta.7+ 版本配置

<Note>
  在新版本中，您可以直接在告警通知规则中配置协作空间，但仍需要在 Flashduty 中提前创建协作空间并配置分派策略。
</Note>

<Steps>
  <Step title="添加通知媒介">
    1. 登录 n9e 控制台，选择 **告警管理 → 通知媒介**，点击 **新增**
    2. 填写媒介名称和标识，选择 **Flashduty** 类型
    3. 在 `URL` 字段填写 Flashduty 的推送地址
    4. 点击 **保存**

    ![添加通知媒介](https://download.flashcat.cloud/flashduty/doc/zh/fd/n9e-1.png)
  </Step>

  <Step title="配置通知规则">
    1. 选择 **告警管理 → 通知规则**，点击 **新增** 或编辑已有规则
    2. 在 **通知配置** 中选择上一步创建的 Flashduty 通知媒介
    3. 选择告警应发送到的协作空间（需提前在 [Flashduty](https://console.flashcat.cloud/channel) 中创建）
    4. 点击 **保存**

    ![配置通知规则](https://download.flashcat.cloud/flashduty/doc/zh/fd/n9e-2.png)
  </Step>

  <Step title="关联告警规则">
    1. 选择 **告警管理 → 告警规则**，点击 **新增** 或编辑已有规则
    2. 在 **通知配置** 中选择上一步创建的通知规则
    3. 点击 **保存**

    ![关联告警规则](https://download.flashcat.cloud/flashduty/doc/zh/fd/n9e-3.png)

    <Check>
      配置完成后，当告警触发时，夜莺会自动将告警推送到 Flashduty。
    </Check>
  </Step>
</Steps>

<span id="v5-v8" />

### v5 \~ v8.0.0-beta.6 版本配置

您可以选择以下两种配置方式之一。

<Tabs>
  <Tab title="按策略配置">
    批量选择告警规则并配置 Webhook 回调地址。

    <Steps>
      <Step title="进入告警规则">
        登录 n9e 控制台，选择 **告警管理 → 告警规则**。
      </Step>

      <Step title="批量更新">
        批量选中需要配置的告警规则，点击右上角 **批量更新告警规则**。
      </Step>

      <Step title="配置回调地址">
        在弹窗中选择 **回调地址** 字段，在输入框中填写 Flashduty 的推送地址。

        ![批量配置回调地址](https://download.flashcat.cloud/saas-n9e-rule.png)
      </Step>

      <Step title="验证配置">
        返回 Flashduty 集成列表，确认是否显示了 **最新事件时间**。

        <Check>
          如果显示了最新事件时间，说明配置成功且已收到事件。
        </Check>
      </Step>
    </Steps>
  </Tab>

  <Tab title="全局配置">
    配置全局 Webhook 地址，推送所有告警事件。

    <Tabs>
      <Tab title="V6 及以上版本">
        <Steps>
          <Step title="进入通知设置">
            登录 n9e 控制台，进入 **系统配置 → 通知设置 → 回调地址**。
          </Step>

          <Step title="启用 Webhook">
            启用一个新的 Webhook，在 `URL` 字段填写 Flashduty 的推送地址。

            ![全局 Webhook 配置](https://download.flashcat.cloud/flashduty/integration/n9e/n9e_v6_webhook.png)
          </Step>
        </Steps>
      </Tab>

      <Tab title="V5.4 ~ V5.15 版本">
        <Steps>
          <Step title="编辑配置文件">
            登录 n9e Server 实例，找到并打开配置文件（通常为 `etc/server.conf`）。
          </Step>

          <Step title="添加 Webhook 配置">
            在 `Alerting` 配置部分添加以下内容：

            ```toml server.conf theme={null}
            [Alerting.Webhook]
            Enable = true
            Url = "{您的推送地址}"
            BasicAuthUser = ""
            BasicAuthPass = ""
            Timeout = "5s"
            Headers = ["Content-Type", "application/json", "X-From", "N9E"]
            ```

            <Warning>
              请将 `Url` 的值替换为您在 Flashduty 获取的推送地址。
            </Warning>
          </Step>

          <Step title="重启服务">
            保存配置文件并重启 n9e Server 使配置生效。
          </Step>

          <Step title="验证配置">
            返回 Flashduty 集成列表，确认是否显示了 **最新事件时间**。
          </Step>
        </Steps>
      </Tab>
    </Tabs>
  </Tab>
</Tabs>

## 严重程度映射

***

夜莺/Flashcat 与 Flashduty 的告警等级映射关系如下：

| 夜莺等级 | Flashduty 等级 | 说明 |
| :--: | :----------: | :- |
|   1  |   Critical   | 严重 |
|   2  |    Warning   | 警告 |
|   3  |     Info     | 提醒 |

## 常见问题

***

<AccordionGroup>
  <Accordion title="为什么 Flashduty 没有收到告警？">
    #### 在 Flashduty 排查

    1. **检查最新事件时间**：查看集成是否显示了 **最新事件时间**。如果没有，说明 Flashduty 未收到推送，请优先排查夜莺配置。

    2. **检查路由规则**：如果您使用的是 **共享集成**，请确认是否配置了 **路由规则**。未配置路由规则时，系统会拒绝新的推送。

    #### 在夜莺/Flashcat 排查

    1. **确认告警已生成**：前往 **告警管理 → 历史告警**，确认配置 Webhook 后是否产生了新告警（状态必须为 **Triggered**）。

    2. **验证回调地址**：进入告警详情，检查 **回调地址** 是否与 Flashduty 推送地址完全匹配。

    3. **检查网络连通性**：登录夜莺 Server，确认可以访问 `api.flashcat.cloud` 域名。

    ```bash theme={null}
    curl -I https://api.flashcat.cloud
    ```

    4. **查看错误日志**：如果网络正常，请检查 Server 日志中是否存在相关错误信息。

    <Tip>
      如果以上步骤仍无法解决问题，请联系 Flashduty 技术支持。
    </Tip>
  </Accordion>

  <Accordion title="告警恢复后 Flashduty 中的故障没有自动关闭？">
    请确认以下几点：

    1. 夜莺告警规则配置了恢复通知
    2. 恢复事件的 Webhook 回调地址与触发事件一致
    3. 告警的唯一标识（fingerprint）在触发和恢复时保持一致
  </Accordion>

  <Accordion title="如何测试集成是否配置成功？">
    您可以通过以下方式测试：

    1. 在夜莺中手动触发一条测试告警
    2. 等待几秒后，检查 Flashduty 集成列表中的 **最新事件时间** 是否更新
    3. 进入协作空间，确认是否生成了对应的故障
  </Accordion>
</AccordionGroup>