> ## 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.serverConcurrency` | `64`                         | 并行推送告警事件的 worker goroutine 数量 |
| `alerter.serverTimeout`     | `30s`                        | 单次推送请求的超时时间                   |
| `alerter.serverRetry`       | `2`                          | 推送失败时的最大重试次数                  |
| `alerter.serverSleep`       | `3s`                         | 两次重试之间的等待时间                   |

<Note>
  引擎启动时会按 `alerter.serverConcurrency` 的值启动对应数量的 worker goroutine，它们从同一个内部队列并发消费并推送告警事件。若将该值设为小于 1，引擎会自动修正为 1（单 worker 串行推送）。
</Note>

**重试策略说明**：当前采用"少次长超时"策略——每次请求最多等待 30 秒，最多重试 2 次。这与早期版本的"多次短超时"策略（10 秒超时、最多 40 次重试）有所不同。新策略更适合网络质量稳定但偶有抖动的场景，能避免在网络短暂拥塞时产生大量无效重试。

**调优建议**：

* **高吞吐场景**（规则数量多、告警频率高）：可适当提高 `alerter.serverConcurrency`（例如 128），以减少事件在内部队列中的积压时间。
* **网络或 CPU 受限场景**：可适当降低 `alerter.serverConcurrency`（例如 16–32），避免并发出站连接过多影响其他业务流量。
* **网络质量差、丢包率高的场景**：可适当增大 `alerter.serverRetry`（例如 5）并缩短 `alerter.serverTimeout`（例如 10s），以便更快发现失败并重试。