Message-Push-Nest/docs/guide/channels.md

# 推送渠道配置

Message Nest 支持多种消息推送渠道，您可以根据需求配置不同的渠道，实现多渠道消息推送。

## 邮件（SMTP）

通过标准 SMTP 协议发送邮件通知。

### 配置参数

| 参数 | 说明 | 示例 |
|------|------|------|
| 渠道名称 | 自定义渠道名称 | `公司邮箱` |
| SMTP 服务器 | 邮件服务器地址 | `smtp.gmail.com` |
| SMTP 端口 | 服务器端口 | `587` (TLS) 或 `465` (SSL) |
| 发件人邮箱 | 发送邮件的邮箱地址 | `noreply@example.com` |
| 发件人名称 | 显示的发件人名称 | `系统通知` |
| 邮箱密码 | 邮箱密码或授权码 | `your_password` |
| 加密方式 | TLS/SSL/无 | `TLS` |

### 常见邮箱配置

#### Gmail

- **SMTP 服务器**: `smtp.gmail.com`
- **端口**: `587` (TLS)
- **注意**: 需要开启"允许不够安全的应用"或使用应用专用密码

#### QQ 邮箱

- **SMTP 服务器**: `smtp.qq.com`
- **端口**: `587` (TLS) 或 `465` (SSL)
- **注意**: 需要在邮箱设置中开启 SMTP 服务并获取授权码

#### 163 邮箱

- **SMTP 服务器**: `smtp.163.com`
- **端口**: `465` (SSL)
- **注意**: 需要开启 SMTP 服务并使用授权码

#### 企业邮箱

根据企业邮箱服务商提供的 SMTP 配置填写。

### 使用场景

- ✅ 用户注册/登录通知
- ✅ 订单确认和物流通知
- ✅ 账单和发票发送
- ✅ 密码重置和安全提醒
- ✅ 营销邮件和活动通知

### 注意事项

::: warning 注意
- 邮件发送可能会被识别为垃圾邮件，建议配置 SPF、DKIM 等记录
- 使用授权码而非邮箱密码，提高安全性
- 注意邮件发送频率限制，避免被封禁
- 建议使用企业邮箱，稳定性更好
:::

## 钉钉机器人

通过钉钉群机器人发送消息到钉钉群。

### 配置步骤

1. **创建钉钉群**
   - 在钉钉中创建一个群聊

2. **添加自定义机器人**
   - 进入群设置 → 智能群助手 → 添加机器人 → 自定义
   - 设置机器人名称和头像

3. **配置安全设置**
   - 选择"自定义关键词"或"加签"方式
   - 记录 Webhook 地址

4. **在 Message Nest 中配置**
   - 渠道名称：自定义名称
   - Webhook URL：复制的 Webhook 地址
   - 安全设置：根据选择填写关键词或密钥

### 配置参数

| 参数 | 说明 | 必填 |
|------|------|------|
| 渠道名称 | 自定义渠道名称 | 是 |
| Webhook URL | 机器人 Webhook 地址 | 是 |
| 安全关键词 | 自定义关键词（如选择此方式） | 否 |
| 加签密钥 | 加签密钥（如选择此方式） | 否 |

### 消息格式

钉钉支持以下格式：
- **Text** - 纯文本
- **Markdown** - 支持 Markdown 格式

### @提醒功能

支持@群成员：
- **@手机号** - 通过手机号@指定成员
- **@所有人** - @群内所有成员（需要机器人权限）

### 使用场景

- ✅ 系统告警和监控通知
- ✅ 任务完成提醒
- ✅ 审批流程通知
- ✅ 团队协作消息
- ✅ 日报/周报推送

### 注意事项

::: warning 注意
- 每个机器人每分钟最多发送 20 条消息
- @所有人功能需要群主授权
- 建议在消息中包含安全关键词，避免发送失败
- 机器人被移除后 Webhook 将失效
:::

## 企业微信机器人

通过企业微信群机器人发送消息到企业微信群。

### 配置步骤

1. **创建企业微信群**
   - 在企业微信中创建群聊

2. **添加群机器人**
   - 进入群设置 → 群机器人 → 添加机器人
   - 设置机器人名称

3. **获取 Webhook**
   - 复制 Webhook 地址

4. **在 Message Nest 中配置**
   - 渠道名称：自定义名称
   - Webhook URL：复制的 Webhook 地址

### 配置参数

| 参数 | 说明 | 必填 |
|------|------|------|
| 渠道名称 | 自定义渠道名称 | 是 |
| Webhook URL | 机器人 Webhook 地址 | 是 |

### 消息格式

企业微信支持以下格式：
- **Text** - 纯文本
- **Markdown** - 支持 Markdown 格式

