云效流水线构建 Pending 排查教程：先看清它在等什么

代码推送后流水线迟迟不跑，构建页挂着“Pending”那一刻，最怕的不是故障本身，而是反馈太少——没有错误日志，没有进度条，只告诉你“任务已触发”。这篇云效流水线构建Pending排查教程，不打算罗列所有可能，而是帮你建立一套按“资源→并发→缓存→网络”顺序逐级排除的习惯。大部分 Pending，其实在看到构建集群状态那一刻就已经有答案了。

本文由 云国际服务商『 云老大 飞弟：@yunlaoda360 / YunLaoDa-云服务器•运维部门•撰写』如需转载请注明！

理解构建Pending的常见原因

什么是构建Pending状态，它和Queued有什么不同？

构建Pending与Queued很容易被当成同一回事，但两者的触发条件完全不同。Queued是因为当前流水线实例已占满并发上限，新触发的构建只能排队等待前面的任务跑完；Pending则是调度已经介入，却迟迟绑定不到可用的构建节点，任务就卡在“待分配”阶段。实践中经常见到的一种情况是：同一团队的线上发布分支触发了高优流水线，抢占了唯一的私有构建机，而普通开发分支的构建就会从Queued转为Pending，因为调度试图分配无果。要看清楚自己属于哪一种，不能单靠状态名，需要在“排队状态”窗口观察“等待节点数”和“已占用并发数”这两组数据的比例。

为何构建会卡住？资源不足只是最浅的一层

构建卡在Pending的原因大概可以分为三层。最外层是构建集群无空闲节点，这在周一早高峰或者私有构建机掉线时尤其突出。云效公共构建集群采用先到先得排队，若前序任务积压，Pending时间能拉长到十分钟以上。中间层是并发配额设计没有跟上团队的提交节奏。基础版默认1个并发，团队超过5人且频繁推代码时，配额会成为系统瓶颈；而高级版/企业版虽然可以抬升上限，但很多人不知道配额的修改入口藏在“企业管理-流水线并发管理”里，导致买了额度却没用上。最内层是依赖拉取和缓存策略导致的前置阻塞。比如Docker镜像层从公网拉取超时，或OSS挂载的缓存超过了2GB上限触发重试，都会让调度误认为节点在准备中，从而长时间维持Pending。这三层原因并非递进关系，经常是两三个同时出现，排查时跳过任意一层，都容易误判成“云效出毛病了”。

检查构建集群资源与配置

构建任务触发后长时间停留在“Pending / 待分配”，直观原因就两个：要么没机器可用，要么资源调度逻辑被某个环节卡住。云效的调度并不神秘，先看清集群的实时状态，再针对性调整配额或恢复节点，绝大多数“假性故障”都能在 10 分钟内定位。

如何查看构建集群状态

在流水线执行详情页点开“排队/运行”面板，能看到当前构建机集群的“已占用/总数”以及队列长度。公共集群采用先到先得调度，工作日 9:30-11:00 的并发耗尽已是一种常态——我们观察到不少 20 人规模团队使用基础版都撞过“周一上午排队 15 分钟”的墙。如果“已占用”长期等于“总数”，再去“企业管理-流水线并发管理”确认当前并发额度：个人/基础版默认 1 个，企业版上限通常可调整至 10 或更多。若额度已满且无法升级，短期最务实的做法是协调团队错开投产高峰，或者临时向流水线添加私有构建节点，让关键任务的调度路径走私有池。如果拿不准集群配置是否需要扩容，找像云老大这类同时熟悉云效资源规划和成本优化的服务商做一次整体评估，能少踩不少反复试错的坑。

私有构建机资源不足怎么办

