#通知管理

#功能概览

通过通知功能，您可以将平台的监控和告警能力集成起来，及时向通知接收人发送预警信息，提醒相关人员采取必要措施以解决问题或避免故障。

#主要功能

• 通知服务器：通知服务器提供向平台上的接收组发送通知消息的服务，例如邮件服务器。
• 接收组：接收组是具有相似逻辑特征的一组通知接收人，通过对接收通知消息的实体进行分类，可以降低维护成本。
• 通知模板：通知模板是一种标准化结构，由自定义内容、内容变量和内容格式参数组成。用于规范通知规则的告警通知消息内容和格式。例如，自定义邮件通知的主题和内容。
• 通知规则：通知规则是一组用于定义如何向特定联系人发送通知消息的规则。在告警、巡检和登录认证等需要通知外部服务的场景中，必须使用通知规则。

#通知服务器

通知服务器提供向平台上的接收人发送通知消息的服务。平台当前支持以下通知服务器：

• 企业通讯工具服务器：支持集成企业微信、钉钉和飞书内置应用，用于向个人发送通知。
• 邮件服务器：通过邮件服务器使用电子邮件发送通知。
• Webhook 类型服务器：支持集成企业微信群机器人、钉钉群机器人、飞书群机器人，或向您指定的服务器发送 WebHook。

#企业通讯工具服务器

企业微信

1. 按照以下示例配置通知服务器参数。填写完成后，切换到 集群管理 > 资源管理 中的 global 集群，并创建资源对象。

   # WeChat Work corpId, corpSecret, agentId acquisition methods can be referenced in the official documentation: https://developer.work.weixin.qq.com/document/path/90665
   apiVersion: v1
   kind: Secret
   type: NotificationServer
   metadata:
     labels:
       cpaas.io/notification.server.type: CorpWeChat
       cpaas.io/notification.server.category: Corp
     name: platform-corp-wechat-server
     namespace: cpaas-system
   data:
     displayNameZh: 企业微信 # Server's Chinese display name, encoded in base64 by default
     displayNameEn: WeChat # Server's English display name, encoded in base64 by default
     corpId: # Corporate ID, encoded in base64 by default
     corpSecret: # Application secret, encoded in base64 by default
     agentId: # Corporate application ID, encoded in base64 by default

2. 创建完成后，需要在平台的 用户角色管理 > 用户管理 中，或者在用户的 个人信息 中更新用户的 企业微信 ID，以确保用户能够正常接收消息。

钉钉

1. 按照以下示例配置通知服务器参数。填写完成后，切换到 集群管理 > 资源管理 中的 global 集群，并创建资源对象。

   # DingTalk appKey, appSecret, agentId acquisition method: https://open-dev.dingtalk.com/fe/app#/corp/app
   apiVersion: v1
   kind: Secret
   type: NotificationServer
   metadata:
     labels:
       cpaas.io/notification.server.type: CorpDingTalk
       cpaas.io/notification.server.category: Corp
     name: platform-corp-dingtalk-server
     namespace: cpaas-system
   data:
     displayNameZh: 钉钉 # Server's Chinese display name, encoded in base64 by default
     displayNameEn: DingTalk # Server's English display name, encoded in base64 by default
     appKey: # Application key, encoded in base64 by default
     appSecret: # Application secret, encoded in base64 by default
     agentId: # Application agent_id, encoded in base64 by default

2. 创建完成后，需要在平台的 用户角色管理 > 用户管理 中，或者在用户的 个人信息 中更新用户的 钉钉 ID，以确保用户能够正常接收消息。

飞书

1. 按照以下示例配置通知服务器参数。填写完成后，切换到 集群管理 > 资源管理 中的 global 集群，并创建资源对象。

   # Feishu appId, appSecret acquisition methods: https://open.feishu.cn/app/
   apiVersion: v1
   kind: Secret
   type: NotificationServer
   metadata:
     labels:
       cpaas.io/notification.server.type: CorpFeishu
       cpaas.io/notification.server.category: Corp
     name: platform-corp-feishu-server
     namespace: cpaas-system
   data:
     displayNameZh: 飞书 # Server's Chinese display name, encoded in base64 by default
     displayNameEn: Feishu # Server's English display name, encoded in base64 by default
     appId: # Application ID, encoded in base64 by default
     appSecret: # Application secret, encoded in base64 by default

2. 创建完成后，需要在平台的 用户角色管理 > 用户管理 中，或者在用户的 个人信息 中更新用户的 飞书 ID，以确保用户能够正常接收消息。

#邮件服务器

1. 在左侧导航栏中，单击 平台设置 > 通知服务器。

2. 单击 立即配置。

