关键词过滤使用指南

什么是关键词过滤？

关键词过滤是接口（Endpoint）层面的一项安全功能，可以在消息推送到渠道之前，根据消息内容中的关键词决定是否放行。

简单来说：在消息发出前做最后一道内容检查。

典型使用场景

场景	推荐模式	说明
过滤垃圾广告	黑名单	拦截包含"广告""推广"等词的消息
过滤敏感词汇	黑名单	拦截包含违规内容的消息
只接收特定告警	白名单	只有包含"Critical""P0"等关键词的消息才放行
只接收指定来源	白名单	消息标题中必须包含"Grafana"才推送

工作原理

在消息流程中的位置

外部请求 → 解析消息 → [关键词过滤] → 推送到渠道
                        ↓
              命中规则 → 返回错误，不推送
              未命中规则 → 继续后续流程

关键词过滤在消息解析完成之后、渠道推送之前执行。一旦触发拦截，消息不会发送到任何渠道。

匹配方式

检查范围：同时检查消息的标题 + 正文
匹配逻辑：将标题和正文拼接后，逐一判断是否包含每个关键词
大小写：不敏感（CPU 和 cpu 视为相同）
匹配类型：子串匹配（关键词是消息内容的一部分即可命中）

两种过滤模式

黑名单模式（默认）

命中列表中任一关键词 → 拦截消息

适用于：排除不需要的消息。

配置的关键词: ["广告", "推广", "赌博"]

消息标题: "服务器CPU告警"
消息正文: "当前CPU使用率95%"
→ 不含任何关键词 → ✅ 放行，正常推送

消息标题: "限时推广优惠活动"
消息正文: "..."
→ 包含"推广" → ❌ 拦截，返回"包含不合法内容"

白名单模式

未命中列表中任何一个关键词 → 拦截消息

适用于：只接收特定的消息。

配置的关键词: ["Critical", "P0"]

消息标题: "[CRITICAL] 磁盘空间不足"
消息正文: "..."
→ 包含"Critical" → ✅ 放行，正常推送

消息标题: "[INFO] 定时任务完成"
消息正文: "..."
→ 不包含任何关键词 → ❌ 拦截，返回"未包含合法内容"

配置方法

第一步：打开配置面板

进入「接口管理」页面
找到要配置的接口卡片
点击卡片右上角的「...」按钮，选择「关键词过滤」

也可以直接点击卡片下方显示的过滤状态标签（显示为「黑名单模式」「白名单模式」或「未配置」）。

第二步：启用并设置

开启开关

打开「启用关键词过滤」开关后，会显示以下配置项：

选择过滤模式

两种模式以卡片形式展示，点击切换：

模式	颜色标识	说明
黑名单模式（默认）	橙色边框	命中关键词则拦截
白名单模式	蓝色边框	未命中任何关键词则拦截

填写关键词列表

每个关键词单独一行输入框
最多支持 50 个关键词
输入框右侧可删除该关键词
底部「添加关键词」按钮增加新行

提示：每行一个关键词，大小写不敏感，匹配到任一关键词即触发对应模式的规则。

第三步：保存

点击底部「保存配置」按钮生效。

保存成功后，接口卡片上会显示当前的过滤模式和状态标签：

橙色标签：黑名单模式运行中
蓝色标签：白名单模式运行中

配置示例

示例一：拦截垃圾信息（黑名单）

你通过 Webhook 接收各种通知，但想过滤掉推广类消息。

配置：

模式：黑名单
关键词：
```
广告
推广
优惠
免费领取
```

效果：

消息内容	是否包含关键词	结果
`服务器告警: CPU 超过 90%`	无	✅ 正常推送
`【推广】限时优惠活动`	命中"推广"、"优惠"	❌ 拦截
`免费领取会员资格`	命中"免费领取"	❌ 拦截
`广告位招租`	命中"广告"	❌ 拦截

示例二：只接收严重告警（白名单）

你接收到大量监控通知，但只想在手机上收到最严重的那些。

配置：

模式：白名单
关键词：
```
Critical
P0
DOWN
```

效果：

消息内容	是否包含关键词	结果
`[CRITICAL] 数据库连接失败`	命中"Critical"	✅ 正常推送
`[P0] 服务不可用`	命中"P0"	✅ 正常推送
`[WARNING] 内存使用率 75%`	无	❌ 拦截
`[INFO] 定时任务执行完成`	无	❌ 拦截

示例三：按来源过滤（白名单）

你的接口同时接收来自 Grafana 和 GitHub 的 Webhook，但只想转发 Grafana 的消息。

配置：

模式：白名单
关键词：
```
grafana
alerts
```

效果：

来源	典型消息内容	是否包含关键词	结果
Grafana	`HighCPU alerts[0].labels.alertname`	命中"alerts"	✅ 放行
GitHub	`octocat pushed to main`	无	❌ 拦截

