从源代码出发，Jenkins 任务排队时间过长问题的解决过程

最近开发了一个部署相关的工具，使用 Jenkins 来构建应用。Jenkins 的任务从模板中创建而来。每次部署时，通过 Jenkins API 来触发构建任务。在线上运行时发现，通过 API 触发的 Jenkins 任务总是会时不时在队列中等待较长的时间。某些情况下的等待时间甚至长达几分钟。直接在 Jenkins 界面上触发的任务却几乎不需要排队，直接马上就可以执行。过长的等待时间影响了构建的效率，这是一个急需解决的问题。这个问题奇怪的地方在于，手动从界面上触发的任务几乎不需要排队，而 API 触发的任务的排队时间则完全随机，毫无规律可言。

当任务在队列中时，Jenkins 会在界面上显示该任务在队列中等待的原因。对于 API 创建的任务，它们的等待原因是“Finished waiting”。从这个原因的字面含义确实看不出来什么。当出现这样的问题时，最直接的办法是从源代码中寻找答案。

从 GitHub 上把 Jenkins 的源代码下载到本地。寻找问题的起点是搜索字符串“Finished waiting”。这个字符串定义在资源包（resource bundle）中，对应的键是 Queue.FinishedWaiting。再搜索使用了这个键的代码，定位到了类 hudson.model.Queue。从名字可以看出来，这个类表示的是 Jenkins 内部的工作队列。在这个类中定义了可能出现在队列中的不同类型的条目。类 WaitingItem 表示的是处于等待状态的条目。这个类的 getCauseOfBlockage()方法刚好用到了Queue.FinishedWaiting 这个键，表示当前条目被阻塞的原因。这个 WaitingItem 类是主要的调查目标。

WaitingItem 类中有 enter() 和 leave() 两个方法，分别表示该条目进入队列和离开队列。看起来那些等待时间过长的任务，在进入了队列之后，经过很长一段时间，它们的 leave() 方法才被调用。

继续追踪这两个方法的调用，会发现 enter() 方法在 scheduleInternal() 中被调用，用来调度新的任务。而 leave() 方法则在 maintain() 中被调用，用来在合适的时机从队列中移除任务并执行。所以看起来问题是出在 maintain() 方法中。

maintain() 方法负责维护队列，并把任务在不同的状态中移动。当有可能影响到任务调度的情况发生时，Jenkins 会在内部调用这个方法。在 scheduleInternal() 方法中，把新的任务添加到队列之后，它会调用 scheduleMaintenance() 方法提交一个 Runnable 任务来调用 maintain() 方法。

经过上面的分析，任务等待时间过长的原因可能是，maintain() 方法被调用时，并没有发现处于等待的任务。所以这个任务需要等到下一次 maintain() 方法调用时才会被执行。这中间可能有与时序相关的问题。

---

问题找到了之后，下一步考虑的是怎么解决问题。如果要从根本上解决问题，应该从 Jenkins 入手，尝试在 Jenkins 中找到问题发生的根源，并进行修复。这种方案要求对 Jenkins 的代码库有足够程度的了解，在本地构建开发环境，并尝试稳定地复现问题。找到问题并解决之后，还需要添加 Pull Request 到 Jenkins 的代码库，并等待新版本的发布。整个过程耗时漫长。作为 Jenkins 的使用者，我自己并没有太大的意愿去花费精力在 Jenkins 自身的问题上。这种与时序有关的问题，很难复现和调试。我需要的是一个能够有效解决问题的 workaround。

前面提到了，产生问题的原因是 maintain() 方法在执行时可能没有发现等待中的任务。那么解决的办法可以很直接，那就是每次提交任务之后，等待几秒钟，再调用一次 maintain() 方法。这样就可以确保 maintain() 方法能够发现等待中的任务。maintain() 方法是由 scheduleMaintenance() 方法调用的，而 scheduleMaintenance() 是 Queue 类的一个公开方法。我只需要能够调用这个 scheduleMaintenance() 方法就可以了。

Jenkins 有一个叫做脚本控制台的功能，可以在运行的 Jenkins 实例上执行 Groovy 脚本。Groovy 脚本可以直接对运行的 Jenkins 实例进行修改。

每个 Jenkins 运行的实例中，Queue 对象只有一个。只需要找到这个 Queue 对象，并调用其中的 scheduleMaintenance() 方法，问题就解决了。脚本控制台已经内置提供了很多 Jenkins 的对象。实际上需要执行的代码很简单。

Jenkins.instance.queue.scheduleMaintenance()

通过在脚本控制台进行测试，发现只要执行了上述的脚本，原本在队列中的任务，马上就可以被调度执行。这也证明了问题确实解决了。

最后一个问题是如何把对 scheduleMaintenance() 的调用自动化，也就是在每次通过 API 触发了任务，等待几秒钟之后，自动调用 scheduleMaintenance() 方法。Jenkins 的脚本控制台并没有提供公开的 API。我采取的做法是用 HTTP 客户端模拟脚本控制台界面上的操作。脚本控制台的界面在运行脚本时，实际上执行了一个表单提交动作。这个表单被提交到了网址 /computer/(built-in)/script，内容类型是 application/x-www-form-urlencoded。请求中只需要包含一个参数 script，表示需要执行的脚本内容。Jenkins 使用的是 BASIC 认证，需要把访问的用户名和密码包含在请求中。使用 HTTP 客户端模拟上述请求并不难。

下面给出了使用 Spring RestTemplate 执行 Groovy 脚本的代码示例。

var headers = new HttpHeaders();
headers.setContentType(MediaType.APPLICATION_FORM_URLENCODED);
var authentication = "Basic " + Base64.getEncoder()
    .encodeToString(String.format("%s:%s", username, password).getBytes(StandardCharsets.UTF_8));
headers.add("Authorization", authentication);
MultiValueMap map = new LinkedMultiValueMap<>();
map.add("script", "Jenkins.instance.queue.scheduleMaintenance()");
var entity = new HttpEntity<>(map, headers);
try {
  restTemplate.exchange(
      String.format("%s/computer/(built-in)/script", jenkinsUrl),
      HttpMethod.POST, entity,
      String.class);
} catch (Exception e) {
  // 处理异常
}

至此，Jenkins 任务排队时间过长的问题得到了解决。虽然并没有从根本上解决问题，但已经是一个在有限的时间内可以完成的不错的解法。