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

# Flashduty Monitors 入门指南

> Monitors 快速开始指南，帮助您快速上手告警功能

要体验 Monitors 功能，核心包含三个步骤：

**1. 安装 monitedge**

部署告警引擎到私有网络

**2. 创建数据源**

配置要监控的数据来源

**3. 创建告警规则**

定义告警条件和通知方式

## 安装 monitedge

`monitedge` 需要部署在用户私有网络内，负责从 SaaS 同步告警规则，周期性查询数据源并进行阈值判定，产生告警事件并推送给 SaaS 端。

**菜单入口**：数据接入 → 边缘引擎 → 引擎安装/升级

支持 Linux、Docker、Kubernetes 三种安装方式。

> [!WARNING]
>
> **引擎集群名字**非常重要：相同名字的 `monitedge` 会组成一个集群，共同分担告警规则，避免单点故障。详见[告警引擎管理](https://docs.flashduty.com/zh/monitors/engine/engine.md)。
>
> * 单套集群：保持默认的 `default` 即可
> * 多套集群（如美东机房、华南机房各一套）：请为每套集群指定不同的名字

![告警引擎安装](https://docs-cdn.flashcat.cloud/imges/mon/64af7649b50f8ba705da9067afffc36a.png)

### 告警引擎状态

`monitedge` 安装完成后，会自动连接 SaaS 端并周期性同步告警规则。您可以在告警引擎状态页面查看当前状态信息。

长期没有心跳的引擎实例会展示删除按钮，可点击移除以避免引擎失联告警。

### 引擎失联告警

建议配置引擎失联告警，在告警引擎挂掉时及时收到通知，详见[引擎失联告警](https://docs.flashduty.com/zh/monitors/engine/engine-lost-alert.md)。

## 创建数据源

**菜单入口**：数据接入 → 数据源 → 新建

![创建数据源](https://docs-cdn.flashcat.cloud/imges/mon/3eee06165afe05405db6187205f7025c.png)

| 配置项 | 说明 |
| - | - |
| **关联告警引擎** | 指定该数据源由哪个告警引擎集群进行数据查询和告警判定，通常选择同机房的集群 |
| **数据源连接地址** | 给 `monitedge` 连接的地址，必须是 `monitedge` 能访问到的内网地址 |

## 创建告警规则

**菜单入口**：规则管理 → 告警规则

告警规则可能会很多，Monitors 提供树形分组结构进行分类管理。每个告警规则都要属于某个分组，您可以先创建分组，再在分组下创建告警规则。

创建 / 编辑告警规则的页面是一个单页表单，自上而下分为六个区块：**基础配置**、**数据源与查询**、**告警判定**、**检测频率 & 生效时间**、**事件配置**、**调查入口**。

### 基础配置

![基础配置](https://docs-cdn.flashcat.cloud/imges/mon/3a2978a22d7a23dd862fdbd409adf663.png)

| 配置项 | 说明 |
| - | - |
| **所属分组** | 规则所在的分组路径（如“默认分组 / 数据库告警”）。编辑已有规则时这一行是可编辑的下拉框，按全路径列出您有权限的分组，选中并保存即把规则移到新分组；分组已被删除或您无权访问时不可编辑，需要返回规则列表重新选择分组 |
| **规则名称** | 告警规则的名称，不支持引用变量（固定名称便于过滤、聚合操作）。同一分组内必须唯一；导入、编辑或移动规则时如与目标分组中已有规则重名，操作会失败 |
| **附加标签** | 类似 Prometheus 中的 `labels`，会附加到所有告警事件上，便于过滤、路由、抑制。值的写法见下文 |

#### 附加标签的写法

附加标签的值有三种写法，按值的内容区分：

| 写法 | 示例 | 处理方式 |
| - | - | - |
| 普通文本或 `${标签名}` | `team=ops`、`instance=${host}` | 告警引擎用告警标签替换 `${标签名}` |
| 包含 `{{` 的 Go 模板 | `msg={{ index $annotations "$A.msg" }}` | 推送到协作空间之前渲染，渲染结果作为普通标签推送 |
| 以 `[TPL]` 开头 | `owner=[TPL]{{ .Labels.team }}` | 原样交给 On-call，由 On-call 渲染，写法见[告警处理](https://docs.flashduty.com/zh/on-call/integration/alert-integration/alert-pipelines.md) |

Go 模板可以使用以下变量：

| 变量 | 说明 |
| - | - |
| `$labels` | 告警的数据标签，例如 `{{ $labels.service }}` |
| `$annotations` | 查询结果附加信息和规则自定义字段。查询附加信息的 key 为 `$<查询名称>.<字段名称>`，需要用 `index` 读取，例如 `{{ index $annotations "$A.msg" }}`。详见[查询结果字段映射](https://docs.flashduty.com/zh/monitors/alert-rules/query-result-fields.md#query-fields-as-labels) |
| `$values` | 告警计算中使用到的数值，例如 `{{ index $values "$A.value" }}` |
| `$severity` | 告警级别 |
| `$status` | `firing` 或 `recovered` |

* 模板只支持 `if` / `else` 和 `index`、`len`、`printf`、`print`、`replace`、`urlquery` 以及比较、逻辑函数，不支持 `range`、`with`、`define`。
* 读取不存在的 key 时，`$labels` 和 `$annotations` 得到空字符串，`$values` 得到 `0`。渲染结果为空的标签不会推送。
* 同一个值不能同时使用 `${...}` 和 `{{...}}`。
* 渲染失败的标签不会推送，告警事件照常推送，错误原因写入 `__alert_rule_label_template_error` 标签，可在告警详情中查看。
* 标签名首尾的空白会在保存时去掉，去掉后不能重复；标签名不能以 `__alert_rule_` 开头。全部附加标签按 JSON 计合计不超过 1024 个字符，`job` 和 `instance` 的值不超过 255 个字符。
* 模板标签的渲染结果另受两条限制，超出都按渲染失败处理（标签不推送，原因写入 `__alert_rule_label_template_error`）：单个标签渲染后不超过 8 KiB；`job`、`instance` 的渲染结果不超过 255 个字符。渲染值到运行期才产生，因此这两种情况不会在保存时被拒绝。
* 告警引擎渲染备注描述、自定义字段和标题时，`$appendLabels` 中的模板标签仍是模板原文。需要在这些位置使用查询结果时，请直接引用 `$annotations`。

### 数据源与查询

区块 2 由两段组成：**数据源** 决定规则生效到哪些数据源，**查询语句** 决定从数据源里查什么、怎么查。

#### 数据源

![数据源选择](https://docs-cdn.flashcat.cloud/imges/mon/9971af45b4bc19bfe807898bf1bf10a0.png)

先选择 **数据源类型**。这里只列出已配置过数据源的类型；如果还没有任何数据源，点击 **前往数据源管理页面**（在新标签页打开，不会丢失当前表单）先创建。

然后选择规则生效到哪些数据源，一个规则可以生效到多个数据源：

* **名称通配**：按名称匹配，新建规则时默认为 `*`（该类型下的所有数据源）。`*` 匹配任意字符串（如 `db-*`），`?` 匹配单个字符，`[0-9]`、`[a-z]` 匹配字符范围，`[!0-9]` 匹配不在范围内的字符。数据源改名会影响匹配。
* **精确匹配**：从下拉列表选择具体数据源，不受改名影响。

两种方式至少填一种，可以同时使用，规则生效到两者匹配结果的并集。腾讯云 CLS 例外：只能精确绑定一个数据源。

> [!TIP]
>
> 需要不受数据源改名影响的稳定绑定时，建议使用精确匹配。详情参见[数据源管理](https://docs.flashduty.com/zh/monitors/data-sources/data-sources.md)。

> [!NOTE]
>
> 保存规则时，您需要对规则引用的每个数据源都有查询权限，包括名称通配在保存时匹配到的数据源（主体账号与 Admin 除外）。因此一条通配规则可能因为匹配到您无权查询的数据源而无法保存。只停用规则不受此限制。数据源授权见[数据源管理](https://docs.flashduty.com/zh/monitors/data-sources/data-sources.md#数据源权限团队授权)。

#### 查询语句

![查询语句](https://docs-cdn.flashcat.cloud/imges/mon/4e38b46952d6cbbfb97c2d28843dcdbe.png)

配置查询类型与查询语句。点击 **使用说明** 可以查看写法说明。表格型查询的值字段、标签字段与附加信息如何映射，详见[查询结果字段映射](https://docs.flashduty.com/zh/monitors/alert-rules/query-result-fields.md)。

#### AI 查询助手

选择数据源类型后，点击查询输入框右上角的 **AI 帮我写**，查询助手会结合当前规则的数据源、查询类型、阈值和其他查询，帮您生成或改写查询语句。

* 生成的语句和相关参数（如 SLS 的项目 / 日志库、腾讯云 CLS 的地域 / 日志主题）会自动填入表单，也可以点击结果卡片上的 **回填** 重新填入。
* 主查询、恢复查询、关联查询、查询预览，以及实体树中的 PromQL 都可以使用查询助手。
* 回填不会自动保存规则，保存前请确认语句与阈值匹配。

### 告警判定

告警判定提供三种检测方式，每种是一个页签，在页签内的卡片标题右侧启用。已启用的页签标题后会显示对勾。

| 检测方式 | 说明 |
| - | - |
| **阈值判定** | 按级别填写阈值表达式，满足条件并达到触发次数后，产生对应级别的告警。高级别触发后不再判断低级别；Critical、Warning、Info 至少填写一项 |
| **数据缺失** | “之前查到过数据，现在查不到了”或“所有查询均无返回数据”时告警，两个条件可以分别启用 |
| **数据存在** | 查询到数据即视为满足条件，达到触发次数后按设定级别产生告警 |

每个页签分为“**告警触发**”和“**告警恢复**”两张卡片（**数据缺失**页签合并为一张“**触发与恢复条件**”）。主要字段：

| 字段 | 说明 |
| - | - |
| **触发方式** | `连续命中` 或 `累计命中`，两者的区别见下一节 |
| **告警级别** | `Critical`、`Warning`、`Info` 三选一，默认 `Critical`。阈值判定的级别由命中的表达式决定 |
| **恢复方式** | 见下文[告警恢复](#告警恢复) |
| **恢复条件** | 连续 N 次正常才恢复，默认 1 |

#### 触发方式：连续命中与累计命中

| 触发方式 | 语义 | 触发条件句子 |
| - | - | - |
| **连续命中**（默认） | 连续满足条件达到设定次数才告警 | 连续 N 次检测都满足条件才告警，N 即**命中次数**，默认 3 |
| **累计命中** | 最近几次检测中，满足条件的次数达标即可，无需连续 | 最近 M 次检测中，有 N 次满足条件就告警，M 即**检测次数**，切到累计命中时默认取 `max(命中次数, 5)` |

* 累计命中下，命中次数不能大于检测次数，两者都不能超过 10000

> [!NOTE]
>
> **累计命中需要告警引擎 `v0.69.0` 及以上。** 更早版本的引擎会按连续命中执行，告警可能延迟或漏报。

#### 告警恢复

恢复方式的可选项由检测方式决定：

| 页签 | 恢复方式 |
| - | - |
| **阈值判定** | `未触发任一阈值就算恢复`（默认）、`结果满足条件才算恢复`（需要额外填写恢复表达式）、`表达式查到数据就算恢复`（需要填写恢复查询语句）、`告警保持活动，直到用户手工关闭` |
| **数据存在** | `查询检测查不到数据即恢复`（默认）、`恢复检测查到数据才恢复`（需要填写恢复查询语句）、`告警保持活动，直到用户手工关闭` |
| **数据缺失** | `所有查询均无返回数据时告警` 的恢复方式固定为“任一查询重新查到数据后自动恢复”；`之前查到过数据，现在查不到了，就告警` 可选择 `数据重新出现后自动结束`（默认）、`数据恢复或超时后自动结束`（需要填写**自动关闭时间**，单位为秒、最小 1）、`仅允许手工关闭` |

阈值判定选择 `未触发任一阈值就算恢复` 或 `结果满足条件才算恢复` 时，还可以勾选**查不到该告警对象的数据时，也算作正常**。适用于 Pod 被删除、分组查询在正常时不返回行等告警对象消失的场景：

* 告警对象由标签字段的完整取值确定。只有告警条件引用的所有查询都执行成功、且都没有返回该对象时，这一轮才算正常；部分查询返回该对象时不计数，也不清零
* 这一轮和“阈值解除”的轮次共用**恢复条件**中的连续次数；对象重新出现并再次触发阈值时，计数清零
* 查询失败、超时或结果超出上限都不算正常
* 因对象消失而恢复时，恢复事件带有标签 `__alert_rule_recovery_reason=data_absent`，事件中的数值是最后一次告警时的值
* 新建规则默认勾选；存量规则保持原行为，需要在编辑页手动勾选。勾选后，已经无法恢复的告警会在后续检测中自动恢复
* 如果对象消失本身需要告警，请同时开启数据缺失检测，两者互不影响

> [!NOTE]
>
> **该选项需要告警引擎 `v0.77.0` 及以上。** 规则处于启用状态时，如果它匹配的任一集群内有引擎低于该版本，或集群内没有已注册的引擎，勾选后保存或启用规则会被拒绝；升级引擎或取消勾选后即可保存。

### 检测频率与生效时间

![检测频率 & 生效时间](https://docs-cdn.flashcat.cloud/imges/mon/0980d71a653985a1706243fc6795685e.png)

| 配置项 | 说明 |
| - | - |
| **检测频率** | 通常是周期性检测，也支持 `cron` 表达式（精确到秒）和 `@every` 快捷写法。默认 `@every 15s`，可以从下拉选项中选择，也可以直接输入 |
| **查询时间偏移** | 设置查询时间偏移量（秒），用于处理数据源存在采集延迟的场景。例如设置为 60，则查询窗口整体向前偏移 60 秒，确保数据已完成写入后再查询。仅适用于 Prometheus、Loki、VictoriaLogs、SLS、Tencent CLS 数据源 |
| **规则时区** | 告警规则的执行时区，决定 `cron` 调度时间和**生效时间**窗口的解释方式。默认 `Asia/Shanghai`，必须填写有效的 IANA 时区名（如 `Asia/Shanghai`、`UTC`、`Europe/London`、`America/New_York`） |
| **生效时间** | 告警规则的生效时间段，非生效时间段内不会触发告警；时间窗口按上面配置的**规则时区**计算。可以添加多个时间窗，每个时间窗由星期（多选）和开始 / 结束时间（`HH:mm`）组成。默认全天生效 |

> [!WARNING]
>
> **时区填写规则**：
>
> * **规则时区**只接受 IANA 标准时区名。`Local`、`UTC+8`、`CST`、`GMT+8` 等简写或偏移量写法会被拒绝
> * **`cron` 表达式不能以 `CRON_TZ=` 或 `TZ=` 开头**。如果您从开源 cron 系统迁移过来并习惯把时区内嵌在 cron 字符串里（例如 `CRON_TZ=Asia/Shanghai 0 0 * * *`），请去掉前缀，把时区填到**规则时区**字段中
>
> **cron 表达式格式规则**：
>
> * `cron` 表达式必须是 **6 段秒级表达式**，顺序为秒、分、时、日、月、周。5 段写法（例如 `*/5 * * * *`）会被拒绝，需要补充秒字段（例如 `0 */5 * * * *`）
> * 支持 `@every` 快捷写法，例如 `@every 30s`，表示每 30 秒检测一次。时长必须是**不小于 1 秒的整数秒**，支持 `@every 1m30s` 这类组合时长；`@every 0s`、`@every 1500ms` 等亚秒或不满足整秒的写法会被拒绝
> * 编辑旧规则时，不符合上述格式的检测频率需要先修正才能保存

> [!NOTE]
>
> 重复通知的最大次数和重复间隔，以及各检测方式的命中次数和恢复次数都必须不小于 1，否则规则不会执行。

### 事件配置

事件配置依次为协作空间、备注描述、重复发送配置，以及自定义字段与关联查询两个平铺小节。

| 配置项 | 说明 |
| - | - |
| **协作空间** | 指定 Flashduty On-call 中的协作空间，不指定则根据集成路由规则投递 |
| **备注描述** | 非结构化文本字段，支持引用变量，便于值班人员快速定位问题 |
| **重复通知** | 告警未恢复时持续通知，可配置间隔和最大次数（默认 10000 次） |
| **自定义字段** | 类似 Prometheus 中的 `annotations`，可附加仪表盘 URL、SOP URL 等。点标题右侧的 `+` 在弹窗里填 **字段名** 与 **字段值**；已添加的字段以 `键=值` 标签列出，点标签可再次修改、点标签上的 × 删除，字段名不能为空也不能重复 |
| **关联查询** | 独立小节，有自己的新增按钮；查询结果不作为阈值判定依据，但可在备注中作为变量引用（如附加日志样例）。某条关联查询在告警引擎上渲染、执行或取字段失败时，它的结果不出现在 `__alert_rule_relate_values` 标签里，失败原因按「查询名: 错误」逐条写入 `__alert_rule_relate_query_error` 标签 |

> [!NOTE]
>
> 最大通知次数并不代表终端用户收到的消息提醒次数。因为 Monitors 产生的告警事件会投递到 On-call，可能会被聚合降噪，最终发送次数取决于 On-call 配置。

### 调查入口

区块 6 用于配置**调查入口**：把每条告警直接接到一个仪表盘视图或一份查好的初始查询上，值班人员从告警一跳就能看到该看的图、该查的数据。

| 配置项 | 说明 |
| - | - |
| **添加仪表盘入口** | 选择仪表盘并可定位到整个仪表盘、某个标签页、分组或图表，同时为该仪表盘的模板变量指定取值 |
| **添加查询入口** | 保存一份初始查询（数据源 + 查询类型 + 查询语句 + 查询参数），默认在告警事件自己的数据源上执行 |
| **调查用途** | 一句话说明这个入口帮助确认什么，可选 |
| **时间范围** | 「告警前 N 分钟，至告警后 M 分钟」，以告警事件时间为锚点，默认告警前 60 分钟、告警后 30 分钟 |

最多 20 个入口，可以拖动调整顺序（顺序只影响展示）；点击入口右侧的眼睛图标可以**预览跳转**：不使用模板变量的入口按当前表单配置和当前时间预览，使用模板变量的入口按该规则的一条真实告警快照预览。入口随规则保存生效，渲染成快照后随告警事件下发，因此改规则不会影响已经产生的告警。

> [!WARNING]
>
> 保存调查入口需要集群内所有告警引擎实例为 `v0.75.3` 或以上版本，否则保存会被拒绝。

字段含义、模板变量、校验限制与快照语义详见[调查入口](https://docs.flashduty.com/zh/monitors/alert-rules/investigation-entries.md)。

## 查看效果

完成配置后，如果告警条件触发，告警规则行的**活跃告警**列会出现该规则当前的活跃告警数量。

![告警规则列表页面](https://docs-cdn.flashcat.cloud/imges/mon/6f1fad7d65b5aee6b89bf0f0a564a1be.png)

> [!TIP]
>
> 告警规则列表的搜索框支持按规则名称、规则 ID 或标签进行搜索过滤，方便快速定位规则。也可以通过 URL 参数 `?rule_id=<ID>` 直接跳转到指定规则。

规则列表用两列描述一条规则的现状：**状态**列是规则的运行状态（健康度，取值见下一节 **规则运行详情**），点击状态标签可以打开运行详情抽屉；**活跃告警**列是该规则当前的活跃告警数量，数量大于 0 时显示为红色。

点击**活跃告警**列的数量，页面会切换到“活跃告警”标签页，并按该规则自动过滤，方便直接查看该规则当前产生的活跃告警。历史告警事件可到 On-call 中查看。详见[活跃告警](https://docs.flashduty.com/zh/monitors/alert-rules/active-alerts.md)。

## 规则运行详情

告警规则列表的每一行都提供运行时自省能力。点击行操作菜单（行尾 `⋮`，菜单项依次为运行详情、克隆、移动、历史版本、删除）中的**运行详情**，打开规则运行详情抽屉，帮助您判断规则的执行健康度并快速排障。

抽屉顶部可以选择要查看的**数据源**（规则可能绑定多个数据源）；这个选择器按查看者对各数据源的查询（`readonly`）权限过滤，没有查询权限的数据源会被静默丢弃，受限查看者看到的数据源可能少于规则实际绑定的数量。下方分为两个标签页：

### 当前状态

* **状态徽章**：规则当前的运行状态，取值和处理建议见下方表格。列表的**状态**列显示的就是这个徽章
* **最近执行**：执行时间、执行耗时、执行结果、查询结果数、最近成功、连续失败、运行阶段、状态更新时间
* **告警实例**：活跃实例总数，并按检测方式拆分为阈值判定、数据存在、数据缺失，以及最近产生的事件类型（告警触发、重复通知、告警恢复、告警关闭）
* **告警引擎与配置**：负责该规则的告警引擎集群、告警引擎实例、版本、在线状态和最近心跳

| 状态 | 出现时机 | 处理建议 |
| - | - | - |
| **运行正常** | 最近一次执行成功 | 无需处理 |
| **执行异常** | 最近一次执行失败，通常是查询语句或数据源报错 | 打开运行详情查看错误类型和错误摘要，修正查询或数据源 |
| **等待运行状态** | 尚未收到告警引擎上报的运行状态：规则可能仍在下发、还没跑过第一轮，或当前引擎版本不支持上报运行状态 | 稍后刷新；长时间不变时检查告警引擎版本与规则下发 |
| **状态已过期** | 超过预期执行周期仍未收到新的运行状态 | 检查负责该规则的告警引擎是否在线，以及规则的数据源是否可连通 |
| **非生效时间** | 规则当前不在**生效时间**窗口内，告警引擎按设计不执行这条规则 | 无需处理；此时展示的是最近一次已知结果，不是故障 |
| **未匹配数据源** | 规则没有匹配到任何可用数据源，例如数据源被删除或改名 | 在规则的数据源配置里重新选择数据源 |
| **Edge 离线** | 负责该规则的告警引擎实例心跳超时 | 检查告警引擎进程与到 SaaS 的网络连通性 |
| **配置待生效** | 规则配置已保存，告警引擎尚未按新版本上报，传播完成前可能仍在执行旧配置 | 等待下发完成；长时间不变时检查告警引擎同步 |
| **规则已停用** | 规则被禁用 | 需要继续监控时重新启用规则 |
| **未知运行状态** | 当前控制台版本无法识别的运行状态 | 刷新页面，或升级控制台到最新版本 |

当状态为 `等待运行状态` 或 `状态已过期` 时抽屉会说明原因；状态为 `非生效时间` 或 `规则已停用` 时，抽屉会提示此时看到的是最近一次已知结果；状态为 `配置待生效` 时，抽屉会说明告警引擎可能仍在执行旧配置。负责该规则的告警引擎不在线，或执行出现错误时，会以醒目横幅展示错误类型和错误摘要。

### 执行历史

按时间范围查询该规则的历史执行记录（支持最近 15 分钟、1 小时、4 小时、1 天，最长 24 小时）。每条记录带执行摘要徽章：`执行失败`、`产生事件`、`告警恢复`、`定期采样`；展开后可查看日志入库时间、告警引擎实例与集群、运行阶段、连续失败次数、各检测模式活跃实例数、产生的事件以及错误摘要。

> [!NOTE]
>
> 执行历史只记录关键执行摘要（异常、事件、恢复和定期采样），不保证每轮评估都生成记录；匹配记录超过 200 条时仅展示最近 200 条，请缩小时间范围。

## 批量操作

告警规则列表支持多选后进行批量操作，提升规则管理效率。

### 批量启用/禁用/删除

在列表中勾选多条规则后，可以一键批量启用、批量禁用或批量删除。

### 批量编辑字段

勾选多条规则后点击**批量更新**，可以统一修改以下 10 个字段：

| 可批量编辑的字段 | 说明 |
| - | - |
| **附加标签** | 统一设置 labels，支持增量修改与全量替换两种方式 |
| **数据源** | 统一切换数据源 |
| **检测频率** | 统一调整检测周期 |
| **规则时区** | 统一切换告警规则的 IANA 时区 |
| **生效时间** | 统一配置生效时间段 |
| **查询时间偏移** | 统一设置查询时间偏移。仅当所有选中规则的数据源都支持（Prometheus、Loki、VictoriaLogs、SLS、Tencent CLS）时可用 |
| **自定义字段** | 统一配置 annotations，支持增量修改与全量替换两种方式 |
| **协作空间** | 统一指定告警投递的协作空间 |
| **重复发送配置** | 统一设置重复通知间隔和次数 |
| **调试日志** | 统一开启或关闭调试日志 |

操作方式：在批量更新面板中先选择要修改的字段，然后设置新值，点击确定即可批量应用到所有选中规则。

批量更新**附加标签**和**自定义字段**时，使用专用的元数据编辑器，支持两种更新方式：

| 更新方式 | 说明 |
| - | - |
| **增量修改**（默认） | 逐条添加“设置”或“删除”操作，指定键和值。编辑时会根据所选规则的现有内容自动补全，并预览每个操作会影响多少条规则。自定义字段的键不能以 `$` 开头，同一批操作中的键不能重复 |
| **全量替换** | 用下方填写的内容完全替换每条规则的该字段，会删除每条规则中未在下方填写的其他内容 |

> [!WARNING]
>
> 修改附加标签可能影响告警路由、聚合或降噪，请谨慎操作。

部分规则更新失败时，会提示失败条数和第一个失败原因，其余规则照常更新。

### 批量移动

勾选多条规则后，点击列表上方的 **移动**，将它们批量移动到其他文件夹。只移动一条时，点击该行行尾 `⋮` 菜单里的 **移动**。

两种入口都打开 **移动到其他分组** 对话框：在树里选择目标文件夹，或先在 **搜索分组** 框里按名称过滤；选中的就是当前文件夹时 **确定** 保持禁用。成功后提示 `移动成功` 并刷新列表。详见[文件夹管理](https://docs.flashduty.com/zh/monitors/folders/folders.md)。

## 导入告警规则

**菜单入口**：告警规则 → 导入

导入采用文件上传方式，一次上传一个规则文件（`.yaml`、`.yml` 或 `.json`，不超过 1 MB）。系统会自动识别文件格式，并在导入前展示预检结果，支持以下四种来源：

| 来源格式 | 说明 |
| - | - |
| **Flashduty Rules YAML** | Flashduty 原生规则 bundle，与导出功能产出的格式一致，适合跨租户或跨环境迁移规则 |
| **Flashduty 规则 JSON** | 历史版本的 Flashduty 规则 JSON 格式 |
| **Prometheus Rules YAML** | 标准的 Prometheus 告警规则 YAML，要求以 `groups` 为根节点，YAML 缩进必须正确 |
| **Nightingale 规则 JSON** | Nightingale v6-v9 的规则 JSON |

### 导入配置

文件上传后可以配置：

* **同名规则处理方式**：`跳过同名规则`（默认，目标分组中已有同名规则时不导入）或 `创建副本`（为同名规则创建副本）
* **导入后启用规则**：仅对 Flashduty Rules YAML 来源显示。关闭时，导入的 Flashduty 规则保持停用
* **协作空间**：指定告警事件投递的协作空间

### 预检结果

系统解析文件后展示预检结果表格，逐条列出规则的导入名称、状态（`可导入` / `跳过` / `无效`）和说明。勾选要导入的规则（默认选中所有可导入的规则）后提交。

> [!NOTE]
>
> Nightingale 规则导入后统一保持停用，需检查数据源匹配和转换警告后再手动启用。常见的转换说明包括：Doris 数据源映射为 MySQL、仅保留最高级别告警条件、级别抑制/查询关联/通知目标等配置未保留、恢复语义按 Flashduty 规则能力近似转换、`Local` 时区转换为 `Asia/Shanghai`、全天生效时间转换为 `00:00-23:59`、缺少评估间隔时持续时间按 15 秒间隔换算等。

### 导入结果

提交后系统展示导入结果：成功、跳过和无效的条数。如果一条都没有导入成功，可以在弹窗中查看原因后重新选择。

## 导出告警规则

在列表中勾选需要导出的规则，点击**导出**按钮。系统以 YAML 格式（Flashduty Rules YAML bundle）展示所选规则的完整配置，您可以：

* **下载**：将 YAML 保存为 `alert-rules.yaml` 文件
* **复制**：将 YAML 内容复制到剪贴板

导出的 YAML 可用于备份，也可以通过文件上传方式导入到其他环境，详见[导入告警规则](#导入告警规则)。

## 规则历史版本

点击规则列表行尾 `⋮` 菜单中的**历史版本**，查看规则的历史修改情况（需要规则的更新权限）。

### 查看历史版本

历史版本列表展示以下信息：

| 列信息 | 说明 |
| - | - |
| **版本** | 版本号，最新一版带“当前版本”标记 |
| **操作人** | 执行变更的用户 |
| **操作时间** | 变更发生的时间 |

### 版本对比

在历史版本列表中勾选两个版本，点击**对比**按钮，系统会以 JSON diff 的方式展示两个版本之间的差异，帮助您快速了解具体修改了哪些配置项。


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