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

# 告警引擎管理

> 管理告警引擎的安装、状态监控和 API Key，确保告警检测持续运行

告警引擎（`monitedge`）是部署在你私有网络中的核心组件，负责从 Flashduty SaaS 端同步告警规则，从本地数据源读取数据进行异常判定，并将告警事件推送到 SaaS 端进行后续处理。

**菜单入口**：告警引擎

告警引擎页面包含三个标签页：**告警引擎状态**、**引擎安装/升级**、**引擎失联告警**。

## 告警引擎状态

展示所有已注册的告警引擎实例信息，列表每 5 秒自动刷新。

| 列信息         | 说明                             |
| ----------- | ------------------------------ |
| **引擎集群名字**  | 同名实例组成一个集群，共同分片处理告警规则          |
| **引擎实例 IP** | 实例运行的 IP 地址                    |
| **引擎实例端口**  | 实例监听的端口号                       |
| **上次心跳时间**  | 最近一次向 SaaS 上报心跳的时间，附带在线/离线状态指示 |
| **引擎实例版本**  | 当前运行的 `monitedge` 版本号          |

<Note>
  引擎实例超过 30 秒未上报心跳，状态会标记为离线（红色）。离线的引擎实例会显示**删除**按钮，你可以点击清除已不存在的实例记录。
</Note>

### 集群数据源 MD5 校验

同一集群内的多个引擎实例应该使用相同的数据源配置。如果系统检测到集群内不同实例的数据源配置 MD5 不一致，会在集群名称前显示红色警示标记，提示你尽快检查引擎配置。

## 引擎安装/升级

提供一键生成安装和升级命令的功能，支持三种部署方式。

### 安装配置

<Steps>
  <Step title="选择部署方式">
    选择 **Linux**、**Docker** 或 **Kubernetes**。
  </Step>

  <Step title="设置引擎集群名字">
    同机房部署多个实例时，使用相同的集群名字可组成高可用集群。不同机房使用不同的集群名字。

    <Tip>
      一般每个机房分别部署一套告警引擎集群，集群名字建议设置为机房名称。
    </Tip>
  </Step>

  <Step title="选择 API Key">
    从下拉列表中选择已有的 API Key，或点击**管理 API Key**创建新的 Key。
  </Step>

  <Step title="复制命令执行">
    页面会根据你的选择自动生成安装命令和升级命令，复制后在目标机器上执行即可。
  </Step>
</Steps>

### 部署方式对比

| 部署方式           | 适用场景                          |
| -------------- | ----------------------------- |
| **Linux**      | 直接在物理机或虚拟机上安装，使用 systemd 管理进程 |
| **Docker**     | 容器化部署，适合已有 Docker 环境的场景       |
| **Kubernetes** | 适合云原生环境，以 Deployment 方式部署     |

## API Key 管理

API Key 用于告警引擎与 SaaS 端的身份认证。你可以在引擎安装/升级页面点击**管理 API Key**打开管理面板。

### 功能说明

| 操作      | 说明                                       |
| ------- | ---------------------------------------- |
| **新增**  | 创建新的 API Key，需要输入名称。每个租户最多创建 5 个 API Key |
| **重命名** | 点击 Key 名称即可编辑修改                          |
| **删除**  | 删除不再使用的 API Key，需要具备 API Key 删除权限        |

管理面板中还会展示每个 API Key 的当前状态：

| 状态            | 说明                                      |
| ------------- | --------------------------------------- |
| **启用中**（绿色图标） | API Key 正常工作，引擎实例可以使用该 Key 与 SaaS 端通信   |
| **禁用中**（黄色图标） | API Key 已被禁用，使用该 Key 的引擎实例将无法与 SaaS 端通信 |

<Warning>
  删除 API Key 后，使用该 Key 的所有引擎实例将无法与 SaaS 端通信。请确保在删除前已将相关引擎切换到其他有效的 API Key。
</Warning>

### 权限要求

* 创建 API Key 需要 `ApiKeyCreate` 权限
* 删除 API Key 需要 `ApiKeyDelete` 权限

如果你没有操作权限，请联系管理员前往访问控制页面授权。

## 引擎 CLI 参数参考

`monitedge` 二进制通过命令行参数进行配置。以下是与告警推送相关的核心参数。

### 告警推送参数

| 参数                                       | 默认值                          | 说明                                                                        |
| ---------------------------------------- | ---------------------------- | ------------------------------------------------------------------------- |
| `alerter.serverURL`                      | `https://api.flashcat.cloud` | FlashDuty SaaS 服务地址                                                       |
| `alerter.serverAPIKey`                   | —（必填）                        | 用于与 SaaS 端认证的 API Key                                                     |
| `alerter.serverTimeout`                  | `30s`                        | 单次推送请求的超时时间                                                               |
| `alerter.alertRuleDeliveryWorkers`       | `64`                         | 普通告警规则事件投递的 worker 数量。事件按告警 key 分区到各 worker 队列，同一条告警的事件始终由同一个 worker 串行投递 |
| `alerter.alertRuleEventQueueSize`        | `2048`                       | 每个投递 worker 的事件队列容量                                                       |
| `alerter.alertRuleEventBatchSize`        | `200`                        | 单次批量投递的事件条数上限，最大 200。队列中的事件会攒批发送，满一批或暂时无新事件时即投递                           |
| `alerter.alertRuleDeliveryResponseBytes` | `8MB`                        | 投递接口响应体的大小上限，超出后本次请求按失败处理                                                 |
| `alerter.serverSleep`                    | `3s`                         | 批量投递失败后的重试退避初始间隔，每次失败后翻倍，最大 30 秒                                          |

普通告警规则的 firing / repeat / recovery 事件由批量投递服务（alertruledelivery）发送到 SaaS 端 `POST /monit/api/edge/alert-rule/v1/events` 接口：事件先进入各 worker 的队列，再按批次合并发送，单批不超过 200 条事件且不超过 4 MB。

**重试策略说明**：批量投递采用指数退避重试——首次失败后等待 `alerter.serverSleep`（默认 3 秒），之后每次失败等待时间翻倍，最大 30 秒，重试没有次数上限，直到投递成功或引擎实例关闭。相比旧的固定间隔重试，指数退避能在网络短暂拥塞时避免高频无效重试。

<Note>
  早期版本通过 `alerter.serverConcurrency` 和 `alerter.serverRetry` 控制一个内部内存队列的并发消费（固定间隔、有限次数重试）。该消费者已不再启动，普通告警规则的投递已切换到上述批量投递服务，这两个参数不再生效，无需配置。
</Note>

**调优建议**：

* **高吞吐场景**（规则数量多、告警频率高）：可适当提高 `alerter.alertRuleDeliveryWorkers`（例如 128），减少事件在队列中的积压时间；必要时同步提高 `alerter.alertRuleEventQueueSize`。
* **网络或 CPU 受限场景**：可适当降低 `alerter.alertRuleDeliveryWorkers`（例如 16–32），避免并发出站连接过多影响其他业务流量。
* **网络质量差、丢包率高的场景**：可适当增大 `alerter.serverSleep`（例如 10s），让退避从更长的初始间隔开始，减少拥塞期间的无效请求。