流水线长时间停在“排队中”或某个阶段没有新日志，往往比直接失败更难处理：失败会给出错误信息，阻塞只留下一个不动的状态。排查时先按阻塞位置分类，再用实例状态、阶段耗时、执行机与并发配额、最近变更记录四类证据逐项验证假设，处置按风险从低到高推进，恢复后补上超时与告警配置防止复发。
要点总览（TL;DR）
- 流水线阻塞先按位置分类：排队未启动、等待执行机或并发槽位、运行中无进展、等待人工环节或外部依赖，位置判断错会让后续排查全部偏离。
- 每条原因先作为假设，用执行机状态与配额、触发记录与依赖关系、阶段日志与网络、变更时间线与首次阻塞时间对齐等证据逐项成立或排除。
- 处置按风险从低到高：先做只读检查与沟通，再改配置与依赖，最后才考虑取消、重跑或重建环境；取消会丢失中间产物并影响下游任务。
- 恢复确认看实例正常结束、关键阶段耗时回到历史区间、产物正常流转三项；复发预防依靠阶段超时、配额告警、执行机健康检查和审批提醒。
先分清阻塞发生在哪一段
“流水线卡住了”是一句笼统描述，不同位置的阻塞，责任方、证据来源和处置方式差别很大。第一步是把实例状态读准：它究竟停在排队、等待资源、运行中无进展，还是等待人工环节。状态判断错了，后面的排查会全部偏离方向。
常见状态可以归为四类，每类对应一组可观察症状：
| 阻塞位置 | 典型状态表现 | 可观察症状 | 初步判断方向 |
|---|---|---|---|
| 排队未启动 | 实例处于排队中，尚未分配执行资源 | 触发记录已生成，但没有任何阶段开始；队列中前面还有实例 | 触发条件、并发上限、队列积压 |
| 等待执行机或并发槽位 | 等待资源 | 实例已进入调度，但长时间拿不到执行机；同项目其他实例占满并发槽位 | 执行机在线状态、标签匹配、并发配额 |
| 运行中无进展 | 某阶段处于运行中，日志长时间不更新 | 阶段耗时远超历史均值；日志停在某条命令；CPU、内存或磁盘指标异常 | 阶段内部命令、外部依赖、执行机资源 |
| 等待人工环节 | 等待审批或等待外部依赖 | 审批单无人处理；上游任务未完成；制品或镜像拉取超时 | 审批人、权限、依赖任务与外部服务 |
定位时还要区分单次阻塞与反复阻塞。单次阻塞通常与某次变更、某台执行机或某个外部服务相关，范围清楚；反复阻塞则表现为同一阶段、同一时段反复卡住，往往指向容量不足、配置不合理或依赖不稳定。范围界定影响后续处置：单次问题优先恢复，反复问题需要在恢复后安排配置调整。
逐项验证原因假设与排除证据
原因在验证之前只是假设。有效率的做法是把常见原因写成几条可检验的假设，为每条假设指定证据来源，按“证据最容易取得、影响面最大”的顺序排查，而不是凭经验直接改配置。
| 原因假设 | 验证证据 | 成立与排除的判断 |
|---|---|---|
| 执行机离线或标签不匹配 | 执行机在线状态、标签与流水线要求的运行环境 | 执行机离线或没有匹配标签的节点，等待资源类阻塞成立 |
| 并发槽位被占满 | 并发配额占用情况、同项目运行中实例数量 | 配额已满且队列持续增长，说明是容量问题而非单实例故障 |
| 执行机磁盘或内存不足 | 执行机资源指标、阶段日志中的写入失败或进程被杀记录 | 资源指标接近上限且日志有对应报错，可确认 |
| 触发条件或分支过滤配置有误 | 触发记录、流水线配置中的分支与路径过滤规则 | 触发记录缺失或与预期分支不符，说明实例根本没有按预期启动 |
| 依赖任务未完成 | 上游任务状态、依赖关系配置 | 上游长期未完成或依赖配置指向错误任务，可解释等待状态 |
| 制品仓库、镜像拉取或第三方接口超时 | 阶段日志中的拉取与请求记录、网络连通性 | 日志停在拉取或请求步骤且有超时记录，可确认外部依赖问题 |
| 近期配置、凭据或环境变更 | 变更时间线与首次阻塞时间是否对齐 | 变更时间早于首次阻塞且之后持续出现，变更嫌疑成立 |
| 审批未处理或权限缺失 | 审批单状态、审批人权限、待办提醒记录 | 审批长期挂起或审批人无权限，可解释等待人工环节 |
排查顺序建议从只读证据开始：先看实例状态与阶段耗时，确认卡在哪一段；再看执行机与配额，排除资源类原因；然后查触发记录与依赖关系，排除配置类原因；接着看阶段日志与网络，判断外部依赖；最后把变更时间线与首次阻塞时间对齐。人工环节的假设可以更早验证，因为审批状态通常一眼可见，成本最低。
验证过程中要注意证据的时间口径一致。例如执行机指标要看阻塞发生时段的数据，而不是当前时刻的快照；变更记录要与首次出现阻塞的时间对齐，避免把无关变更当成原因。一条假设被排除后应记录排除依据，防止后续重复排查同一方向。
按风险从低到高的处置顺序
处置的核心原则是先做不影响他人的动作，再动配置，最后才考虑取消、重跑或重建环境。每一步都应明确影响范围和停止点，避免为了恢复一条流水线而引入新的问题。
第一级：只读检查与沟通。查看完整阶段日志、确认执行机在线状态与配额占用、联系审批人或依赖任务负责人。这些动作不改变任何系统状态，风险最低，也常常直接解决问题，例如审批人处理后实例自动继续。
第二级：处理配置与依赖问题。确认是分支过滤、依赖关系还是凭据过期导致阻塞后，修改前先记录当前配置内容或导出配置，保留回滚依据。修改后观察新触发的实例是否正常，避免在旧实例上反复验证。
第三级：取消或重跑实例。这一步有明确代价：取消会终止当前执行，已产生的中间产物可能丢失，依赖该实例产物的下游任务会一并受影响。适用条件是实例已确认无法自行恢复、且重跑成本可控。执行前确认影响范围，包括下游任务、已发布产物和正在使用该环境的其他人员；重跑时优先复用已有缓存，减少重复构建。
第四级：清理执行机或重建环境。当执行机磁盘写满、环境被污染或进程僵死时才会走到这一步。操作前完成必要备份，明确停止点：如果清理后问题依旧，应停止继续操作并转入环境层面的排查，而不是反复重建。涉及共享执行机时，先确认没有其他流水线正在使用。
恢复确认与复发预防
实例重新运行不等于问题解决。恢复确认要看三件事：实例状态正常结束；关键阶段耗时回到历史正常区间，而不是勉强通过；产物能够正常流转到下游环节，包括制品入库、部署或交付。三项都满足，才能判定恢复。
恢复之后，把本次阻塞的原因、验证证据和处置动作整理成排查条目，记录阻塞位置、触发条件、责任环节和最终处置方式。反复出现的阻塞类型应单独标记，作为配置调整的输入。
复发预防可以从几个配置入手：为关键阶段设置超时，让无进展的实例尽早暴露而不是无限等待；为并发配额和执行机资源设置告警阈值，在占满之前收到提醒；对执行机做定期健康检查，提前发现离线或资源不足；为审批环节设置提醒，缩短等待人工环节的时间。这些配置的具体形式取决于团队使用的流水线工具，原则是让阻塞从“靠人发现”变成“有信号可查”。
在管理层面，阻塞处置涉及工作项状态流转、变更记录和复盘沉淀。ONES 支持集成 Jenkins、GitLab CI 等第三方流水线工具，集成后自动同步流水线数据并更新执行状态和日志；流水线与项目关联后，可在项目、迭代、需求中查看构建与发布过程，帮助识别阻塞。处置完成后，把阻塞原因与处置记录关联到对应需求或工作项，配合效能度量数据回顾反复阻塞的环节，能让下一次排查更快定位。
常见问题
流水线反复在同一阶段卡住，和偶发一次卡住的处理有什么不同？
偶发阻塞通常与某次变更、某台执行机或某个外部服务相关，范围清楚，优先恢复即可。反复阻塞表现为同一阶段、同一时段反复卡住，往往指向容量不足、配置不合理或依赖不稳定。处理上先按单次问题恢复，恢复后再安排配置调整，例如检查并发配额是否长期吃紧、该阶段依赖的外部服务是否稳定，并把这类阻塞单独标记为待优化项。
取消流水线实例前需要确认哪些影响？
取消会终止当前执行，已产生的中间产物可能丢失，依赖该实例产物的下游任务会一并受影响。执行前确认三件事：下游任务是否已排队等待该产物、是否有产物已经发布出去、是否有其他人员正在使用该实例占用的环境。确认实例已无法自行恢复、且重跑成本可控时再取消；重跑时优先复用已有缓存，减少重复构建。
执行机磁盘写满导致阻塞，清理时要注意什么？
清理执行机属于破坏性操作，操作前完成必要备份，并明确停止点：如果清理后问题依旧，应停止继续操作，转入环境层面的排查，避免反复重建。共享执行机还要先确认没有其他流水线正在使用。清理完成后观察新触发的实例是否正常，而不是在旧实例上反复验证。
怎么判断流水线是真的恢复了，而不是勉强通过？
看三项：实例状态正常结束；关键阶段耗时回到历史正常区间；产物能够正常流转到下游环节，包括制品入库、部署或交付。三项都满足才算恢复。只看到实例变绿而阶段耗时明显偏高，说明问题可能只是暂时绕过，需要继续观察后续几次执行。
阻塞处置完成后，怎么把经验沉淀下来避免下次重复排查？
把本次阻塞的原因、验证证据和处置动作整理成排查条目，记录阻塞位置、触发条件、责任环节和最终处置方式，反复出现的阻塞类型单独标记，作为配置调整的输入。在 ONES 中，可将阻塞原因与处置记录关联到对应需求或工作项，配合效能度量数据回顾反复阻塞的环节，让下一次排查更快定位。
