消息规则使用教程

一. 场景说明

　很多第三方工具、定时任务、现成脚本集成pushplus的时候，并没有很好的实现pushplus的接口参数，一方面pushplus在不断的增加新功能、扩展新渠道，一方面第三方开发者图省事只完成了最基本的请求就认为完成了。

　比如有的脚本工具上没有to参数，无法发送好友消息；有的脚本上只支持填写一个渠道参数，无法同时推送到多个渠道消息。往往还有很多脚本发布以后没有人维护更新，使用者也无法联系到对应开发者。使用者便来联系pushplus，希望把逻辑都放到pushplus上来实现。

　消息规则就是为了解决上面的问题，把这段逻辑放到 pushplus 上：第三方只需要请求原来的发送地址，平台按你配置的规则提取字段、判断是否命中、改写标题和内容，再转发到一个或多个渠道。

典型场景包括：

阿里云监控、主机监控、Prometheus 等只能填写一个 Webhook，需要同时通知微信和群机器人。
Jenkins、路由器插件、老脚本已经写死了 pushplus 请求，无法改代码，但想补标题、改渠道或套预处理。
邮件推送到 {令牌}@yp9.cn 后，按主题或正文再分发到不同渠道。

注意：消息规则功能仅对会员开放。非会员或未开启总开关时，请求仍按原来的直推逻辑发送。

配置流程可以概括为五步：

二. 工作原理

　开启消息规则后，消息接口和邮件推送都会先进入规则引擎，不再立刻按请求里的 channel 直发。

处理顺序如下：

确认账号是会员，并且总开关已开启。
按绑定令牌、触发来源筛出可用规则，再按匹配顺序从小到大执行。
从请求头、Query、请求体或邮件主题/正文中提取变量。
判断是否在触发时间段、是否满足条件、是否被频率限制。
用标题模板、内容模板、消息模板和预处理编码改写消息。
按发送目标拆成一条或多条消息发出。目标里没填的字段，仍沿用原请求的值。

总开关有三种模式，在「我的」->「个人中心」->「消息规则」里切换：

模式	说明
关闭（推送与原来一致）	不走规则，和以前一样直推
开启，未命中时仍按默认方式推送	命中规则就按规则发；一条都没命中时，仍按原请求推送
开启，未命中时不推送	命中才发；全部未命中则返回「未命中任何消息规则」

打开消息规则页面

三. 配置操作

配置前请先开通会员。然后进入「我的」->「个人中心」->「消息规则」。

1. 开启消息规则

在页面上方把「消息规则」从关闭改成两种开启模式之一。只新增规则、不打开总开关，请求仍会直推，规则不会生效。

建议先选「开启，未命中时仍按默认方式推送」，确认规则命中正常后再改成严格模式。

2. 新增一条规则

点击「新增消息规则」，进入 forwardRule.html。先填写基础信息：

规则名称：方便自己识别，例如「阿里云监控多渠道」。
匹配顺序：数字越小越先匹配。多条规则可以同时命中；如果勾选「命中后不再匹配后续规则」，命中后会停止。
绑定 Token：全部令牌、用户令牌，或指定某个消息令牌。只想改某一个脚本时，给它单独建消息令牌并绑到这条规则上。
触发来源：全部 / 消息接口 / 邮件。阿里云监控、脚本走消息接口。
状态：保存后是否启用这条规则。

3. 提取模板变量

从请求里取出字段，供条件和通知内容使用。日常用「序列化数据」即可，键填字段名；请求体是 JSON 时可用点路径，如 alerts.0.job。

来源	适用场景	提取方式
请求体	消息接口 POST JSON / 表单	序列化数据、JSONPath、正则、原始全文
Query参数	URL 上的 title、template、topic	序列化数据、正则
请求头	User-Agent、自定义头	序列化数据、正则
主题 / 邮件正文	邮件推送	原始全文、正则、JSONPath

不需要自己提取的内置变量可以直接用：

消息接口：title、content、body、template、token、ip、method、contentType
邮件：另外还有 subject、from、to、cc

模板和条件里都写成 {{变量名}}。Query 与请求体有同名字段时，内置 title / content 以 Query 为准；若要单独取 Body 里的字段，请再加一个自定义变量。页面上的「填写说明」也有同样的对照表。

4. 设置触发条件

