内容替换使用指南

什么是内容替换？

内容替换是接口（Endpoint）层面的一项内容处理功能，可以在消息推送到渠道之前，把消息中指定的字面量字符串自动替换成另一个字符串。

简单来说：在消息发出前，按你设定的规则自动"改写"内容。

它与关键词过滤是"兄弟功能"：关键词过滤负责"拦"（命中就不发），内容替换负责"改"（照常发，但内容被改写后再发）。

典型使用场景

场景	说明
统一链接域名	把消息里的 `http://` 自动改成 `https://`，避免部分渠道不支持明文链接
脱敏处理	把消息里出现的 token、密钥等敏感串替换成 `***` 再推送
品牌词统一	把产品旧名替换成新名，无需改动上游推送方
屏蔽特定词汇	把不希望出现的词替换成空（即删除），但消息仍正常发送
渠道兼容	某些渠道不支持 `< > &` 等特殊字符，统一替换成安全字符

工作原理

在消息流程中的位置

外部请求 → 解析消息 → [关键词过滤] → [内容替换] → 写入日志 → 推送到渠道
                        ↓(先,基于原文)   ↓(后,改写内容)
                      拦截则结束      替换后内容进入日志与渠道

内容替换在关键词过滤之后、写入推送日志和渠道推送之前执行。这意味着：

关键词过滤基于原始内容判断，替换操作不会让被改掉的字面量绕过过滤规则；
推送日志里记录的，以及实际发到微信/邮件/Telegram 等渠道的，都是替换后的内容。

作用范围

内容替换会同时作用于以下四个字段：

字段	是否替换	说明
`title`	✅	消息标题
`content`	✅	消息正文
`url`	✅	消息链接
`extraData`	✅	附加数据（含各渠道命名空间），深度递归替换其中所有字符串值

匹配方式

