Jenkins基础教程（45）配置Jenkins 服务器之配置代理：Jenkins代理配置全攻略：给你的构建机器人开分身术

最新推荐文章于 2025-11-24 20:51:43 发布

原创最新推荐文章于 2025-11-24 20:51:43 发布 · 328 阅读

7 ·

CC 4.0 BY-SA版权

文章标签：

#jenkins #服务器 #运维

Jenkins基础教程专栏收录该内容

185 篇文章

订阅专栏

每次看着Jenkins服务器独自扛下所有构建任务，你是否想过给它找个帮手？没错，就是给Jenkins配置代理！

一、Jenkins代理是什么？能吃吗？

1.1 代理的基本概念

在Jenkins世界里，代理（Agent）是指被主Jenkins服务器控制的其他机器或容器，用于分担构建任务。想象一下，如果Jenkins主服务器是大脑，那么代理就是它的手脚，可以延伸到不同环境执行任务。

代理在Jenkins中又常被称为"节点"（Node）或"从机"（Slave），但它们指的是同一个概念。

1.2 为什么你需要代理？

使用代理有几个让人无法拒绝的理由：

并行构建：同时在多个节点上运行任务，大幅缩短反馈周期
环境隔离：在不同的操作系统或环境中测试代码，避免"在我机器上是好的"尴尬
资源优化：将负载分散到多台机器，防止主服务器过载
专业化处理：为特定任务（如Android构建、性能测试）配置专用节点

想想看，当你的iOS构建在Mac节点上进行，同时Android构建在Linux节点上运行，那是多么美妙的画面！

二、代理配置前的准备工作

2.1 确定你的代理需求

在开始配置前，先问自己几个问题：

我需要什么操作系统的代理？Windows、Linux还是macOS？
我的代理机器需要什么软件和工具？
代理机器与主服务器之间的网络连接情况如何？
我需要多少代理才能满足当前的构建需求？

2.2 系统要求检查

代理机器需要满足以下基本条件：

Java环境：Jenkins代理需要Java运行环境。
网络连接：代理必须能够与Jenkins主服务器通信。
磁盘空间：足够的空间来存储工作区和构建产物。
工具链：根据你的项目需要，安装相应的构建工具（如Maven、Gradle、Node.js等）。

对于Linux代理，安装Java的命令如下：

sudo apt update
sudo apt install openjdk-11-jdk -y

三、实战：配置Jenkins代理节点

接下来，让我们一步步创建一个Jenkins代理节点。我会以Linux代理为例，但原理适用于所有操作系统。

3.1 通过界面添加代理节点

第一步：进入节点管理页面

登录Jenkins管理界面，点击左侧菜单中的"管理Jenkins"，然后选择"管理节点和云"。

你会看到一个节点列表，通常只包含内置的"master"节点。

第二步：创建新节点

点击"新建节点"按钮，输入节点名称（如"linux-agent-1"），选择"永久代理"选项，然后点击"确定"。

第三步：配置节点属性

现在进入节点配置界面，需要填写几个关键信息：

名称：节点的唯一标识符
描述：可选，帮助识别节点用途
远程工作目录：代理机器上的路径，用于存储工作区和构建产物
标签：用于将任务指向特定节点的标识符
启动方式：代理如何启动和连接到主服务器

标签特别有用，例如你可以创建"android-build"、"frontend-test"等标签，然后在任务配置中指定这些标签，确保任务在正确的节点上运行。

3.2 配置代理连接方式

Jenkins支持多种代理连接方式，最常用的是SSH和JNLP。

SSH启动方式（推荐）

SSH是最简单安全的启动方式。选择"Launch agent via SSH"后，需要配置：

主机：代理机器的IP地址或主机名
端口：SSH端口，默认22
凭证：用于身份验证的SSH密钥或用户名密码
主机密钥验证策略：如何验证主机真实性

要配置SSH密钥，首先在代理机器上生成密钥对：

ssh-keygen -t rsa -b 4096 -C "jenkins-agent"

