流水线“卡住不动”可能来自三种完全不同的原因：阶段还在等待条件、任务已经执行失败，或执行结果没有回传到平台。定位时先确认卡点所在环节的“最后可信状态”——执行侧是否仍在运行、任务是否已经结束、外部系统是否已有结果，再对照平台展示状态，就能把模糊的“卡住”归入具体类型，并选择对应的处置方式。
要点总览（TL;DR）
- 定位卡点的核心是先确认“最后可信状态”：执行侧是否已开始、是否已结束、结束结果是什么，再与平台展示状态对照。
- 阶段等待的特征是执行侧尚未开始或尚未结束，证据包括排队、审批未提交、上游阶段未完成、资源池无空闲执行器。
- 执行失败的特征是任务已结束且结果非成功，证据包括退出码非零、日志明确报错、产物缺失或测试未通过。
- 状态回传缺失的特征是执行侧已完成而平台状态未更新，证据包括回调或轮询记录缺失、报错，或外部系统已有结果而平台无记录。
- 推荐排查顺序为执行侧真实状态、平台侧展示状态、两者之间的回传链路，处置后需验证状态、产物、通知与下游触发是否恢复正常。
卡点现象先落到哪一层：症状与范围界定
“流水线卡住了”只是用户侧的感受，排查的第一步是把它拆成可观察、可记录的症状。同一个页面长时间不推进，可能对应任务仍在排队、执行器正在运行但无日志输出、任务已结束而平台未刷新等多种情况。先记录现象，再判断原因，可以避免凭第一眼印象直接下结论。
常见症状与对应观察点
- 任务长时间处于排队或运行中：记录进入该状态的时间、当前所处的阶段和任务名称，观察是否有心跳或日志增量。
- 阶段不推进：确认是当前阶段内部任务未完成，还是阶段之间的流转条件未满足，例如上游阶段未成功、审批未通过。
- 页面无新日志：区分“没有新日志产生”和“有新日志但未展示”，前者指向执行侧，后者指向展示或回传链路。
- 通知未发出：确认通知规则是否覆盖该事件，以及通知依赖的状态变更是否已经发生。
区分卡点所在层级
把流水线拆成三层来定位：编排层负责阶段顺序、触发条件和流转规则；阶段与任务执行层负责具体任务的调度与运行；执行器与外部系统对接层负责实际执行以及结果回传。卡点在编排层表现为阶段之间不流转，在执行层表现为任务不开始或不结束，在对接层表现为执行侧与平台侧状态不一致。记录卡点所在层级，后续的证据采集才有明确方向。
确认影响范围与排查基线
范围判断决定问题的优先级和处理方式。需要确认：是单条流水线还是多条流水线同时卡住；是单个分支还是全部分支受影响；是否只在特定触发方式下出现，例如定时触发正常而代码提交触发异常；是否与某个执行器、某个资源池或某个外部系统相关。多条流水线同时卡住，通常指向共享资源或对接链路；单条流水线卡住，更可能与本次变更、本次任务参数有关。
同时记录四项基线信息：卡点首次出现的时间点、触发方式、最近一次流水线配置或环境变更、最近一次成功的执行记录。这份基线既用于本次排查对照，也用于恢复后确认是否真正回到正常状态。
| 记录项 | 填写内容 | 用途 |
|---|---|---|
| 卡点位置 | 流水线名称、阶段、任务、所在层级 | 确定排查入口 |
| 持续时间 | 进入异常状态的时间、已持续时长 | 判断是否超过正常执行时长 |
| 影响范围 | 流水线条数、分支范围、触发方式 | 区分单点问题与共享链路问题 |
| 最近变更 | 配置、镜像、执行器、对接参数的改动 | 缩小可疑范围 |
| 最近成功记录 | 上一次正常完成的时间与版本 | 作为恢复对照基线 |
三类原因的判定依据与排除顺序
三类原因对应三种不同的“最后可信状态”。阶段等待时，任务尚未真正开始或尚未满足继续条件；执行失败时，任务已经结束且结果非成功；状态回传缺失时，执行侧已经完成，平台侧却没有收到或没有更新结果。判定时以证据为准，不以页面显示单一现象为准。
阶段等待的证据
阶段等待的共同特征是执行侧没有产生“已开始并失败”或“已完成”的结果。可核验的证据包括：任务处于排队状态且资源池无空闲执行器；阶段配置了人工审批且审批尚未提交；任务在等待上游阶段成功，而上游阶段本身仍在运行或未触发；流水线在等待定时窗口或外部触发条件。这类情况下，日志通常停留在准备阶段，或根本没有任务日志。确认等待对象是谁、等待条件是什么，是判定阶段等待的关键。
执行失败的证据
执行失败的特征是任务已经结束，且结束状态为非成功。可核验的证据包括：任务退出码非零；日志中出现明确的报错堆栈、依赖下载失败、编译错误或测试断言失败；构建产物缺失或产物校验不通过；测试报告显示未通过用例。需要注意，部分任务在失败后仍会显示为运行中，直到超时或被清理，因此应优先查看执行侧的任务结束记录，而不是只看平台页面状态。
状态回传缺失的证据
状态回传缺失的特征是执行侧与平台侧状态不一致。可核验的证据包括：执行侧日志或执行器记录显示任务已完成，平台状态长期停留在运行中或未更新；回调请求记录缺失、返回错误或超时；轮询任务未执行或执行报错；外部系统已有构建结果，平台侧没有对应记录。这类问题容易被误判为执行失败，因为页面表现同样是“不推进”，区别在于执行侧是否已经产生成功结果。
推荐排查顺序
按“执行侧真实状态 → 平台侧展示状态 → 两者之间的回传链路”的顺序排查，可以最快缩小范围：
- 先查执行侧：任务是否已开始、是否已结束、结束结果是什么。这一步确定“事实”。
- 再查平台侧：平台记录的任务状态、阶段状态与执行侧是否一致。这一步确定“差异”。
- 最后查回传链路：回调地址、凭证、网络连通性、轮询任务是否正常。这一步确定“差异产生的位置”。
每一步都需要可验证的记录支撑，例如执行器日志、任务结束时间、回调请求记录。仅凭一段截断的日志或一次页面刷新就下结论，容易把回传问题误判为执行问题，导致处置方向错误。
| 判定维度 | 阶段等待 | 执行失败 | 状态回传缺失 |
|---|---|---|---|
| 执行侧状态 | 未开始或未结束 | 已结束，结果非成功 | 已结束，结果成功 |
| 关键证据 | 排队、审批未提交、上游未完成、无空闲执行器 | 退出码非零、日志报错、产物缺失、测试未通过 | 执行侧已完成但平台未更新、回调或轮询记录异常 |
| 平台侧表现 | 停留在等待或排队 | 显示失败或停留在运行中直至超时 | 长期停留在运行中或状态不更新 |
| 排查重点 | 等待对象与流转条件 | 失败原因与影响产物 | 回传链路与状态同步 |
按卡点类型分别处置
判定类型后，处置动作差异明显。阶段等待以补齐条件为主，执行失败以修复后重跑为主，状态回传缺失以修复链路并同步状态为主。三类处置都可能涉及重跑、回滚或手动修改状态，执行前需要确认影响范围和停止条件。
阶段等待的处置
先确认等待对象：如果是人工审批，联系审批人完成审批或调整审批规则；如果是上游阶段未完成，先处理上游阶段的问题；如果是资源池无空闲执行器，扩容执行器或调整排队策略，避免高优先级流水线被长期阻塞。处置完成后观察阶段是否按预期流转。若等待时间已明显超出正常范围，可先终止本次执行再重新触发，终止前确认不会影响已产生的中间产物。
执行失败的处置
保留失败日志、失败任务参数和已产生的产物，作为修复依据。修复代码、依赖或配置后重跑。重跑前确认三件事：重跑是否会覆盖已有产物、是否会重复触发下游部署或通知、失败任务是否已产生部分外部副作用。若失败发生在部署类任务，应先确认目标环境的当前状态，再决定重跑还是回滚。重跑后以任务结束状态和产物校验结果作为恢复依据。
状态回传缺失的处置
先核对回传链路：回调地址是否正确、凭证是否过期、网络是否可达、轮询任务是否在运行。链路修复后，可手动触发一次状态同步，让平台侧状态与执行侧对齐。手动同步前确认幂等性：同步动作是否会重复触发下游阶段、是否会产生重复通知或重复部署。若无法确认幂等性，先在下游阶段设置为手动触发，再执行同步。同步完成后核对平台状态、执行侧记录和下游触发记录三者是否一致。
风险边界与停止条件
- 重跑、回滚或手动改状态前，记录当前状态和已产生的产物，保留可回退的版本信息。
- 涉及生产环境部署的任务，重跑前确认目标环境状态，必要时先暂停下游自动触发。
- 手动同步状态时，若发现下游已被重复触发，立即停止后续同步并检查重复触发的范围。
- 若同一卡点在处置后短时间内再次出现，停止反复重跑，转为排查根因。
恢复验证与复发预防
处置完成不等于问题解决。恢复验证要确认流水线不仅“动起来了”，而且状态、产物、通知和下游触发都回到预期。复发预防则把本次排查中发现的薄弱环节固化为规则或监控。
恢复验证清单
- 状态推进：任务和阶段状态推进到预期阶段，平台侧与执行侧记录一致。
- 产物正常：构建产物已生成并通过校验，部署类任务的目标环境状态符合预期。
- 通知正常：该发出的通知已发出，没有重复通知。
- 下游未被重复触发：下游阶段或部署任务只被触发一次，触发记录可查。
- 证据留存：保留本次排查的日志、状态变更记录和回传记录，便于后续复盘。
复发预防措施
针对三类原因分别设置防线：为阶段等待设置超时与提醒，等待超过阈值时通知责任人，避免审批或资源问题长期无人处理；为执行失败保留可追溯日志和产物，确保失败原因可复查；为状态回传增加对账或告警，当执行侧已完成而平台状态长时间未更新时主动发现。定期统计卡点类型分布，识别高频原因，把高频问题转化为配置规范或自动化检查。
在团队协作层面，卡点定位后的状态记录、处置交接和复盘结论需要有统一的承载位置。ONES 可集成 Jenkins、GitLab CI 等第三方流水线工具，集成后自动同步编排的流水线数据，更新执行状态和日志；流水线与项目关联后，可在项目、迭代、需求中查看代码提交、流水线构建和产品发布过程，帮助团队识别阻塞环节。处置过程中的判断依据、责任人和恢复结论可以记录在工作项与文档中，形成可追溯的排查记录；相关数据报表也可用于回溯 DevOps 工具链中的操作，为定期复盘卡点类型分布提供依据。具体集成范围和配置方式以团队实际环境为准。
常见问题
流水线页面显示“运行中”，但执行侧日志已经结束，应该按哪类问题处理？
这种情况优先按状态回传缺失处理。判定依据是执行侧已经产生结束记录，而平台状态没有随之更新。此时先核对回调地址、凭证有效期和网络连通性，再检查轮询任务是否在运行。链路修复后可手动触发一次状态同步，同步前确认幂等性，避免重复触发下游阶段或重复发送通知。若同步后平台状态仍不更新，需要进一步排查平台侧的状态处理逻辑。
任务失败后页面仍停留在运行中，如何避免把它误判为回传问题？
关键看执行侧的任务结束记录。部分任务失败后会保持运行中状态，直到超时或被清理，页面表现与回传缺失相似。排查时先查执行器的任务结束时间和退出码，若退出码非零或日志中有明确报错，就属于执行失败；若执行侧记录显示成功完成，才转向回传链路排查。仅凭页面状态无法区分这两类情况。
阶段等待超过多长时间应该介入处理？
没有统一阈值，应结合该阶段的历史正常耗时设定。常用做法是以最近若干次成功执行的阶段耗时为参考，设置超时提醒，超过阈值时通知责任人。人工审批类等待可单独设置提醒周期。若等待对象是资源池，需要观察排队任务数量与执行器数量是否长期不匹配，再决定扩容还是调整排队策略。
手动同步状态或重跑之前，需要确认哪些前提？
需要确认三件事：同步或重跑是否会覆盖已有产物；是否会重复触发下游部署、通知或其他外部副作用；目标环境当前处于什么状态。涉及生产环境时，可先暂停下游自动触发，再执行同步或重跑。若无法确认幂等性，先在下游阶段切换为手动触发。执行前记录当前状态和可回退的版本信息，并设定停止条件，例如发现下游被重复触发时立即停止后续操作。
同一类卡点反复出现，排查重点应该放在哪里？
反复出现说明单次处置只解决了表象。建议统计一段时间内的卡点类型分布，识别高频原因：阶段等待频繁出现，检查审批规则和资源容量；执行失败集中出现，检查依赖稳定性、构建环境和测试用例质量；回传缺失反复出现，检查回调凭证有效期、网络策略和轮询任务的运行状态。把高频原因转化为配置规范或自动检查，比反复重跑更有效。
