精通 DevOps 工具与最佳实践 - DevOps 知识中心 精通 DevOps 工具与最佳实践 - DevOps 知识中心

排查 Jenkins 代理常见连接问题及解决方案

遇到 Jenkins 代理显示“离线”或“连接被拒绝”的问题？本综合指南提供了常见连接问题的逐步解决方案。学习排查网络、防火墙、JNLP、SSH 和代理配置问题，确保您的 Jenkins 构建执行器始终可用并高效运行。包含实用技巧和日志分析，帮助您更快解决问题。

排查 Jenkins 代理常见连接问题及解决方案

Jenkins 代理（也称为节点）是大多数构建工作实际运行的地方。当某个代理离线时，症状很明显：任务在队列中等待，标签无法满足，团队开始重新运行那些从未启动的构建。有用的工作是找出哪个层面出了问题：网络可达性、SSH、入站远程连接、Java、凭据、磁盘，还是控制器本身。

理解代理为何可能变得不可达是有效排查的第一步。这些问题可能源于网络配置错误、代理设置不正确、防火墙限制，或者 Jenkins 控制器本身的问题。通过系统地检查这些方面，您可以快速找到根本原因并实施解决方案。

Jenkins 代理断开的常见原因

多种因素可能导致代理离线。识别具体症状是缩小潜在原因范围的关键：

  • 代理不可达： Jenkins 控制器无法与代理建立连接。
  • 连接被拒绝： 代理机器主动拒绝了控制器的连接尝试。
  • 代理在成功连接后报告离线： 代理已连接但随后断开了连接。
  • JSch 错误（针对基于 SSH 的代理）： 与用于 SSH 连接的 Java 安全通道库相关的特定错误。

网络和防火墙问题

网络连接性是代理连接问题最常见的罪魁祸首。确保 Jenkins 控制器能够访问代理机器，反之亦然，至关重要。

验证网络可达性

在深入 Jenkins 特定配置之前，先确认基本的网络连接：

  1. Ping 代理： 从 Jenkins 控制器机器上，尝试 ping 代理机器的 IP 地址或主机名。
    ping <agent-hostname-or-ip>
  2. Telnet 到代理端口： 测试 Jenkins 用于连接代理的端口是否打开并处于监听状态。对于 JNLP 代理，通常是端口 50000。对于 SSH 代理，是 SSH 端口（默认 22）。
    telnet <agent-hostname-or-ip> <agent-port>
    如果连接超时或被拒绝，则很可能是网络或防火墙问题阻止了该端口。

防火墙配置

Jenkins 控制器、代理机器或中间网络设备上的防火墙都可能阻止必要的端口。

  • Jenkins 控制器防火墙： 确保控制器可以发起连接到代理的端口。
  • 代理机器防火墙： 确保代理机器的防火墙（例如 ufw、firewalld、Windows 防火墙）允许来自 Jenkins 控制器 IP 地址的入站连接到代理端口。
  • 网络防火墙： 如果您的网络有内部防火墙，请验证控制器和代理之间的流量是否被允许。

示例：在代理上允许端口 50000（使用 ufw 的 Linux）

# 允许来自特定 IP（Jenkins 控制器）的连接
sudo ufw allow from <jenkins-controller-ip> to any port 50000

# 或者允许来自任何 IP 的连接（安全性较低）
sudo ufw allow 50000

# 重新加载防火墙规则
sudo ufw reload

示例：在代理上允许端口 22（使用 firewalld 的 Linux）

# 永久允许来自特定源 IP 的 SSH 服务
sudo firewall-cmd --permanent --zone=public --add-rich-rule='rule family="ipv4" source address="<jenkins-controller-ip>" port protocol="tcp" port="22" accept'

# 重新加载防火墙规则
sudo firewall-cmd --reload

提示： 为了更好的安全性，始终优先允许来自特定 IP 地址的连接。

Jenkins 代理配置问题

Jenkins 内部或代理本身的错误配置是连接问题的常见来源。