注意：如果使用了入站配置的 JSONPath 映射，关键词检查的是最终提取出的标题和正文，不是原始的 JSON 数据。

示例四：多关键词组合防护（黑名单）

构建一个较为完善的过滤规则，拦截多种垃圾内容。

配置：

模式：黑名单

关键词：

加微信
扫码
代购
刷单
赚钱
彩票

只要消息的标题或正文中出现以上任意一个词，就会被拦截。

匹配细节说明

子串匹配

关键词不需要独立成词，只要是内容的连续一部分就算命中：

消息内容	关键词	是否命中	原因
`CPU 使用率过高`	`cpu`	✅ 命中	大小写不敏感
`服务器 alerting 中`	`alert`	✅ 命中	子串匹配
`这是一条正常消息`	`正常`	✅ 命中	中文同样适用
`warning`	`warn`	✅ 命中	子串匹配
`warnxxx`	`warn`	✅ 命中	子串匹配
`abc`	`xyz`	❌ 未命中	内容中不存在

标题和正文联合检查

系统会将标题和正文拼在一起做匹配：

标题: "服务器告警"
正文: "CPU 使用率 90%"
↓ 拼接后检查
"服务器告警 cpu 使用率 90%"

即使关键词只出现在标题或只出现在正文，都会被检测到。

短路返回

匹配到第一个命中的关键词就立即返回结果，不会继续检查剩余关键词。这在有大量关键词时可以保证性能。

被拦截时的行为

当消息被关键词过滤拦截时：

不会推送到任何渠道
不会产生推送日志
调用方会收到错误响应：
- 黑名单模式：包含不合法内容
- 白名单模式：未包含合法内容

这意味着被拦截的消息完全消失，不会有任何痕迹留在系统中。

与其他功能的关系

与入站配置的关系

如果接口同时启用了入站配置和关键词过滤，处理顺序如下：

原始数据 → 入站配置（格式转换） → 标准化消息 → 关键词过滤 → 推送渠道
                                    ↑
                              检查的是转换后的标题和正文

关键词过滤检查的是经过入站配置转换后的最终消息内容，不是原始 JSON。

与免打扰的关系

关键词过滤在免打扰检查之前执行。如果消息被关键词过滤拦截了，根本走不到免打扰环节。

消息到达 → 关键词过滤（先） → 更新时间 → 获取渠道 → 免打扰检查（后） → 推送
            ↑ 拦截则直接结束

常见问题

Q：关键词区分大小写吗？

不区分。CPU、cpu、Cpu 都视为同一个词。

Q：一个中文算一个关键词还是多个字？

整个输入框的内容作为一个关键词。比如填写"免费领取"，那么只有当消息内容中出现完整的"免费领取"这四个字的连续组合时才会命中。"免费"和"领取"分开出现不会触发。

Q：可以配置多少个关键词？

最多 50 个。达到上限后「添加关键词」按钮会自动隐藏。

Q：空关键词会被忽略吗？

是的，保存时会自动过滤掉空白关键词。但启用过滤时必须至少有一个有效关键词，否则无法保存。

Q：修改配置后立即生效吗？

是的，保存后立即生效，无需重启服务或重新部署。

Q：被拦截的消息能恢复吗？

不能。被拦截的消息不会被存储或记录到日志中，无法事后恢复。如果担心误拦截，建议先用少量关键词测试效果，再逐步完善规则。

Q：如何临时关闭过滤而不删除配置？

关闭「启用关键词过滤」开关并保存即可。已填写的关键词和模式设置会保留，下次重新开启时无需重新配置。

关键词过滤使用指南 ​

什么是关键词过滤？ ​

典型使用场景 ​

工作原理 ​

在消息流程中的位置 ​

匹配方式 ​

两种过滤模式 ​

黑名单模式（默认） ​

白名单模式 ​

配置方法 ​

第一步：打开配置面板 ​

第二步：启用并设置 ​

开启开关 ​

选择过滤模式 ​

填写关键词列表 ​

第三步：保存 ​

配置示例 ​

示例一：拦截垃圾信息（黑名单） ​

示例二：只接收严重告警（白名单） ​

示例三：按来源过滤（白名单） ​

示例四：多关键词组合防护（黑名单） ​

匹配细节说明 ​

子串匹配 ​

标题和正文联合检查 ​

短路返回 ​

被拦截时的行为 ​

与其他功能的关系 ​

与入站配置的关系 ​

与免打扰的关系 ​

常见问题 ​

Q：关键词区分大小写吗？ ​

Q：一个中文算一个关键词还是多个字？ ​

Q：可以配置多少个关键词？ ​

Q：空关键词会被忽略吗？ ​

Q：修改配置后立即生效吗？ ​

Q：被拦截的消息能恢复吗？ ​

Q：如何临时关闭过滤而不删除配置？ ​