> ## Documentation Index
> Fetch the complete documentation index at: https://docs.molesignal.com/llms.txt
> Use this file to discover all available pages before exploring further.
# 通知渠道与投递
> 配置 SMTP、Slack、飞书和 Webhook 连接器，再通过用户、策略、模板和兜底路由投递通知。
MoleSignal 将服务商凭证、接收人和路由规则分开管理。连接器只需配置一次，再把用户身份或兜底目标
绑定到连接器，并通过通知策略决定何时使用这些路由。
| 资源 | 用途 |
| --------- | --------------------------- |
| **企业连接器** | 保存组织级服务商凭证和传输配置。 |
| **用户通知** | 绑定各平台身份，并排列个人投递端点。 |
| **通知策略** | 匹配事件、解析接收人、选择模板并控制升级。 |
| **通知模板** | 复用纯文本、Markdown 或 HTML 消息正文。 |
| **兜底路由** | 在个人投递失败后，定义有序的团队和组织目标。 |
| **投递记录** | 查看投递尝试、耗时、错误、重试、确认与升级。 |
## 支持的连接器
| 连接器 | 配置 | 支持的目标 |
| ------------------------------ | --------------------------------------- | ------------------------------ |
| Email SMTP（`email_smtp`） | SMTP 主机、端口、凭证、发件地址、TLS 模式、超时 | 用户邮箱或固定邮箱 |
| Slack 应用（`slack_app`） | Bot Token、Slack API 基础地址、超时 | Slack 用户 ID 或频道 ID |
| Slack Webhook（`slack_webhook`） | Incoming Webhook 地址、超时 | 已配置 Webhook 或按目标覆盖的 Webhook 地址 |
| 飞书应用（`lark_app`） | App ID、App Secret、API 基础地址、接收人 ID 类型、超时 | 用户身份、邮箱或群聊 ID |
| 飞书 Webhook（`lark_webhook`） | 自定义机器人 Webhook 地址、可选签名密钥、超时 | 已配置 Webhook 或按目标覆盖的 Webhook 地址 |
| 通用 Webhook（`webhook`） | 默认地址、HTTP 方法、请求头、超时 | 用户、地址、群组或按目标指定的 Webhook 地址 |
所有连接器的超时必须在 1 到 60 秒之间。URL 必须是绝对 `http` 或 `https` 地址。
## 创建并测试连接器
查看连接器需要 `alerts.read`；创建、编辑、测试、启停或删除连接器需要 `alerts.manage`。
前往**设置 → 通知管理 → 企业连接器**。
点击**新建连接器**，填写唯一名称并选择连接器类型。连接器创建后不能更改类型。
按下文填写凭证和传输参数。除非准备稍后再启用，否则保持**允许此连接器投递**开启。
点击**保存连接器**。MoleSignal 会加密保存完整配置，API 响应会把敏感值替换为 `***`。
编辑已保存的连接器，选择兼容的目标类型，输入真实目标，再点击**测试连接**。最近一次测试会把
连接器状态更新为**已连接**或**异常**。
新连接器必须先保存才能测试。编辑连接器时，不要改动已掩码的 `***`，系统会保留原有密钥。
## 配置各服务商
### Email SMTP
填写 SMTP 主机、端口、按需填写用户名、密码，以及有效的**发件地址**。按邮件服务器选择 TLS 模式：
| TLS 模式 | 适用场景 |
| ---------- | ----------------------------- |
| `none` | SMTP 连接不使用 TLS。不要在不可信网络上使用。 |
| `starttls` | 先连接再升级到 STARTTLS，常用端口为 `587`。 |
| `tls` | 从连接开始就使用 TLS，常用端口为 `465`。 |
测试时选择 `fixed_address` 或 `direct_user`，并输入 `oncall@example.com` 这类有效邮箱。
### Slack 应用
创建能调用 `chat.postMessage` 的 Slack 应用和 Bot Token，并把机器人加入需要接收通知的频道。填写：
* **Bot Token** —— 通常以 `xoxb-` 开头；
* **API 基础地址** —— 除非使用兼容代理，否则保留 `https://slack.com/api`；
* **超时** —— 1 到 60 秒。
`direct_user` 目标填写 Slack 成员 ID，`fixed_group` 目标填写频道 ID。目标不能包含空格；`#alerts`
这类显示名称不是频道 ID。
### Slack Webhook
在 Slack 创建 Incoming Webhook，并把地址填入 **Webhook 地址**。`fixed_group` 目标使用连接器中配置的
地址；`webhook` 目标会把目标值作为本次投递的替代地址。
MoleSignal 发送包含 `text` 字段的 JSON。任何非 2xx 响应都会将本次投递标记为失败。
### 飞书应用
创建能够获取 tenant access token 并发送消息的企业自建应用，填写 **App ID** 和 **App Secret**。
除非使用其他兼容的飞书端点，否则保留默认 API 基础地址。
所选接收人 ID 类型只用于 `direct_user`：
| 目标类型 | 目标值 |
| --------------- | --------------------------------------------------- |
| `direct_user` | 按**接收人 ID 类型**填写 `open_id`、`user_id`、`union_id` 或邮箱 |
| `fixed_address` | 邮箱；MoleSignal 使用 `receive_id_type=email` 发送 |
| `fixed_group` | 飞书群聊 ID；MoleSignal 使用 `receive_id_type=chat_id` 发送 |
### 飞书 Webhook
把自定义机器人地址填入 **Webhook 地址**。如果机器人启用了签名校验，再填写**签名密钥**。MoleSignal
会为每次请求生成时间戳和 HMAC-SHA256 签名。
`fixed_group` 目标使用已配置地址，`webhook` 目标可以用另一个绝对 URL 覆盖。请求体与签名格式见
[Webhook 连接器](/zh-Hans/alert-webhook-channels)。
### 通用 Webhook
填写默认地址，并选择 `POST`、`PUT` 或 `PATCH`。请求头使用 JSON 对象：
```json theme={null}
{
"Authorization": "Bearer ",
"X-Environment": "production"
}
```
MoleSignal 发送以下 JSON：
```json theme={null}
{
"target": {
"type": "fixed_group",
"value": "platform-oncall",
"metadata": {}
},
"message": {
"title": "Checkout error rate is high",
"text": "The error rate exceeded 5%.",
"markdown": "**Checkout** error rate exceeded 5%.",
"html": null,
"metadata": {}
}
}
```
`direct_user`、`fixed_address` 和 `fixed_group` 会请求已配置的默认地址，并把目标作为路由数据放入
请求体。`webhook` 会用目标值替换默认地址。2xx 响应表示成功；响应包含 `X-Request-ID` 时，MoleSignal
会把 Header 值记录为服务商消息 ID。
Webhook 地址、Authorization Header、Token、密码和签名密钥都属于凭证。不要把凭证值写入测试目标、
通知模板或事件属性。
## 绑定用户通知方式
管理员可以打开**设置 → 通知管理 → 用户通知**，选择成员，再点击**绑定通知方式**。每个通知身份会
选择一个连接器和一个外部身份，例如邮箱、Slack 用户 ID 或飞书用户 ID。
绑定后按以下步骤配置：
1. 发送测试，确认服务商接受该身份；
2. 组织确认归属后，将身份标记为已验证；
3. 在**告警事件**、**值班通知**或**报告**偏好中启用该身份；
4. 有多个身份时，按主用到备用的顺序排列；
5. 按需配置免打扰时段，并决定严重告警能否绕过免打扰。
成员可以在**账号设置 → 通知设置**中管理个人身份和偏好。读取其他成员设置需要
`org.members.read`，修改或确认其他成员身份需要 `org.members.manage`。
删除通知身份前，先从所有投递偏好中移除该身份。
## 创建模板和策略
打开**设置 → 通知管理 → 通知模板**，创建可复用的纯文本、Markdown 或 HTML 正文。选择通知类别，
插入支持的占位符，再使用预览属性检查渲染结果。
然后打开**通知策略**并创建路由规则：
1. 选择事件类型和通知类别；
2. 添加 JSON 匹配条件并设置策略优先级；
3. 选择接收人解析器和解析器配置；
4. 选择尊重用户偏好、强制一个连接器或通过多个连接器发送；
5. 选择模板，并启用用户、团队或组织兜底；
6. 按需设置确认超时和升级路由；
7. 检查实时投递预览；预览会解析真实用户和路由，但不会发送消息。
策略当前覆盖告警生命周期和值班排班事件。策略编辑器会列出运行中后端支持的事件类型和接收人解析器。
## 配置兜底路由
打开**设置 → 通知管理 → 兜底路由**。选择组织或团队范围，再选择通知类别。添加一个或多个已启用的
连接器，选择 `fixed_address` 或 `fixed_group`，并填写服务商目标。
已启用的个人路由阶段失败后，MoleSignal 会按页面显示顺序尝试兜底路由。通知策略决定是否启用用户、
团队和组织兜底。
## 查看和重试投递
打开**设置 → 通知管理 → 投递记录**，按事件 ID、状态或阶段筛选。选择一条记录，可以查看脱敏目标、
连接器、耗时、服务商错误和完整投递链路。
* `alerts.read` 可以查看投递历史；
* `alerts.acknowledge` 可以确认来源事件；
* `alerts.manage` 可以重试失败路由。
重试会创建新的投递尝试，不会修改已有历史。
## 连接器生命周期与状态
| 状态 | 含义 |
| ------- | ----------------------------- |
| **未知** | 连接器还没有完成过成功或失败的测试。 |
| **已连接** | 最近一次测试成功。 |
| **异常** | 最近一次测试失败；后续测试成功前，正常路由会跳过该连接器。 |
| **已停用** | MoleSignal 不会通过该连接器测试或投递。 |
停用连接器不会删除引用。用户身份、通知策略或兜底路由仍引用连接器时，不能删除连接器。先迁移
这些引用，再删除连接器。
## 排查投递问题
| 现象 | 检查项 |
| ----------------- | ------------------------------------------------- |
| SMTP 身份验证或 TLS 失败 | 检查主机、端口、凭证、TLS 模式、发件地址、DNS 和出向网络。 |
| Slack 返回 API 错误 | 检查 Bot Token、`chat.postMessage` 权限、目标 ID 和频道成员关系。 |
| 飞书拒绝消息 | 检查应用权限、接收人 ID 类型、群聊成员关系、Webhook 密钥和服务器时间。 |
| Webhook 返回错误 | 检查 URL、方法、Header JSON、超时，以及对端是否返回 2xx。 |
| 用户没有收到通知 | 检查身份和连接器是否启用、类别偏好是否包含该身份，以及免打扰是否生效。 |
| 兜底路由没有执行 | 检查策略是否启用该层兜底，以及对应类别是否存在已启用路由。 |
创建规则并处理告警事件生命周期。
查看 Webhook 请求体、目标覆盖、签名与安全要求。