3. 参考以下说明配置相关参数。

   参数	描述
   服务地址	支持 SMTP 协议的通知服务器地址，例如 smtp.yeah.net。
   端口	通知服务器的端口号。当勾选 使用 SSL 时，必须填写 SSL 端口号。
   服务器配置	使用 SSL：SSL（Secure Socket Layer）是一种标准安全技术。SSL 开关用于控制是否在服务器与客户端之间建立加密连接。 跳过不安全验证：insecureSkipVerify 开关用于控制是否验证客户端证书和服务器主机名。启用后，将不会验证证书以及证书中的主机名与服务器主机名的一致性。
   发件人邮箱	通知服务器中的发件人邮箱账号，用于发送通知邮件。
   启用认证	如果需要认证，请配置邮件服务器的用户名和授权码。

4. 单击 确定。

#Webhook 类型服务器

支持集成企业微信群机器人、钉钉群机器人、飞书群机器人，或向您指定的 Webhook 服务器发送 HTTP 请求。

企业微信群机器人

1. 在左侧导航栏中，单击 集群管理 > 集群。

2. 单击 global 集群旁边的操作按钮 > CLI 工具。

3. 在 global 集群的主节点上执行以下命令：

   kubectl patch secret -n cpaas-system platform-wechat-server -p '{"data":{"enable":"dHJ1ZQo="}}'

   提示：dHJ1ZQo= 是 true 的 base64 编码值；如需禁用，请将 dHJ1ZQo= 替换为 ZmFsc2UK，即 false 的 base64 编码值。

钉钉群机器人

1. 在左侧导航栏中，单击 集群管理 > 集群。

2. 单击 global 集群旁边的操作按钮 > CLI 工具。

3. 在 global 集群的主节点上执行以下命令：

   kubectl patch secret -n cpaas-system platform-dingtalk-server -p '{"data":{"enable":"dHJ1ZQo="}}'

   提示：dHJ1ZQo= 是 true 的 base64 编码值；如需禁用，请将 dHJ1ZQo= 替换为 ZmFsc2UK，即 false 的 base64 编码值。

飞书群机器人

1. 在左侧导航栏中，单击 集群管理 > 集群。

2. 单击 global 集群旁边的操作按钮 > CLI 工具。

3. 在 global 集群的主节点上执行以下命令：

   kubectl patch secret -n cpaas-system platform-feishu-server -p '{"data":{"enable":"dHJ1ZQo="}}'

   提示：dHJ1ZQo= 是 true 的 base64 编码值；如需禁用，请将 dHJ1ZQo= 替换为 ZmFsc2UK，即 false 的 base64 编码值。

Webhook 服务器

1. 在左侧导航栏中，单击 集群管理 > 集群。

2. 单击 global 集群旁边的操作按钮 > CLI 工具。

3. 在 global 集群的主节点上执行以下命令：

   kubectl patch secret -n cpaas-system platform-webhook-server -p '{"data":{"enable":"dHJ1ZQo="}}'

   提示：dHJ1ZQo= 是 true 的 base64 编码值；如需禁用，请将 dHJ1ZQo= 替换为 ZmFsc2UK，即 false 的 base64 编码值。

#为 Webhook 通知配置自定义请求头

如果目标 Webhook 端点需要自定义 HTTP 请求头，请先在 cpaas-system 命名空间中创建一个 Secret，后续再将其与接收组关联。

1. 在左侧导航栏中，单击 集群管理 > 集群。

2. 单击 global 集群旁边的操作按钮 > CLI 工具。

3. 在 global 集群的主节点上创建如下所示的 YAML 文件。

   apiVersion: v1
   kind: Secret
   metadata:
     name: webhook-header-secret
     namespace: cpaas-system
   type: NotificationSender
   data:
     X-Secret: <base64-encoded-header-value>

4. 将 YAML 文件保存为 webhook-header.yaml，并应用资源。

   kubectl apply -f webhook-header.yaml

#接收组

接收组是一组具有相似逻辑特征的通知接收人。例如，您可以将运维团队设置为接收组，以便在配置通知规则时进行快速选择和管理。

1. 在左侧导航栏中，单击 运维中心 > 通知。

2. 切换到 接收组 选项卡。

3. 单击 创建接收组，并按照以下说明配置相关参数。

   参数	描述
   邮箱	为整个接收组添加一个邮箱。平台将向该邮箱以及组内所有联系人的邮箱发送通知。
   Webhook URL/企业微信群机器人/钉钉群机器人/飞书群机器人	请根据已配置的通知服务器填写对应的通知方式 URL。配置完成后，该组中的联系人将通过此方式接收通知。
   联系人配置	单击 添加联系人 将平台中已有的用户添加到接收组中。请确保所选联系人的联系信息（电话、邮箱、接口回调）的准确性，以避免漏收消息通知。

4. 单击 添加。

#将接收组与 Header Secret 关联

如果已配置的 Webhook 端点需要自定义请求头，请将接收组与 为 Webhook 通知配置自定义请求头 中创建的 Secret 关联。