### @提醒功能

支持@群成员：
- **@用户ID** - 通过用户ID@指定成员
- **@手机号** - 通过手机号@指定成员
- **@所有人** - @群内所有成员

### 使用场景

- ✅ 企业内部通知
- ✅ 项目进度更新
- ✅ 系统运维告警
- ✅ 工作流审批提醒
- ✅ 会议和日程通知

### 注意事项

::: warning 注意
- 每个机器人每分钟最多发送 20 条消息
- 消息内容不能包含敏感词
- 机器人被移除后 Webhook 将失效
- 建议使用 Markdown 格式，展示效果更好
:::

## 飞书机器人

通过飞书群机器人发送消息到飞书群。

### 配置步骤

1. **创建飞书群**
   - 在飞书中创建群聊

2. **添加自定义机器人**
   - 进入群设置 → 群机器人 → 添加机器人 → 自定义机器人
   - 设置机器人名称和描述

3. **配置安全设置**
   - 选择"签名校验"方式
   - 记录 Webhook 地址和签名密钥

4. **在 Message Nest 中配置**
   - 渠道名称：自定义名称
   - Webhook URL：复制的 Webhook 地址
   - 签名密钥：复制的签名密钥

### 配置参数

| 参数 | 说明 | 必填 |
|------|------|------|
| 渠道名称 | 自定义渠道名称 | 是 |
| Webhook URL | 机器人 Webhook 地址 | 是 |
| 签名密钥 | 签名校验密钥 | 否 |

### 消息格式

飞书支持以下格式：
- **Text** - 纯文本
- **Markdown** - 支持 Markdown 格式（推荐）

### 使用场景

- ✅ 团队协作通知
- ✅ 项目进度更新
- ✅ 系统监控告警
- ✅ 工作流提醒
- ✅ 日报周报推送

### 注意事项

::: warning 注意
- 每个机器人每分钟最多发送 20 条消息
- 建议使用签名校验提高安全性
- 机器人被移除后 Webhook 将失效
- Markdown 格式展示效果更好
:::

## Telegram 机器人

通过 Telegram Bot 发送消息到 Telegram 聊天。

### 配置步骤

1. **创建 Telegram Bot**
   - 在 Telegram 中搜索 `@BotFather`
   - 发送 `/newbot` 命令创建新机器人
   - 按提示设置机器人名称和用户名
   - 记录 Bot Token（格式：`123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11`）

2. **获取 Chat ID**
   - **个人聊天**：向机器人发送任意消息，然后访问 `https://api.telegram.org/bot<YourBOTToken>/getUpdates` 查看 `chat.id`
   - **群组聊天**：将机器人添加到群组，发送消息后同样方式获取 `chat.id`（群组 ID 通常为负数）
   - **频道**：将机器人添加为频道管理员，使用频道用户名（如 `@channel_name`）或频道 ID

3. **在 Message Nest 中配置**
   - Bot Token：填入创建机器人时获得的 Token
   - Chat ID：填入接收消息的聊天 ID
   - 自定义 API 地址（可选）：如使用自建代理服务器
   - 代理地址（可选）：如需通过代理访问 Telegram API

### 配置参数

| 参数 | 说明 | 必填 | 示例 |
|------|------|------|------|
| 渠道名称 | 自定义渠道名称 | 是 | `Telegram通知` |
| Bot Token | 机器人 Token | 是 | `123456:ABC-DEF...` |
| Chat ID | 接收消息的聊天 ID | 是 | `123456789` 或 `-100123456789` |
| 自定义 API 地址 | 自建代理服务器地址 | 否 | `https://api.example.com` |
| 代理地址 | HTTP/SOCKS5 代理 | 否 | `socks5://127.0.0.1:1080` |

### 代理配置说明

Telegram 在某些地区可能无法直接访问，支持以下代理方式：

**1. 自定义 API 地址（优先级最高）**
- 适用于自建 Telegram API 代理服务器
- 示例：`https://api.example.com`
- 如果配置了此项，代理地址将被忽略

**2. 代理地址（优先级较低）**
- 支持 HTTP/HTTPS/SOCKS5 代理
- HTTP 代理：`http://127.0.0.1:7890`
- HTTPS 代理：`https://proxy.example.com:8080`
- SOCKS5 代理：`socks5://127.0.0.1:1080`
- 带认证的 SOCKS5：`socks5://username:password@host:1080`

### 消息格式

Telegram 支持以下格式：
- **Text** - 纯文本
- **Markdown** - Markdown 格式（支持 Telegram Markdown 语法）
- **HTML** - HTML 格式（支持部分 HTML 标签）

### 使用场景

