使用 Jenkins 构建代理-未完纪

Jenkins 架构面向分布式构建，可为不同项目使用不同环境，并让多个代理并行运行作业，平衡负载。

控制器是 Jenkins 安装中的原始节点，负责管理代理、编排工作、调度与监控作业。代理可以运行在本地或云计算机，通过网络连接控制器，并需要安装 Java。

三分钟简介视频：什么是 Jenkins Agent。

代理概念

代理提供 executor，按控制器请求执行工作，包括 Pipeline 步骤、自由风格作业等。

通常用标签描述代理能力。例如 Arm64 机器可标记 aarch64，让作业只在该架构上运行；安装了代码签名应用的代理可标记 code-signing，供需要签名的作业使用。

代理既可允许运行任意作业，也可限制只执行明确分配给它的作业。

executor 数量

数量决定代理能并发执行多少任务。控制器建议设为 0，避免资源竞争，执行工作交给代理节点。

这样控制器专注管理构建和协调代理，提高稳定性与性能。具有特定能力的代理可配置多个 executor，以高效处理并发构建。

使用方式

“Use this node as much as possible”：尽可能把作业分配给该节点。
“Only build jobs with label expressions matching this node”：只执行标签表达式匹配的作业。

使用 Docker 配置代理

代理可运行于物理机、虚拟机、Kubernetes 或 Docker。本节通过 SSH 将 Docker 代理连接到 Jenkins。

环境

需要一台安装了 Java、Jenkins、Docker，并准备好 SSH 密钥对的机器。安装帮助见 Jenkins 安装文档。

生成 SSH 密钥对

在可访问的机器运行 ssh-keygen。可以是控制器机器、容器宿主机、现有代理机器，或开发机。

Windows 可使用 Windows OpenSSH、Git for Windows 自带版本或 Cygwin；Linux、macOS、BSD 等可使用系统提供的 OpenSSH。之后需要把密钥内容复制到控制器和代理，因此先确保能复制文件内容。

终端执行 ssh-keygen -f ~/.ssh/jenkins_agent_key，输入口令，可以为空。输出应类似：

ubuntu@desktop:~$ ssh-keygen -f ~/.ssh/jenkins_agent_key
Generating public/private rsa key pair.
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in /home/ubuntu/.ssh/jenkins_agent_key
Your public key has been saved in /home/ubuntu/.ssh/jenkins_agent_key.pub
The key fingerprint is:
SHA256:XqxxjqsLlvDD0ZHm9Y2iR7zC6IbsUlMEHo3ffy8TzGs
The key's randomart image is:
+---[RSA 3072]----+
|  o+             |
| ...o  .         |
|  .o .+ .        |
|    o+.+ o o     |
|  ... o.So* .    |
|  o+ = +.X=      |
| o oO + *..+     |
|. oo.o o .E .    |
| o... oo.. o     |
+----[SHA256]-----+

创建 Jenkins SSH 凭据

从仪表盘进入 Manage Jenkins。
在 Security 下选择 Credentials。

在 Stores scoped to Jenkins 的 global 项选择 Add Credentials。

按实际情况填写：Kind 为 SSH username with private key；ID 为 jenkins；Description 为 The Jenkins SSH key；Username 为 jenkins。
Private Key 选择 Enter directly，再点击 Add，填入私钥文件 ~/.ssh/jenkins_agent_key 的内容。
Passphrase 输入生成密钥时使用的口令；未设口令则留空。
点击 Create。

创建 Docker 代理

Linux

使用 docker-ssh-agent 镜像启动第一个代理：

docker run -d --rm --name=agent1 -p 22:22 \
-e "JENKINS_AGENT_SSH_PUBKEY=<your_public_key>" \
jenkins/ssh-agent:alpine-jdk21

将 <your_public_key> 替换为自己的公钥。可在生成密钥的机器运行 cat ~/.ssh/jenkins_agent_key.pub 获取。不要给值加方括号，必须包含 .pub 文件完整内容，包括 ssh-XXXX 前缀。

原文示例公钥：

ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAAQQCo9+BpMRYQ/dL3DS2CyJxRF+j6ctbT3/Qp84+KeFhnii7NT7fELilKUSnxS30WAvQCCo2yU1orfgqr41mM70MB

如果主机已有 SSH 服务占用 22 端口，例如你正通过 SSH 登录该机，请使用其他映射端口，如 -p 4444:22。

现在 agent1 容器已经启动，可用 docker ps 查看。

Windows

同样使用 docker-ssh-agent 镜像：

docker run -d --rm --name=agent1 --network jenkins -p 22:22 `
  -e "JENKINS_AGENT_SSH_PUBKEY=<your_public_key>" `
  jenkins/ssh-agent:jdk21

替换自己的公钥，可通过 Get-Content $Env:USERPROFILE\.ssh\jenkins_agent_key.pub 查看。

使用 docker ps 确认容器。还可运行 docker container inspect agent1 | Select-String -Pattern '"IPAddress": "\d+\.\d+\.\d+\.\d+"'，查看 Jenkins 中应填写的 Host。

在 Jenkins 配置 agent1

进入 Manage Jenkins。
选择 Nodes。

点击 New Node，输入节点名称，选择 Permanent Agent，再点击 Create。
填写 Remote root directory、Labels、Usage、Launch method、Host、Credentials 和 Host Key verification Strategy。