refactor notify-rules

Author: UlricQin

content/zh/docs/usage/notify-rules.md

@@ -16,7 +16,7 @@ toc: true
 
 ## 设计初衷
 
-老版本的夜莺没有通知规则的概念，是在告警规则里直接配置通知媒介和通知接收人，虽然直观，但是不够灵活，有如下问题：
+老版本的夜莺没有通知规则的概念，是在告警规则里直接配置通知媒介和通知接收人，虽然直观，但是不够灵活，有如下问题（如果是新用户，可以跳过下面的问题背景）：
 
 - 告警规则中启用抑制之后，通知媒介仍然只能写死的问题。之前版本的告警规则中如果启用了抑制规则，通常意味着，不同的阈值想要使用不同的级别，进而使用不同的通知媒介发送告警，比如 Critical 级别的告警使用电话、短信，Info 级别的告警使用 Email。但是之前版本的告警规则中，通知媒介是写死的，无法做到不同的级别不同的媒介。
 - 接入电话、短信等通知方式不方便。这次我们提供了通用的 HTTP、脚本发送方式，HTTP 的参数、Header、Body 都可以自定义，这样一来，可以更方便接入不同通知媒介了。
@@ -29,36 +29,58 @@ toc: true
 
 <img src="/img/usage/notify-rules/01.png" alt="通知规则和告警规则的联动逻辑"/>
 
-之前的版本，是在告警规则里直接配置通知媒介+告警接收人，耦合严重。新版本是在告警规则里关联通知规则，具体如何发送是在通知规则里定义的，这样一来，告警规则和通知规则解耦，多个告警规则可以关联一个通知规则，如果想要改动通知方式，只需要改动通知规则即可。
+- **告警规则** 负责产生告警事件，**通知规则** 负责对事件做后续处理、通知
+- **告警规则** 的配置中，选择关联的 **通知规则**
 
