DevOps知识中心
DevOps知识中心

诊断 Jenkins 连接问题：网络和代理问题

通过掌握关键连接故障排除步骤来恢复您的 Jenkins 环境。本指南侧重于诊断和解决与主从（Master-Agent）通信相关的问题，涵盖防火墙配置、JNLP 端口设置和 SSH 认证失败等关键网络方面。学习如何使用 `telnet` 等工具验证可达性，并了解常见的环境陷阱，以确保您的 Jenkins 代理保持在线，并使您的 CI/CD 流水线顺畅运行。

42 浏览量

诊断 Jenkins 连接问题：网络和代理问题

Jenkins 在很大程度上依赖于中央控制器（Master）与其执行环境（Agents 或 Nodes）之间的强大通信。当连接失败时，构建会停滞，管道会中断，持续集成也会停止。诊断这些问题需要系统的方法，通常首先关注网络拓扑，然后是代理配置和协议故障。

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

1. 理解 Jenkins Master-Agent 通信

在故障排除之前，必须了解 Jenkins Master（控制器）如何与其代理进行通信。Jenkins 提供两种主要方法，每种方法都有独特的诊断要求：

1.1 Java 网络启动协议 (JNLP)

在 JNLP 模型中，Jenkins 代理会发起与 Master 的连接。这是推荐且最常见的方法。代理连接到 Master 上的特定端口（JNLP 代理端口）。

  • 方向： 代理连接到 Master。
  • 所需端口： Master 的 JNLP 端口（默认通常为 50000，或动态分配）。

1.2 安全外壳 (SSH)

在 SSH 模型中，Jenkins Master 会发起与代理的连接。这要求代理机器运行 SSH 服务器。

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

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

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

2.1 验证所需端口是否已打开

您必须确保流量可以根据您的通信模型在必需的端口上流动。

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

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

从连接机器到目标机器在所需端口上使用 telnet 或 nc (Netcat)。成功连接可确认网络可达性且没有本地防火墙阻止该端口。

JNLP 可达性检查（从代理到 Master）

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

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

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

提示： “Connection Refused”（连接被拒绝）错误表示网络路径已打开，但服务（Jenkins）未在该端口上监听，或者 Master 上的 本地 防火墙正在阻止它。如果连接超时，则机器之间的防火墙很可能是罪魁祸首。

2.3 设置固定的 JNLP 端口

如果您使用 JNLP，最好配置一个固定端口以避免歧义并简化防火墙规则。默认情况下，Jenkins 可能会使用动态端口范围，这会使安全设置复杂化。

  1. 导航到 Manage Jenkins > Manage Nodes and Clouds > Configure Global Security。
  2. 在 Agents 下，找到 TCP port for inbound agents 选项。
  3. 选择 Fixed 并指定一个端口（例如 50000）。
  4. 确保 Master 机器上的主机操作系统防火墙（例如 iptables、firewalld 或 Windows 防火墙）已打开此端口。

3. 排查 JNLP 代理问题

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

3.1 检查 Master 上的代理日志

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

  • 查找常见错误，例如 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 使用正确的 Master 主机名和端口。如果 Jenkins 位于反向代理之后，请确保 Master 配置反映了外部 URL。
  • 验证 Secret Token： 如果节点重新配置，令牌可能会过期或更改。下载最新的 .jar 并使用代理启动页面上提供的最新密钥。

4. 排查 SSH 代理问题

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

4.1 在 Jenkins 外部验证 SSH 连接

尝试使用 Jenkins 中配置的完全相同的用户名和凭据，从 Master 连接到代理机器。

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 或 Path to JDK 变量指向代理机器上有效的 Java 安装目录。

5.2 工作区和用户权限

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

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

5.3 时间同步

虽然不常见，但 Master 和代理机器之间显著的时间漂移可能导致 SSL/TLS 握手失败，从而导致连接断开或被拒绝。请确保两台机器都通过网络时间协议 (NTP) 进行同步。

摘要和后续步骤

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

故障排除清单：

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

如果所有连接尝试都失败，请检查系统日志（Master 上的 /var/log/jenkins/jenkins.log）以获取更深层次的 Java 堆栈跟踪，这可能会揭示潜在的配置问题。