Jenkins 从节点实战配置（一）—— 基于JAR代理的跨平台节点连接

1. Jenkins从节点配置基础入门

第一次接触Jenkins从节点配置时，我也被各种专业术语搞得一头雾水。简单来说，Jenkins从节点就是帮主节点干活的"小弟"，主节点负责调度任务，从节点负责执行任务。这种架构特别适合需要跨平台、跨设备执行构建任务的场景。

为什么要用JAR代理方式连接从节点呢？我总结了几点优势：首先，这种方式几乎可以在任何支持Java环境的设备上运行，无论是Windows服务器、Linux虚拟机还是Mac开发机；其次，JAR代理方式对网络环境要求相对宽松，特别适合企业内网中那些网络策略比较严格的场景；最后，它的配置过程简单明了，不需要复杂的SSH密钥管理。

在实际项目中，我遇到过各种从节点环境：有性能强劲的物理服务器，也有轻量级的云主机，甚至还有开发人员的本地笔记本。使用JAR代理方式，这些异构环境都能很好地接入Jenkins主控系统。记得有一次客户需要在ARM架构的开发板上执行构建任务，JAR代理方式也完美支持。

2. 全局安全配置与代理设置

2.1 开启代理功能

配置从节点的第一步，是要在主节点上开启代理功能。这个步骤看似简单，但有几个关键点需要注意。进入Jenkins管理界面后，找到"Dashboard → Configure Global Security"路径，这里就是代理功能的总开关。

在"Agents"部分，你会看到几个重要选项：

• TCP port for inbound agents：这是从节点连接主节点的端口，建议选择"Random"让系统自动分配，这样更安全
• Agent protocols：通常保持默认选择即可，除非你有特殊需求
• Enable Agent → Master Access Control：这个安全选项建议勾选，可以防止未经授权的从节点接入

我刚开始配置时犯过一个错误：直接固定使用某个端口号，结果和公司内部其他服务冲突了。后来发现选择随机端口才是最佳实践，Jenkins会自动管理端口分配，省去了很多麻烦。

2.2 防火墙与网络策略配置

在企业环境中，防火墙往往是最大的拦路虎。根据我的经验，90%的连接问题都出在网络策略上。这里有几个实用建议：

1. 确保主节点的代理端口（默认是50000）在防火墙上开放
2. 如果从节点位于不同网段，可能需要网络团队开通相关策略
3. 云环境中的安全组规则也需要相应调整

我曾经帮一个客户调试从节点连接问题，花了半天时间才发现是云平台的安全组没配置正确。所以建议在开始前就检查好网络连通性，可以用telnet命令测试端口是否可达：

telnet <主节点IP> 50000

3. 创建与配置从节点

3.1 新增节点基本信息

在Jenkins主界面点击"Manage Jenkins → Manage Nodes and Clouds → New Node"，就可以开始创建从节点了。这里有几个关键字段需要填写：

• Node name：给从节点起个有意义的名字，比如"build-win64"或"test-linux"
• Permanent Agent：选择这个类型，表示是长期运行的从节点
• Number of executors：根据从节点的CPU核心数设置，一般建议设置为核心数的1-2倍

我建议命名时遵循一定的规范，比如"环境-用途-序号"这样的格式。曾经见过一个项目有20多个从节点，命名乱七八糟，后期维护起来特别痛苦。

3.2 详细参数配置

创建节点后，还需要完善一些重要参数：

• Remote root directory：设置从节点的工作目录，确保有足够空间
• Labels：给从节点打标签，比如"linux"、"docker"等，方便任务调度
• Usage：建议选择"Only build jobs with label expressions"，这样可以精确控制任务分配
• Launch method：选择"Launch agent by connecting it to the controller"

这里有个小技巧：工作目录最好设置在快速存储设备上，比如SSD。我遇到过构建过程特别慢的情况，后来发现是因为工作目录放在了机械硬盘上。

4. JAR代理连接实战

4.1 获取连接凭证