- ✅ 个人消息通知
- ✅ 系统监控告警
- ✅ 自动化脚本通知
- ✅ 跨国团队协作
- ✅ 服务器状态推送
- ✅ 定时任务提醒

### 注意事项

::: warning 注意
- Bot Token 需要妥善保管，泄露后需要重新生成
- 群组 Chat ID 通常为负数（如 `-100123456789`）
- 机器人需要有发送消息的权限
- 在群组中使用时，需要将机器人添加为成员
- 在频道中使用时，需要将机器人设为管理员
- 代理配置优先级：自定义 API 地址 > 代理地址
- 如果在国内使用，建议配置代理或自定义 API 地址
:::

::: tip 提示
**获取 Chat ID 的简便方法：**
1. 将机器人添加到聊天中
2. 向机器人发送任意消息
3. 在浏览器访问：`https://api.telegram.org/bot<YourBOTToken>/getUpdates`
4. 在返回的 JSON 中找到 `"chat":{"id":123456789}` 即为 Chat ID
:::

## Bark 推送

Bark 是一款 iOS 专用的推送软件，通过此渠道您可以将消息推送到您的 iPhone 上。

### 配置步骤

1. **安装 Bark App**
   - 在 iPhone 上从 App Store 下载安装 [Bark](https://apps.apple.com/cn/app/bark-customed-notifications/id1403753828)

2. **获取 Push Key**
   - 打开 Bark App，您会看到类似于 `DxHcxxxxxRxxxxxxcm` 的设备 Key
   - 如果使用自建服务器，请使用完整的服务器地址

3. **在 Message Nest 中配置**
   - Push Key：填入您的设备 Key 或自建服务器地址
   - 其他参数（可选）：根据需要填写分组、铃声、图标、时效性等

### 配置参数

| 参数 | 说明 | 必填 | 示例 |
|------|------|------|------|
| 渠道名称 | 自定义渠道名称 | 是 | `iPhone通知` |
| Push Key | 设备 Key 或自建 IP | 是 | `DxHcxxxxxRxxxxxxcm` |
| 存档 | 是否存档 (1 或 0) | 否 | `1` |
| 分组 | 推送分组 | 否 | `MessageNest` |
| 推送声音 | 推送铃声名称 | 否 | `glass` |
| 推送图标 | 图标 URL | 否 | `https://example.com/icon.png` |
| 推送时效 | active/timeSensitive/passive | 否 | `active` |
| 跳转 URL | 点击推送跳转的网址 | 否 | `https://github.com` |

### 消息格式

Bark 支持以下格式：
- **Text** - 纯文本

### 使用场景

- ✅ 个人即时通知
- ✅ 监控告警提醒
- ✅ 自动化操作反馈
- ✅ 关键信息推送

### 注意事项

::: warning 注意
- 仅支持 iOS 设备
- 确保 iPhone 已开启 Bark 的通知权限
- 自建服务器需要确保服务器外网可访问
- 部分铃声可能需要 Bark App 的 Pro 版本或特定版本支持
:::

## PushMe 推送

PushMe 是一款即时消息推送服务，支持多平台消息通知。

### 配置步骤

1. **获取 Push Key**
   - 访问 PushMe 官网或您的自建服务
   - 注册/登录后获取您的 Push Key

2. **在 Message Nest 中配置**
   - Push Key：填入您的 Push Key
   - 自定义 API 地址：如果使用自建服务，请填写完整的 API 地址（如 `https://push.example.com/`）
   - 其他参数：根据需要填写日期、类型等

### 配置参数

| 参数 | 说明 | 必填 | 示例 |
|------|------|------|------|
| 渠道名称 | 自定义渠道名称 | 是 | `PushMe通知` |
| Push Key | PushMe Key | 是 | `your_push_key` |
| 自定义 API 地址 | 自建服务地址 | 否 | `https://push.i-i.me/` |
| 日期 | 消息日期 | 否 | `2024-01-01` |
| 类型 | 消息类型 | 否 | `text` |

### 消息格式

PushMe 支持以下格式：
- **Text** - 纯文本

### 使用场景

- ✅ 个人通知
- ✅ 系统告警
- ✅ 跨平台消息同步

## 微信测试公众号

通过微信测试公众号发送模板消息。

### 配置步骤

1. **申请测试公众号**
   - 访问 [微信公众平台测试号](https://mp.weixin.qq.com/debug/cgi-bin/sandbox?t=sandbox/login)
   - 使用微信扫码登录

2. **获取配置信息**
   - appID：测试号信息中的 appID
   - appsecret：测试号信息中的 appsecret

3. **添加模板消息**
   - 在"模板消息接口"中添加模板
   - 记录模板 ID

4. **关注测试公众号**
   - 使用微信扫描测试号二维码关注
   - 记录用户的 OpenID

5. **在 Message Nest 中配置**
   - 填写 appID、appsecret、模板ID、OpenID

### 配置参数

| 参数 | 说明 | 必填 |
|------|------|------|
| 渠道名称 | 自定义渠道名称 | 是 |
| appID | 测试公众号 appID | 是 |
| appsecret | 测试公众号 appsecret | 是 |
| 模板ID | 模板消息 ID | 是 |
| OpenID | 接收用户的 OpenID | 是 |

### 使用场景

- ✅ 个人项目测试
- ✅ 小范围通知
- ✅ 开发环境调试

### 注意事项

::: warning 注意
- 测试公众号仅供开发测试使用，不能用于生产环境
- 测试公众号有关注人数限制（100人）
- 模板消息格式需要符合微信规范
- 正式使用需要申请正式公众号
:::

## 自定义 Webhook

向自定义的 HTTP 接口发送消息。

### 配置参数

| 参数 | 说明 | 必填 |
|------|------|------|
| 渠道名称 | 自定义渠道名称 | 是 |
| Webhook URL | 目标 HTTP 接口地址 | 是 |
| 请求方法 | GET/POST/PUT 等 | 是 |
| 请求头 | 自定义 HTTP 请求头 | 否 |
| 请求体模板 | 自定义请求体格式 | 否 |

### 请求体模板

支持使用变量：
- `{{title}}` - 消息标题
- `{{text}}` - 纯文本内容
- `{{html}}` - HTML 内容
- `{{markdown}}` - Markdown 内容

**示例：**

```json
{
  "message": "{{title}}",
  "content": "{{text}}",
  "timestamp": "{{timestamp}}"
}
```

### 使用场景

- ✅ 集成第三方系统
- ✅ 自建消息服务
- ✅ 对接其他通知平台
- ✅ 自定义消息处理逻辑

### 注意事项

::: tip 提示
- 确保目标接口可访问
- 注意接口的请求频率限制
- 建议添加认证信息保证安全
- 可以通过请求头传递 Token 等认证信息
:::

## 自托管消息

将 Message Nest 站点作为消息接收平台，用户登录站点查看消息。

### 核心定位

**与其他渠道的区别：**
- **邮件/钉钉/企业微信** - 推送到外部平台
- **自托管消息** - 存储在 Message Nest 站点，用户登录站点查看

### 配置参数

| 参数 | 说明 | 必填 |
|------|------|------|
| 渠道名称 | 自定义渠道名称 | 是 |
| 渠道描述 | 渠道用途说明 | 否 |

### 功能特点

- ✅ 站点作为消息接收平台
- ✅ 无需外部依赖
- ✅ 消息集中存储和管理
- ✅ 支持多种格式展示（Text/HTML/Markdown）
- ✅ 支持消息搜索和筛选
- ✅ 支持消息已读/未读状态

### 使用场景

- ✅ 站内消息中心
- ✅ 系统公告发布
- ✅ 内部工作流通知
- ✅ 系统告警记录
- ✅ 消息归档平台

### 查看消息

1. 登录 Message Nest 站点
2. 进入"自托管消息"或"消息中心"页面
3. 查看接收到的消息列表
4. 点击消息查看详情

### 注意事项

::: tip 提示
- 消息不会自动清理，需要手动清理
- 建议定期清理不需要的消息，避免占用过多存储空间
- 可以根据需要导出消息记录
- 适合作为消息的集中查看和管理平台
:::

## 渠道管理

### 创建渠道

1. 登录管理后台
2. 进入"推送渠道"页面
3. 点击"新建渠道"
4. 选择渠道类型
5. 填写配置信息
6. 保存并测试

### 测试渠道

创建渠道后，建议先进行测试：

1. 在渠道列表中找到新建的渠道
2. 点击"测试"按钮
3. 发送测试消息
4. 确认消息正常接收

### 编辑和删除

- **编辑**：点击渠道的"编辑"按钮，修改配置信息
- **删除**：点击"删除"按钮，确认后删除（注意：删除后关联的任务和模板将无法使用该渠道）

### 最佳实践

1. **命名规范** - 使用清晰的渠道名称，便于识别
2. **分类管理** - 按用途或环境分类（如：生产环境邮件、测试环境钉钉）
3. **定期检查** - 定期检查渠道配置是否有效
4. **安全管理** - 妥善保管密钥和密码信息
5. **备用渠道** - 配置多个渠道作为备用，提高可靠性

## 下一步

- 查看 [发送任务](/guide/tasks) 了解如何使用渠道发送消息
- 查看 [消息模板](/guide/template) 了解如何创建模板
- 查看 [API 文档](/api/v1) 了解如何通过 API 发送消息