Jenkins 节点离线 agent offline 速查：JNLP、服务与磁盘

更新时间：2026-10-24。FAQ 速查页，面向构建排队不动、节点列表里一片灰色 offline 标记的同学。Jenkins 节点离线的本质是控制器与执行节点之间的连接断了，或者控制器主动把节点摘出调度——病因收敛在六根轴上：节点上的 agent 进程/服务根本没起、JNLP 入站端口被防火墙挡死、磁盘写满触发自动摘机、流水线要的标签和节点标签对不上（表现为排队而非 offline）、节点 Java 版本与控制器要求不符、以及网络抖动导致长连接反复断开。顺一遍基本必中。如果是流水线语法报错而不是排队，转 No such DSL method 速查。

本文要回答的问题

• 节点状态 offline，怎么分清是 agent 没起、端口不通还是控制器主动摘机？
• 构建一直卡在「Waiting for next available executor」，节点明明在线为什么排不上？
• 「磁盘空间不足」自动摘机后，清完磁盘怎么让节点回来？
• JNLP 端口是什么，容器/虚拟机场景要放行哪个？
• 节点时好时坏、日志里反复 connect/disconnect 查哪里？

一、报错原文与典型现象

offline 的「报错」分散在三处：节点列表的状态列、节点详情页的 agent 日志、以及构建页的排队提示（控制器地址以 jenkins.example.com 占位，路径以 /proj/demo 占位）：

# 节点详情页 / agent 日志
java.net.ConnectException: Connection refused (Connection refused)
    at java.base/sun.nio.ch.Net.connect0(Native Method)
Caused: hudson.remoting.JnlpAgentEndpointResolver could not resolve
jenkins.example.com:50000

# 节点详情页的红字提示
This agent is offline because Jenkins failed to launch the agent process.
# 或：磁盘监控自动摘机
Disk space is too low. Only 0.512GB free on /proj/demo/jenkins.

# 构建页排队提示
Waiting for next available executor on 'linux-docker'
# 节点列表里没有任何节点带这个标签 = 永远排队

读现象先分三类：状态灰 offline 带连接异常 = 链路问题；offline 带磁盘提示 = 控制器主动摘机；节点在线但构建排队 = 标签/执行器配置问题。三类修法互不相干，先定性。

二、病因处置速查表

报错现象 / 场景	可能原因	快速验证	处置
offline + Connection refused	agent 进程/系统服务没启动	节点上 systemctl status jenkins-agent 或查进程	启动服务并设开机自启
offline + 无法解析 JNLP 端口	入站 agent 端口（默认 50000）被防火墙挡	控制器侧 nc -zv <节点地址> 50000；节点侧 ss -lntp	放行端口；核对全局安全配置里的 TCP 端口设置
offline + Disk space is too low	workDir 磁盘满触发自动摘机	节点上 df -h 看挂载点	清理构建残留，节点页点恢复上线；调低阈值
节点在线但构建永远排队	流水线 label 与节点标签不匹配	对比 Jenkinsfile 的 agent 标签与节点配置的标签	统一标签命名；或给节点补标签
启动即报 Java 版本错误	节点 Java 与控制器要求的大版本不符	节点上 java -version 对照控制器系统信息	节点装齐要求的 JDK 大版本
反复 connect/disconnect	网络抖动、NAT 会话超时、负载过高	看 agent 日志断连频率与时间分布	查链路稳定性；给 remoting 调 keepalive

三、排查决策图

下面这张图是标准排查路线，颜色按角色区分：红是报错入口与命中的根因，蓝是排查动作，绿是通过分支，橙是修复动作，紫是防复发沉淀。

读这张图抓分水岭：节点详情页把 offline 原因和 agent 日志摆在明面上，先看它指认的是「链路类」还是「配置类」。链路类（服务没起、端口不通、Java 不符）去节点机器上查；配置类（磁盘满、标签不对）一半在控制器配置里。两类都不沾的「在线但排队」，答案几乎总是标签。

四、逐条排查展开

先看节点详情页，它会说人话。 节点列表点进 offline 节点，页面顶部直接给出原因（连接异常、磁盘低、手动摘机），下方是 agent 启动日志的尾部。Connection refused 说明节点那侧没有进程在监听——agent 服务没起；Connection timed out 则是中间链路（防火墙/安全组）丢包。这一步不定性就 SSH 上节点乱查，是空转的开始。

