故障排查

收不到消息

按顺序检查：

1. 机器人是否已经加入目标群；
2. Webhook 地址或应用凭证是否正确；
3. 事件是否真的触发（在来源系统查看投递记录）；
4. 目标群和事件过滤是否把消息挡掉了；
5. 服务日志中是否有鉴权、签名或网络错误。

Webhook 校验失败

• 确认签名密钥与来源系统一致；
• 检查请求头是否完整；
• 确认服务器时间偏差不会导致签名过期；
• 如果来源系统支持重放，先用一次测试事件验证。

权限不足

• 自建应用是否已发布并获得管理员授权；
• 所需权限是否在应用申请页中开通；
• 租户是否限制了机器人可用的能力；
• 权限变更后是否重新授权。

重复通知

• 来源系统是否重复投递同一事件；
• 是否配置了多个目标群或重复的订阅；
• Webhook 触发器是否被多个规则匹配；
• 检查重试策略是否导致重复发送。

私信或群成员操作失败

• 自建应用是否具备对应的消息和通讯录权限；
• 目标成员是否在机器人可见范围内；
• 群设置是否限制了机器人操作。

私有化部署相关

• 服务器能否访问飞书开放平台；
• 反向代理是否正确转发回调和健康检查；
• 数据库和持久化卷是否可写；
• 升级后配置是否仍然兼容。

提示

排查时先用一个测试群和一条测试事件，避免在正式群里反复试错。仍无法解决时，带上时间、群 ID、事件类型和日志片段联系交付支持。