配置好从节点信息后，Jenkins会生成连接所需的命令和凭证。在节点管理页面，点击对应节点名称进入详情页，然后找到"Launch agent"按钮，这里就包含了连接所需的所有信息。

关键信息包括：

• Jenkins主节点URL
• 从节点名称
• 加密的工作目录路径
• 认证令牌

我习惯把这些信息保存到一个文本文件中，方便后续操作。特别是在自动化部署场景下，这些凭证可以直接集成到部署脚本中。

4.2 启动代理连接

在从节点机器上，你需要先确保Java环境已经安装。然后执行从Jenkins获取的连接命令，基本格式如下：

java -jar agent.jar -jnlpUrl http://jenkins-server:8080/computer/节点名/slave-agent.jnlp -secret 加密令牌 -workDir "工作目录"

这里有几个常见问题需要注意：

1. Java版本要兼容，建议使用JDK 8或11
2. 网络要能连通Jenkins主节点
3. 工作目录要有读写权限

我在实际部署中发现，使用nohup命令可以让代理在后台稳定运行：

nohup java -jar agent.jar -jnlpUrl ... > agent.log 2>&1 &

5. 容器化环境特殊处理

5.1 Docker部署的端口映射

如果用Docker部署Jenkins，从节点连接时需要特别注意端口映射问题。启动容器时，除了映射Web界面的8080端口外，还必须映射代理端口（默认50000）：

docker run -u root --rm -d \ -p 8080:8080 \ -p 50000:50000 \ --name jenkins \ -v jenkins-data:/var/jenkins_home \ jenkins/jenkins:lts

我曾经踩过一个坑：只映射了8080端口，结果从节点死活连不上。后来才发现代理端口也需要映射出来。

5.2 容器内从节点的配置

如果从节点本身也是容器，配置方法略有不同。需要在启动从节点容器时挂载docker.sock，并确保容器内有Java环境：

docker run -d --name jenkins-agent \ -v /var/run/docker.sock:/var/run/docker.sock \ -e JENKINS_URL=http://jenkins-server:8080 \ -e JENKINS_AGENT_NAME=docker-agent \ jenkins/inbound-agent

这种配置方式特别适合需要在容器内执行构建任务的场景，比如构建Docker镜像等。

6. 连接验证与排错

6.1 验证连接状态

从节点成功连接后，在Jenkins管理界面可以看到节点状态变成绿色在线。点击节点名称可以查看详细信息，包括：

• 系统信息（操作系统、Java版本等）
• 已执行的任务统计
• 当前负载情况

我建议首次连接成功后，立即运行一个简单的测试任务，验证从节点是否真的能正常工作。有时候连接显示正常，但实际执行任务时会遇到各种权限问题。

6.2 常见问题排查

根据我的经验，从节点连接失败通常有以下几种原因：

1. 网络问题：检查防火墙、安全组、代理设置等
2. Java版本不兼容：确保使用支持的Java版本
3. 权限不足：检查工作目录的读写权限
4. 端口冲突：确认代理端口没有被其他服务占用

一个实用的排错方法是查看代理的日志输出。如果是用nohup方式启动的，日志会保存在指定的日志文件中：

tail -f agent.log

7. 生产环境优化建议

7.1 自动化部署方案

手动配置从节点虽然简单，但在大规模部署时效率太低。我推荐使用自动化工具来管理从节点生命周期，比如：

1. 用Ansible或Chef编写部署脚本
2. 将连接命令集成到系统启动脚本中
3. 使用配置管理工具维护从节点配置

我曾经为一个客户设计过全自动的从节点部署方案，新机器上线后只需要执行一个初始化脚本，就能自动完成所有配置并连接到Jenkins主节点。

7.2 监控与维护

从节点上线后，还需要建立监控机制：

1. 监控从节点的在线状态
2. 定期检查磁盘空间和内存使用情况
3. 设置自动告警，当从节点离线时及时通知

在大型Jenkins集群中，可以考虑使用Prometheus+Grafana来监控所有从节点的健康状态。我见过最夸张的情况是，一个从节点因为磁盘满了离线两周都没人发现，严重影响了构建任务。