JNLP 代理配置

Java 网络启动协议（JNLP）代理使用专用端口与 Jenkins 控制器通信。主要配置涉及代理的启动方法和控制器的可用端口。

代理在 Jenkins UI 中显示离线

如果代理在 Jenkins UI 中显示离线，意味着控制器无法建立或维持连接。

  1. 检查代理启动方法： 确保代理配置为正确启动。常见方法包括：
    • 通过连接主节点启动代理： 这需要从代理端手动启动。
    • 通过 SSH 启动代理： 通过 SSH 凭据和主机设置进行配置。
    • 使用内置节点属性启动代理： 针对特定场景。
  2. 验证 JNLP 端口可用性： Jenkins 控制器需要在配置的 JNLP 端口（默认 50000）上监听。导航到 Manage Jenkins -> System -> Advanced -> File -> TCP port for JNLP agents 并确保其已设置且可访问。

启动 JNLP 代理时出现“连接被拒绝”

这通常意味着 Jenkins 控制器上的 JNLP 端口（默认 50000）未打开或无法从代理机器访问。验证控制器上的防火墙规则，并确保端口配置正确。

提示： 重新启动 Jenkins 控制器有时可以解决临时的 JNLP 端口问题。

SSH 代理配置

当使用 SSH 连接到代理时，多个因素可能导致问题：

  1. SSH 凭据错误： 验证 Jenkins 中为 SSH 连接配置的用户名、密码或私钥。确保私钥格式正确（例如 PEM 格式）并具有正确的权限。
  2. 代理上 SSH 服务器未运行： 确保 SSH 守护进程（sshd）在代理机器上运行。
    # 在代理机器上
sudo systemctl status sshd
# 或者
sudo service ssh status
    如果未运行，请启动它：
    sudo systemctl start sshd
sudo systemctl enable sshd
  3. SSH 端口不匹配： 确保 Jenkins 中配置的 SSH 端口与 SSH 服务器监听的端口（默认 22）匹配。
  4. 代理主机名/IP 解析： Jenkins 控制器必须能够解析代理的主机名或 IP 地址。
  5. SSH 密钥权限： 在代理机器上，Jenkins 连接用户的 ~/.ssh/authorized_keys 文件必须具有正确的权限（通常为 600）。

示例：手动测试 SSH 连接

从 Jenkins 控制器机器，尝试使用与 Jenkins 中配置相同的凭据和端口 SSH 到代理：

ssh -p <ssh-port> <jenkins-user>@<agent-hostname-or-ip>

如果此手动 SSH 命令失败，则问题出在 Jenkins 的 SSH 配置之外，很可能是代理上的网络、防火墙或 SSH 服务器设置。

代理工作目录权限

Jenkins 需要特定权限才能在代理的文件系统上运行。Jenkins 用于连接代理的用户（或运行代理进程的用户）需要对代理配置的工作目录具有写权限。

  • 验证所有者和权限： 在代理上，检查 Jenkins 主目录及其子目录的所有权和权限。
    ls -ld /path/to/jenkins/agent/home
ls -l /path/to/jenkins/agent/home
  • 授予权限（如有必要）： 确保 Jenkins 连接的用户具有读写访问权限。谨慎使用 chown 和 chmod。

Jenkins 控制器问题

有时，问题可能不在于代理，而在于 Jenkins 控制器本身。

控制器过载

如果 Jenkins 控制器负载过重（运行许多任务，CPU/内存使用率高），它可能难以管理代理连接。监控控制器的资源利用率。

JNLP 端口冲突

如果 JNLP 端口（默认 50000）已被 Jenkins 控制器上的另一个进程使用，代理将无法连接。

  • 检查端口使用情况： 在控制器机器上，使用 netstat 或 ss 查看哪个进程正在使用该端口。
    sudo netstat -tulnp | grep 50000
# 或者
sudo ss -tulnp | grep 50000
    如果另一个进程正在使用它，您需要重新配置 Jenkins 或其他应用程序以使用不同的端口。

