概念
1、agent
agent实际执行所分配的构建任务如代码推送、测试、编译、打包、部署。不同的agent可以进行任务区分如java环境,前端环境
2、executor
规定agent节点可以同时执行的任务数量,可以根据系统资源调整executor的个数,完成系统的任务执行
3、label
给节点打标签可用于分组,调用的时候更方便
场景
任务调度异常:Job 一直处于排队状态
1. 故障现象
多个构建任务需要执行,但部分任务一直处于 Queue 状态,没有分配到 Agent。
2. 原因分析
-
没有符合 Label 要求的 Agent。
-
符合条件的 Agent 已经没有空闲 Executor。
-
Agent 处于 Offline 状态。
-
Job 或 Pipeline 存在其他节点调度限制。
-
任务受到并发限制或资源锁限制。
3. 排查思路
第一步:检查 Label 是否匹配
确认 Job 或 Jenkinsfile 指定的 Label,以及 Agent 实际配置的 Label。
第二步:检查 Agent 状态
确认符合条件的 Agent 是否在线、是否可以接收任务。
第三步:检查 Executor 使用情况
确认节点的 Executor 是否已经被其他任务占用。
第四步:检查其他调度限制
检查并发构建限制、Pipeline 配置以及资源锁等因素。
Agent 节点 Offline 故障排查
1. 故障现象
Agent 原本可以正常执行构建任务,突然变成 Offline,导致任务无法调度到该节点。
2. 原因分析
-
Controller 与 Agent 之间网络通信异常。
-
Agent 服务器上的 Java 进程异常退出。
-
SSH 认证失败。
-
Java 版本不满足 Jenkins Agent 的运行要求。
-
Agent Remoting 通信异常。
-
Agent 服务器资源不足。
3. 排查思路
第一步:检查网络通信
确认 Controller 与 Agent 之间的网络和必要通信端口是否正常。
ping <agent_ip>
nc -zv <agent_ip> <port>
注意:SSH 方式通常需要检查 22 端口;Inbound Agent 则需要根据实际配置检查对应通信方式和端口。
第二步:检查服务和进程状态
Controller:
systemctl status jenkins
journalctl -u jenkins -n 100
Agent:
ps -ef | grep java
第三步:检查 Java 环境
java -version
which java
echo $JAVA_HOME
确认 Java 版本是否满足当前 Jenkins Agent Remoting 的运行要求。
第四步:检查 SSH 认证
ssh -v user@agent_ip
检查密钥、用户权限、认证配置是否正常。
第五步:查看 Jenkins 系统日志
重点关注 Agent 断开时间附近的日志,分析连接失败、认证失败、进程退出或 Remoting 异常等信息。
故障排查原则
Jenkins 故障排查不能只依赖某一个命令,需要结合故障现象、日志和实际运行状态逐步缩小范围。
建议按照以下顺序:
-
确定故障范围:单个 Job、多个 Job,还是整个 Agent。
-
检查 Jenkins 节点状态和任务调度情况。
-
检查网络、进程、运行环境和权限。
-
查看日志,定位具体异常。
-
修复后重新执行任务,验证是否恢复。
进度
-
已理解:Agent、Executor、Label 的关系。
-
已掌握基本排查思路:任务排队、Agent Offline。
-
待实践:SSH Agent 连接、Remoting 日志分析、真实故障恢复。