宝塔-云讯通消息转发部署文档

本文档从零开始手把手教你把宝塔面板（BT Panel）的告警通知接入云讯通，实现服务器监控告警、任务通知等消息自动推送到云讯通群。

宝塔机器人是单向推送（宝塔 → 云讯通），不支持在云讯通里回复消息到宝塔。

0. 你需要提前准备好的东西

项	值	来源
宝塔面板账号	——	需要有面板管理权限
云讯通服务器域名	`https://dev.ysykj.icu`	项目运维
云讯通 App	——	已登录的正常账号

1. 在云讯通 App 创建宝塔机器人

操作步骤

1. 打开云讯通 App → 底部导航「消息」→ 右上角「+」→「添加机器人」

2. 选择「宝塔机器人」

3. 填写：

字段	填什么
机器人名称	随便起，如"服务器告警"

4. 安全方式配置（至少选一种）：

安全方式说明

宝塔机器人不支持动态 HMAC 加签，提供以下两种安全方式：

安全方式	说明	是否必选
自定义关键词	系统自动生成一个安全关键词，会写入宝塔请求模板，用于验证告警来源	默认启用
IP 地址白名单	只有来自白名单 IP 的请求才会被处理，可填多个 IP 或 CIDR（如 `192.168.1.0/24`）	可选，最多 10 条

踩坑提醒：宝塔不支持加签（HMAC），所以关键词验证是主要的安全手段。如果你知道宝塔服务器的固定 IP，建议同时开启 IP 白名单。

5. 点击「完成」→ 机器人创建成功，跳转到成功页

2. 在宝塔面板配置消息通道

2.1 进入告警通知设置

1. 登录宝塔面板

2. 左侧菜单 → 「告警通知」（或「软件管理」→ 安装「告警通知」插件）

3. 点击 「通知设置」 或 「消息通道」

【截图空位】 宝塔面板 — 告警通知 → 通知设置页面

2.2 添加自定义消息通道

1. 在通知设置页面，找到 「消息通道」 或 「通知方式」

2. 点击 「添加通知方式」 或 「新增通道」

3. 通知方式选择 「自定义」 或 「Webhook」

【截图空位】 宝塔面板 — 添加自定义消息通道

2.3 填写 Webhook 地址

在云讯通 App 的创建成功页，找到 「Webhook 地址」，点击「复制地址」。

回到宝塔面板，把地址粘贴到 「Webhook 地址」 或 「URL」 输入框。

Webhook 地址格式：

https://dev.ysykj.icu/api/im-robot-webhook.php?access_token=<64位随机Token>

2.4 填写请求参数

在宝塔面板的 「请求方式」 选择 POST，「数据格式」 选择 application/json。

在 「内容参数」 或 「Body」 输入框里，粘贴云讯通 App 成功页提供的 JSON 模板：

{ "title": "$title", "msg": "$msg", "type": "$type", "keyword": "你的安全关键词" }

说明：

- $title、$msg、$type 是宝塔的内置变量，发送告警时会自动替换为实际内容

- keyword 是你在第 1 步创建机器人时设置的安全关键词，必须和云讯通里的一致

- 云讯通 App 的成功页会自动把你的关键词填入模板，直接复制即可

2.5 保存并测试

1. 点击宝塔面板的 「保存」 或 「测试」

2. 宝塔会立即发送一条测试告警到你的 Webhook 地址

3. 检查云讯通 App → 对应的机器人会话里是否收到了测试消息

3. 配置告警规则（可选）

宝塔面板支持多种告警场景，配置好消息通道后，需要设置告警规则才会触发通知。

3.1 常见告警场景

告警类型	触发条件	示例
CPU 告警	CPU 使用率超过阈值	持续 5 分钟超过 80%
内存告警	内存使用率超过阈值	持续 5 分钟超过 90%
磁盘告警	磁盘使用率超过阈值	超过 85%
网站异常	网站状态异常	网站停止或返回 502
数据库告警	MySQL/Redis 异常	服务停止
SSL 证书到期	证书剩余天数不足	提前 7 天通知
计划任务	定时任务执行结果	备份成功/失败

3.2 配置步骤

1. 宝塔面板 → 「告警通知」→「告警规则」

2. 点击「添加规则」

3. 选择告警类型（如 CPU 使用率）

4. 设置阈值和持续时间

5. 通知方式选择你刚创建的自定义消息通道

6. 保存

4. 消息格式说明

宝塔发送的原始数据

宝塔面板发送告警时，会发送如下 JSON：