高级排查和日志

当标准检查无法揭示问题时，需要进行更深入的调查。

Jenkins 控制器日志

查看 Jenkins 控制器日志中与代理连接相关的错误。这些日志可以提供特定的错误消息。

  • 位置： 通常位于 $JENKINS_HOME/jenkins.log，或通过 Manage Jenkins -> System Log 访问。
  • 查找： 提及代理主机名、IP 地址、连接尝试、JSch 异常或“连接被拒绝”错误的消息。

代理日志

如果代理正在运行但报告离线，请检查其日志以查找任何错误。

  • JNLP 代理： 代理进程本身可能会将日志输出到其控制台或指定的日志文件。
  • SSH 代理： 日志可能位于代理机器上的 $JENKINS_HOME/agent.log，或者如果连接在 SSH 级别失败，则与 sshd 相关。

启用调试日志

对于非常持久的问题，临时启用相关 Jenkins 组件的调试日志可以提供更详细的信息。

  • JNLP/代理通信： 您可能需要调整 Java 系统属性或使用 Jenkins 的日志配置（Manage Jenkins -> System Log -> Log Recorders）来增加 hudson.slaves 或相关包的详细程度。

防止重复中断的实用习惯

排查 Jenkins 代理连接问题需要系统的方法，从基本的网络检查开始，逐步深入到 Jenkins 特定配置。

  • 验证网络： 始终从 ping 和 telnet/nc 开始，确保基本的网络可达性和端口访问。
  • 检查防火墙： 确保控制器和代理上的防火墙以及任何网络防火墙都允许所需端口上的流量。
  • 验证凭据： 仔细检查 SSH 密钥、用户名和密码。
  • 确认代理服务： 对于 SSH 代理，确保 sshd 正在运行且可访问。
  • 监控 Jenkins 日志： 控制器日志是了解连接失败的主要来源。
  • 使用特定 IP： 在可能的情况下，配置防火墙和 Jenkins 使用特定的 IP 地址，而不是广泛的地址范围或 0.0.0.0。

通过遵循这些步骤，您可以有效地诊断和解决大多数常见的 Jenkins 代理连接问题，使您的 CI/CD 管道平稳运行。

无需猜测即可解读离线消息

“离线”这个词太宽泛，无法单独排查。在更改 Jenkins 设置之前，打开代理页面并阅读 Jenkins 给出的确切原因。“连接被拒绝”、“权限被拒绝”、“主机密钥验证失败”、“JNLP 代理被拒绝”和“通道已关闭”之间存在很大差异。它们都以离线节点结束，但指向不同的层面。

我通常用通俗的语言写下症状：“控制器无法到达 TCP 端口 22”、“SSH 登录成功但 Java 无法启动”、“入站代理启动但无法回调控制器”或“代理连接后在构建期间断开”。这一句话让调查保持专注。

如果代理从未连接过，怀疑配置、DNS、防火墙、凭据或启动命令。如果它连续连接了几个月，今天开始失败，检查最近的更改：轮换的 SSH 密钥、Jenkins 升级、插件更新、新的防火墙规则、过期的证书、代理镜像重建或云网络更改。时间线通常比错误文本更有用。

SSH 代理：将登录问题与启动问题分开

对于基于 SSH 的代理，测试 Jenkins 使用的相同路径。从控制器主机，以 Jenkins 配置的用户身份连接：

ssh -vvv jenkins-agent-user@agent-hostname

详细输出会告诉您故障发生在身份验证之前、身份验证期间还是登录之后。如果 SSH 从未到达服务器，Jenkins 无法解决这个问题。检查路由、安全组、网络 ACL、主机防火墙和 SSH 守护进程。如果 SSH 到达服务器但拒绝了密钥，请检查 Jenkins 中的凭据、用户的 authorized_keys、文件权限以及帐户是否被锁定。

