诊断 Jenkins 连接问题：网络与代理故障

Jenkins 高度依赖中央控制器与其执行环境（代理或节点）之间的稳定通信。当连接失败时，构建会停滞，流水线会中断，持续集成也会陷入停顿。诊断这些问题需要系统化的方法，通常首先关注网络拓扑，然后检查代理配置和协议故障。

本综合指南提供了逐步说明，帮助您排查最常见的 Jenkins 连接问题，包括难以捉摸的防火墙问题、配置错误的 JNLP 端口以及代理启动失败，从而帮助您快速恢复稳定运行和可靠的 CI/CD 流水线。

---

1. 理解 Jenkins 控制器与代理的通信

在开始排查之前，了解 Jenkins 控制器如何与代理通信至关重要。Jenkins 提供两种主要方法，每种方法都有独特的诊断要求：

1.1 Java 网络启动协议 (JNLP)

在 JNLP 模型中，Jenkins 代理主动连接到控制器。这是推荐且最常用的方法。代理连接到控制器上的特定端口，现在通常称为入站代理 TCP 端口。

• 方向： 代理连接到控制器。
• 所需端口： 控制器的入站代理 TCP 端口（默认通常为 50000，或动态分配）。

1.2 安全外壳 (SSH)

在 SSH 模型中，Jenkins 控制器主动连接到代理。这要求代理机器上运行 SSH 服务器。

• 方向： 控制器连接到代理。
• 所需端口： 代理的 SSH 端口（通常为 22）。
• 要求： 必须在 Jenkins 中正确配置 SSH 凭据（密钥或密码）。

2. 初始网络与防火墙诊断

网络问题，尤其是防火墙限制，是导致连接问题的最常见原因。如果代理突然离线或新代理无法连接，请从这里开始排查。

2.1 验证所需端口是否开放

您必须确保根据通信模型，必要的端口上能够正常传输流量。

连接类型	源	目标	所需端口	状态检查
Web 界面	用户/代理	控制器	8080（或自定义）	浏览器访问
入站代理	代理	控制器	50000（或自定义）	telnet 或 nc
SSH（控制器 -> 代理）	控制器	代理	22（或自定义）	ssh 或 telnet

2.2 使用 Telnet/Netcat 进行可达性测试

从连接机器使用 telnet 或 nc（Netcat）连接到目标机器的所需端口。成功连接确认网络可达，且本地防火墙未阻止该端口。

入站代理可达性检查（从代理到控制器）

# 替换 <CONTROLLER_IP> 和 <JNLP_PORT>
telnet <CONTROLLER_IP> 50000

# 预期成功输出：
# Connected to <CONTROLLER_IP>.
# Escape character is '^]'.

# 预期失败输出：
# Trying <CONTROLLER_IP>...
# telnet: connect to address <CONTROLLER_IP>: Connection refused

提示： “连接被拒绝”错误表示网络路径是开放的，但服务（Jenkins）未在该端口上监听，或者控制器上的本地防火墙阻止了连接。如果连接超时，则很可能是机器之间的防火墙导致的问题。

2.3 设置固定 JNLP 端口

如果使用 JNLP，最佳实践是配置固定端口，以避免歧义并简化防火墙规则。除非您设置固定端口，否则 Jenkins 可能会使用随机入站代理端口，这会使安全设置复杂化。

1. 导航至 管理 Jenkins > 安全（或在旧版 Jenkins 中为 配置全局安全）。
2. 在 代理 下，找到 入站代理的 TCP 端口 选项。
3. 选择 固定 并指定端口（例如 50000）。
4. 确保在控制器机器的操作系统防火墙（例如 iptables、firewalld 或 Windows 防火墙）中开放此端口。

3. 排查 JNLP 代理问题

如果网络检查通过，问题通常与身份验证、配置或环境不匹配有关。

3.1 在控制器上检查代理日志

尝试启动 JNLP 代理时，请查看 Jenkins 自身提供的日志。导航到特定代理配置页面，查看 日志 部分。这通常会提供最清晰的错误信息。

