代理配置 #
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