-## 配置说明
+## 配置原理
+
+> 这部分讲解了通知规则的原理逻辑，建议您阅读。如果您着急，也可以先阅读[具体配置举例](#具体配置举例)，实操之后再回来阅读原理。
 
 通知规则可以支持不同的通知媒介，而且可以定义不同的媒介适用的范围，比如电话这个通知媒介，只适用于 Critical 的告警，而 Email 则适用于 Critical、Warning、Info 所有告警。下面是一个通知规则配置样例：
 
 <img src="/img/usage/notify-rules/02.png" alt="通知规则配置样例"/>
 
-对于通知媒介，我们会内置一些，方便大家开箱即用：
+夜莺内置了几十种通知媒介，方便大家开箱即用：
 
 <img src="/img/usage/notify-rules/03.png" alt="内置媒介列表"/>
 
-打开通知媒介的配置，其中有个「变量配置」不太好理解。我说个场景：比如 DBA 团队和 BigData 团队都想使用企微这个通知媒介发告警，但是他们想使用不同的企微机器人，即 Webhook 地址基本相同，但是 URL 参数中的 Key 不同（不同的 Key 代表不同的机器人）。此时应该怎么做？
+打开通知媒介的配置，其中有个「变量配置」稍难理解。可以把通知媒介看做一个 function，把「变量配置」看做是在定义这个 function 的参数。
+
+**需求场景一**
+
+比如 DBA 团队和 BigData 团队都想使用企微这个通知媒介发告警，但是他们想使用不同的企微机器人（即机器人的 Webhook 中的 Key 不同）。此时应该怎么做？
+
+**使用变量传入企微机器人的 Key**
+
+DBA 和 BigData 两个团队各自在配置通知规则时，都选用企微通知媒介，但是传入不同的机器人 Key 作为参数。
+
+**具体配置方法**
 
-在夜莺的设计里，不希望创建两个不同的通知媒介。还是希望只有企微一个通知媒介，但是这个通知媒介支持传参，DBA 同学在配置告警通知规则的时候，选择企微这个通知媒介的同时，要填写自己的机器人的 Key，BigData 同学也是一样，也是配置企微通知媒介 + BigData 的企微机器人 Key。这样一来，一个通知媒介就可以支持多个机器人了。
+内置的企微媒介支持两个参数（在「变量配置」定义，相当于在定义 function 的参数）：
 
-如何让通知媒介支持参数呢？就是在媒介的变量配置中进行创建。内置的企微通知媒介就是创建了两个参数，一个 Key（表示企微机器人Key），一个 Bot Name（机器人名称，自定义的，纯粹是为了方便记忆，类似备注的效果）。进而，在企微媒介的 HTTP 配置中，就可以引用这个参数，比如：
+- key：表示企微机器人 Key
+- bot_name：自定义机器人名称，相当于备注
+
+企微的 「HTTP 配置」可以看做 function 的实现，在实现里可以引用参数。
 
 <img src="/img/usage/notify-rules/04.png" alt="通知媒介变量定义"/>
 
-这个场景相对简单，媒介通知的时候，获取用户填写的 Key 即可。还有更复杂的场景。比如发短信，此时媒介参数如何定义？如果直接定义成 Phone，然后让用户在通知规则中手写手机号，那就有点费劲了。而且用户的联系方式如果发生变化，除了要到个人中心修改自己的手机号，还要到通知规则里改，太过麻烦。而手机号已经在个人的联系方式中了，那直接把二者贯通即可。
+之后，在通知规则中即可使用“企微通知媒介”（类似于在通知规则中做 function 的最终调用，调用时传入 key 和 bot_name 参数的值）。
+
+**需求场景二**
+
+短信发送场景下，需要给「短信媒介」传入手机号才可以，但如果在通知规则中写具体的手机号就不够灵活，比如用户的联系方式发生变化，就要修改所有的通知规则。
+
+实际上，用户的个人联系方式中，已经包含手机号信息了，在通知规则中调用某个“通知媒介”的时候，直接选择用户、团队作为接收者，无需填写具体的手机号。
 
 对于这类场景，可以概括为：媒介需要的参数来自用户的 Profile 信息。这个时候，就需要在媒介的变量配置中，引用用户的 Profile 信息。比如：
 
 <img src="/img/usage/notify-rules/05.png" alt="通知媒介管理用户 Profile"/>
 
-媒介变量这里，联系方式选择 Phone，然后就会有一系列的魔法，魔法效果是：
+媒介变量这里，联系方式选择 Phone，运行机制为：
 
-- 通知规则那里，系统根据媒介里的 Phone 联系方式，知道用户想发通知给某些人，通知规则那里就可以选择联系人或团队了，而不是手写手机号。
-- 在 HTTP 的 request body 或 query string 中，可以引用一个魔法变量：`{{ $sendto }}`，表示被通知对象的手机号。这样一来，通知媒介就可以根据这个变量，把告警通知发给正确的人了。`{{ $sendto }}` 这个设计是从 Zabbix 学的，如果你用过 Zabbix，应该会很熟悉。
+- 通知规则那里，自动出现用户、团队的选择框，您可以在此选择告警接收人。
+- 在 HTTP 的 request body 或 query string 中，可以引用一个变量：`{{ $sendto }}`，表示被通知对象的手机号。这样一来，通知媒介就可以根据这个变量，把告警通知发给正确的人了。`{{ $sendto }}` 这个设计和 Zabbix 是一样的。
 
 ## 具体配置举例
 
@@ -69,8 +91,6 @@ toc: true
 - [对接钉钉、飞书、企微通知](https://flashcat.cloud/blog/n9e-v8-notify-practice/)
 - [对接阿里云短信](https://flashcat.cloud/docs/content/flashcat-monitor/nightingale-v7/usage/notification/ali-sms/)
 
-另外，在微信视频号：SRETALK 上也放置了一个视频教程，演示如何接入飞书告警，您可以自行搜索查看。
-
 ## 邮件告警配置
 
 上面给的文档链接讲解了常用的 IM 告警媒介，这里再补充一个邮件告警的配置说明。要想发送告警邮件，核心有三个地方需要注意：