moviepilot企业微信消息推送失败原因？

Question

MoviePilot 企业微信消息推送失败的常见技术原因之一是应用配置错误。例如，企业微信中自建应用的AgentId或Secret配置不正确，会导致调用接口时身份验证失败。此外，网络策略限制、回调URL无法访问或未通过可信域名验证，也会中断推送流程。部分情况下，消息内容包含敏感词或超出长度限制，将被企业微信后台拦截。需检查日志信息并结合返回码（如40013、40035等）精准定位问题。

Answer 1

1. 常见技术问题分析：应用配置错误导致消息推送失败

在使用 MoviePilot 集成企业微信消息推送功能时，最常见的技术障碍之一是应用配置不正确。这通常表现为 AgentId 或 Secret 配置错误，导致调用企业微信 API 时身份验证失败。

• AgentId 错误：每个自建应用都有唯一的 AgentId，若在 MoviePilot 中填写了错误的 ID，系统将无法识别该应用。
• Secret 不匹配：Secret 是用于获取 access_token 的关键凭证，一旦配置错误或被重置而未同步更新，会导致 token 获取失败。
• Token 获取异常：由于 AgentId/Secret 错误，调用 /gettoken 接口返回 errcode: 40013（invalid appid）或 40001（invalid credential）。

2. 网络策略与访问控制限制

即使应用配置正确，网络层面的问题也可能中断消息推送流程。以下为常见网络相关因素：

问题类型	具体表现	可能返回码
回调URL不可达	服务器防火墙屏蔽、内网部署未做端口映射	40035（无效 URL 格式或无法访问）
可信域名未验证	企业微信要求回调域名必须备案并通过验证	94000（domain unverified）
出站策略限制	MoviePilot 所在服务器无法访问 qyapi.weixin.qq.com	Connection timeout / DNS resolution failed

3. 消息内容合规性与格式限制

企业微信对推送消息的内容有严格的安全审查机制。即便前序步骤均正常，仍可能因内容问题导致推送失败。

1. 消息长度超过限制（如文本消息超过 2048 字符）。
2. 包含敏感词汇（如“赌博”、“发票”等），触发内容过滤引擎。
3. JSON 结构不符合 API 规范，例如缺少 touser、msgtype 字段。
4. 使用了不支持的 media_id 或图文链接格式错误。

{
  "touser": "zhangsan",
  "msgtype": "text",
  "agentid": 1000007,
  "text": {
    "content": "这是一条测试消息"
  },
  "safe": 0
}

上述 JSON 示例需确保字段完整且 content 不含违规内容。

4. 日志分析与错误码定位方法

精准排查推送失败原因的关键在于日志分析与企业微信返回码解读。以下是典型错误码及其含义：

错误码	含义	建议操作
40013	invalid appid	检查 AgentId 是否正确
40001	invalid credential	核对 Secret 并重新获取 access_token
40035	invalid parameter	检查请求参数格式
90001	user not in chat	确认接收用户存在于企业通讯录
93002	message too long	压缩消息内容至 2048 字符以内

5. 故障排查流程图（Mermaid 格式）

graph TD
    A[消息推送失败] --> B{检查日志返回码}
    B -->|40013| C[验证 AgentId 正确性]
    B -->|40001| D[核对 Secret 配置]
    B -->|40035| E[检查请求参数合法性]
    B -->|其他错误| F[查看网络可达性]
    F --> G[测试 qyapi.weixin.qq.com 连通性]
    G --> H[确认回调URL可公网访问]
    H --> I[检查企业微信可信域名设置]
    I --> J[审查消息内容长度与敏感词]
    J --> K[重新发起推送]