然后将公钥（~/.ssh/id_rsa.pub）内容添加到代理机器的~/.ssh/authorized_keys文件中。

JNLP启动方式

如果选择"Launch agent via Java Web Start"，Jenkins会提供一个JAR文件下载链接。你需要：

下载agent.jar文件到代理机器
运行提供的命令，包含秘密密钥和Jenkins URL

JNLP方式适用于网络限制较严格的环境。

3.3 验证代理连接

配置完成后，保存设置并返回节点列表。新节点应该会尝试连接。如果一切正常，节点状态将显示为在线（Online）。

如果连接失败，可以：

检查网络连通性
验证SSH密钥或凭证是否正确
查看Jenkins日志获取详细错误信息

四、另一种代理：为Jenkins配置网络代理

除了构建代理节点，还有一种常见需求：让Jenkins服务器本身通过代理访问外部网络。这在企业环境中很常见，主要用于解决Jenkins主节点访问外部资源（如下载插件、拉取代码）的问题。

4.1 通过系统环境变量配置

编辑Jenkins的启动脚本（通常位于/etc/init.d/jenkins或/usr/lib/systemd/system/jenkins.service），在JAVA_OPTS或JENKINS_OPTS变量后添加代理设置：

JAVA_OPTS="$JAVA_OPTS -Dhttp.proxyHost=your.proxy.host -Dhttp.proxyPort=8080 -Dhttps.proxyHost=your.proxy.host -Dhttps.proxyPort=8080"

如果需要代理认证，添加：

JAVA_OPTS="$JAVA_OPTS -Dhttp.proxyUser=yourProxyUser -Dhttp.proxyPassword=yourProxyPassword -Dhttps.proxyUser=yourProxyUser -Dhttps.proxyPassword=yourProxyPassword"

然后重启Jenkins服务：

sudo systemctl restart jenkins

4.2 通过Jenkins管理界面配置

更简单的方法是通过Jenkins的Web界面配置代理：

登录Jenkins，点击"Manage Jenkins" → "System Settings"
找到"HTTP(S) Proxy Configuration"部分
填写代理服务器信息：

- Proxy Host：代理服务器地址
- Proxy Port：代理服务器端口
- Username/Password：如果需要认证
- No Proxy Hosts：不需要代理的主机列表

点击"Save"保存配置

4.3 项目级代理配置

对于特定项目，可能需要特殊的代理设置。可以在项目配置页面的"Build Environment"部分，勾选"Use custom HTTP(S) proxy settings"并填写代理信息。

五、高级代理管理与优化

5.1 使用标签智能分配任务

标签是Jenkins中非常有用的功能，它允许你根据节点特性对节点进行分类。

例如，你可以：

给所有Windows节点添加"windows"标签
给高性能机器添加"high-memory"标签
给特定工具链的节点添加"docker"、"android-sdk"等标签

在Pipeline或任务配置中，可以使用标签指定运行节点：

pipeline {
    agent {
        label 'android-sdk && high-memory'
    }
    stages {
        // 阶段定义
    }
}

5.2 代理与流水线(Pipeline)集成

在声明式Pipeline中，可以轻松指定代理：

pipeline {
    agent none // 在阶段级别定义代理
    stages {
        stage('Build on Linux') {
            agent {
                label 'linux'
            }
            steps {
                sh 'make'
            }
        }
        stage('Test on Windows') {
            agent {
                label 'windows'
            }
            steps {
                bat 'run-tests.bat'
            }
        }
    }
}

这种配置允许你在同一个Pipeline的不同阶段使用不同的代理，充分利用各节点的特长。

5.3 代理状态监控与管理

定期检查代理状态很重要。在"Manage Nodes and Clouds"页面，可以：

查看代理的在线状态
检查代理的负载情况
临时下线节点进行维护
查看节点的构建历史

对于经常离线的代理，可以：

检查网络稳定性
验证代理机器资源是否充足
查看代理日志排查问题

六、实战示例：完整配置Linux代理节点

让我们通过一个完整示例，一步步配置一个Linux代理节点。

6.1 代理机器准备