不添加条件则每次请求都转发。也可以按变量做过滤，例如只转发 alertState 等于 ALERT 的告警。

支持同时满足全部条件，或满足任一条件。运算符包括等于、包含、正则、大于、在列表中、为空等。熟悉表达式时，可以切到表达式模式，例如 alertState == 'ALERT' && Number(curValue) >= 90。图形模式下会同步显示等价表达式，方便核对。

5. 改写通知内容

消息标题、消息内容留空，则沿用原标题和原内容。
需要补全或重排时，用 {{变量名}} 拼新内容，也可点「插入变量」。
消息模板可选 html / markdown / txt / json，也可改成变量。
预处理信息是在内容渲染完成后再加工，适合做替换、追加。请先在预处理信息里创建编码。

这一步就是「对无法修改的脚本做补全」：脚本只传了 content，规则可以补上标题、模板、渠道和预处理。

6. 添加发送目标

一条规则最多 5 个发送目标。每个目标都可以指定：

发送渠道：微信公众号、Webhook、企业微信、邮件、App、QQ 机器人等；留空则用该 Token 的默认渠道。
渠道参数：Webhook 编码、企业微信编码、邮箱编码等，对应发送接口的 option。
消息类型：一对一、一对多、好友消息。一对多再选群组，好友消息再选好友。

渠道、参数、类型都可以改成变量，按请求内容动态决定发到哪里。需要同时通知多个渠道时，再点「添加发送目标」。

7. 高级设置和在线测试

高级设置里可以限制「N 秒内最多触发几次」、生效时间段和星期。跨零点时间段有效，例如 22:00 到 06:00。全不勾选星期表示每天生效。

配完后先点「在线测试」，用一条真实报文模拟，不会真正发送。确认变量提取正确、条件能命中、标题内容渲染符合预期，再保存。

上图是把阿里云风格的 JSON 贴进去后的结果：条件 alertState == 'ALERT' 满足，规则会转发。

在 pushplus 中准备好要接收的渠道，例如企业微信机器人 Webhook，记下编码 qywx。
开通会员，打开消息规则，选择「开启，未命中时仍按默认方式推送」。
新增规则，触发来源选「消息接口」，绑定对应 Token。
从请求体提取 alertName、alertState、instanceName、curValue。
条件设为 alertState 等于 ALERT，恢复通知可不转发，避免打扰。
标题填 {{alertName}}，内容填实例和当前值。
添加多个发送目标：微信公众号一对一、Webhook（qywx）、如有需要再加邮件。
阿里云回调地址保持原样，不必改成多个地址：

http://www.pushplus.plus/send/{token}?template=cloudMonitor

发生告警时，阿里云仍然只 POST 一次。pushplus 命中规则后，会按目标拆成多条消息。主机监控和事件监控的报文不同，可用在线测试把真实 JSON 贴进去验证。

2. 无法修改的脚本、工具：补全 pushplus 请求

很多现成工具已经写死了请求体，例如只传 token 和 content，没有 title、channel、template。源码改不了，或者改了下次升级又会被覆盖。

常见来源：

路由器插件、旧版 Jenkins / xxl-job 任务，只配了 token。
第三方「通知到 Webhook」功能，JSON 字段和 pushplus 不完全对应。
同事留下的脚本，只能改 Token，不能改请求体。

做法：

给这个工具单独建一个消息 token，规则只绑定这个 token，避免影响你自己的其他推送。
触发来源选「消息接口」。
用内置变量 content / body 做条件，例如内容包含 ERROR 才转发，或内容不为空就转发。
在通知内容里补全标题，例如 生产环境告警，或 {{content}} 截一段当标题。
需要整理正文时，套一条预处理编码，把原始文本替换、追加说明。
发送目标改成你真正要收的渠道。目标里指定了 channel / option 后，会覆盖脚本里缺省或错误的渠道。

脚本继续这样调用即可，不用改代码：

{
  "token": "消息token",
  "content": "disk usage 92% on gateway-01"
}

规则命中后，实际发出的消息可以是：标题「网关磁盘告警」，内容补上主机名和时间，同时发到微信和企业微信。

如果工具连 JSON 都不能改、只能填一个 URL，把地址写成：

https://www.pushplus.plus/send/{消息token}

其余 title、channel、template、topic 都交给规则补。