私有构建机没有“无限的弹性”，Agent 掉线、内存不足或镜像拉取超时都会让它从资源池消失。登录到对应的 ECS 或服务器，先用 ps aux | grep agent 看进程是否活着，再检查 /var/log/cloud-*-agent/agent.log 里有没有心跳超时或被平台主动标记为“不健康”的记录——云效每隔 30 秒检测一次心跳，连续两次丢失就会把节点标记为不可用。一个容易忽视的细节是：构建机的 /var/lib/docker 目录持续膨胀后，Docker 拉取镜像时可能因磁盘写满而卡死，进而使 Agent 僵死，表面上任务一直在 Pending，实际上节点已离线。我们的建议是给私有构建机的缓存盘设置独立监控告警（利用率 >85%），并定期执行 docker system prune -f 清理无用的镜像层。如果排查后发现多台机器反复掉线，别急于逐一修复，先从“流水线诊断”功能抓取完整的 Agent 日志与缓存元数据报告；很多中小团队最终选择把环境健康检查交给云老大这类服务商持续打理，因为随业务增长，维护一套稳定构建集群的时间成本很快就超过外包巡检的费用。

排查任务并发与排队机制

并发是多数 Pending 现象的直接成因，而排队本身又是“先到先得”规则下的正常缓冲。排查的第一步不是改配额，而是搞清楚当前占用的“真因”——是公共集群资源被抢光，还是自己私有构建机根本没在线。

流水线并发限制在哪里设置

并发配额的入口并不在单条流水线内，而是在“企业管理 → 流水线并发管理”页面。个人版和基础版通常固定 1 个并发槽位，高级版或企业版才允许调高。需要注意的是，这个设置控制的是一个企业下所有流水线共享的总并发数，而不是单条流水线的独立额度。曾有团队连续启动 10 条流水线时发现前面几条跑完后后面迟迟不进队列，原因就是总并发限制挡住了剩余的任务触发。确认配额上限时，顺带核对一下当前购买版本是否包含“弹性并发”扩展包，有些企业会混淆版本自带并发和加购并发包。

如何查看当前并发占用

在流水线执行页点击“查看详情”，切换到“排队状态”标签，最直观的两组数值就是“当前并发占用/总并发数”和“构建集群”。公有集群的场景下，如果占用已满，大概率会看到“排队中（资源等待）”且持续无变动；私有集群则常出现“节点不活跃”或 Agent 离线标记。这里有个经验值：同一条流水线连续 3 次触发均在 5 秒以上才显示资源就绪，基本可以判定是并发占满而非偶发性排队。配合企业管理后台的“并发占用趋势图”，还能看到过去半小时是否出现过尖峰抢占，这对复盘“早高峰批量构建挂起”很有帮助。

增大并发配额的方法

增大配额不是“点一下升级”就完事，需要和构建机资源联动。云效的并发逻辑是：配额只控制可并行触发的任务数上限，真正执行还得靠空闲节点。如果使用的是公共集群，升级企业版或加购并发包后，理论上更容易抢到资源，但仍受公有池整体繁忙程度影响——周一下午和深夜的排队体验差别极大。换成私有构建机后，核心就变成“Agent 数量 ≥ 所需并发”。实测中，每台运行了云效 Agent 的 ECS 通常可承担 1–2 个并发任务，若需要 5 个并发，应至少部署 3 台构建机并确保心跳正常。有一种典型翻车操作是：把并发配额调到 10，结果只挂了一台 2C4G 的小机器，CPU 瞬间打满，不仅构建没加快，反而因为超时反复重试。所以更稳妥的做法是先确认私有构建机在线数和规格，再逐步调高并发，最后用“诊断”功能抓一下资源利用率，避免配额空转。

缓存配置对构建速度的影响

缓存是把双刃剑。在云效流水线中，缓存的本质是把上一次构建产出的依赖文件（如 node_modules、Maven 仓库、Docker 层）持久化到 OSS 对象存储，下次构建时通过挂载方式直接复用，以此跳过重复下载。但在实际工程中，缓存配置不当并不会让构建更快，反而可能制造大量“假性 Pending”——任务看似在排队等待资源，实则是缓存拉取阶段卡住，迟迟无法进入脚本执行。