如果手动 SSH 登录成功但 Jenkins 仍然失败，请查看远程根目录和 Java 启动。Jenkins 需要一个可写目录来存放远程文件，并且代理用户需要具有在该目录中创建文件的权限。一个常见的错误是将远程根目录指向由 root 拥有或被其他进程清理的路径。

在代理上运行这些检查：

whoami
pwd
java -version
test -w /path/to/jenkins-agent && echo writable
df -h /path/to/jenkins-agent

Java 版本很重要，因为现代 Jenkins 控制器需要代理上兼容的 Java 版本。具体要求取决于您的 Jenkins 版本，因此请查看您版本的 Jenkins 文档，而不是假设旧的代理镜像仍然有效。

入站代理：回调路径是常见的陷阱

当控制器无法向代理发起 SSH 时，通常使用入站代理，例如位于 NAT 后面或受限网络中的代理。代理进程在 Jenkins 外部启动并连接回控制器。这意味着网络路径是反向的：代理必须解析并到达 Jenkins URL。

在代理主机上，测试 Jenkins URL 完全按照配置的方式：

curl -I https://jenkins.example.com/

如果 Jenkins 位于反向代理后面，请确认 Manage Jenkins > System 中的公共 URL 正确。错误的 Jenkins URL 可能导致生成的代理命令指向代理无法解析的内部主机名。如果为入站代理启用了 WebSocket 模式，请确保代理支持 WebSocket 升级标头。如果您改用 TCP 入站代理端口，请确认固定端口已配置并且可从代理网络访问。

TLS 问题可能看起来像 Jenkins 问题。如果代理在最小的容器镜像中运行，它可能没有您的内部 CA 证书。curl 通常会很快暴露这一点。将 CA 证书安装到代理镜像中，而不是禁用证书验证。

在构建期间断开的代理

成功连接然后在构建期间断开的代理通常不是基本的连接问题。查看资源压力和进程生命周期。

检查操作系统是否杀死了代理进程：

dmesg -T | grep -i -E 'killed process|out of memory'
journalctl -u jenkins-agent --since '2 hours ago'

还要检查磁盘空间。Jenkins 远程连接、检出、测试报告和归档工件都需要空间。完整的工作区卷可能使代理看起来不可靠，因为远程进程无法写入临时文件或日志。

如果断开发生在大量控制台输出、工件归档或测试报告发布期间，请查看网络稳定性和控制器负载。代理通道是一个实时连接。控制器上的长时间垃圾回收暂停、过载的代理、空闲连接超时和数据包丢失都可能关闭它。对于跨越负载均衡器或公司代理的代理，请验证空闲超时设置和保活行为。

DNS 和主机密钥问题

DNS 更改很容易被忽略。Jenkins 可能连接到 build-agent-01，而您的手动测试使用 IP 地址。从控制器测试主机名：

getent hosts build-agent-01
nc -vz build-agent-01 22

如果主机名解析到错误的地址，请修复 DNS 或代理配置。避免长期的 /etc/hosts 补丁，除非您有明确的所有权流程，因为它们会成为不可见的基础设施。

对于 SSH 代理，主机密钥验证可保护 Jenkins 免于连接到意外的机器。如果代理被重建，其主机密钥可能已更改。不要盲目禁用验证。确认重建，从控制器用户的 known_hosts 中删除旧密钥，并通过配置的 Jenkins 策略接受新密钥。

生产代理的恢复清单

当多个代理同时离线时，避免在找到共同原因之前逐一修复它们。询问：

  1. Jenkins 控制器是否重启或升级？
  2. 共享凭据是否轮换？
  3. 基础代理镜像是否更改？
  4. 防火墙、代理、VPN 或 DNS 更改是否已推出？
  5. 所有失败的代理是否位于同一子网、云账户、Kubernetes 命名空间或可用区？

如果只有一个代理失败，检查该主机。如果整个组一起失败，检查共同的依赖项。这在较大的 Jenkins 集群中可以节省大量时间。