微信内容安全:文本同步、图片异步与推送
小程序里用户能填昵称、发反馈、传图片,这些内容都要过微信的内容安全接口。文本接口是同步的,命中违规可以当场拦截;图片接口是异步的,上传时只能先返回地址,等微信把结论推回来再处理。
两条链路的失败方式完全不同:文本接口超时会拖慢发布,图片结论没收到会让前端一直停在“检测中”,推送地址配错则两条链路一起静默。本文基于 Go 1.26、Gin 1.12、silenceper/wechat v2.1.14,代码在 internal/security、internal/wechat/handler 与 internal/file/handler。
两条链路:同步文本、异步图片
微信小程序的内容安全有两个 2.0 接口:
| 能力 | 接口 | 返回方式 | 当前用途 |
|---|---|---|---|
| 文本检测 | msg_sec_check | 同步返回 suggest / label | 昵称、意见反馈 |
| 图片检测 | media_check_async | 先返回 trace_id,结论走消息推送 | 小程序专用上传 |
两个接口都必须在服务端调用:需要 access_token,也需要用户的 openid。前端小程序拿不到也不应该持有这些凭据,只能把待检测内容交给后端。
封装层做了编译期断言,确保实现覆盖接口:
// 编译期断言:Service 实现内容安全接口
var _ api.ContentSecurityApi = (*Service)(nil)
接口把能力拆成五件事:文本检测、图片检测、取 trace 上下文、记录结论、查询状态。调用方只依赖这个接口,不直接碰微信 SDK。
前提:openid 与近两小时访问
两个检测接口都要求 openid,而且微信文档写明:用户需在近两小时访问过小程序。这不是“绑定过微信”就永久有效,而是要求最近有会话。
服务端先从会员的社交绑定记录里取小程序 openid:
func (s *Service) resolveOpenID(ctx context.Context, userID int64) (string, error) {
if userID <= 0 || s.socialUserApi == nil {
return "", nil
}
socialUser, err := s.socialUserApi.GetSocialUserByUserId(
ctx, userID, enums.Member.GetVal(), enums.WechatMiniProgram.GetVal())
if err != nil {
return "", err
}
if socialUser == nil {
return "", nil
}
return socialUser.Openid, nil
}
resolveOpenID 只负责查绑定,不判断“最近是否访问过”。这个条件由微信侧判断:openid 太旧时接口会报错,当前实现按“接口异常”处理,记日志后放行。
这带来一个必须知道的边界:**只通过手机号注册、没有绑定小程序的会员,文本和图片检测都会被跳过。**如果同一份内容也能从 Web 端提交,内容安全就形同虚设。检测能力接在哪几个入口,决定了它实际覆盖哪些用户。
文本检测:只有 risky 才拦截
文本检测是同步调用,适合放在发布动作之前:
func (s *Service) CheckText(ctx context.Context, userID int64, scene int, content string) error {
content = strings.TrimSpace(content)
if content == "" {
return nil
}
openid, err := s.resolveOpenID(ctx, userID)
if err != nil {
log.Warn().Err(err).Int64("userId", userID).Msg("内容安全:查询会员 openid 失败,跳过文本检测")
return nil
}
if openid == "" {
log.Warn().Int64("userId", userID).Msg("内容安全:会员未绑定微信小程序,跳过文本检测")
return nil
}
resp, err := s.wechatClient.MiniProgram().GetSecurity().MsgCheckContext(ctx, &miniSecurity.MsgCheckRequest{
OpenID: openid,
Scene: miniSecurity.MsgScene(scene),
Content: content,
})
if err != nil {
log.Warn().Err(err).Int64("userId", userID).Msg("内容安全:文本检测接口异常,跳过拦截")
return nil
}
if resp.Result.Suggest == miniSecurity.CheckSuggestRisky {
return ErrContentRisky
}
return nil
}
scene 的取值与微信对齐:
| 值 | 场景 | 项目里的调用点 |
|---|---|---|
| 1 | 资料 | 修改昵称 |
| 2 | 评论 | 意见反馈 |
| 3 | 论坛 | 预留 |
| 4 | 社交日志 | 预留 |
只有 suggest == risky 才返回错误。pass 和 review 都放行:pass 是安全,review 是“建议人工审查”,不一定违规。直接拦截 review 会误伤大量正常内容;更合理的做法是记录 trace_id 和 label,进入人工复核队列。当前实现只打日志,没有建复核队列。
命中违规时的提示文案统一为“所发布内容含违规信息”,与微信审核指引一致,不向用户暴露具体标签。
文本长度也有硬限制:SDK 注释写明 content 上限是 2500 字,必须 UTF-8。意见反馈自身限制 1000 字,昵称更短,所以现有入口不会触顶。以后接入长文、文章评论或论坛帖子时,要先按字符数截断或分段;字符数可以用 文本统计工具 先核对,别等接口报错才发现超限。
图片检测:先返回 URL,再等推送
图片接口是异步的。上传时服务端只能提交检测并拿到 trace_id,结论最长可能在 30 分钟后才推送:
func (s *Service) CheckImageAsync(ctx context.Context, userID int64, scene int, mediaURL string) (string, error) {
mediaURL = strings.TrimSpace(mediaURL)
if mediaURL == "" {
return "", nil
}
openid, err := s.resolveOpenID(ctx, userID)
if err != nil {
log.Warn().Err(err).Int64("userId", userID).Msg("内容安全:查询会员 openid 失败,跳过图片检测")
return "", nil
}
if openid == "" {
log.Warn().Int64("userId", userID).Msg("内容安全:会员未绑定微信小程序,跳过图片检测")
return "", nil
}
traceID, err := s.wechatClient.MiniProgram().GetSecurity().MediaCheckAsyncContext(ctx, &miniSecurity.MediaCheckAsyncRequest{
MediaURL: mediaURL,
MediaType: mediaTypeImage,
OpenID: openid,
Scene: uint8(scene),
})
if err != nil {
return "", err
}
trace := api.ImageCheckTrace{UserID: userID, Scene: scene, MediaURL: mediaURL}
if err := s.redisCache.Set(ctx, imageCheckTraceKey+traceID, trace, imageCheckTraceTTL); err != nil {
log.Warn().Err(err).Str("traceId", traceID).Msg("内容安全:缓存图片检测 trace 上下文失败")
}
if err := s.redisCache.Set(ctx, imageCheckStatusKeyOf(mediaURL), api.ImageCheckStatusPending, imageCheckTraceTTL); err != nil {
log.Warn().Err(err).Str("traceId", traceID).Msg("内容安全:缓存图片检测状态失败")
}
return traceID, nil
}
关键设计是两份缓存:
cms:media_check:trace:<trace_id>:保存提交者、场景、媒体地址。推送报文只带trace_id,必须靠它还原“哪个文件、由谁提交”。cms:media_check:status:<sha1(media_url)>:保存pending/pass/risky,供小程序按媒体地址轮询。
状态键不能直接用 URL 做 Redis key:地址可能很长、带查询参数和特殊字符。代码先做 SHA-1 摘要:
func imageCheckStatusKeyOf(mediaURL string) string {
sum := sha1.Sum([]byte(mediaURL))
return imageCheckStatusKey + hex.EncodeToString(sum[:])
}
上传接口在返回前提交检测,但检测调用失败不影响上传成功:
if traceID, err := h.contentSecurityApi.CheckImageAsync(c.Request.Context(), userID, scene, fileURL); err != nil {
log.Warn().Err(err).Int64("userId", userID).Str("url", fileURL).
Msg("内容安全:小程序上传图片异步检测提交失败")
} else {
log.Info().Int64("userId", userID).Int("scene", scene).Str("traceId", traceID).Str("url", fileURL).
Msg("内容安全:小程序上传图片已提交异步检测")
}
response.Success(c, fileURL)
小程序拿到 URL 后轮询 media-check/status?url=...,看到 pass 再发布,看到 risky 就提示违规。unknown 表示没有检测记录:可能是未提交、记录已过期,或会员没有绑定小程序。
这里有一个容易被忽略的风险:图片在提交检测前已经落存储并返回了 URL。如果存储是公开读,违规图片在推送到达、文件被删除之前,可能有几十分钟的可访问窗口。更稳妥的做法是上传到隔离目录或私有桶,检测通过后再公开;当前实现依赖“上传后尽快删除”来兜底。
推送只有一个地址:事件分流与报文兼容
微信小程序后台的“消息推送”只能配置一个 URL。虚拟支付的道具发货、代币支付、退款,以及内容安全的异步检测结果,全部推到同一个地址。所以服务端不能按“一个功能一个回调”来设计,必须按事件名分流。
统一入口的路径是:
/api/weixin/mp/message/callback/:channelId
GET 用于配置地址时的签名校验,通过后原样返回 echostr;POST 用于接收事件:
func (h *MessagePushHandler) HandleMessagePush(c *gin.Context) {
// ...
event := parsePushEvent([]byte(notifyData.Body))
var outcome pushOutcome
if event == eventMediaCheck {
outcome = h.handleMediaCheckPush(c, notifyData.Body)
} else {
outcome = h.handleChannelNotify(c, channelID, payClient, notifyData)
}
h.recordOperateLog(c, channelID, channel, event, notifyData.Body, outcome)
// 内容安全的推送不让平台重推(重推也是同一个结论),其余事件按处理结果应答
if event == eventMediaCheck {
support.WriteAck(c, payClient, nil)
return
}
// ...
}
事件名是外部契约:
| 事件 | 含义 | 处理 |
|---|---|---|
wxa_media_check | 图片异步检测结果 | 写状态、命中违规时删除文件 |
xpay_goods_deliver_notify | 虚拟支付道具发货 | 更新支付订单 |
xpay_coin_pay_notify | 虚拟支付代币支付 | 更新支付订单 |
xpay_refund_notify | 虚拟支付退款 | 更新支付订单 |
报文格式是另一个坑。MP 后台的数据格式是全局配置,虚拟支付要求 XML,内容安全又可能按 JSON 推送。解析结构体必须同时打 xml 和 json 标签:
type mediaCheckPush struct {
MsgType string `xml:"MsgType" json:"MsgType"`
Event string `xml:"Event" json:"Event"`
TraceID string `xml:"trace_id" json:"trace_id"`
ErrCode int `xml:"errcode" json:"errcode"`
IsRisky mediaCheckField `xml:"isrisky" json:"isrisky"`
Result struct {
Suggest string `xml:"suggest" json:"suggest"`
Label mediaCheckField `xml:"label" json:"label"`
} `xml:"result" json:"result"`
}
只打一种标签,换格式后字段会全部为空:trace_id 为空就直接报错,suggest 为空则可能把违规当成通过。
label 和 isrisky 还有类型不稳定问题:官方文档标为数字,实际推送里出现过 "100" 这样的字符串。声明成 int64 会在 JSON 字符串下报错,声明成 string 又会在数字下报错。代码用一个自定义类型把原文收下来,再按需转成整数:
type mediaCheckField string
func (f *mediaCheckField) UnmarshalJSON(data []byte) error {
raw := strings.Trim(strings.TrimSpace(string(data)), `"`)
if raw == "null" {
raw = ""
}
*f = mediaCheckField(raw)
return nil
}
解析后统一判断是否违规:
Risky: push.ErrCode == 0 &&
(push.Result.Suggest == mediaCheckRiskySuggest || push.IsRisky.Int64() == 1),
suggest=risky 和 1.0 版本的 isrisky=1 都算违规;errcode != 0 说明检测未完成,不当作违规,也不当作通过。
应答策略:内容安全不让平台重推
微信要求回调在 5 秒内响应。处理逻辑要快:写 Redis、命中违规时删除文件,都不应该做重活。
支付事件和内容安全的应答策略不同:
- 支付事件更新订单失败时,返回失败应答,让微信按 2/4/8… 的间隔重推,最多 15 次;
- 内容安全事件无论处理成功还是失败,都返回成功应答,不触发重推。
原因是重推没有意义:同一份检测结论再推一次,trace_id 还是那个,文件还是那个,失败通常是上下文过期或本地存储异常。代码里对内容安全固定写成功应答:
if event == eventMediaCheck {
support.WriteAck(c, payClient, nil)
return
}
如果 trace_id 匹配不到提交记录,服务只记一条摘要并正常返回,不报错。这样处理两种情况:检测提交超过 24 小时、上下文已过期;或者这条推送不是本服务提交的。两种情况都不应该让微信反复重推。
失败放行:边界与风险
整条链路的选择是“可用性优先”:检测依赖不成立时放行,避免一个第三方接口故障把发布功能全部堵死。
| 场景 | 行为 | 风险 |
|---|---|---|
| 会员未绑定小程序 | 跳过检测 | Web 端或手机号用户不受覆盖 |
| openid 超过两小时未访问 | 微信报错,跳过检测 | 活跃会话之外的内容未检测 |
| 文本接口超时/限频 | 记日志,放行 | 违规文本可能发布 |
| 图片检测提交失败 | 上传仍成功,无状态记录 | 前端轮询到 unknown |
| Redis 写入失败 | 检测已提交,但无法匹配结论 | 推送到达后找不到文件 |
| 命中违规但删除文件失败 | 记错误日志,状态仍为 risky | 文件可能仍可访问 |
这套策略适合“内容安全是辅助手段、还有人工审核或举报机制”的产品。如果合规要求必须“先审后发”,就不能失败放行,需要改成:
- 文本文档检测失败时拒绝发布,并给用户可重试的提示;
- 图片进入隔离区,检测通过前不返回公开 URL;
- 检测结论写入持久化表,而不是只放 Redis;
- 对
review建议建立人工复核队列。
这些都会牺牲可用性或增加成本,是否值得取决于业务对内容风险的容忍度。
验证与排查
内容安全的解析逻辑有独立单测,覆盖 XML、JSON、1.0 的 isrisky、非法报文和 trace 缺失:
go test ./internal/security/ -v
实际输出(节选):
=== RUN TestParseMediaCheckPushXML
--- PASS: TestParseMediaCheckPushXML (0.00s)
=== RUN TestParseMediaCheckPushJSON
--- PASS: TestParseMediaCheckPushJSON (0.00s)
=== RUN TestParseMediaCheckPushLegacyIsRisky
--- PASS: TestParseMediaCheckPushLegacyIsRisky (0.00s)
=== RUN TestHandleMediaCheckPushWithoutTrace
--- PASS: TestHandleMediaCheckPushWithoutTrace (0.01s)
PASS
ok app/internal/security 0.086s
线上排查按链路分段:
| 现象 | 先查什么 | 常见原因 |
|---|---|---|
| 文本发布很慢 | 文本检测接口耗时、access_token 获取 | 微信接口超时、限频 |
| 文本违规没拦住 | openid 是否为空、日志是否有“跳过文本检测” | 会员未绑定小程序、openid 过期 |
| 图片一直 pending | trace 键是否存在、推送是否到达 | 推送地址未配置、报文解析失败 |
| 图片状态 unknown | 是否调用了小程序专用上传接口 | 用了通用上传,未提交检测 |
| 命中违规文件还在 | 删除文件日志 | 文件能力未注入、存储删除失败 |
| 推送一直重推 | 是否返回了成功应答 | 事件名判断错误、应答格式不符 |
Redis 里可以直接核对两类键:
redis-cli --scan --pattern 'cms:media_check:trace:*'
redis-cli --scan --pattern 'cms:media_check:status:*'
trace 键在读取时会被删除(GetDelete),所以推送处理后看不到是正常的;status 键会保留 24 小时,供前端继续轮询。
命中标签可以用可读文案排查。代码把微信的标签转成中文,例如 20001 时政、20002 色情、20003 辱骂、20008 欺诈、20013 版权。日志里同时记录 trace_id、label、suggest 和媒体地址,定位时不要只看“是否违规”,要看命中的具体标签。
FAQ
为什么图片不用同步检测?
微信的同步图片接口 img_sec_check 已在 2021 年停止更新,官方建议迁移到 media_check_async。异步接口不阻塞上传,但结论要等推送,产品上必须接受“先展示、后撤下”的窗口。
文本接口返回 review 要不要拦截?
当前不拦截。review 表示建议人工审查,不等于违规;直接拦截会误伤正常内容。更稳妥的做法是记录 trace_id 和标签,进入人工复核,而不是在发布链路上直接拒绝。
为什么会员没绑定小程序就跳过检测?
检测接口必须传 openid,没有绑定就拿不到。跳过是为了不让手机号注册用户在发布时直接报错。代价是这部分用户的内容不受微信内容安全覆盖,需要靠站内审核或其他手段补足。
推送地址为什么不能给内容安全单独配一个?
微信小程序后台的“消息推送”全局只能配一个 URL,虚拟支付也要求推到同一个地址。所以只能在服务端按 Event 分流,不能按功能拆回调地址。
内容安全推送失败了,微信会重推吗?
不会。当前实现无论处理结果如何都返回成功应答,避免同一结论反复推送。失败要靠日志和监控发现,不能依赖平台重试。
结语:内容安全不是“调一个接口”就结束了。文本要接受同步延迟和 review 语义,图片要接受异步窗口和公开 URL 风险,推送要处理单地址分流与 XML/JSON 兼容,最后还要明确失败时是放行还是拦截。
用 文本统计工具 检查待检测文本的字符数;同一个消息推送地址还承载虚拟支付事件,回调分流与幂等可参考 PayPal capture 与回调幂等,更多后端文章在 后端开发分类。
Comments
No comments yet — be the first to say something