流水线阻塞时，先别急着重跑。按“阻塞位置—等待对象—证据”三步走：确认任务卡在排队、资源分配、依赖等待还是外部调用超时，再用队列状态、执行日志、资源占用和依赖服务响应逐项验证，最后按风险从低到高处置。本文聚焦交付流执行环节的排查与恢复，平台对接和发布准入规则不在此展开。
要点总览（TL;DR）
- 先按“阻塞位置—等待对象—证据”三步定位：区分调度排队、执行资源不足、依赖等待与外部调用异常，再对照症状找到首个查看位置。
- 验证顺序建议从调度排队到执行资源、依赖等待、外部调用，逐类记录证据并排除误判；日志持续输出、阶段有推进属于慢，日志长时间无新增且状态不变才按阻塞处理。
- 处置按风险从低到高：重试失败任务、清理临时空间、调整优先级可直接执行；扩容节点、临时提高并发需评估资源余量；终止任务、回滚制品、修改配置须先备份并设停止点。
- 恢复后逐项验证任务重跑成功、阶段耗时回到正常区间、下游可正常触发，并补上队列积压与执行超时告警、并发配额与资源水位阈值。
- 每次阻塞记录起止时间、根因证据、处置动作与影响范围，把反复出现的阻塞点纳入流程改进。
先分清流水线卡在哪一类阻塞
流水线“卡住”是表象，背后的等待对象各不相同。快速分类的价值在于：不同类别的首个查看位置完全不同，找错地方会浪费大量时间。先看任务当前状态和最近一条日志的时间戳，再对照下表判断。
| 症状表现 | 可能类别 | 首个查看位置 |
|---|---|---|
| 任务长期处于“排队中”，状态不变，日志无输出 | 调度排队 | 队列长度、并发配额、任务优先级 |
| 任务已分配执行节点，但阶段迟迟不开始或启动缓慢 | 执行资源不足 | 节点 CPU/内存水位、磁盘空间、镜像拉取耗时 |
| 阶段停在“等待上游”“等待制品”等状态 | 上下游依赖未就绪 | 上游流水线状态、制品仓库、触发条件 |
| 日志停在某次外部调用，之后无新输出，最终超时失败 | 外部服务或网络异常 | 第三方服务响应、凭据有效期、网络连通性 |
分类时注意一个常见混淆：任务耗时长但日志持续输出、阶段有推进，属于性能问题，按优化处理；日志长时间无新增且状态不变，才按阻塞处理。本文讨论的是后者，范围限定在交付流执行环节的阻塞排查，平台对接配置与发布审批规则设计不在本文展开。
逐类验证原因并排除误判
分类只是提出假设，结论要靠证据。建议按“调度排队→执行资源→依赖等待→外部调用”的顺序排查，因为前三类往往相互牵连：排队可能由资源不足引起，资源不足又可能被依赖等待放大。每验证一类，记录证据，排除后再进入下一类。
调度排队：看队列与配额
先确认队列中等待的任务数量是否明显高于日常水平，再核对当前并发配额是否被占满。如果配额已满，查看占用配额的任务是否包含长时间运行或异常挂起的任务。优先级设置也值得检查：低优先级任务在高负载时被持续延后，表现就是“永远排不上”。证据是队列长度曲线与配额占用明细，两者结合才能判断是容量问题还是个别任务拖累。
执行资源不足：看节点水位与镜像拉取
任务已分配节点却启动缓慢，重点看三类指标：CPU 与内存水位是否接近上限、磁盘剩余空间是否不足以写入工作目录、镜像拉取是否耗时异常。镜像拉取慢常被误认为“卡死”，实际是网络或镜像仓库响应问题，日志中通常有拉取进度记录，可据此区分。证据是节点监控数据与任务启动阶段的日志时间线。
依赖等待：确认上游与制品
阶段显示等待上游时，逐一核对：上游流水线是否成功完成、所需制品是否已产出并推送至仓库、触发条件是否满足（例如分支匹配、标签规则）。常见误判是把上游失败当成下游阻塞——下游只是如实等待。证据是上游流水线的最终状态和制品仓库中对应版本的记录。
外部调用：核对服务、凭据与网络
日志停在某次外部调用后无输出，先确认第三方服务是否可用、响应是否变慢，再检查调用凭据是否过期，最后验证执行节点到目标服务的网络连通性。凭据过期往往表现为调用立即失败而非挂起，网络不通则常表现为长时间等待后超时，两者在日志中的表现不同，可据此缩小范围。
排除误判：慢与阻塞的界线
判断标准是“有无推进”：日志持续新增、阶段状态变化，即使耗时长也属于性能问题；日志时间戳长时间不变、状态停留原地，才按阻塞处理。建议在排查开始时记录当前时间与最后一条日志时间，间隔超过该阶段正常耗时的数倍仍无输出，再启动阻塞排查流程，避免把正常的长任务当成故障处理。
按风险等级处置阻塞
确认原因后，处置动作按风险从低到高推进，每完成一步观察效果，再决定是否进入下一步。低风险操作可以直接执行；中风险操作需要评估资源余量；高风险操作必须先备份配置、确认影响范围，并设置停止点。
低风险处置
- 重试失败任务：适用于外部调用超时、镜像拉取失败等瞬时性问题，重试前确认失败原因已消失，避免无效重试。
- 清理临时空间：磁盘水位过高时，清理工作目录中的临时文件与旧构建产物，释放空间后重新触发。
- 调整队列优先级：确认个别低优先级任务长期占用配额时，调整其优先级或暂停，让关键任务先执行。
中风险处置
- 扩容执行节点：资源水位持续偏高时增加节点，扩容后确认新节点已注册并可用，再重新调度任务。
- 临时提高并发：适用于队列积压但资源有余量的场景，提高后观察节点负载，避免把排队问题转化为资源过载。
- 跳过非关键检查并记录：为尽快恢复交付，可临时跳过非关键检查项，但须在任务记录中注明跳过原因与范围，事后补做。
高风险处置与停止点
终止运行中任务、回滚制品、修改流水线配置属于高风险操作。执行前先备份当前配置，确认受影响的任务、分支与下游依赖范围，并通知相关角色。涉及生产发布或数据变更时设置停止点：先暂停流水线，通知发布负责人与相关团队，确认影响范围后再决定是否继续。回滚制品时尤其注意下游是否已消费该制品，避免回滚引发连锁问题。
处置过程中的状态流转与责任人交接，可以在 ONES 中与项目关联的流水线视图里跟踪：集成 Jenkins、GitLab CI 等工具后，ONES 会同步流水线数据并更新执行状态和日志，团队能在项目、迭代、需求中看到构建与发布进展，处置动作和结论也能记录在对应工作项上，便于交接时追溯。
恢复验证与复发预防
流水线重新跑通不等于问题解决，需要按验证项逐条确认，再把本次暴露的薄弱环节补进日常配置。
恢复验证项
- 任务重新执行成功，且失败阶段与阻塞前的阶段一致，确认不是绕过问题。
- 各阶段耗时回到正常区间，与历史同期数据对比无明显偏离。
- 下游流水线可正常触发并完成，确认阻塞未传导至后续环节。
- 队列长度回落至日常水平，执行节点资源水位恢复正常。
防复发配置清单
- 为队列积压设置告警：等待任务数超过阈值时通知负责人，阈值参考日常峰值设定。
- 为执行超时设置告警：单阶段耗时超过正常值的数倍时触发提醒，及早区分慢与阻塞。
- 明确并发配额与资源水位阈值，定期核对配额分配是否与实际负载匹配。
- 定期检查外部服务凭据有效期与依赖服务可用性，把凭据到期纳入例行检查。
复盘记录
每次阻塞处置后记录四项内容：阻塞起止时间、根因类别与证据、采取的处置动作及风险等级、影响范围（涉及的任务、分支与下游）。记录落在对应工作项或迭代中，后续同类问题可直接对照历史处置路径。ONES 支持在项目、迭代、需求中可视化 CI/CD 过程，并提供多维度数据报表追溯工具链操作，团队可以据此集中查看阻塞发生的位置与频次，把反复出现的阻塞点纳入流程改进。
常见问题
流水线任务一直显示排队中，但资源监控看起来还有余量，应该先查什么？
先查并发配额，而不是节点资源。排队中的任务尚未分配到执行节点，节点水位再低也不会被使用。核对当前并发配额是否被占满，再看占用配额的任务里是否有长时间运行或异常挂起的任务。如果配额已满而节点空闲，说明瓶颈在配额设置或个别任务占用，可考虑临时提高并发或暂停低优先级任务，让关键任务先执行。
重试失败任务后仍然阻塞，什么情况下不该继续重试？
重试适用于外部调用超时、镜像拉取失败等瞬时性问题。如果重试后日志仍停在同一次调用、失败原因没有变化，说明问题不在瞬时波动，继续重试只会消耗时间。此时应回到验证环节：确认第三方服务是否可用、凭据是否过期、网络是否连通，找到根因后再处置。对涉及生产发布的任务，反复重试还可能造成重复发布，需先暂停并通知发布负责人。
为了尽快恢复交付，可以临时跳过哪些检查？跳过之后怎么补？
可临时跳过的是非关键检查项，例如不影响制品正确性的辅助校验；安全扫描、制品签名等关键检查不建议跳过。跳过时在任务记录中注明跳过原因、范围和责任人，恢复后在下一轮流水线或单独任务中补做，并确认补做结果。若跳过的是与发布准入相关的检查，应先与发布负责人确认，避免把阻塞问题转化为质量风险。
回滚制品时，下游已经消费了该制品怎么办？
回滚前先确认受影响范围：哪些下游流水线、环境或已发布版本使用了该制品。下游已消费时，回滚可能引发连锁问题，需要同步通知相关团队，评估是否一并回退下游产物或发布修复版本。回滚属于高风险操作，执行前备份当前配置，确认受影响的任务、分支与下游依赖，涉及生产环境时设置停止点，先暂停流水线再决定是否继续。
阻塞恢复后，告警阈值怎么设才不容易误报或漏报？
阈值参考日常水平设定，而不是套用固定数值。队列积压告警可参考日常等待任务数的峰值，略高于峰值触发；执行超时告警可参考该阶段历史正常耗时的数倍。阈值设定后观察一段时间，根据误报和漏报情况调整。同时把并发配额、资源水位阈值和外部服务凭据有效期纳入例行检查，减少同类阻塞再次发生。
