代理配置 #

Agent(代理)是执行构建任务的工作节点。本节详细介绍各种Agent的配置方法。

Agent连接方式 #

方式 说明 适用场景
SSH 通过SSH连接 Linux/Unix系统
JNLP 通过Java Web Start Windows/防火墙环境
Windows Service Windows服务 Windows系统
Docker Docker容器 容器化构建
Kubernetes K8s Pod 云原生环境

SSH Agent配置 #

前提条件 #

bash
# Agent机器安装Java
sudo apt install openjdk-11-jdk

# 创建jenkins用户
sudo useradd -m -s /bin/bash jenkins

# 配置SSH免密登录
ssh-keygen -t rsa
ssh-copy-id jenkins@agent-host

Master配置 #

text
Manage Jenkins → Manage Nodes → New Node

Name: linux-agent-1
Type: Permanent Agent

配置:
  Remote root directory: /home/jenkins/agent
  Labels: linux docker
  Launch method: Launch agents via SSH
  
  Host: 192.168.1.100
  Credentials: ssh-key-credentials
  Host Key Verification Strategy: Known hosts file
  Port: 22

SSH凭据配置 #

text
Manage Jenkins → Credentials → System → Global credentials

Kind: SSH Username with private key
ID: ssh-agent-key
Username: jenkins
Private Key: Enter directly / From file

高级SSH配置 #

text
JavaPath: /usr/lib/jvm/java-11/bin/java

JVM Options: -Xmx2g -XX:+UseG1GC

Prefix Start Agent Command: 
Suffix Start Agent Command:

Connection Timeout: 300
Maximum Number of Retries: 10
Wait Between Retries: 15

JNLP Agent配置 #

适用场景 #

  • Agent在防火墙后面
  • Master无法直接SSH到Agent
  • Windows系统

配置步骤 #

text
Manage Jenkins → Manage Nodes → New Node

Name: jnlp-agent-1
Type: Permanent Agent

配置:
  Remote root directory: C:\jenkins\agent
  Labels: windows
  Launch method: Launch agent via execution of command on the master

Agent端启动 #

bash
# 下载agent.jar
curl -o agent.jar http://JENKINS_URL/jnlpJars/agent.jar

# 启动Agent
java -jar agent.jar \
  -jnlpUrl http://JENKINS_URL/computer/agent-name/slave-agent.jnlp \
  -secret YOUR_SECRET_KEY \
  -workDir /home/jenkins/agent

获取Secret Key #

在节点页面查看Agent的secret key:

text
http://JENKINS_URL/computer/agent-name/

Windows服务配置 #

powershell
# 安装为Windows服务
jenkins-agent.exe install

# 启动服务
jenkins-agent.exe start

# 停止服务
jenkins-agent.exe stop

Docker Agent配置 #

Docker Cloud配置 #

text
Manage Jenkins → Manage Nodes and Clouds → Configure Clouds

Add a new cloud: Docker

Docker Host URI: unix:///var/run/docker.sock
  或 tcp://docker-host:2375

Enabled: ✓

Docker Agent模板 #

text
Docker Agent Templates:
  Labels: docker-maven
  Docker Image: maven:3.8-openjdk-11
  Remote FS Root: /home/jenkins
  Instance Capacity: 5
  
  Container Settings:
    Volumes: /var/run/docker.sock:/var/run/docker.sock
    Environment: MAVEN_OPTS=-Xmx2g

Pipeline中使用 #

groovy
pipeline {
    agent {
        docker {
            image 'maven:3.8-openjdk-11'
            args '-v $HOME/.m2:/root/.m2'
        }
    }
    
    stages {
        stage('Build') {
            steps {
                sh 'mvn clean package'
            }
        }
    }
}

Kubernetes Agent配置 #

Kubernetes Cloud配置 #

text
Manage Jenkins → Manage Nodes and Clouds → Configure Clouds

Add a new cloud: Kubernetes

