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

<Note>
  Linux 方式生成的安装/升级命令会从 `https://static.flashcat.cloud/monitedge/install.sh` 拉取安装脚本。脚本托管在公网 CDN（Aliyun OSS）上，无需 `Referer` 请求头，随每次稳定版发布刷新；命令里的脚本地址是固定的，没有参数可以改成其他脚本源。

  离线或内网环境需要把 `install.sh` 和它引用的 `releases/download/<vX.Y.Z>/` 制品、`checksums.txt` 一起镜像到内网，并替换命令里的脚本地址；脚本内部的制品下载地址未参数化，镜像路径与默认公网路径不一致时需要一并调整脚本内容。
</Note>

### 部署方式对比

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

### 自动升级

Linux 部署的告警引擎支持由服务端推送的自动升级，部署方式选择 **Linux** 时页面上会提示：

> Linux 环境下的告警引擎支持服务端推送的自动升级，开启后无需手动执行升级命令；上方命令仍可作为手动升级的备用方式

推送与否由平台侧决定，控制台没有开关：完成上述安装配置后，Linux 实例会在收到推送时自行升级；尚未开通推送时，继续复制页面生成的**升级命令**在目标机器上执行即可。

| 项目 | 说明 |
| - | - |
| **适用部署方式** | 仅 Linux（systemd）部署生效；Docker 与 Kubernetes 部署不参与自动升级，升级方式仍是更换镜像版本 |
| **执行方式** | 引擎在心跳响应中收到目标版本号后，自行下载并校验制品、原子替换二进制，再以新版本继续运行；全程无需在目标机器上执行命令 |
| **升级成功** | 替换后的进程进入约 180 秒观察期，首次心跳成功即视为升级成功，本次升级完成 |
| **失败回滚** | 观察期内没有成功心跳（例如新版本无法完成认证或协议交互），或新版本连续启动仍未提交心跳（最多 3 次启动机会）时，自动回滚到上一版本 |
| **重试策略** | 本机回滚过的目标版本在平台发布更新的版本之前不再尝试；同一次升级失败后约 30 分钟内不再重试 |
| **退出自动升级** | 启动参数 `--alerter.disableAutoUpdate` 可让单个实例不再接受自动升级；容器环境、二进制所在目录不可写时也会自动跳过 |

自动升级需要引擎能够访问制品镜像，默认使用公网镜像；离线或内网环境需通过 `--alerter.updateMirror` 指向内部镜像，详见[引擎 CLI 参数参考](#引擎-cli-参数参考)的“自动升级参数”。

## 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），让退避从更长的初始间隔开始，减少拥塞期间的无效请求。

### 自动升级参数

| 参数 | 默认值 | 说明 |
| - | - | - |
| `alerter.disableAutoUpdate` | `false` | 关闭服务端推送的自动升级。设为 `true` 后该实例不再执行自动升级；容器环境会被自动识别并跳过，该参数优先级更高 |
| `alerter.updateMirror` | `https://static.flashcat.cloud/monitedge` | 自动升级制品的镜像根地址。引擎按 `<镜像根地址>/releases/download/<vX.Y.Z>/` 下载制品与校验文件；离线或内网环境需要改为内部镜像 |

自动升级仅在 Linux（systemd）部署下生效，并且要求引擎能够访问制品镜像。不满足条件时，请在控制台复制**升级命令**手动升级。


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