遇到队列堆积时，我一般不会先加节点，而是先看队列里等待项的原因。原因确认了，后面的操作才有方向。
当Jenkins队列中持续出现“Waiting for next available executor”且有多个构建在排队时，先不要急着加节点。通过访问 /queue/api/json 接口，查看每个等待项的 why 字段，确认是“没有匹配标签的节点”还是“匹配节点都在忙”。如果是后者，说明标签匹配到节点但资源不足；如果是前者，说明标签表达式没有对应任何在线节点，属于标签配置错误。这个区分直接决定后续操作是调换标签还是扩容节点。
先看队列状态，再决定扩不扩节点
这个区分不靠猜。打开 {JENKINS_URL}/queue/api/json，能看到一堆等待中的 item。每个 item 的 why 字段会写清楚原因：比如 “All nodes of label 'linux' are offline” 表示标签没匹配到在线节点；“node 'build-01' is busy” 表示有节点但 executor 被占满。两种原因的对策完全不同。
用命令行看更直接：
curl -s 'http://jenkins.example.com/queue/api/json' | jq '.items[] | {task: .task.name, why: .why}'如果没有 jq，也可以把输出存成文件，再搜索 why 字段。
标签维度先分能力，再分任务
当标签配置不合理时，加更多节点也可能继续堆积。
标签设计建议按“能力维度”而不是“任务维度”划分。例如用 os-linux、gpu-required、small-resource 表示节点能够提供的环境，而不是用 project-a、project-b 表示任务归属。在流水线中调用 node('os-linux && gpu-required') 组合标签，让同一组节点服务于多类任务。这样当某类任务空闲时，节点还能被其他任务使用，避免节点闲置，也避免某类任务独享节点造成堆积。
组合表达式的基础是一个节点可以打多个标签。比如一台 Linux 机器同时打上 os-linux、docker、gpu，另一台只打 os-linux、docker。要求 node('os-linux && gpu') 的任务只会去第一台；要求 node('os-linux && docker') 的任务可以在两台之间选，充分利用空闲 executor，而不是所有 docker 任务都卡在一个节点上。
注意逻辑表达式的优先级
标签表达式写错也会造成任务堆积，而且比资源不足更难发现。
标签表达式中的逻辑词（&&、||、!）优先级和括号要严格注意。常见错误是写成 node('a || b && c')，实际解析为 a || (b && c)，如果意图是 (a || b) && c，必须加括号。否则可能匹配到大量不符合条件的节点，导致执行错误或资源占用；反过来，表达式过严也会导致任务永远等待。每修改一次标签，建议用“Manage Jenkins”里的“Node/Node”页面查看匹配节点数是否在预期范围。
也可以结合脚本控制台确认匹配节点列表。修改后先看返回的节点数量，再跑一个简单的构建验证。
任务堆积时的处理顺序
如果队列已经堆起来，我建议按下面的顺序处理，而不是直接改全局配置：
- 先通过 /queue/api/json 看 why 字段，判断等待原因是“没节点”还是“节点忙”。
- 用 Groovy 脚本控制台统计不同标签表达式下的等待任务数量：
def waiting = jenkins.model.Jenkins.instance.queue.items.findAll {
it.task instanceof hudson.model.Queue.WaitingItem
}
def counts = [:].withDefault { 0 }
waiting.each { item ->
counts[item.label] = counts[item.label] + 1
}
counts.each { label, count ->
println(label + ': ' + count)
}执行后能看到哪些标签组合的队列最深，优先处理长期堆积的标签。
- 找到堆积最严重的标签组合，查看匹配的节点数和在线状态。如果匹配节点少，临时调整流水线或项目里的标签表达式，把任务迁移到其他空闲节点。具体可以在“Restrict where this project can be run”位置修改，也可以改流水线中的 node() 参数。
- 迁移前确认目标节点的环境，比如依赖库、容器运行时、gpu 驱动是否齐全。迁移后观察队列深度是否下降。
如果标签调整后队列仍然不降，问题可能不在标签，而是任务本身长时间占用 executor。比如构建步骤中没有设置 timeout，或者测试命令一直等待输入。这时需要检查任务日志，而不是继续调标签。
回滚边界和后续维护
每次修改标签表达式前，建议把原表达式记录在构建配置或代码仓库的提交信息里。这样如果调整后任务因为环境不符而失败，可以快速回滚到原来的表达式。
标签配置的后续维护主要看两点：一是节点上的标签是否还和实际环境一致，二是队列深度是否在正常范围。周期性用脚本统计 waiting item 数量，比等任务堆积再关注要省事。给节点打多个标签时，也不要只用一个 docker 这样的标签区分所有能力，否则不同需求的任务会挤在一起，最终还是要回到按能力拆分标签的路子。