Name: kubernetes
Kubernetes URL: https://kubernetes.default
Kubernetes Namespace: jenkins
Credentials: kubeconfig
Jenkins URL: http://jenkins:8080
Jenkins tunnel: jenkins:50000

Pod模板 #

text
Pod Templates:
  Name: maven-pod
  Namespace: jenkins
  Labels: maven
  
  Containers:
    Name: maven
    Image: maven:3.8-openjdk-11
    Command: cat
    TTY: true
    Working Directory: /home/jenkins/agent
    
  Volumes:
    - Empty Dir Volume: maven-repo
    - Host Path Volume: /var/run/docker.sock

Pipeline中使用 #

groovy
pipeline {
    agent {
        kubernetes {
            yaml '''
                apiVersion: v1
                kind: Pod
                metadata:
                  labels:
                    app: jenkins-agent
                spec:
                  containers:
                  - name: maven
                    image: maven:3.8-openjdk-11
                    command:
                    - cat
                    tty: true
                    volumeMounts:
                    - name: maven-cache
                      mountPath: /root/.m2
                  volumes:
                  - name: maven-cache
                    persistentVolumeClaim:
                      claimName: maven-cache-pvc
            '''
        }
    }
    
    stages {
        stage('Build') {
            steps {
                container('maven') {
                    sh 'mvn clean package'
                }
            }
        }
    }
}

Agent环境配置 #

工具配置 #

groovy
pipeline {
    agent { label 'linux' }
    
    tools {
        jdk 'JDK 11'
        maven 'Maven 3.8'
    }
    
    stages {
        stage('Build') {
            steps {
                sh 'java -version'
                sh 'mvn --version'
            }
        }
    }
}

环境变量 #

groovy
pipeline {
    agent { label 'linux' }
    
    environment {
        JAVA_HOME = '/usr/lib/jvm/java-11'
        MAVEN_HOME = '/opt/maven'
    }
    
    stages {
        stage('Build') {
            steps {
                sh 'mvn clean package'
            }
        }
    }
}

自定义工作空间 #

groovy
pipeline {
    agent {
        label 'linux'
        customWorkspace '/opt/build/myapp'
    }
    
    stages {
        stage('Build') {
            steps {
                sh 'pwd'
            }
        }
    }
}

Agent故障排查 #

连接问题 #

bash
# 检查SSH连接
ssh jenkins@agent-host

# 检查Java版本
java -version

# 检查网络连通性
ping jenkins-master
telnet jenkins-master 50000

日志查看 #

text
Manage Jenkins → Manage Nodes → [节点名称] → Log

常见错误 #

text
1. SSH连接失败
   - 检查SSH服务状态
   - 验证凭据配置
   - 检查防火墙规则

2. Java版本不兼容
   - 确保Agent安装了正确版本的Java
   - 配置正确的JavaPath

3. 工作目录权限问题
   - 检查目录权限
   - chown -R jenkins:jenkins /home/jenkins/agent

4. 磁盘空间不足
   - df -h
   - 清理旧构建

Agent最佳实践 #

1. 使用标签 #

text
Labels: linux docker java maven

2. 配置资源限制 #

groovy
pipeline {
    agent {
        kubernetes {
            yaml '''
                spec:
                  containers:
                  - name: maven
                    resources:
                      limits:
                        memory: "2Gi"
                        cpu: "2"
                      requests:
                        memory: "1Gi"
                        cpu: "1"
            '''
        }
    }
}

3. 使用持久化缓存 #

groovy
pipeline {
    agent {
        kubernetes {
            yaml '''
                spec:
                  volumes:
                  - name: maven-cache
                    persistentVolumeClaim:
                      claimName: maven-cache
            '''
        }
    }
}

4. 配置健康检查 #

groovy
options {
    timeout(time: 30, unit: 'MINUTES')
    retry(3)
}

下一步学习 #

小结 #

  • 支持多种Agent连接方式
  • SSH适合Linux环境
  • JNLP适合防火墙环境
  • Docker/Kubernetes适合云原生
  • 使用标签组织和管理Agent
  • 注意资源限制和健康检查
最后更新:2026-03-28