研发平台对接飞书后消息延迟或收不到，排查顺序建议固定为三步：先确认消息是否已从研发平台发出，再核对飞书侧渠道配置与权限，最后检查接口调用与投递链路。每一步都要拿到日志、返回码或配置截图作为证据，避免把猜测直接当成原因。本文按症状界定、原因验证、分类处置、恢复验证四个环节展开，适用于单条通知、单个群、单个应用或全部通知出现异常时的定位。
要点总览（TL;DR）
- 排查按固定顺序推进：先确认研发平台是否已生成发送记录，再核对飞书侧应用权限、机器人与群配置、接收对象范围，最后检查接口返回码、限流与重试情况。
- 完全收不到与延迟到达的排查起点不同：前者优先查通知规则、权限与接收对象，后者优先查接口限流、超时与重试排队。
- 每一步都要用日志、返回码或配置截图作为证据，未确认的假设先继续验证，不直接改配置。
- 处置涉及生产配置变更时先备份、记录变更前状态并明确回滚方式，一次只改一项，用测试消息验证后再放开到正式范围。
- 恢复后观察一段时间的发送成功率与延迟分布，把权限、群绑定、通知规则纳入变更检查，并对发送失败设置告警。
先分清症状：完全收不到还是延迟到达
排查起点由症状决定。完全收不到和延迟到达指向的原因范围不同，先分类能减少无效检查。完全收不到通常意味着消息在某个环节被拦截或未发出，例如通知规则未命中、应用无消息权限、机器人被移出群、接收人不在可见范围。延迟到达则说明消息最终送达，链路是通的，问题更可能出在接口限流、重试排队、超时后补发或消息队列积压。两类症状的优先检查项不同，混在一起查容易反复切换方向。
界定影响范围同样重要。需要确认异常是集中在一条消息、一个群、一个应用，还是所有通知都受影响。单条消息异常更可能是内容或接收对象问题；单个群异常优先查机器人与群配置；单个应用异常查该应用的消息权限与接口调用；全部通知异常则要怀疑平台侧发送服务、网络出口或飞书应用整体状态。范围越具体，后续验证越容易收敛。
时间点和近期变更是缩小原因范围的关键线索。记录首次发现异常的时间、异常前最后一次正常收到消息的时间，并回顾这段时间内是否发生过应用配置调整、权限变更、机器人增减、群成员调整、研发平台版本升级或网络策略变化。很多通知中断都能对应到一次具体变更，变更记录本身就是重要证据。
开始排查前，先收集以下材料，形成一份症状记录：
| 记录项 | 填写内容 | 用途 |
|---|---|---|
| 现象 | 完全收不到 / 延迟到达，延迟大致时长 | 确定优先检查方向 |
| 影响范围 | 单条、单群、单应用或全部通知 | 缩小原因范围 |
| 时间 | 首次异常时间、最后一次正常时间 | 关联近期变更 |
| 近期变更 | 应用配置、权限、人员、版本、网络调整 | 形成原因假设 |
| 已收集证据 | 研发平台发送记录、接口返回码、飞书侧配置截图、群成员截图 | 支撑后续判断 |
这份记录在后续每一步都会被引用。缺少发送记录时，先补查研发平台的事件与通知日志，再进入原因分析。
按顺序定位：渠道配置、权限与接口三类原因及排除证据
原因定位按“研发平台侧—飞书侧—接口侧”的顺序推进，每一类都用可观察的证据判断成立或排除。顺序的意义在于：如果研发平台根本没有发出消息，后面检查飞书配置和接口返回都没有意义；如果发送记录存在且接口返回成功，问题就落在飞书侧的接收环节。
研发平台侧：事件是否触发、规则是否命中、是否留下发送记录
先确认业务事件是否真实发生，例如工作项状态变更、评论、指派、评审完成等触发条件是否满足。再核对通知规则：规则是否启用、触发条件是否与本次事件匹配、接收对象是否被规则覆盖、是否存在多条规则互相覆盖或静默。最后查发送记录，确认平台是否为这条消息生成了发送任务，以及任务状态是成功、失败还是待发送。发送记录缺失说明消息未进入发送环节，问题在平台侧规则或事件；发送记录为失败则直接带着返回信息进入接口侧检查。
飞书侧：应用权限、机器人与群配置、接收对象可见范围
飞书侧的检查围绕“消息有没有资格送到目标位置”展开。应用维度看消息权限是否已开通、权限变更后是否重新发布生效；机器人维度看机器人是否仍在目标群内、是否被移出或群已解散；接收对象维度看用户是否在职、是否在应用可见范围内、群成员是否包含预期接收人。权限或可见范围不匹配时，接口可能返回成功但实际无人收到，这类情况必须靠飞书侧配置截图与成员列表核对，不能只看接口返回码。
接口侧：返回码、限流、重试与超时
接口侧的证据来自调用返回结果和调用日志。重点看返回码含义、错误信息、调用时间与耗时，判断是参数错误、鉴权失败、频率限制还是超时。出现限流时，消息通常表现为延迟到达或部分丢失；出现超时且重试策略不完善时，消息可能直接丢失。还要确认重试是否真的执行、重试间隔与次数是否合理、是否存在重复发送。把调用时间与飞书实际收到时间对比，可以判断延迟发生在调用前排队、调用中超时还是送达后展示环节。
下表把三类原因、验证方法和排除证据放在同一口径下对照，逐项确认后再下结论：
| 原因类别 | 典型假设 | 验证方法 | 成立证据 | 排除证据 |
|---|---|---|---|---|
| 研发平台侧 | 事件未触发、通知规则未命中、未生成发送任务 | 查事件日志、通知规则配置、发送记录 | 无事件记录或规则条件不匹配；发送记录为空 | 事件与规则均正常，发送记录存在且状态为成功 |
| 飞书侧配置 | 应用无消息权限、机器人被移出群、接收人不在可见范围 | 核对应用权限、群成员列表、应用可见范围 | 权限缺失或接收对象不在范围内；接口成功但无人收到 | 权限齐全、机器人在群、接收对象有效 |
| 接口侧 | 鉴权失败、参数错误、限流、超时、重试未生效 | 查调用返回码、耗时、重试日志 | 返回限流或超时错误；重试记录缺失或间隔过短 | 返回成功且耗时正常，飞书侧可查到对应消息 |
在研发平台侧核对通知规则与发送记录时，如果平台本身提供工作项通知配置和通知记录查看能力，可以直接在平台内完成这一步。以 ONES 为例，工作项变更可配置通知规则，排查时可结合规则配置与通知记录判断消息是否触发和发出；ONES 提供 API 接口用于与企业系统集成，接口调用情况可作为链路检查的参考。飞书侧的具体配置项与消息类型，需以实际对接方式和飞书应用后台为准。
分场景处置：配置修正、权限补齐与接口重试
处置只针对已经拿到证据的原因执行，未确认的假设先继续验证。以下按原因分类给出动作、风险与停止点。涉及生产配置变更时，先备份原配置、记录变更前状态，并明确回滚方式；变更后先在测试群或测试接收人上验证，再放开到生产范围。
渠道配置错误的修正
- 导出或截图当前通知规则、机器人配置、群绑定关系，作为回滚依据。
- 修正规则条件、接收对象或群绑定，一次只改一项，便于判断哪项改动生效。
- 用一条测试消息触发，确认发送记录生成且状态成功。
- 在飞书侧确认测试消息到达预期群或接收人，再恢复正式通知。
停止点：如果修正后测试消息仍不到达，停止继续改配置，回到接口侧检查返回码，避免在多个配置项上反复叠加改动。
权限缺失的补齐
- 确认缺失的是应用消息权限、可见范围还是群内机器人权限，只补缺失项。
- 权限变更后按飞书应用的要求完成生效操作，并记录变更时间与操作人。
- 用测试接收人验证，确认其能收到消息且内容完整。
- 评估权限扩大后的影响范围，确认没有把消息推送给不应接收的人员。
停止点：权限补齐涉及范围扩大时，先与消息接收范围的责任人确认，再执行变更；无法确认接收范围时暂停扩大。
接口限流或超时的重试
- 根据返回码确认是限流还是超时，区分后可恢复错误与不可恢复错误。
- 对限流类错误采用退避重试，逐步拉长间隔，控制单位时间内的调用量。
- 对超时类错误先确认请求是否已被对方处理，再决定是否重试，避免重复发送。
- 重试仍失败时记录失败消息与返回信息，转为人工补发或告警处理。
停止点：重试次数达到预设上限仍失败时停止自动重试，保留失败记录并触发告警，避免持续调用放大限流。
验证恢复与预防复发
处置完成后，用测试消息验证送达与延迟是否恢复。测试应覆盖此前异常的范围：单群异常就在该群验证，单应用异常就用该应用发送，全部通知异常则抽取多个群和多个接收人验证。记录发送时间与飞书实际收到时间，计算延迟是否回到正常水平，并确认消息内容、跳转信息完整。
单次测试通过不代表恢复稳定。建议观察一段时间内的发送成功率与延迟分布，重点看是否仍有零星失败、延迟是否集中在特定时段。观察窗口内如果再次出现异常，回到原因对照表复查，确认是原原因未彻底解决还是出现了新的变更。
预防复发从三方面建立检查机制：
- 把应用消息权限、机器人所在群、通知规则条件、接收对象范围纳入配置变更检查清单，任何调整都记录变更人与时间。
- 对通知发送失败建立告警，按失败数量和连续失败次数设置阈值，避免长期静默丢失。
- 定期巡检发送成功率与延迟趋势，结合研发平台的发送记录抽查，发现异常提前处理。
最后形成一份恢复验证记录，包含验证时间、验证范围、测试消息结果、观察期内的成功率与延迟情况，以及本次原因和处置动作。这份记录既用于确认本次故障闭环，也为下一次同类问题提供对照依据。
常见问题
研发平台侧发送记录显示成功，但飞书群里仍然收不到消息，应该先查哪里？
这种情况优先核对飞书侧的接收环节。接口返回成功只说明调用被接受，不代表消息一定展示给了目标人员。先确认机器人是否仍在目标群内、群是否已解散或被迁移，再核对应用可见范围是否包含群内成员，以及接收人是否在职。权限或可见范围不匹配时，接口可能返回成功但实际无人收到，需要靠群成员列表与应用配置截图核对，不能只看返回码。
消息只是延迟几分钟到达，还需要按完整流程排查吗？
延迟到达说明链路是通的，排查可以跳过“消息是否发出”这一步，直接从接口侧入手：查看调用耗时、是否出现限流返回码、重试间隔与次数是否合理，以及是否存在消息排队积压。同时对比发送时间与飞书实际收到时间，判断延迟发生在调用前排队、调用中超时还是送达后展示环节。如果延迟集中在特定时段，还要结合该时段的调用量和平台侧其他任务情况一起看。
补齐飞书应用权限后，为什么测试消息还是收不到？
先确认权限变更是否已按要求完成生效操作，部分配置需要重新发布应用后才生效。其次确认测试接收人是否在应用可见范围内，以及测试群是否已绑定当前机器人。如果权限与范围都正确，回到接口侧查看测试消息的返回码与耗时，排除鉴权失败或参数错误。建议一次只改一项配置并记录变更时间，便于判断哪项改动真正生效。
接口出现限流时，自动重试应该怎么设置才不至于放大问题？
对限流类错误采用退避重试，逐步拉长间隔，并控制单位时间内的调用量，避免持续高频调用加重限流。对超时类错误，先确认请求是否已被对方处理，再决定是否重试，防止重复发送。设置重试次数上限，达到上限仍失败时停止自动重试，保留失败消息与返回信息，转为人工补发或触发告警。重试策略调整后，用测试消息验证延迟是否回到正常水平。
如何避免同类通知中断再次发生？
把应用消息权限、机器人所在群、通知规则条件、接收对象范围纳入配置变更检查清单，任何调整都记录变更人与时间。对通知发送失败建立告警，按失败数量和连续失败次数设置阈值，避免长期静默丢失。定期巡检发送成功率与延迟趋势，结合研发平台的发送记录抽查。发生异常时保留当时的配置截图与日志，为下一次排查提供对照。