{ "title": "CPU使用率告警", "msg": "服务器CPU使用率持续超过80%\n当前值: 85.3%\n持续时间: 5分钟", "type": "监控告警", "keyword": "你的安全关键词" }

云讯通收到的消息

云讯通后端会解析宝塔的 JSON，清理 Markdown 标记（如 #、>），组合成纯文本消息：

CPU使用率告警服务器CPU使用率持续超过80% 当前值: 85.3% 持续时间: 5分钟

消息格式遵循云讯通的文本消息气泡样式，和飞书/Telegram 的文本消息一致。

5. 验证：发消息测试

5.1 在宝塔面板发送测试告警

1. 宝塔面板 → 告警通知 → 消息通道

2. 找到你创建的自定义通道

3. 点击 「测试」 按钮

4. 宝塔会发送一条测试消息

5.2 检查云讯通是否收到

- 打开云讯通 App → 消息页面

- 找到机器人会话（名称是你创建时填的，如"服务器告警"）

- 应该能看到一条测试消息

5.3 查看后端日志

如果没收到消息，查看服务器日志：

tail -f /www/wwwroot/dev.ysykj.icu/storage/im-robot-webhook.log

正常会看到：

WEBHOOK: access_token=xxx — 收到请求

ROBOT: matched id=xx type=baota — 匹配到机器人

KEYWORD: passed — 关键词验证通过

DISPATCH: text="xxx" — 消息已转发

6. 常见问题排查

消息没收到

现象	排查步骤
宝塔测试发送失败	检查 Webhook 地址是否完整复制（包括 `?access_token=` 后面的参数）
宝塔发送成功但云讯通没收到	查看后端日志 `im-robot-webhook.log`，看请求有没有到
日志显示 `Webhook 地址无效`	access_token 不对，重新从云讯通 App 成功页复制地址
日志显示 `keyword mismatch`	宝塔 JSON 模板里的 `keyword` 值和云讯通里设置的不一致
日志显示 `IP not in whitelist`	开了 IP 白名单但宝塔服务器 IP 不在白名单里，添加宝塔服务器 IP 到白名单

消息内容异常

现象	排查步骤
收到消息但内容是空的	宝塔 JSON 模板里的 `$title`、`$msg`、`$type` 变量写错了，检查拼写
消息内容有 `#` 或 `>` 符号	宝塔发的 Markdown 标记，云讯通会自动清理。如果仍有残留，检查模板格式
收到重复消息	宝塔可能配置了多个通知方式，或者告警规则设置了重复通知间隔

连接问题

现象	排查步骤
宝塔发送超时	检查服务器防火墙是否放行了 443 端口；检查宝塔服务器能否访问 `https://dev.ysykj.icu`
SSL 证书错误	宝塔面板 → 设置 → 检查 SSL 证书是否有效；或临时关闭 SSL 验证测试

附录 A：宝塔面板关键操作路径

操作	路径
告警通知首页	左侧菜单 → 告警通知
消息通道	告警通知 → 通知设置 → 消息通道
告警规则	告警通知 → 告警规则
计划任务通知	计划任务 → 添加任务 → 通知方式

附录 B：云讯通后端关键文件

文件	作用
`backend/api/im-robot-webhook.php`	Webhook 入口（接收宝塔 POST 请求）
`backend/im-robots.php`	机器人管理逻辑（创建/校验/关键词验证/IP 白名单）
`backend/im.php`	消息分发核心函数
`static/icons/robot-baota.svg`	宝塔机器人默认图标

附录 C：配置参数对照表

宝塔面板字段	云讯通 App 字段	说明
Webhook 地址	创建成功页的「Webhook 地址」	完整 URL，含 access_token 参数
请求方式	——	固定 `POST`
数据格式	——	固定 `application/json`
内容参数（Body）	创建成功页的「宝塔内容参数」	JSON 模板，含 `$title`/`$msg`/`$type` 变量
——	自定义关键词	安全关键词，需填入 JSON 模板的 `keyword` 字段
——	IP 地址白名单	可选，填宝塔服务器的公网 IP

附录 D：宝塔 JSON 模板变量说明

变量	说明	示例值
`$title`	告警标题	`CPU使用率告警`
`$msg`	告警详情（多行）	`当前值: 85.3%\n持续时间: 5分钟`
`$type`	告警类型	`监控告警` / `计划任务` / `SSL证书`

云讯通后端会自动清理 $msg 中的 Markdown 标记（# 标题、> 引用），输出纯文本。

欢迎回来

功能已关闭

个人中心

修改密码