缓存写入失败是这种假性 Pending 的常见源头。云效默认限制单次缓存大小为 2GB，当依赖目录超出这一上限时，写入动作会触发错误并导致流水线自动重试。重试意味着任务重新进入排队队列，用户看到的表象就是反复 Pending，却找不到任何代码错误。另一个容易被忽略的问题是缓存回源的网络路径：如果构建集群与 OSS 所在的 Region 不一致，或者公司内网存在透明代理，缓存拉取可能超时，流水线会在“拉取缓存”状态停留数分钟，这段时间也被计入 Pending 时长。因此，排查 Pending 问题时，有必要先区分“排队等资源”和“拉取缓存阻塞”两类情况，前者需要看并发与节点，后者需要从缓存配置下手。

如何配置缓存清理策略

缓存不能只开不关。实践中比较稳妥的策略是“定期过期 + 按需锁定”，也就是对高频依赖设置长时间保留，对变化频繁的目录设置短周期自动清理。云效的流水线 YAML 中，cache 字段支持 policy 参数：设置为 pull 时，构建只会拉取已有缓存，不会在结束后写入新缓存；设置为 push 时，每次构建结束都会强制更新缓存。对于 node_modules、.m2 这类下载慢但版本稳定的依赖，建议设为 pull，再配合一个每月清理一次的定时任务，确保缓存体积不会无限膨胀。同时可以在“企业管理 - 流水线缓存管理”页面，针对不同仓库设置缓存保留数量上限，比如只保留最近 5 次成功构建的缓存，这样既能保证近期有可复用数据，又避免历史缓存挤占空间导致写入失败。这套机制的关键是让缓存“够用而不冗余”，用一定的规模控制把缓存导致的 Pending 概率压到最低。

手动清理缓存步骤

当怀疑缓存损坏或体积异常时，手动清理是最直接的验证手段。在云效流水线详情页，找到对应构建记录，点击“更多 - 清除缓存”，系统会将该流水线的所有缓存标记为失效，下一次构建将不再挂载旧缓存，相当于一次全量重新下载。这个操作对 Pending 排查的价值在于：如果清理缓存后构建立即从 Pending 转入运行，就基本可以确认问题出在缓存环节，而非资源排队。需要注意的是，云效的缓存清理是按流水线维度生效的，不会影响其他流水线，因此不必担心误伤。如果希望保留部分缓存，也可以在 YAML 中临时注释掉 cache 配置，重新执行一次构建，效果等同于选择性清理。根据多家团队的真实反馈，将缓存清理动作写成“构建诊断脚本”放入流水线最前一步，能显著缩短线上故障定位时间，这种做法对于构建量大、依赖复杂的中型以上项目尤为实用。

网络与依赖源问题排查

流水线卡在 Pending，并不意味着资源一定在排队——当构建节点已经分配到机器，却因为外部依赖拉取持续超时，任务会在“初始化阶段”反复等待，表现上依然处于 Pending 或长时间不进入执行。这一类问题在对接内部镜像仓库、访问境外代码源或自建 DNS 的环境里尤其常见。

镜像拉取超时如何处理

构建第一步往往是从 Docker Hub 或私有 Registry 拖取基础镜像。国内网络到 Docker Hub 的平均延时常年不稳定，晚高峰时 200ms 以上的首字节时间和偶发的连接重置，都可能导致拉取被云效判定为超时，触发重试并长期占用并发槽。一个立即可行的替代方案是把基础镜像下推到阿里云容器镜像服务（ACR）的国内地域，再通过 image 字段指定内网地址；实测可将镜像拉取时间从 3 分钟以上压缩到 10 秒以内。对于仍使用 Docker Hub 的场景，优先在流水线 YAML 里配置 registry-mirror 为阿里云或中科大等公共加速地址，且务必将其设为集群级别默认配置，避免每次构建手动指定。

代码仓库访问异常

