WinSW部署的Jenkins Agent连接中断且无法自动重启故障咨询

DevOps 小满

2026-9-1

问题根因

你看到的java.nio.channels.ClosedChannelException是Jenkins Agent WebSocket长连接被异常断开的典型报错，常见触发原因包括网络闪断、防火墙/上网行为管理的空闲连接回收、Jenkins控制器侧超时回收会话、Windows网络栈临时重置。这类异常属于Agent进程内部的业务连接故障，不会触发Windows服务层的失败判定。
Windows服务（包括你通过WinSW注册的服务）自带的"失败后自动重启"策略，仅在服务进程本身异常退出（比如进程崩溃、返回非0退出码、被系统强制终止）时才会触发。本次故障发生时，Agent的java进程并没有退出，只是内部的WebSocket连接挂死，服务状态始终显示为"运行中"，因此你配置的重启策略根本不会被触发。
默认的WinSW配置仅检测进程是否存在，不会校验业务连通性，只要java.exe进程还在运行，WinSW就会判定服务状态正常，不会主动执行重启动作。

修复方案

第一步：更新WinSW服务配置，开启主动健康检测。打开WinSW同名的xml配置文件，在<service>根节点下添加如下配置，让WinSW定期检测服务运行状态，发现异常主动终止进程触发重启：

<!-- 开启服务健康检测 -->
<healthcheck>
    <!-- 每5秒检测一次服务状态 -->
    <interval>5000</interval>
    <!-- 检测到异常时直接重启服务 -->
    <action>restart</action>
    <!-- 给进程留10秒优雅退出窗口，超时强制终止 -->
    <gracePeriod>10000</gracePeriod>
</healthcheck>
<!-- 优先终止父进程，避免子进程残留导致服务启动失败 -->
<stopparentprocessfirst>true</stopparentprocessfirst>

第二步：调整Agent启动参数，开启进程内自动重连。先把agent.jar替换为和当前Jenkins控制器版本完全匹配的版本，修改启动命令添加重连参数，参考如下：

java -jar agent.jar -url http://你的Jenkins服务地址/ -secret 对应节点的连接密钥 -name 节点名称 -webSocket -workDir "D:\jenkins-agent-workspace" -reconnect 10

其中-reconnect 10表示连接断开后每10秒尝试重连一次，偶发网络闪断时可以直接在进程内恢复连接，不需要触发服务重启。注意：该参数仅支持Jenkins 2.307及以上版本。

第三步：补全Windows服务恢复规则。打开服务管理器，找到对应的Jenkins Agent服务，在"恢复"标签页做如下调整：
- 第一次失败：重新启动服务
- 第二次失败：重新启动服务
- 后续失败：重新启动服务
- 重置失败计数时间：86400（即24小时后重置失败计数，避免多次故障后不再触发重启）
- 重启服务等待时间：5000（即5秒后执行重启）
第四步：优化Windows TCP配置，减少长连接被异常掐断的概率。打开注册表编辑器，定位到HKLM\SYSTEM\CurrentControlSet\Services\Tcpip\Parameters路径，新建两个DWORD类型值：
- TcpMaxDataRetransmissions，数值设为5
- KeepAliveTime，数值设为300000（即5分钟发送一次TCP保活探测包，避免中间网络设备因为连接空闲超时切断会话）
  修改完成后重启机器生效。

验证方法

所有配置修改完成后重启Jenkins Agent服务，手动断开机器网络10秒后恢复，观察Agent是否能自动重新连接到Jenkins控制器；
手动结束运行Agent的java.exe进程，观察服务是否能在5秒内自动重启拉起Agent；
查看服务恢复配置页，确认所有失败场景的动作均为重启，无配置遗漏。

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