匹配类型：字面量子串匹配（不是正则），因此特殊字符（如 . * (）无需转义，也不会有误匹配风险
大小写：敏感（区分大小写）。Error 能命中 Error，但不会命中 error 或 ERROR
生效顺序：规则按列表从上到下顺序应用，并且级联——上一条规则的输出会作为下一条规则的输入
to 为空：表示把 from 这个字面量删除（替换为空串）

配置方法

第一步：打开配置面板

进入「接口管理」页面
找到要配置的接口卡片
点击卡片右上角的「...」按钮，选择「内容替换」

也可以直接点击卡片下方显示的替换状态标签（显示为「已启用 (N 条)」或「未配置」）。

第二步：启用并设置

开启开关

打开「启用内容替换」开关后，会显示规则列表。

填写替换规则

每条规则由两部分组成：

待替换内容（from）：消息中要被找到并替换的字面量，必填，最长 100 个字符
替换为（to）：替换后的目标字符串，可留空（表示删除该字面量），最长 200 个字符

规则以 from → to 的形式逐行排列：

每行一条规则
最多支持 50 条规则
每行右侧可删除该规则
底部「添加规则」按钮增加新行

提示：规则按从上到下的顺序依次执行，且前一条的结果会传递给下一条（级联）。如果你的规则之间存在先后依赖，请注意排列顺序。

第三步：保存

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

保存成功后，接口卡片上会显示「已启用 (N 条)」状态标签。关闭开关并保存则停用替换（已配置的规则会保留，下次开启无需重填）。

配置示例

示例一：统一升级 http 为 https

你的推送方有时发出 http:// 链接，而部分渠道对明文链接支持不好。

配置：

启用：开
规则：
```
http://  →  https://
```

效果：

原始内容	替换后内容
`查看详情: http://example.com/a`	`查看详情: https://example.com/a`
`http://old.host/x`	`https://old.host/x`

所有出现的 http:// 都会被改写，其余内容不变。

示例二：敏感信息脱敏

消息里偶尔会带上学名 token，希望在推送出去前先遮掉。

配置：

启用：开
规则：
```
sk-1234567890abcdef  →  ***
```

效果：

原始内容	替换后内容
`部署完成, token=sk-1234567890abcdef`	`部署完成, token=***`

注意：from 是区分大小写的完整字面量。如果 token 大小写不固定，需要为每种形式分别配置一条规则。

示例三：级联替换

通过多条规则串联，实现"先把 A 改成 B，再把 B 改成 C"。

配置：

启用：开
规则：
```
Error  →  Warn
Warn   →  Warning
```

效果（级联）：

原始内容	处理过程	最终内容
`Alert: Error on host`	`Error`→`Warn`，接着 `Warn`→`Warning`	`Alert: Warning on host`

如果只想做单次替换，把第二条规则去掉即可。

示例四：删除特定词汇 + 改写 extraData

extraData 中的渠道附加数据也会被递归替换。

配置：

启用：开

规则：

internal-  →  (空)
staging    →  prod

假设传入消息：

json

{
  "title": "internal-部署通知",
  "content": "服务已发布",
  "extraData": {
    "wechat": { "channelType": "text", "note": "来自 staging 环境" }
  }
}

效果：

标题：internal-部署通知 → 部署通知
extraData.wechat.note：来自 staging 环境 → 来自 prod 环境

即 extraData 里嵌套的所有字符串值都会按照同样的规则被改写。

匹配细节说明

字面量子串匹配

只要 from 是消息内容的连续一部分，就会被替换（全部出现位置都会被替换，不止第一处）：

消息内容	from	to	结果	说明
`abc error def`	`error`	`x`	`abc error def`	区分大小写，`error`≠`Error`，不命中
`Error: Error`	`Error`	`Warn`	`Warn: Warn`	两处都替换
`这是一段正常文本`	`正常`	`OK`	`这是一段OK文本`	中文同样适用
`a.b*c`	`.*`	`-`	`a-b-c`	字面量，`.*` 就按字符本身匹配，不是正则

区分大小写

消息内容	from	是否命中
`CPU 告警`	`cpu`	❌ 不命中（大小写不同）
`CPU 告警`	`CPU`	✅ 命中

如果希望同时覆盖多种大小写，需要为每种形式分别配置一条规则。

顺序级联

规则按列表顺序依次应用，上一条的输出作为下一条的输入：

原始:  "A"
规则1: A → B
规则2: B → C
结果:  "C"

如果规则顺序反过来（先 B→C 再 A→B），则结果为 B（因为第一步没有 A 可匹配）。请按需排列顺序。

extraData 递归替换

extraData 可能是多层嵌套的对象或数组，内容替换会深度遍历其中的每一个字符串值，非字符串的值（数字、布尔、null）保持不变，对象结构也保持不变。

to 为空 = 删除

to 留空时，该字面量被替换为空串，等同于从内容中移除：

消息内容	from	to	结果
`广告位招租`	`广告`	(空)	`位招租`

与其他功能的关系

与关键词过滤的关系

消息到达 → [关键词过滤] → [内容替换] → [写入日志] → [推送到渠道]
              ↑ 基于原文判断               ↑ 替换后的内容进入日志与渠道

关键词过滤先执行，且基于未被替换的原始内容判断。因此，即使一条规则会把某个敏感词替换掉，关键词过滤仍会基于原始内容命中并拦截。两者串行、互不冲突。

与入站配置的关系

如果接口同时启用了入站配置和内容替换，处理顺序为：

原始数据 → 入站配置（格式转换） → 标准化消息 → 关键词过滤 → 内容替换 → 推送渠道
                                              ↑           ↑
                                         检查的是原文   改写的是转换后的最终内容

内容替换作用的是经过入站配置转换后的最终消息内容。

与免打扰的关系

内容替换在免打扰检查之前完成。被免打扰静默的消息，其日志中记录的也是替换后的内容。

对调用方响应的影响

内容替换对调用方完全透明：

接口返回的是正常的成功响应，不会包含"已替换"之类的额外标记
调用方无法从响应中得知内容是否被改写
按渠道 ID 直接推送（pushByChannel）的路径不经过内容替换（该路径没有接口上下文），只有「按接口推送」（令牌 / 接口 ID）才会生效

对日志的影响

推送日志中保存的标题与正文是替换后的内容。如果你需要审计原始内容，请注意这一点——替换后的日志中无法直接看到原文。

常见问题

Q：内容替换区分大小写吗？

区分。CPU 和 cpu 视为不同的字面量。如果上游推送的大小写不固定，需要为每种形式各配一条规则。

Q：支持正则表达式吗？

不支持。内容替换使用字面量（子串）匹配，不是正则。这避免了特殊字符转义和性能（ReDoS）问题，也更直观。如果你需要"模式匹配"，目前请用多条字面量规则组合逼近。

Q：一条规则能配多少个字符？

from 最长 100 个字符，to 最长 200 个字符（可为空）。超过会在保存时被拒绝。

Q：最多几条规则？

最多 50 条。达到上限后「添加规则」按钮会自动隐藏。

Q：规则的生效顺序重要吗？

重要。规则按从上到下的顺序级联执行：上一条的替换结果会作为下一条的输入。如果规则之间存在依赖，请留意排列顺序。

Q：会替换 extraData 里的内容吗？

会。extraData（含各渠道命名空间）中所有字符串值都会被递归替换，但对象结构和其他类型的值保持不变。

Q：被替换的内容在日志里能查到原文吗？

不能。推送日志保存的是替换后的内容。如果业务需要保留原文做审计，请在调用方侧另行记录。

Q：按渠道 ID 直接推送也会替换吗？

不会。内容替换仅对「按接口推送」（令牌 / 接口 ID）生效；按渠道 ID 直接推送的路径没有接口上下文，不会应用替换规则。

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

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

Q：如何临时关闭替换而不删除规则？

关闭「启用内容替换」开关并保存即可。已配置的规则会保留，下次重新开启时无需重新填写。

内容替换使用指南 ​

什么是内容替换？ ​

典型使用场景 ​

工作原理 ​

在消息流程中的位置 ​

作用范围 ​

匹配方式 ​

配置方法 ​

第一步：打开配置面板 ​

第二步：启用并设置 ​

开启开关 ​

填写替换规则 ​

第三步：保存 ​

配置示例 ​

示例一：统一升级 http 为 https ​

示例二：敏感信息脱敏 ​

示例三：级联替换 ​

示例四：删除特定词汇 + 改写 extraData ​

匹配细节说明 ​

字面量子串匹配 ​

区分大小写 ​

顺序级联 ​

extraData 递归替换 ​

to 为空 = 删除 ​

与其他功能的关系 ​

与关键词过滤的关系 ​

与入站配置的关系 ​

与免打扰的关系 ​

对调用方响应的影响 ​

对日志的影响 ​

常见问题 ​

Q：内容替换区分大小写吗？ ​

Q：支持正则表达式吗？ ​

Q：一条规则能配多少个字符？ ​

Q：最多几条规则？ ​

Q：规则的生效顺序重要吗？ ​

Q：会替换 extraData 里的内容吗？ ​

Q：被替换的内容在日志里能查到原文吗？ ​

Q：按渠道 ID 直接推送也会替换吗？ ​

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

Q：如何临时关闭替换而不删除规则？ ​