• 查找常见错误，如 java.net.ConnectException 或 hudson.remoting.ChannelClosedException。

3.2 确保代理参数正确

使用 Jenkins 提供的命令（java -jar agent.jar ... 命令）手动启动代理时，请确保参数正确。

# JNLP 启动的示例命令结构
java -jar agent.jar -jnlpUrl http://<JENKINS_URL>/computer/<AGENT_NAME>/slave-agent.jnlp -secret <SECRET_TOKEN> -workDir "/path/to/workspace"

• 验证 JNLP URL： 确保 URL 使用正确的控制器主机名和端口。如果 Jenkins 位于反向代理之后，请确保 Jenkins URL 配置反映了外部 URL。
• 验证密钥令牌： 如果节点被重新配置，令牌可能会过期或更改。下载最新的 .jar 文件，并使用代理启动页面上提供的最新密钥。

4. 排查 SSH 代理问题

如果使用 SSH 启动代理，连接失败通常源于身份验证或 Shell 环境问题。

4.1 在 Jenkins 外部验证 SSH 连接

尝试使用 Jenkins 中配置的确切用户名和凭据，从控制器连接到代理机器。

ssh -i /path/to/keyfile jenkins_user@<AGENT_IP>

• 如果失败，则是环境问题：SSH 服务已关闭、用户凭据/密钥错误，或密钥权限过于宽松（chmod 600 keyfile.pem）。

4.2 检查 SSH 身份验证方法

1. 密钥： 确保与 Jenkins 凭据管理器中存储的私钥对应的公钥已正确添加到代理用户的 ~/.ssh/authorized_keys 文件中。
2. 密码： 如果使用密码，请确保代理上的 SSH 服务器配置为允许密码身份验证（出于安全考虑，不推荐）。

4.3 SSH 代理启动超时

如果 SSH 连接成功但代理启动失败，Jenkins 可能在尝试执行初始化脚本时超时。在代理配置页面中增加 SSH 连接超时设置。

5. 常见代理环境故障

一旦网络连接建立，如果代理的操作环境不正确，代理仍可能失败。

5.1 Java 环境（至关重要）

Jenkins 代理需要兼容的 Java 运行时环境（JRE/JDK）才能执行 agent.jar 文件。

• 验证 Java 是否存在： 在代理机器上运行 java -version。
• 验证 JAVA_HOME： 确保 Jenkins 代理配置中的 JAVA_HOME 或 JDK 路径 变量指向代理机器上有效的 Java 安装目录。

5.2 工作区和用户权限

Jenkins 用于运行代理的用户账户（通过 SSH 登录或系统服务）必须对定义的远程根目录（工作区）具有读写权限。

• 操作： 验证远程根目录（例如 /home/jenkins/workspace）的所有权和权限。

5.3 时间同步

虽然不常见，但控制器和代理机器之间的显著时间偏差可能导致 SSL/TLS 握手失败，从而导致连接断开或拒绝。确保两台机器通过网络时间协议（NTP）同步。

总结与检查清单

排查 Jenkins 连接问题是一个逐步排除的过程，从网络边界向内进行。通过系统检查防火墙、使用 telnet 等工具验证端口可达性，并确认通信协议（JNLP 或 SSH）已正确认证和配置，您可以快速定位并解决连接问题。

排查检查清单：

1. 网络防火墙： 是否允许流量在所需端口（JNLP 为 50000+，SSH 为 22）上双向通行？
2. 本地防火墙： 控制器/代理上的操作系统防火墙（Windows/Linux）是否阻止了端口？
3. 协议测试： 从连接机器到目标机器的相关端口上，telnet 是否成功？
4. Java： 代理上是否安装了兼容的 Java 版本，并且路径是否正确？
5. 身份验证： SSH 密钥/密码是否有效，或者 JNLP 密钥令牌是否最新？

如果所有连接尝试均失败，请检查 Jenkins 控制器日志（通常可从服务日志或 /var/log/jenkins/jenkins.log 获取），查找远程处理和 Java 堆栈跟踪信息。