Jenkins Inbound Agent Docker镜像文档

1. 概述

1.1 镜像简介

Jenkins Inbound Agent Docker镜像集合是一套预配置的Docker镜像，旨在简化Jenkins入站代理（Inbound Agent）的部署与运行。该镜像集合将运行Jenkins入站代理所需的基础组件与标准Docker镜像相结合，提供了开箱即用的代理环境。

1.2 主要用途

作为Jenkins控制器（Controller）的代理节点，用于执行构建、测试、部署等任务。通过入站模式（Agent主动连接控制器），解决传统出站模式（控制器主动连接Agent）中网络可达性限制问题，适用于动态容器化环境。

2. 核心功能与特性

• 基于标准镜像构建：采用官方标准Docker镜像作为基础，确保兼容性与稳定性。
• 入站代理模式：支持Agent主动连接Jenkins控制器，无需控制器暴露网络端口或直接访问Agent，适用于复杂网络环境。
• 轻量级设计：仅包含运行入站代理的核心组件，减少资源占用。
• 多环境适配：可直接作为容器模板应用于主流容器编排平台（如Kubernetes、AWS ECS/Fargate、Azure Container Instances等）。

3. 使用场景与适用范围

3.1 典型使用场景

• Kubernetes集群：作为Pod模板集成到Jenkins Kubernetes插件，实现动态代理调度。
• 云容器服务：在AWS ECS/Fargate、Azure Container Instances等Serverless容器服务中部署，弹性扩展Jenkins代理资源。
• 跨网络环境：在控制器与代理处于不同网络分区（如公网/内网隔离）时，通过入站模式建立连接。
• 临时任务代理：为一次性或周期性任务快速创建临时代理，任务完成后自动销毁。

3.2 适用范围

• Jenkins控制器版本：支持Jenkins 2.303.1及以上（需兼容入站代理协议）。
• 网络要求：Agent需能访问Jenkins控制器URL（HTTP/HTTPS）。
• 容器环境：支持Docker、containerd等主流容器运行时，兼容Kubernetes、Docker Compose等编排工具。

4. 使用方法与配置说明

4.1 基本使用（Docker Run）

通过docker run命令启动入站代理，需指定Jenkins控制器地址、代理密钥及代理名称。

命令示例：

docker run -d \
  -e JENKINS_URL="[***]" \  # Jenkins控制器URL（需包含协议、主机、端口）
  -e JENKINS_SECRET="agent-secret-from-jenkins" \     # 代理密钥（从Jenkins控制器获取）
  -e JENKINS_AGENT_NAME="my-inbound-agent" \          # 代理名称（需在Jenkins控制器中预配置）
  jenkins/inbound-agent:latest                        # 镜像名称（可指定具体版本，如4.13-1）

4.2 环境变量配置

以下为核心环境变量说明，用于配置代理连接参数：

4.3 Docker Compose配置示例

通过Docker Compose定义代理服务，适用于本地测试或小规模部署。

docker-compose.yml示例：

version: '3.8'
services:
  jenkins-inbound-agent:
    image: jenkins/inbound-agent:latest
    environment:
      - JENKINS_URL=[***]  # 替换为实际Jenkins控制器URL
      - JENKINS_SECRET=your-agent-secret            # 替换为从Jenkins获取的代理密钥
      - JENKINS_AGENT_NAME=compose-agent            # 自定义代理名称
      - JENKINS_AGENT_WORKDIR=/home/jenkins/workdir # 自定义工作目录
    restart: unless-stopped                         # 异常退出后自动重启

启动命令：

docker-compose up -d

4.4 Kubernetes Pod模板示例

在Jenkins中配置Kubernetes Pod模板时，可直接引用该镜像。以下为Pod模板核心配置片段：

apiVersion: v1
kind: Pod
spec:
  containers:
  - name: jenkins-agent
    image: jenkins/inbound-agent:latest
    env:
    - name: JENKINS_URL
      value: "[***]"  # Jenkins控制器在K8s集群内的Service地址
    - name: JENKINS_SECRET
      valueFrom:
        secretKeyRef:
          name: agent-secrets                # 存储代理密钥的K8s Secret
          key: agent-secret
    - name: JENKINS_AGENT_NAME
      valueFrom:
        fieldRef:
          fieldPath: metadata.name           # 使用Pod名称作为代理名称

5. 注意事项

• 密钥安全性：JENKINS_SECRET为敏感信息，建议通过环境变量文件、Docker Secrets或Kubernetes Secrets管理，避免明文暴露。
• 网络连通性：确保Agent容器能够解析并访问JENKINS_URL，可通过docker exec -it <container-id> curl <JENKINS_URL>验证网络连通性。
• 镜像版本：建议使用固定版本标签（如4.13-1）而非latest，确保部署一致性。
• 资源限制：根据任务需求配置容器CPU/内存资源限制，避免影响Jenkins控制器或其他服务。