Jenkins流水线代理镜像文档

镜像概述

本镜像为Jenkins CI/CD平台提供专用代理节点（Agent），用于接收并执行Jenkins主节点分发的流水线任务。通过部署该代理，可实现构建任务的分布式处理，减轻主节点负载，同时支持多环境并行构建，提升流水线执行效率。

核心功能与特性

核心功能

• 接收Jenkins主节点任务调度，执行构建、测试、部署等流水线步骤
• 支持主流开发语言环境（如Java、Python、Node.js等，具体依赖镜像标签）
• 提供基础构建工具链（Git、Maven、Gradle等）
• 支持与Jenkins主节点的安全通信（JNLP协议或SSH协议）

特性

• 轻量级设计：基于Alpine或Debian Slim基础镜像，减少资源占用
• 可扩展性：支持通过环境变量或配置文件自定义工具链
• 多协议支持：兼容JNLP（Java Web Start）和SSH两种代理连接方式
• 持久化存储：支持挂载工作目录，保留构建缓存和临时文件
• 安全加固：默认禁用root权限运行，降低安全风险

使用场景与适用范围

适用场景

• 分布式构建：大型项目多模块并行构建，提高构建速度
• 多环境测试：在不同工具版本或系统环境中执行测试任务
• 资源密集型任务：将编译、打包等资源消耗型任务分配至专用代理节点
• 跨平台构建：在Linux、Windows等不同操作系统环境中执行任务（需对应系统版本镜像）

适用范围

• Jenkins 2.x及以上版本的CI/CD流水线
• 需要扩展构建资源的团队或企业
• 多团队共享Jenkins平台的场景
• 对构建环境一致性有要求的项目

使用方法与配置说明

前置条件

• 已部署Jenkins主节点，并确保网络互通（默认需开放50000端口，JNLP通信）
• 已在Jenkins主节点创建代理节点，并获取代理连接密钥（Secret）
• 主机已安装Docker引擎（19.03+）

快速启动（JNLP模式）

1. 获取代理配置信息

在Jenkins主节点中：

1. 进入「Manage Jenkins」→「Nodes」→「New Node」创建代理节点
2. 记录节点名称（Agent Name）、连接密钥（Secret）、主节点URL（Jenkins URL）

2. 启动代理容器

docker run -d \
  --name jenkins-agent \
  -e JENKINS_URL="[***]" \  # Jenkins主节点URL
  -e JENKINS_AGENT_NAME="my-agent-01" \          # 代理节点名称（需与Jenkins配置一致）
  -e JENKINS_SECRET="abcd1234-ef56-gh78-ij90-klmnopqrstuv" \  # 代理连接密钥
  -e JENKINS_AGENT_WORKDIR="/home/jenkins/agent" \  # 工作目录（默认/home/jenkins/agent）
  -v /var/run/docker.sock:/var/run/docker.sock \    # 如需Docker-in-Docker功能（可选）
  -v jenkins-agent-workdir:/home/jenkins/agent \    # 持久化工作目录（可选）
  your-registry/jenkins-agent:latest

3. 验证代理状态

在Jenkins主节点「Manage Jenkins」→「Nodes」中，查看代理节点状态是否为「在线」

docker-compose部署示例

创建docker-compose.yml文件：

version: '3.8'
services:
  jenkins-agent:
    image: your-registry/jenkins-agent:latest
    container_name: jenkins-agent
    environment:
      - JENKINS_URL=[***]
      - JENKINS_AGENT_NAME=my-agent-01
      - JENKINS_SECRET=abcd1234-ef56-gh78-ij90-klmnopqrstuv
      - JENKINS_AGENT_WORKDIR=/home/jenkins/agent
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock  # 可选，用于构建Docker镜像
      - jenkins-agent-workdir:/home/jenkins/agent
    restart: unless-stopped

volumes:
  jenkins-agent-workdir:

启动命令：

docker-compose up -d

SSH模式配置（可选）

若需使用SSH协议连接代理，需额外配置：

1. 在Jenkins主节点创建SSH凭证（用户名+私钥）
2. 启动代理时暴露22端口并设置SSH密钥：

docker run -d \
  --name jenkins-agent-ssh \
  -p 2222:22 \
  -e SSH_USER=jenkins \
  -e SSH_PUBKEY="ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQ..." \  # Jenkins主节点公钥
  your-registry/jenkins-agent:ssh-latest

3. 在Jenkins节点配置中选择「SSH」连接方式，填写主机地址、端口及凭证

环境变量配置

常见问题

Q：代理启动后Jenkins主节点显示「离线」？

A：检查以下项：

1. JENKINS_URL是否可从代理容器内访问（可通过docker exec -it <容器ID> curl $JENKINS_URL验证）
2. JENKINS_SECRET是否与Jenkins节点配置一致
3. 防火墙是否开放50000端口（JNLP默认端口）

Q：如何自定义代理内的工具链？

A：可通过构建自定义镜像实现，示例Dockerfile：

FROM your-registry/jenkins-agent:latest
# 安装额外工具
RUN apk add --no-cache python3 py3-pip
RUN pip3 install pytest

注意事项

• 生产环境建议使用持久化存储卷挂载工作目录，避免构建缓存丢失
• 多代理节点建议使用Docker Swarm或Kubernetes进行编排管理
• 定期更新镜像以获取安全补丁和工具链更新
• 敏感信息（如JENKINS_SECRET）建议通过 secrets 管理工具注入，避免明文暴露