流水线执行卡点：区分阶段等待、执行失败与状态回传缺失

流水线长时间没有新进展时，“卡住”可能对应三种不同问题：阶段在等待某个条件、任务执行失败，或执行结果没有回传到平台。三者混在一起看，容易把等待误判为失败，把回传缺失误判为执行卡死。本文按“流水线状态→执行日志→回传记录”的证据顺序，给出症状分类、排查方法、处置动作和恢复验证清单，适用于交付流执行过程中的卡点定位。

要点总览（TL;DR）

• 先看流水线自身状态：阶段是否处于待审批、待上游、资源排队等显式等待，这是阶段等待的直接证据。
• 再看执行日志与退出码：非零退出码、错误堆栈或超时终止记录指向执行失败，下游未启动通常应回到上游定位。
• 最后核对回传记录：流水线侧已完成或已失败而平台侧仍显示进行中、或平台侧无该次执行记录，才按状态回传缺失处理。
• 处置前先保存阶段状态、日志尾部、退出码和平台侧记录；取消、重跑、补发回传都设停止点，避免覆盖现场或重复触发。
• 恢复后同时核对流水线状态、平台状态、产物与通知四项一致，并通过等待超时提醒、失败告警和定期对账减少复发。

卡点现象与三类问题的范围界定

“卡住”是观察到的现象，不是原因。排查的第一步，是把现象落到具体位置：哪个阶段停住了、停了多久、最后一次日志输出是什么、平台侧显示什么状态。不同位置对应不同类别，后续核查的证据来源也不同。

现象	可能归属	首个核查点
某阶段长时间停留，但日志显示正在等待审批、等待上游阶段或等待执行资源	阶段等待	流水线侧该阶段的显式状态与等待对象
日志停止更新，任务以非零退出码结束，或出现超时终止记录	执行失败	失败任务的日志尾部与退出码
流水线侧已显示完成或失败，平台侧仍显示进行中，或平台侧没有任何执行记录	状态回传缺失	平台侧回传记录与流水线侧最终状态是否一致
阶段停留且无新日志，同时平台状态不更新	需进一步区分：可能是等待，也可能是回传缺失叠加	先取流水线侧原始状态，再比对平台侧

三类问题的边界可以用一句话区分：阶段等待是“流水线知道自己在等什么”，执行失败是“流水线已经给出了失败结论”，状态回传缺失是“流水线已有结论，但平台没有收到或没有正确呈现”。判断时以流水线侧的原始记录为准，平台侧展示作为比对对象。

本文聚焦交付流执行中的卡点定位与处置。流水线与平台的对接配置、发布准入与质量门禁规则属于相邻主题，这里只在排查需要时提及状态一致性，不展开配置细节。

按证据链区分三类卡点的排查顺序

建议固定按三步推进：先看流水线自身状态，再看执行日志与退出码，最后核对回传记录。这个顺序的价值在于，前一步的结论会缩小后一步的检查范围，避免在错误方向上反复重跑。

假设	验证动作	支持证据	排除证据
阶段等待	查看当前阶段状态字段与等待对象，确认是否存在待审批、待上游完成、资源排队等显式标记	阶段状态明确为等待类；等待对象可指名（某审批人、某上游阶段、某执行资源池）；日志在等待开始后无新增属于正常	阶段状态为运行中且日志持续输出；或状态显示失败；或流水线已结束但阶段仍标记等待
执行失败	定位失败任务，查看日志尾部、退出码与超时记录	非零退出码；错误堆栈或明确的失败信息；超时终止记录；后续阶段因依赖失败而未启动	退出码为零且日志正常结束；阶段处于显式等待；失败仅出现在平台侧展示而流水线侧无对应记录
状态回传缺失	比对流水线侧最终状态与平台侧记录，检查是否存在回传条目及时间戳	流水线侧已完成或已失败，平台侧仍为进行中；平台侧无该次执行的回传记录；两侧状态更新时间明显不一致	平台侧状态与流水线侧一致；平台侧记录完整且时间戳吻合；差异可由正常的同步延迟解释

三类常见误判需要单独提醒。第一，把等待审批当成执行卡死，于是取消重跑，结果只是重新进入等待，还丢失了原审批上下文。第二，把上游阶段失败导致的下游未启动当成下游自身故障，实际应回到上游定位退出码。第三，把平台侧状态未更新当成流水线仍在执行，实际流水线早已结束，问题出在回传环节。判断回传缺失前，应先确认平台侧是否存在合理的同步延迟窗口，超出该窗口仍无记录，再按回传缺失处理。

当流水线接入研发管理平台后，执行状态与日志会同步到平台侧，流水线也与项目关联，便于在项目、迭代、需求中查看构建过程并识别阻塞。ONES 的 DevOps 方案支持集成 Jenkins、GitLab CI 等第三方流水线工具，集成后自动同步编排的流水线数据、执行状态和日志。排查时可以把平台侧记录与流水线侧原始状态并列比对；具体到阶段等待状态的细分展示与回传对账机制，需以实际集成配置和产品当前能力为准。

三类卡点的处置动作与风险边界

处置动作取决于已判定的类别。在动手之前，先保存现场：截取当前阶段状态、日志尾部、退出码和平台侧状态记录。重跑、取消、补发回传都可能覆盖或改变现场，先留证据再操作。

阶段等待的处置