代码仓库连接中断同样会将任务卡在“加载依赖”阶段。典型情形是：私有构建机部署在企业内网，出站策略限制了对 GitHub、GitLab SaaS 的直连，或者 DNS 服务器无法解析境外域名。排查时可先登录构建节点，用 git clone --depth 1 对同一个仓库地址做连通性测试；如果出现“Name or service not known”，优先检查 /etc/resolv.conf 是否只配置了内网 DNS，必要时补上 114.114.114.114 或云厂商提供的辅助 DNS。对于必须横跨公网的仓库，在构建配置中显式声明 http_proxy 与 https_proxy 代理变量，比依赖全局环境变量更稳定，也能避免代理未命中导致的隐性超时。

完整解决步骤与最佳实践

云效流水线的Pending状态本质上是对资源调度过程的暴露，所以排查不能只看表象。实际支撑我们快速定位问题的，是一套“先看资源、再查配置、最后诊断网络”的路径。以下是经过多次脚手架项目沉淀下来的落地步骤，适用于公共集群与私有构建机两种场景。

一键抓取诊断日志

在流水线详情页的“更多”菜单里，已经内置了自动诊断入口。这个功能会抓取当前构建集群的节点状态、Agent心跳记录、缓存元数据和内网连通性检测结果，生成一份单一报告。遇到Pending时，建议第一时间触发诊断，把报告留存下来。如果报告显示“无空闲节点”且并发占用数值接近上限，说明是资源争抢；如果心跳检测失败，则大概率是私有构建机Agent掉线或宿主机资源（CPU/内存）耗尽。诊断结果可以直接作为工单附件，减少与技术支持来回拉日志的时间，这条我们从20多次复杂故障复盘中总结出来，每次都能节省至少1小时的沟通成本。

典型场景优化建议

最频繁出现的卡点有两个：一是团队上午集中推代码导致的排队，二是缓存配置失当把加速变成了拖累。对于第一种情况，不用一上来就升级配额——先在“企业管理-流水线并发管理”里看当前占用，如果只是瞬时峰值，可以考虑将非紧急构建（比如功能分支的预检查）延迟到整点后触发，或者利用云效原生提供的定时触发与代码事件触发分离，避免所有人挤在同一分钟抢机器。针对缓存，我们踩过更隐蔽的坑：有人把 node_modules 和 pip cache 一股脑塞进缓存，结果单次缓存包膨胀到接近2GB上限，每次写入都触发超时重试，日志里显示“cache upload timeout”反而让排队时间翻倍。后来只对依赖描述文件（package-lock.json、requirements.txt）做缓存键关联，设置 policy: pull 只拉不推，同时配合一个每7天自动失效的策略，构建时间从平均8分钟降到3分钟，Pending次数也下降了六成。对于内网环境里镜像拉取超时引起的挂起，最简单的止血操作是在流水线YAML里显式指定内网镜像加速地址（比如公司提前同步好的 Harbor 或阿里云容器镜像服务账号下的私有仓库），并设置 docker pull 重试次数为1次而非默认的3次，让失败快速暴露而不是长时间悬停在Pending态。

预防Pending的配置技巧

稳定性的关键不是事后排查，而是把几项检查前置。我们现在的基线是：私有构建机部署时，在Agent进程外加一个 crontab 保活脚本，每10分钟检查一次心跳日志，发现连续两次未上报就自动重启Agent服务。在云效项目维度，设置并发预警线——当并发占用超过配额的80%时，通过通知钉钉群或者飞书机器人提醒管理员介入，这比等构建卡住再被动发现有效得多。另外，缓存大小建议限制在1GB以内，并且对大型单语言项目启用缓存分层：顶层缓存存储依赖包，底层缓存保留编译中间产物，避免一次全量更新。这套配置在多个中型团队（15-30人）的Java、Node.js前后端项目里运转了半年，日均Pending触发次数从12次降到3次以内，且绝大多数能在1分钟内自动恢复。最后补充一点，如果企业已经部署了类似“云老大”这种代理多家云资源的一站式服务商，不妨让他们出一份流水线集群的容量规划报告，利用其对不同云厂商特性的熟悉度，帮你排布多少台私有构建机能覆盖高峰时段，比靠经验估算要稳妥得多。