Jenkins Infra 一体化代理镜像 (All-in-one Agent Image)

镜像概述和主要用途

Jenkins Infra 一体化代理镜像是 Jenkins 基础设施（Jenkins Infra）的官方代理镜像，旨在简化 Jenkins 环境中代理节点的配置与管理。作为“一体化”（All-in-one）镜像，它集成了 Jenkins 代理运行所需的常用工具、依赖库及协议支持，可直接作为 Jenkins 控制器的代理节点，用于执行 CI/CD 任务、构建流程及自动化操作，减少用户手动配置代理环境的复杂度。

核心功能和特性

1. 预集成常用工具链

• 内置 Java 运行时环境（支持 Jenkins 所需的 Java 版本）
• 包含版本控制工具（Git、Subversion）
• 集成构建工具（Maven、Gradle、npm、yarn）
• 支持容器化操作（Docker CLI、Podman）
• 预装系统工具（curl、wget、jq、sudo 等）

2. 多协议支持

• 兼容 Jenkins 主流代理协议：JNLP（Java Network Launch Protocol）、SSH 协议
• 支持 Jenkins 控制器与代理节点的双向通信加密

3. 与 Jenkins Infra 深度兼容

• 针对 Jenkins 官方基础设施组件（如 Jenkins 控制器、配置中心、监控工具）优化
• 符合 Jenkins Infra 安全规范和最佳实践

4. 轻量级与可扩展性

• 基于精简基础镜像（如 Alpine Linux），减少资源占用
• 支持通过环境变量、挂载配置文件或构建参数自定义工具版本及代理行为

5. 标准化部署

• 提供统一的代理节点环境，避免因工具版本差异导致的构建不一致问题
• 支持大规模 Jenkins 集群中的代理节点批量部署

使用场景和适用范围

1. Jenkins 控制器的代理节点

作为 Jenkins 控制器的工作节点，执行 CI/CD 流水线任务（代码拉取、构建、测试、部署等）。

2. 开发/测试环境的快速验证

在本地或测试环境中快速启动 Jenkins 代理，验证流水线配置或工具兼容性。

3. 复杂构建流程的执行

适用于需要多种工具协同的构建任务（如 Java 项目编译 + Docker 镜像打包 + 推送仓库）。

4. Jenkins Infra 标准化部署

在 Jenkins 官方基础设施或企业级 Jenkins 集群中，作为标准化代理节点使用，确保环境一致性。

5. 临时任务节点

用于临时执行一次性任务（如数据备份、日志收集、批量脚本运行），任务结束后销毁节点。

详细使用方法和配置说明

前提条件

• 已安装 Docker 环境（20.10+ 版本）
• 可访问 Jenkins 控制器（需获取代理连接所需的 URL、密钥等信息）

1. 获取镜像

从 Docker Hub 或 Jenkins Infra 镜像仓库拉取最新版本：

docker pull jenkins-infra/all-in-one-agent:latest

如需指定版本，可替换 latest 为具体版本号（如 v1.2.3）。

2. 通过 docker run 运行代理节点

2.1 JNLP 协议连接（推荐）

通过 JNLP 协议连接 Jenkins 控制器（需提前在 Jenkins 控制器中创建代理节点并获取连接参数）：

docker run -d \
  --name jenkins-agent \
  -e JENKINS_URL="[***]" \  # Jenkins 控制器 URL
  -e AGENT_NAME="my-agent" \                          # 代理节点名称（需与 Jenkins 控制器中配置一致）
  -e AGENT_SECRET="agent-secret-from-jenkins" \       # 代理连接密钥（从 Jenkins 控制器获取）
  -e PROTOCOL="jnlp" \                                # 连接协议（jnlp/ssh，默认 jnlp）
  -v /var/run/docker.sock:/var/run/docker.sock \       # 如需使用 Docker 命令，挂载 Docker 套接字（可选）
  jenkins-infra/all-in-one-agent:latest

2.2 SSH 协议连接

通过 SSH 协议连接 Jenkins 控制器（需在 Jenkins 控制器中配置 SSH 凭证）：

docker run -d \
  --name jenkins-agent-ssh \
  -e JENKINS_URL="[***]" \
  -e AGENT_NAME="ssh-agent" \
  -e PROTOCOL="ssh" \
  -e SSH_USER="jenkins" \                             # SSH 用户名（需与 Jenkins 控制器中配置一致）
  -e SSH_PUB_KEY="ssh-rsa AAAAB3NzaC1yc2EAAA..." \    # SSH 公钥（用于 Jenkins 控制器认证）
  -p 2222:22 \                                        # 映射 SSH 端口（宿主机端口:容器端口）
  jenkins-infra/all-in-one-agent:latest

3. 通过 docker-compose 配置

创建 docker-compose.yml 文件，定义代理节点服务：

version: "3.8"
services:
  jenkins-agent:
    image: jenkins-infra/all-in-one-agent:latest
    container_name: jenkins-agent
    environment:
      - JENKINS_URL=[***]  # Jenkins 控制器 URL
      - AGENT_NAME=compose-agent                    # 代理节点名称
      - AGENT_SECRET=agent-secret-from-jenkins      # 代理连接密钥
      - PROTOCOL=jnlp                               # 连接协议
      - TOOLS_PATH=/opt/tools                       # 工具安装路径（可选，默认 /usr/local/bin）
    volumes:
      - agent-workdir:/home/jenkins/workspace       # 挂载工作目录，持久化任务数据
      - /var/run/docker.sock:/var/run/docker.sock    # 可选：挂载 Docker 套接字
    restart: unless-stopped

volumes:
  agent-workdir:  # 定义工作目录卷

启动服务：

docker-compose up -d

4. 环境变量配置说明

5. 自定义工具版本

如需修改内置工具版本（如 Java、Maven），可通过构建参数自定义镜像：

docker build \
  --build-arg JAVA_VERSION=17 \
  --build-arg MAVEN_VERSION=3.9.6 \
  -t my-custom-agent:latest \
  [***]

注意事项

1. 网络连通性：确保代理容器与 Jenkins 控制器之间网络可达（JNLP 协议默认使用端口 50000，SSH 协议默认使用端口 22）。

2. 权限管理：

   • 挂载 Docker 套接字（/var/run/docker.sock）时需注意安全风险，避免容器内非授权操作宿主机 Docker。
   • 生产环境中建议使用非 root 用户运行容器，可通过 --user 参数指定 UID/GID。

3. 资源限制：根据任务需求通过 --memory、--cpus 限制容器资源，避免资源耗尽。

4. 持久化数据：建议将工作目录（WORKDIR）挂载为 Docker 卷，避免任务数据因容器重启丢失。

参考链接

• 镜像源码及更多文档：jenkins-infra/packer-images
• Jenkins 代理配置官方文档：Jenkins Agent Setup