交付流水线显示“卡住”时，先别急着重跑。更稳妥的做法是按“阶段是否进入、任务是否执行、状态是否回传”三层取证，用同一时间戳口径对齐流水线平台、作业日志和跟踪看板三处记录，再判断卡点属于阶段等待、执行失败还是状态回传缺失。本文围绕交付流执行跟踪展开，给出症状记录、证据对照、排查顺序与恢复验证方法；流水线与平台的对接配置、发布准入审批规则不在本篇范围内。
要点总览（TL;DR）
- 卡点归因按三层取证：先看阶段是否进入，再看作业是否执行成功，最后看状态是否回传，三处记录用同一时间戳口径对齐。
- 阶段长时间未进入，优先核对队列记录、并发占用、前置依赖和人工审批，这些属于阶段等待类原因。
- 作业已启动但报错或超时，以作业日志、退出码和失败步骤为证据，归为执行失败。
- 作业已完成而跟踪看板未更新，比对平台侧完成时间与看板最后更新时间，时间差超出同步周期则按状态回传缺失处理。
- 恢复验证需同时满足阶段按时进入、作业成功、看板与平台状态一致；日常可用阶段超时告警、状态一致性巡检和失败日志归档降低复发。
卡点现象与排查范围界定
“卡住”是一个笼统描述，直接拿去排查会导致两个系统来回切换却找不到落点。排查开始前，先把现象拆成可观察的症状，并固定一组基础信息，后续所有证据都围绕这组信息对齐。
常见症状可以归为四类：阶段长时间停留在未开始或进行中；作业已触发但长时间没有日志输出；作业在流水线平台显示成功，跟踪看板状态却停在旧值；上游阶段完成但下游阶段没有被触发。四类症状指向的原因方向不同，记录时要写清楚观察到的是哪一类，而不是只写“流水线卡了”。
需要先固定的信息包括：流水线名称与本次运行编号、卡点所在阶段和作业、首次发现卡点的时间、最近一次完整成功运行的编号与时间。最近成功运行是重要的对照基线，它说明这条流水线此前在相同配置下可以走通，能帮助排除“配置从未生效”这类方向。
建议用一张卡点现象记录表承载这些信息，现场边查边填：
| 字段 | 填写内容示例 | 用途 |
|---|---|---|
| 流水线名称与运行编号 | 订单服务发布流水线 / 运行 #2317 | 锁定排查对象，避免与其他运行混淆 |
| 卡点阶段与作业 | 集成测试阶段 / test-api 作业 | 确定取证位置 |
| 症状类型 | 阶段未进入 / 作业无日志 / 看板未更新 / 下游未触发 | 决定先查哪类证据 |
| 时间窗口 | 首次发现时间、当前已等待时长 | 与日志、回传记录对齐 |
| 最近成功基线 | 运行 #2310，前一日 14:20 完整通过 | 判断是否为新增异常 |
范围界定同样重要。本次排查只处理交付流执行跟踪中的卡点定位与恢复，涉及流水线与研发平台对接的参数配置、发布准入审批与质量门禁规则设计时，应转交对应负责人，避免在排查过程中顺手改动配置，把一次卡点扩大成配置事故。
三类卡点的原因假设与排除证据
三层取证对应三类原因假设。每一类假设都需要特定证据才能成立，也需要特定证据才能排除。排查时先列假设、再找证据，在拿到日志或回传记录之前，只把方向写成“疑似”，不写成结论。
阶段等待：阶段没有进入执行
阶段等待的共同特征是阶段或作业尚未真正开始执行。可能的原因包括：执行资源排队，代理节点被其他运行占用；并发上限已满，本次运行在队列中等待；前置依赖未满足，上游阶段或外部依赖没有完成；人工审批节点尚未有人处理。
验证这类假设需要三类证据：阶段进入时间，即平台记录中该阶段实际开始的时间，若为空则说明未进入；队列记录，查看本次运行是否处于排队状态以及排队原因；依赖状态，确认前置阶段结果和外部依赖的完成情况。若队列记录显示正在排队且资源确实被占用，阶段等待假设成立；若阶段进入时间存在且早于发现卡点的时间，则应转向执行失败方向。
执行失败：作业已启动但未正常结束
执行失败的特征是作业已经启动，但没有以成功状态结束。常见原因包括：脚本报错，命令返回非零退出码；环境或凭据失效，例如部署目标不可达、访问令牌过期；执行超时，作业运行时间超过设定上限被终止。
成立证据是作业日志中出现明确的错误信息、退出码非零、失败步骤可定位。排除证据同样明确：日志完整、退出码为零、各步骤均显示成功，则执行失败假设可以排除，问题应转向状态回传。需要注意，日志为空本身不能直接判定执行失败，也可能是作业尚未真正启动，此时应回到阶段等待方向核对进入时间。
状态回传缺失：执行完成但跟踪看板未更新
状态回传缺失的特征是流水线平台侧记录显示作业已完成，而跟踪看板上的状态仍停留在进行中或未开始。可能原因包括：状态回调未送达，网络或配置导致通知丢失；字段映射不一致，平台侧的状态值与看板侧期望的取值对不上；状态更新存在延迟，尚未到同步周期。
验证方法是比对平台侧执行记录的完成时间与看板状态最后更新时间，计算两者时间差。若时间差明显超出正常同步周期，且平台侧记录完整，则回传缺失假设成立；若时间差在正常范围内，应等待一个同步周期后再观察，避免把正常延迟误判为故障。
三类假设的证据要求可以整理为一张对照表，现场逐项核对：
| 卡点类型 | 典型原因 | 成立所需证据 | 排除所需证据 |
|---|---|---|---|
| 阶段等待 | 资源排队、并发上限、前置依赖未满足、人工审批未处理 | 阶段进入时间为空或晚于预期；队列记录显示排队；依赖状态未完成 | 阶段进入时间已记录且早于卡点发现时间 |
| 执行失败 | 脚本报错、环境或凭据失效、超时 | 日志含错误信息；退出码非零；失败步骤可定位 | 日志完整、退出码为零、步骤均成功 |
| 状态回传缺失 | 回调未送达、字段映射不一致、更新延迟 | 平台侧已完成，看板未更新，时间差超出同步周期 | 时间差在正常同步周期内，或看板已随下一周期更新 |
这张表的作用是约束判断顺序：先看阶段是否进入，再看作业是否成功，最后看状态是否回传。跳过前两层直接怀疑回传，容易在作业确实失败时误改同步配置。
按顺序排查的操作步骤
排查路径从外到内，依次确认运行存在、阶段进入、作业执行、状态回传，每一步都有判断分支和停止条件。按顺序走可以减少系统间反复切换，也能避免在证据不足时动手处置。
第一步：确认运行是否真实存在
比对触发记录与运行列表，确认本次运行在流水线平台中确实创建。若触发记录存在而运行列表中没有对应条目，说明运行未成功创建，问题在触发环节，不属于本文三类卡点，应转交流水线配置负责人。若运行存在，记录运行编号，进入下一步。
第二步：判断阶段是否进入
查看卡点阶段的进入时间。未进入，按阶段等待方向核对队列记录、并发占用和前置依赖，确认是资源排队、并发上限还是审批未处理；已进入但未完成，进入第三步查作业执行。这一步的判断结果直接决定后续取证位置，不要跳过。
第三步：查作业日志与退出码
对已进入的作业，打开执行日志，定位失败步骤和退出码。日志中出现明确报错时，按报错内容判断是脚本问题、环境问题还是凭据问题，并记录失败步骤名称与关键日志片段。作业因超时被终止时，记录实际运行时长与超时阈值。若日志显示作业成功完成，进入第四步。
第四步：比对回传记录与状态字段
作业成功但看板未更新时，取平台侧完成时间与看板最后更新时间做比对，并核对状态字段取值是否与看板期望值一致。时间差超出同步周期，按回传缺失处理；字段取值对不上，按映射不一致处理。此处的证据应截图或记录具体时间点，便于后续验证。
处置操作的前置条件与停止点
排查过程中可能涉及重跑、清理队列、修改回传配置三类操作，每一类都需要先满足条件再动手：
- 重跑：确认原运行日志已留存、失败原因已定位或已记录待查，再发起重跑；同一运行连续重跑两次仍失败时停止重跑，回到日志分析，避免用重跑掩盖稳定复现的问题。
- 清理队列：仅在确认排队由异常占用导致、且已与占用方确认可以释放时执行；清理前记录当前队列内容，清理后观察是否影响其他运行。
- 修改回传配置：仅在时间差与字段比对均指向配置问题时执行；修改前备份原配置，修改后先用一次测试运行验证，验证不通过立即回滚。
三类操作的共同停止点是：证据不足以指向该操作时不动手。排查记录中应写明每次操作的时间、操作人和操作前后的状态，便于复盘。
在采用 ONES DevOps 解决方案并集成第三方流水线工具的场景中，ONES 会同步编排的流水线数据、更新执行状态和日志，并将流水线与项目关联。排查时可以把运行编号、卡点阶段和失败日志片段回填到对应需求或工作项上，使执行记录与项目上下文放在同一处，交接给下一位排查人时不必重新对齐信息。具体同步字段的粒度以实际集成配置为准。
恢复验证与复发预防
卡点解除不等于恢复有效。验证要回答两个问题：本次运行是否走通，以及看板状态是否与平台一致。两者都满足，才能判定恢复。
恢复验证标准与记录
验证标准有三条：同一运行或重跑后，卡点阶段在预期时间内进入；作业以成功状态结束，退出码为零；跟踪看板状态与平台侧执行记录一致，时间差在正常同步周期内。三条中任一条不满足，说明卡点未真正解除，应回到对应排查步骤继续取证。
验证证据需要留存，建议用一张恢复验证记录承载：运行编号、重跑次数、阶段进入时间、作业结束时间与退出码、看板状态更新时间、平台与看板状态比对结果、验证人。日志片段和状态比对截图一并附在记录中，作为后续复盘和同类问题对照的依据。
三项日常巡检建议
同类卡点复发通常有迹可循，以下三项巡检可以按团队实际情况选用：
- 阶段等待超时告警：为关键阶段设置进入时间阈值，超过阈值未进入时通知负责人，把排队和审批积压从“事后发现”提前到“等待中即发现”。
- 状态一致性巡检：定期比对平台侧完成记录与看板状态，发现时间差持续超出同步周期的运行，提前处理回传问题。
- 失败日志归档：保留失败运行的日志与退出码，按运行编号归档，便于复发时直接对照历史失败步骤，缩短定位时间。
三项巡检之外，还应统一跟踪看板与执行记录的时间口径，例如统一使用同一时区、同一时间来源。口径统一后，下次排查可以直接比对时间戳，不必重复做时间换算。ONES 支持多种数据报表，可追溯 DevOps 工具链中的操作，团队可据此定期查看卡点分布与处理时长，判断哪类卡点出现频率较高，再决定优先补哪项巡检。
常见问题
阶段进入时间显示为空，但队列里也看不到本次运行，应该先查哪里？
这种情况先回到第一步确认运行是否真实创建。比对触发记录与运行列表：若触发记录存在而运行列表中没有对应条目，说明运行未成功创建，问题在触发环节，应转交流水线配置负责人；若运行存在但阶段进入时间为空且队列无记录，则核对前置依赖状态和人工审批节点，确认是否因依赖未满足或审批未处理导致阶段未被调度。
作业日志为空，能直接判定为执行失败吗？
不能。日志为空有两种可能：作业尚未真正启动，属于阶段等待方向；或作业已启动但日志采集未生效。应先核对阶段进入时间，若进入时间为空或晚于预期，按阶段等待排查队列与依赖；若进入时间已记录，再检查日志采集配置和作业启动记录，确认作业是否实际运行。
平台侧显示作业成功，看板状态却没更新，等多久可以判定为回传缺失？
先确认该流水线正常的同步周期。取平台侧完成时间与看板最后更新时间计算时间差，若时间差在正常同步周期内，等待一个周期后再观察，避免把正常延迟误判为故障；若时间差明显超出同步周期且平台侧记录完整，按回传缺失处理，进一步核对回调记录与状态字段映射。
重跑后仍然卡在同一阶段，继续重跑还是先做别的？
同一运行连续重跑两次仍失败时停止重跑，回到日志分析。重跑只能排除偶发因素，稳定复现的卡点通常有确定原因，继续重跑会掩盖问题并消耗执行资源。此时应保留原运行日志，按排查顺序重新核对阶段进入时间、作业日志与退出码，必要时再检查回传记录。
使用 ONES 集成第三方流水线后，排查卡点可以利用哪些记录？
在采用 ONES DevOps 解决方案并集成第三方流水线工具的场景中，ONES 会同步编排的流水线数据、更新执行状态和日志，并将流水线与项目关联。排查时可以把运行编号、卡点阶段和失败日志片段回填到对应需求或工作项上，让执行记录与项目上下文放在同一处，交接时减少重复对齐信息。具体同步字段的粒度以实际集成配置为准。