在代理机器上执行以下命令：

# 更新系统
sudo apt update

# 安装Java
sudo apt install openjdk-11-jdk -y

# 创建Jenkins工作目录
sudo mkdir -p /var/jenkins_workspace
sudo useradd -d /var/jenkins_workspace -m jenkins
sudo chown -R jenkins:jenkins /var/jenkins_workspace

# 生成SSH密钥对（如果尚未存在）
sudo -u jenkins ssh-keygen -t rsa -f /var/jenkins_workspace/.ssh/id_rsa -q -N ""

6.2 主服务器配置

在Jenkins主服务器上：

进入"Manage Jenkins" → "Manage Nodes and Clouds"
点击"New Node"，输入名称"ubuntu-build-agent"
选择"Permanent Agent"，点击"Create"
配置节点属性：

- Remote root directory：/var/jenkins_workspace
- Labels：ubuntu linux build
- Usage：Use this node as much as possible
- Launch method：Launch agents via SSH
- Host：代理机器的IP地址
- Credentials：添加SSH凭证
- Host Key Verification Strategy：Non verifying Verification Strategy

点击"Save"

6.3 验证配置

返回节点列表，新节点应该显示为在线状态。点击节点名称，可以查看详细信息和日志。

为了测试代理节点，可以创建一个简单的Pipeline任务：

pipeline {
    agent {
        label 'ubuntu-build-agent'
    }
    stages {
        stage('Test') {
            steps {
                sh 'uname -a'
                sh 'java -version'
            }
        }
    }
}

运行这个任务，如果一切正常，它将在代理节点上执行，输出系统信息和Java版本。

七、常见问题与解决方案

7.1 代理连接问题

问题：代理节点显示离线状态

解决方案：

检查网络连通性：确保主服务器可以访问代理机器的SSH端口
验证SSH凭证：测试SSH连接是否正常工作
查看代理日志：在节点详情页面点击"Log"查看错误信息

7.2 权限问题

问题：代理无法写入工作目录

解决方案：

检查目录所有权：确保工作目录属于Jenkins用户
验证文件权限：确保Jenkins用户有读写权限

# 修复权限示例
sudo chown -R jenkins:jenkins /var/jenkins_workspace
sudo chmod -R 755 /var/jenkins_workspace

7.3 资源不足问题

问题：代理运行缓慢或构建失败

解决方案：

监控代理资源使用情况（CPU、内存、磁盘）
减少并行构建数量
增加代理机器资源或添加更多代理节点

八、最佳实践与总结

8.1 Jenkins代理最佳实践

经过多年的实践，社区总结出一些Jenkins代理最佳实践：

专机专用：为不同用途（构建、测试、部署）配置专用节点
标签规范：建立统一的标签命名规范，方便管理
版本一致：保持所有代理节点上的工具版本一致
定期维护：定期更新代理节点的系统和软件
监控告警：设置代理监控，节点离线时及时通知
安全加固：严格管理代理访问权限，定期轮换凭证

8.2 总结

配置Jenkins代理看似复杂，但一旦掌握，就能极大提升你的CI/CD流水线效率。通过将工作负载分散到多个节点，你可以：

实现更快的构建速度
提供更稳定的构建环境
支持更多样化的构建需求

记住，Jenkins代理不仅是一种技术选择，更是一种效率投资。花时间配置和维护代理节点，将在项目生命周期中带来巨大的时间回报。

现在，是时候给你亲爱的Jenkins服务器找几个得力助手，让它从繁重的工作中解放出来了！

附录：常用代理管理命令

# 在代理机器上手动启动JNLP代理
java -jar agent.jar -jnlpUrl http://JENKINS_URL/computer/NODE_NAME/slave-agent.jnlp -secret SECRET -workDir "/path/to/workdir"

# 检查代理状态
curl -s http://JENKINS_URL/computer/api/json | jq '.computer[] | .displayName + ": " + .offlineCauseReason'

# 通过CLI管理节点
java -jar jenkins-cli.jar -s http://JENKINS_URL/ list-nodes