Jenkins代理无法运行Pipeline问题排查求助

问题背景 #

Jenkins版本2.401.2 LTS，控制器与代理均运行Windows系统：

• JNLP代理在WebGUI中显示已成功启动并连接，但指定该代理的Pipeline始终停留在「Build Scheduled」状态无进展
• Pipeline代码指定代理标签为TestAgent：

  pipeline {
    agent {
      label 'TestAgent'
    }
    
    stages {
      stage('Retrieve Source Code') {
        steps {
          //steps
        }
      }
    }
  }
  

• 开启Built-In-Node选项时Pipeline可正常构建，但指定代理时系统日志显示任务仍尝试在Built-In-Node运行
• 代理PC任务管理器无Jenkins相关进程，代理日志无任务相关记录

故障排查步骤与配置检查 #

1. 节点标签与调度规则验证 #

• 确认代理节点的**标签（Label）**完全匹配Pipeline中的TestAgent：区分大小写，检查是否包含空格/特殊字符，WebGUI节点配置页的「Labels」字段需与Pipeline代码完全一致
• 检查节点「Usage」设置：确保选择「Use this node as much as possible」，而非「Only build jobs with label expressions matching this node」（若为后者，需确认Pipeline的标签表达式完全匹配节点规则）

2. 代理节点连接状态深度排查 #

• 查看节点「Offline Cause」：在WebGUI节点列表中点击代理节点名称，查看是否存在隐性离线提示（如临时断开、资源不足）
• 带调试参数重启JNLP代理：在代理PC上手动执行启动命令，生成详细日志排查连接问题：

  java -jar agent.jar -jnlpUrl http://<Jenkins控制器地址>/computer/TestAgent/slave-agent.jnlp -secret <代理密钥> -debug
  

• 检查代理PC防火墙/杀毒软件：确认允许Jenkins控制器与代理的JNLP端口（可在控制器全局安全配置中指定固定端口）通信，同时允许java.exe/javaw.exe出站连接

3. Pipeline与调度配置检查 #

• 排查全局代理覆盖：查看Jenkins全局配置中的「Default agent」设置，确认未强制使用内置节点；同时检查Job配置的「Advanced Project Options」，确认无节点限制被覆盖
• 确认代理节点执行器数量：确保节点配置中「# of executors」≥1，若为0则无法接收任务
• 查看队列任务详情：在Jenkins首页点击「Build Queue」，查看该Pipeline任务的「Why am I waiting?」提示，排查是否存在节点占用、标签不匹配、权限限制等问题

4. 系统时间与权限验证 #

• 对齐控制器与代理系统时间：从提供的时间差截图确认偏差是否超过5分钟，Jenkins JNLP连接依赖时间同步，时间差过大可能导致身份验证失败
• 检查代理启动权限：确保代理以管理员权限启动，或至少拥有本地创建临时文件、执行进程的权限；若以服务方式运行，确认服务账户具备登录权限

5. 插件兼容性检查 #

• 验证JNLP相关插件：确认「JNLP Agent Protocol」插件已安装且版本与Jenkins 2.401.2 LTS兼容，无插件损坏或版本不匹配情况
• 排查调度类插件干扰：若安装了「Node Label Parameter」等插件，检查是否存在全局规则干扰节点调度逻辑

内容的提问来源于stack exchange，提问作者joekevinrayan96