1. 确认等待对象：是审批人未处理、上游阶段未完成，还是执行资源排队。
2. 等待审批时，联系对应审批人或在协作渠道催办，保留等待开始时间以便判断是否超出预期。
3. 等待上游时，转到上游阶段核查其状态，不在下游重复触发。
4. 资源排队时，确认队列位置与预计等待时长，必要时调整排队策略；调整前确认不会挤占其他在途任务。
5. 停止点：等待对象明确且仍在合理时限内时，不执行取消或重跑。

执行失败的处置

1. 定位失败任务，记录退出码、错误日志与失败发生的阶段。
2. 判断失败是否可复现：由代码或配置引起的失败，修复后重跑；由环境或资源瞬时问题引起的失败，确认环境恢复后重跑。
3. 重跑前保留原次执行的日志，避免覆盖后无法对比。
4. 停止点：同一失败连续重跑仍未通过时，停止重跑，转为修复根因，避免反复消耗资源并淹没原始错误信息。

状态回传缺失的处置

1. 核对回传记录：确认平台侧是否收到该次执行的回传、回传时间与内容是否完整。
2. 确认流水线侧最终状态无误后，补发或重试回传。
3. 补发前确认该次执行未被重复触发，避免同一构建产生两条记录或重复触发下游动作。
4. 停止点：补发多次仍不一致时，停止重复补发，转为检查回传链路本身，并记录差异样本供后续分析。

取消操作属于破坏性动作，会终止正在运行的任务并可能丢失未持久化的中间产物。执行取消前，确认该阶段确实不属于正常等待，且已保存必要日志。涉及补发回传时，先确认下游是否已根据平台状态触发过动作，避免重复触发。

恢复验证与复发预防

处置完成不等于恢复完成。需要同时核对流水线侧、平台侧和产物三个层面，确认状态一致后才算闭环。

验证项	检查内容	通过标准
流水线状态	当前阶段与整体执行状态	状态为完成或失败，且与日志结论一致
平台状态	平台侧该次执行的记录与状态	与流水线侧一致，时间戳合理
产物	构建产物是否生成、版本号是否正确	产物存在且可追溯到该次执行
通知	相关通知是否发出、接收对象是否正确	通知内容与实际结果一致，无重复通知

需要保留的记录包括：失败任务的完整日志与退出码、等待阶段的开始时间与等待对象、平台侧回传记录及时间戳、补发回传的操作记录。这些记录既用于本次复盘，也用于判断同类问题是否重复出现。

复发预防可以从三个方向入手。等待类问题设置等待超时提醒，超过预期时限即通知责任人；失败类问题配置失败告警，把退出码与失败阶段带入通知内容；回传类问题建立回传心跳或定期对账，按固定周期比对流水线侧与平台侧状态，发现不一致时生成待核查清单。ONES 支持多种数据报表，可追溯团队在 DevOps 工具链中的操作，用于集中度量与分析；告警与对账的具体配置方式，以实际集成环境和产品能力为准。

把三类卡点的判断固化为检查顺序，并在每次处置后完成状态、产物与通知的一致性验证，团队就能在下一次出现“卡住”时快速落到具体类别，减少无效重跑和误取消。

常见问题

平台侧显示进行中，但流水线侧已经结束，能直接判定为状态回传缺失吗？

先确认是否处在合理的同步延迟窗口内。集成后的状态同步通常存在短暂延迟，超出该窗口仍无记录或状态不一致，才按回传缺失处理。判断依据是流水线侧最终状态与平台侧回传条目的时间戳：平台侧完全没有该次执行的回传记录，或两侧更新时间明显不一致，支持回传缺失的结论；平台侧记录完整且时间戳吻合，则应回到执行日志继续排查。

阶段长时间没有新日志，一定是执行卡死吗？

不一定。等待审批、等待上游阶段完成、执行资源排队时，阶段处于显式等待状态，日志在等待开始后没有新增属于正常现象。此时应先查看阶段状态字段与等待对象，能指名等待的是某审批人、某上游阶段还是某资源池，就按阶段等待处置，联系对应责任人或确认队列位置。若阶段状态为运行中且日志持续输出，或状态已显示失败，才转向执行失败方向排查。

同一失败连续重跑多次仍未通过，继续重跑还是先修复？

建议停止重跑，转为修复根因。反复重跑会持续消耗资源，并可能覆盖原始失败日志，使错误信息难以对比。更稳妥的做法是保留首次失败的完整日志与退出码，判断失败由代码、配置还是环境瞬时问题引起：代码或配置问题修复后重跑，环境问题确认恢复后重跑。重跑前保留原次执行日志，便于对比两次结果。

补发回传时需要注意什么，如何避免重复触发下游动作？

补发前先确认两件事：流水线侧最终状态无误，且该次执行没有被重复触发。补发回传可能让平台侧再次按状态触发下游动作，若下游已根据先前状态执行过，重复补发会造成重复触发或产生两条构建记录。补发多次仍不一致时，停止重复补发，转为检查回传链路本身，并记录差异样本供后续分析。

接入研发管理平台后，排查三类卡点能获得哪些便利？

以 ONES 的 DevOps 方案为例，集成 Jenkins、GitLab CI 等第三方流水线工具后，平台会自动同步编排的流水线数据、执行状态和日志，并把流水线与项目关联，可在项目、迭代、需求中查看构建过程并识别阻塞。排查时可以把平台侧记录与流水线侧原始状态并列比对。阶段等待状态的细分展示、回传对账与告警配置的具体实现，需以实际集成配置和产品当前能力为准。