insight: update doc of alert notification using v1alpha2

docs/zh/docs/insight/faq/alertnotify-enable-v2api.md

@@ -1,94 +1,43 @@
 # Insight 告警通知开启  v1alpha2
 
-Insight 引入了新的模板体系，新的模板体系在渲染的数据结构上做了调整，因此和旧版本（v1alpha1）存在兼容性的问题。
-为了避免产生兼容性的问题，默认不启用。用户需要主动开启。
-需要特别注意的是，开启时，需要立即迁移模板到 v1alpha2 语法，否则将产生“使用已保存的原消息模板无法正常发送告警消息”错误的问题。（运维实践：记住备份旧模板数据）
+Insight 引入了新的模板体系，新的模板体系在渲染的数据结构上做了调整，因此和旧版本（v1alpha1） **存在兼容性** 的问题。 因此 默认不启用 v1alpah2。运维可以根据客户的需求开启。
 
-本文接下来将介绍：
+!!! note
 
-- [开启新模板](#v1alpha2)
-- [迁移至新模板](#_1)
+    开启后，需要 **立即迁移模板到 v1alpha2 语法** ，否则告警消息将无法正常的发送给 企业微信、电子邮件、飞书等。
+    **运维最佳实践，务必通过 SQL 备份旧模板数据。**
 
-## 启用 v1alpha2
+## 为什么引入新的模板
 
-### 方法 1：(推荐) 通过 helm 命令 upgrade
+引入 v1alpah2 的原因是调整模板可以到的数据，在 v1alpah2 的模板里可以访问到 **更多更完整的** 告警数据。
 
-1. 在 Helm upgrade 的执行命令中增加如下参数：
+![告警通知v1alpha2说明](../images/alert-v1alpha2.png)
 
-    ```shell
-    --set server.alerting.notifyTemplate.version="v1alpha2"
-    ```
+### 两个版本数据访问的差异
 
-2. 除 #1 之外亦可编辑 helm 的 values 文件，如下：
+在 **v1alpha1** 版本 模板访问到的数据 有 2 个 限制：
 
-    ```diff
-    server:
-      alerting:
-        notifyTemplate:
-    -     version: v1alpha1
-    +     version: v1alpha2
-    ```
+1. 除了 “邮件标题” 之外，模板只能用模板格式化某一条 Alert 的数据（<span style="color: #87CEEB;">蓝色部分</span>）。因此，一些 **换行符** ，还有 **首行的 `[1]FIRING` 字样** 无法定制。
 
-### 方法 2：临时调整配置文件（configmap）
+    ![告警通知v1alpha2](../images/alert-v1alpha2-notify.png)
 
-1. 编辑 insight-server 的配置文件（configmap）insight-server-config，调整配置文件如下：
+2. “邮件标题” 仅能访问 CommonLabels 里的数据（<span style="color: orange;">橙色部分</span>）。
 
-    ```diff
-    alerting:
-      notifyTemplate:
-    -   version: v1alpha1
-    +   version: v1alpha2
-    ```
-
-2. 编辑保存之后，重启 insight-server 即可。
-
-## 模板迁移
+而在 **v1alpha2** 版本里修复了这 2 个限制，任何模板都可以完整放到告警 Data 数据（<span style="color: purple;">紫色部分</span>）。
 
-模板的迁移主要是因为数据结构从 AmAlert 调整为 AMHookRequest，新的模板语句可以渲染和展示更多的有用信息。
-
-### 数据架构
-
-这是 v1alpha2 的模板里使用的结构：
-
-```go
-type AMHookRequest struct {
-	Version           string            `protobuf:"bytes,1,opt,name=version,proto3" json:"version,omitempty"`
-	GroupKey          string            `protobuf:"bytes,2,opt,name=groupKey,proto3" json:"groupKey,omitempty"`
-	Status            string            `protobuf:"bytes,3,opt,name=status,proto3" json:"status,omitempty"`
-	Receiver          string            `protobuf:"bytes,4,opt,name=receiver,proto3" json:"receiver,omitempty"`
-	GroupLabels       map[string]string `protobuf:"bytes,5,rep,name=groupLabels,proto3" json:"groupLabels,omitempty" protobuf_key:"bytes,1,opt,name=key,proto3" protobuf_val:"bytes,2,opt,name=value,proto3"`
-	CommonLabels      map[string]string `protobuf:"bytes,6,rep,name=commonLabels,proto3" json:"commonLabels,omitempty" protobuf_key:"bytes,1,opt,name=key,proto3" protobuf_val:"bytes,2,opt,name=value,proto3"`
-	CommonAnnotations map[string]string `protobuf:"bytes,7,rep,name=commonAnnotations,proto3" json:"commonAnnotations,omitempty" protobuf_key:"bytes,1,opt,name=key,proto3" protobuf_val:"bytes,2,opt,name=value,proto3"`
-	ExternalURL       string            `protobuf:"bytes,8,opt,name=externalURL,proto3" json:"externalURL,omitempty"`
-	Alerts            []*AmAlert        `protobuf:"bytes,9,rep,name=alerts,proto3" json:"alerts,omitempty"`
-	TruncatedAlerts   int64             `protobuf:"varint,10,opt,name=truncatedAlerts,proto3" json:"truncatedAlerts,omitempty"`
-}
-```
+因为作用域的调整，所以导致  v1alpha1 和 v1alpha2 存在不兼容的情况。具体的差异是： **需要在模板里手动通过 go-templates 的 `range` 关键字手动遍历循环 Alerts 数据数据。**
 
-这是 v1alpha1 的模板里使用的结构：
-
-```go
-type AmAlert struct {
-	Status       string            `protobuf:"bytes,1,opt,name=status,proto3" json:"status,omitempty"`
-	Labels       map[string]string `protobuf:"bytes,2,rep,name=labels,proto3" json:"labels,omitempty" protobuf_key:"bytes,1,opt,name=key,proto3" protobuf_val:"bytes,2,opt,name=value,proto3"`
-	Annotations  map[string]string `protobuf:"bytes,3,rep,name=annotations,proto3" json:"annotations,omitempty" protobuf_key:"bytes,1,opt,name=key,proto3" protobuf_val:"bytes,2,opt,name=value,proto3"`
-	StartsAt     string            `protobuf:"bytes,4,opt,name=startsAt,proto3" json:"startsAt,omitempty"`
-	EndsAt       string            `protobuf:"bytes,5,opt,name=endsAt,proto3" json:"endsAt,omitempty"`
-	GeneratorURL string            `protobuf:"bytes,6,opt,name=generatorURL,proto3" json:"generatorURL,omitempty"`
-	Fingerprint  string            `protobuf:"bytes,7,opt,name=fingerprint,proto3" json:"fingerprint,omitempty"`
-}
-```
+### 升级示例
 
-可以注意到，最大的差别是，旧结构仅仅是新结构的 `.Alerts`  字段，新结构提供更丰富的 CommonLabels，CommonAnnotations 等信息。
+我们以邮件的正文和标题的模板为例，讲解 2 个不同版本的差异：
 
-## 示例
+#### 邮件正文
 
-以邮件通知模板为例，下面是新旧模板的 diff。可以看到，第二行新增了 `{{range .Alerts}}` 语法，只需将原有模板包裹在 `range` 关键字中即可。
-需要特别注意的是，邮件的标题和正文**共享相同的数据结构**，不再进行特殊处理，从而降低心智负担。
+下面是邮件正文新旧模板的 diff。
 
-```diff
-+<b style="font-weight: bold">[{{ .Alerts | len -}}] {{.Status}}</b><br />
-+{{range .Alerts}}
+```text linenums="1"
+<b style="font-weight: bold">[{{ .Alerts | len -}}] {{.Status}}</b><br />
+{{range .Alerts}}
 ruleName: {{ .Labels.alertname }} <br />
 groupName: {{ .Labels.alertgroup }} <br />
 severity: {{ .Labels.severity }} <br />
@@ -101,29 +50,36 @@ value: {{ .Annotations.value }} <br />
 startsAt: {{ .StartsAt }} <br />
 {{if ne "0001-01-01T00:00:00Z" .EndsAt }} EndsAt: {{ .EndsAt }} <br /> {{ end }}
 description: {{ .Annotations.description }} <br />
-+<br />
-+{{end}}
+<br />
+{{end}}
 ```
 
+1. `第 2 行` 和 `第 16 行` ，分别新增了 `{{range .Alerts}}` 和 `{{end}}`，将旧版本的模板包裹在 `range` 关键字中。基本上大多数的模板只要这么处理。
+2. `第 15 行`，增加 `<br />` 作为换行符。渲染出来的内容不会 “堆叠在” 一起，而是按照 Alert 一组一组展示。
+
+#### 邮件标题
+
+需要特别注意的是，v1alpha2 的邮件模板的标题和正文 **共享相同的数据结构** ，不再进行特殊处理，从而降低负担。
+
 旧模板的写法：
 
-```
+```text
 [{{ .status }}] [{{ .severity }}] alert: {{ .alertname }}
 ```
 
-新模板里，可以注意到 severity 调整为 CommonLabels.severity，这才是原始的无额外处理的数据结构。
+新模板里，可以注意到 severity 调整为 CommonLabels.severity，这才是原始的数据结构。
 
-```
+```text
 [{{ .Status }}] [{{ .CommonLabels.severity }}] alert: {{ .CommonLabels.alertname }}
 ```
 
-### 更多示例
+#### 更多示例
 
-飞书、钉钉和企业微信的通知模板。
+飞书、钉钉和企业微信的通知模板：
 
-```diff
-+[{{ .Alerts | len -}}] {{.Status}}
-+{{range .Alerts}}
+```text
+[{{ .Alerts | len -}}] {{.Status}}
+{{range .Alerts}}
 Rule Name:   {{ .Labels.alertname }}
 Group Name:  {{ .Labels.alertgroup }}
 Severity:    {{ .Labels.severity }}
@@ -136,5 +92,48 @@ Cluster:     {{ .Labels.cluster | toClusterName }}
 Starts At:   {{ .StartsAt }}
 {{if ne "0001-01-01T00:00:00Z" .EndsAt }}Ends At:     {{ .EndsAt }}
 {{ end }}Description: {{ .Annotations.description }}
-+{{end}}
+{{end}}
 ```
+
+## 如何在 Insight 中启用 v1alpha2
+
+当确认需要 开启 v1alpah2 的能力之后，我们可以通过如下的 2 个配置开启。需要注意：
+
+1. **内置模板** ：insight-server 内置一套中文和英文的模板，开启 v1alpha2 之后，程序会自动更新 内置模板 到新版本，无需迁移；
+2. **客户创建模板** ：因为兼容性问题，insight-server 默认不会迁移客户创建的模板。因此，在模板迁移之前，所有的告警通知都将失效，因为无法正确的解析模板，无法正确的生成通知内容，因此无法通知到外部的 webhook，邮件，企业微信。
+
+!!! note
+
+    注意，如果客户不能接受迁移期间内无告警通知，那么此方案不可行。
+
+
+### 方法 1：(推荐) 通过 helm 命令 upgrade
+
+1. 在 Helm upgrade 的执行命令中增加如下参数：
+
+    ```shell
+    --set server.alerting.notifyTemplate.version="v1alpha2"
+    ```
+
+2. 除 **Helm 命令升级** 外亦可编辑 Helm 的 values 文件，如下：
+
+    ```diff title="values.yaml"
+    server:
+      alerting:
+        notifyTemplate:
+    -     version: v1alpha1
+    +     version: v1alpha2
+    ```
+
+### 方法 2：临时调整配置文件（configmap）
+
+1. 编辑 insight-server 的配置文件（configmap）insight-server-config，调整配置文件如下：
+
+    ```diff title="insight-server-config.yaml"
+    alerting:
+      notifyTemplate:
+    -   version: v1alpha1
+    +   version: v1alpha2
+    ```
+
+2. 编辑保存之后，重启 insight-server 即可。