1. 在左侧导航栏中，单击 集群管理 > 集群。

2. 单击 global 集群旁边的操作按钮 > CLI 工具。

3. 在 global 集群的主节点上编辑对应的接收组（NotificationGroup）资源。

   kubectl edit notificationgroups.ait.alauda.io -n cpaas-system <notification-group-name>

4. 向 metadata.annotations 添加 cpaas.io/notification.webhook.config 注解。其值必须为用于自定义请求头的 Secret 名称。

   apiVersion: ait.alauda.io/v1beta1
   kind: NotificationGroup
   metadata:
     name: <notification-group-name>
     namespace: cpaas-system
     annotations:
       cpaas.io/notification.webhook.config: webhook-header-secret

#通知模板

通知模板是一种标准化结构，由自定义内容、内容变量和内容格式参数组成。用于规范通知规则的告警通知消息内容和格式。

平台管理员或运维人员可以根据不同的告警通知方式设置通知模板，自定义通知消息的内容和格式，帮助用户快速获取关键告警信息并提升运维效率。

平台管理员可以将平台通知模板设为公开。公开模板可在项目通知规则中被选用，因此项目管理员无需在每个项目中重复创建模板，即可复用平台维护的消息格式。

#创建模板

1. 在左侧导航栏中，单击 运维中心 > 通知。

2. 切换到 模板 选项卡。

3. 单击 创建模板。

4. 在 基本信息 区域中，配置以下参数。

   参数	描述
   消息类型	根据通知用途选择消息类型。 告警消息：发送由告警规则触发的告警消息，与平台告警功能配合使用； 组件异常消息：发送由某些组件异常触发的通知信息。
   公开	使模板可用于项目通知规则。该选项适用于平台通知模板。模板设为公开后，项目管理员在创建或更新通知规则时，可以从平台公开模板组中选择该模板。公开模板在模板列表中会带有只读的 公开 标签，并在详情页显示公开状态。当您将公开模板重新设为私有时，在提交更改前，请在对话框中确认影响。

5. 在 模板配置 区域中，引用不同的模板类型以配置变量和内容格式参数。

6. 单击 创建。

#引用变量

变量是通知消息（NotificationMessage）中标签或注解的键，格式为 {{.labelKey}}。为了方便用户快速获取关键信息，可以为变量设置自定义显示名称，例如：告警级别: {{ .externalLabels.severity }}。

当通知规则基于通知模板向用户发送通知消息时，模板中的变量会引用通知消息中对应的标签值（实际监控数据）。最终，监控数据将以标准化的内容格式发送给用户。

平台默认提供以下基础变量：

#电子邮件中的特殊格式标记语言

在电子邮件通知中，下表列出了常见的 HTML 格式标签及其说明：

#通知规则

通知规则是一组用于定义如何向特定联系人发送通知消息的规则。在告警、巡检和登录认证等需要通知外部服务的场景中，必须使用通知规则。

#前提条件

要使用 企业通讯工具服务器 通知联系人，用户必须先在 个人信息 中填写其 WeChat Work ID，以修改自己的联系信息。

#操作步骤

1. 在左侧导航栏中，单击 运维中心 > 通知。

2. 单击 创建规则，并按照以下说明配置相关参数。

   参数	描述
   接收组	接收组是一组逻辑上归类的通知接收人，平台将使用指定的通知方式向其发送通知。
   通知接收人	可选择添加一个或多个通知接收人，平台将根据接收人在 个人信息 中配置的联系方式发送通知。
   通知方式	支持 企业微信、钉钉、飞书、企业微信群机器人、钉钉群机器人、飞书群机器人、WebHook URL 等多种方式，并支持多选。 注意：配置通知服务器后将显示部分参数。
   通知模板	选择用于展示通知信息的通知模板。在项目视图中，模板按来源分组。您可以选择项目模板或平台公开模板。

3. 单击 创建。

#为项目设置通知规则

平台的通知规则、通知模板和接收组默认按租户隔离。作为项目管理员，您无法查看或使用其他项目或平台管理员配置的通知规则、私有通知模板或接收组。平台公开通知模板除外：您可以在创建或更新通知规则时选择它们，但不能在项目视图中编辑或删除它们。

#前提条件

1. 您已联系平台管理员完成通知服务器配置。

2. 如果需要通过企业通讯工具进行通知，还需要确保待通知联系人已在 个人信息 中正确配置其通讯工具 ID。

#操作步骤

1. 在 项目管理 视图中，单击 项目名称。

2. 在左侧导航栏中，单击 通知。

3. 切换到 接收组 选项卡，参考 接收组 创建接收组。

4. 切换到 模板 选项卡，参考 通知模板 创建通知模板。如果已有合适的平台公开模板，则可以跳过此步骤，并在创建通知规则时选择该模板。

5. 切换到 规则 选项卡，参考 通知规则 创建通知规则。