agent 服务要注册成系统服务，别裸跑。 物理机/虚拟机节点把 agent 注册为 systemd 服务（单元文件里写好 java -jar agent.jar 的完整参数），systemctl enable --now 一次到位；重启节点后服务没自启是「重启后批量 offline」的固定剧本。启动失败看 journalctl -u jenkins-agent 的最后几十行，八成是 agent.jar 路径、workDir 不存在或权限不对。

JNLP 入站端口两端都要通。 控制器侧在「全局安全配置 → Agents → TCP port for inbound agents」固定一个端口（不要用随机），节点侧防火墙与安全组放行它。验证用两条命令对拍：

# 控制器或任意机器上
nc -zv <节点地址> 50000
# 节点本机
ss -lntp | grep 50000

控制器是容器部署时，这个端口还要在容器映射/负载均衡上透传——容器场景只放行了 Web 端口 8080 而漏了 JNLP 端口，是「网页正常、节点全 offline」的经典事故。

磁盘满自动摘机：清完要手动接回。 Jenkins 的磁盘监控发现 workDir 所在分区低于阈值（默认 1GB）会把节点标记 offline 自我保护。处置三步：节点上 df -h 确认、du -sh /proj/demo/jenkins/workspace/* 找到吃磁盘的构建残留清掉，然后回节点详情页点「恢复上线（Bring this node back online）」——很多人清了磁盘忘了这一步，节点就一直灰着。长期方案是给流水线配 discard old builds、给 workspace 配定时清理任务。

标签不匹配：节点在线、构建永远排队。 Jenkinsfile 里 agent { label 'linux-docker' } 而没有任何节点带着一模一样的标签，构建就在队列里等一辈子。对拍两边：Jenkinsfile 的标签串 vs 节点配置页 Labels 字段（空格分隔的多个标签，逐字符匹配、大小写敏感）。还有一种隐蔽情形：标签对上了，但节点的执行器数被配成 0 或被「仅运行绑定本节点的任务」限制住，同样排队。

Java 版本与抖动断连。 节点 java -version 的大版本必须满足控制器对 agent 的要求，版本过低时 agent 启动日志直接报 UnsupportedClassVersionError。网络层面，remoting 长连接对中间设备的会话超时敏感——跨 NAT/负载均衡的链路空闲超时被掐，表现为周期性断连重连；处置是链路设备调大空闲超时，或在节点启动参数里缩短 remoting 的 keepalive 间隔。

五、规范做法与预防

• agent 一律 systemd 托管：开机自启 + 失败自动拉起，杜绝裸 nohup。
• JNLP 端口固定并文档化：随防火墙/安全组规则一起入库评审。
• 磁盘双保险：构建历史配保留策略，workspace 配定时清理，磁盘监控接入告警。
• 标签命名规范：系统-能力 格式（如 linux-docker、win-msvc）写进团队文档，新节点对表配标签。
• 节点页 offline 原因进巡检：每天扫一眼节点列表，灰色节点当天消化。
• workDir 独立分区：与系统盘分离，磁盘满不殃及节点操作系统。

这一篇在知识体系里的位置

本篇是 Jenkins 排错速查簇的执行环境入口篇，定位「没有可用执行器」：节点正常但流水线步骤报不存在看 No such DSL method 速查；装执行环境所需插件失败看 Jenkins 插件找不到/装不上速查。「节点详情页读原因 → 链路类/配置类分诊 → 修复后手动接回」这条主线对一切节点类问题通用。

一句话总结

Jenkins 节点离线先开节点详情页读 offline 原因分诊：连接异常类查链路——agent 用 systemd 托管并开机自启、全局安全配置固定 JNLP 端口且两端防火墙放行（容器部署记得透传）、节点 Java 大版本对齐控制器要求；配置类查配额——磁盘满自动摘机要清 workspace 后回节点页手动恢复上线，构建永远排队基本等于流水线 label 与节点标签对不上或执行器配成 0。agent 服务化、端口文档化、磁盘清理策略与标签规范入库，节点离线问题基本绝迹。