Jenkins CI/CD 自动化部署环境搭建完全指南

Jenkins CI/CD 自动化部署环境搭建完全指南

Someone Lv5

持续集成与持续交付(CI/CD)是现代软件开发流程的核心实践。Jenkins 作为最成熟的开源自动化服务器,可以帮助团队实现代码提交后的自动构建、测试和部署。本文将详细介绍在 Ubuntu 22.04 上搭建 Jenkins 自动化部署环境的完整流程,涵盖安装配置、Pipeline 编写、Git 集成、插件管理以及安全加固等关键环节。

Jenkins 架构概述

Jenkins 采用主从(Master/Agent)架构设计:

  • Master 节点:负责任务调度、Web UI 管理和构建记录存储
  • Agent 节点:执行具体的构建任务,支持多平台分布式构建
  • 共享数据目录$JENKINS_HOME(默认 /var/lib/jenkins/)存放所有配置、构建记录和插件

环境要求

资源项最低配置推荐配置
CPU2 核4 核以上
内存4 GB8 GB 以上
磁盘20 GB50 GB 以上(SSD)
操作系统Ubuntu 20.04+ / CentOS 7+Ubuntu 22.04 LTS
JavaJDK 11JDK 17(推荐)或 JDK 21

第一步:安装 Java 运行环境

Jenkins 基于 Java 运行,最新版本要求 JDK 11 或更高版本:

1
2
3
4
5
6
7
8
9
10
11
# 安装 OpenJDK 17(推荐)
sudo apt update
sudo apt install -y openjdk-17-jdk

# 验证安装
java -version

# 设置 JAVA_HOME 环境变量
echo 'export JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64' | sudo tee /etc/profile.d/java.sh
echo 'export PATH=$JAVA_HOME/bin:$PATH' | sudo tee -a /etc/profile.d/java.sh
source /etc/profile.d/java.sh

第二步:安装 Jenkins

Jenkins 官方提供 APT 仓库,推荐通过仓库方式安装以便后续更新:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# 导入 Jenkins GPG 密钥
curl -fsSL https://pkg.jenkins.io/debian-stable/jenkins.io-2023.key | sudo tee \
/usr/share/keyrings/jenkins-keyring.asc > /dev/null

# 添加仓库
echo "deb [signed-by=/usr/share/keyrings/jenkins-keyring.asc] \
https://pkg.jenkins.io/debian-stable binary/" | sudo tee \
/etc/apt/sources.list.d/jenkins.list

# 安装 Jenkins
sudo apt update
sudo apt install -y jenkins

# 查看服务状态
sudo systemctl status jenkins

Jenkins 默认监听 8080 端口。安装完成后,浏览器访问 http://your-server-ip:8080 即可看到解锁页面。

获取初始管理员密码

1
sudo cat /var/lib/jenkins/secrets/initialAdminPassword

复制该密码,在 Web 页面中输入完成解锁。之后按引导安装推荐插件并创建管理员用户。

第三步:Jenkins 基础配置

修改默认端口

如果 8080 端口被占用,可以修改监听端口:

1
2
3
4
5
6
7
8
# 编辑 Jenkins 配置文件
sudo vim /etc/default/jenkins

# 修改 HTTP_PORT 参数
HTTP_PORT=9090

# 重启 Jenkins
sudo systemctl restart jenkins

配置 Nginx 反向代理(可选)

将 Jenkins 放在 Nginx 反向代理后面,可以统一管理 HTTPS 和子域名:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
server {
listen 80;
server_name jenkins.yourdomain.com;

location / {
proxy_pass http://127.0.0.1:8080;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;

# WebSocket 支持(Pipeline Blue Ocean 需要)
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
}
}

完成后为域名配置 SSL 证书(可参考本站 Let’s Encrypt SSL 指南),然后设置 Jenkins 的 JENKINS_URL

1
sudo systemctl edit jenkins

添加:

1
2
[Service]
Environment="JENKINS_URL=https://jenkins.yourdomain.com"

第四步:安装必要插件

解锁 Jenkins 后,进入 Dashboard > Manage Jenkins > Plugins > Available plugins,安装以下核心插件:

插件名称用途
Git PluginGit 仓库集成(默认已安装)
PipelinePipeline as Code 支持
Blue Ocean现代化 Pipeline 可视化界面
Credentials Binding凭据安全绑定
Docker PipelineDocker 构建与容器化部署
SSH AgentSSH 密钥代理用于远程部署
Email Extension高级邮件通知
Slack NotificationSlack 消息通知
Build Timestamp构建时间戳

第五步:配置 Git 和凭据

添加 Git 仓库凭据

  1. 进入 Dashboard > Manage Jenkins > Credentials > System > Global credentials (unrestricted)
  2. 点击 Add Credentials
  3. 选择凭证类型:SSH Username with private key(适用于 SSH 协议的 Git 仓库)
  4. 将部署用的 SSH 私钥粘贴进去

对于 HTTP/HTTPS 协议的仓库,选择 Username with password,填入 Git 平台的用户名和访问令牌(Token)。

安装 Git 工具

1
2
3
4
5
# Jenkins 服务器上安装 Git
sudo apt install -y git

# 验证
git --version

第六步:编写第一个 Pipeline

Jenkins Pipeline 使用 Groovy 编写,分为两种形式:Declarative Pipeline(声明式)和 Scripted Pipeline(脚本式)。

声明式 Pipeline 示例

以下是一个完整的 Java 项目 CI/CD Pipeline,包含构建、测试和部署三个阶段:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
pipeline {
agent any

tools {
maven 'Maven-3.9' // 需要在 Global Tool Configuration 中配置
jdk 'JDK-17'
}

environment {
// 定义环境变量
PROJECT_NAME = 'my-app'
DEPLOY_SERVER = '192.168.1.100'
DEPLOY_PATH = '/opt/app'
}

stages {
stage('Checkout') {
steps {
// 从 Git 仓库拉取代码
git branch: 'main',
url: 'git@github.com:your-org/my-app.git',
credentialsId: 'github-ssh-key'
}
}

stage('Build') {
steps {
echo '开始构建...'
sh 'mvn clean package -DskipTests'
}
post {
success {
echo '构建成功!'
archiveArtifacts artifacts: 'target/*.jar'
}
failure {
echo '构建失败!'
}
}
}

stage('Test') {
steps {
echo '运行单元测试...'
sh 'mvn test'
}
post {
always {
// 发布测试报告
junit 'target/surefire-reports/*.xml'
}
}
}

stage('Deploy') {
when {
branch 'main' // 仅 main 分支触发部署
}
steps {
echo '部署到生产服务器...'
sshagent(credentials: ['deploy-ssh-key']) {
sh """
scp target/${PROJECT_NAME}.jar \
deploy@${DEPLOY_SERVER}:${DEPLOY_PATH}/
ssh deploy@${DEPLOY_SERVER} "
systemctl restart ${PROJECT_NAME}
"
"""
}
}
}
}

post {
always {
echo 'Pipeline 执行完毕'
}
success {
// 发送成功通知
emailext(
subject: "[Jenkins] ${env.JOB_NAME} - Build #${env.BUILD_NUMBER} 成功!",
body: "项目 ${PROJECT_NAME} 构建部署成功。\n查看详情: ${env.BUILD_URL}",
to: 'team@example.com'
)
}
failure {
// 发送失败通知
emailext(
subject: "[Jenkins] ${env.JOB_NAME} - Build #${env.BUILD_NUMBER} 失败!",
body: "项目 ${PROJECT_NAME} 构建失败,请检查。\n查看日志: ${env.BUILD_URL}console",
to: 'team@example.com'
)
}
}
}

创建 Pipeline 任务

  1. 点击 New Item(新建任务)
  2. 输入任务名称,选择 Pipeline
  3. 在 Pipeline 定义中,选择 Pipeline script from SCM
  4. 配置 Git 仓库地址和分支
  5. 脚本路径设置为 Jenkinsfile(项目仓库中存放 Pipeline 脚本的文件名)

第七步:Jenkinsfile 最佳实践

将 Pipeline 脚本保存在项目仓库中(文件名为 Jenkinsfile),实现 Pipeline as Code:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
// Jenkinsfile - 放在项目根目录
pipeline {
agent any

options {
// 保留最近 10 次构建记录
buildDiscarder(logRotator(numToKeepStr: '10'))
// 超时设置:构建超过 30 分钟则自动终止
timeout(time: 30, unit: 'MINUTES')
// 禁止并发构建
disableConcurrentBuilds()
}
// ... stages 同上
}

Pipeline 共享库

对于多个项目共享的 Pipeline 逻辑,可以创建共享库:

  1. 创建一个 Git 仓库存放共享 Groovy 脚本
  2. 在 Jenkins 中配置 Manage Jenkins > System > Global Pipeline Libraries
  3. 在 Pipeline 中引用:
1
2
3
4
5
6
7
8
9
10
11
12
@Library('my-shared-library') _

pipeline {
agent any
stages {
stage('Build') {
steps {
mySharedBuild() // 调用共享库中的函数
}
}
}
}

第八步:Docker 集成

让 Jenkins 使用 Docker

1
2
3
4
5
# 将 Jenkins 用户加入 docker 组
sudo usermod -aG docker jenkins

# 重启 Jenkins 使权限生效
sudo systemctl restart jenkins

Docker Pipeline 示例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
pipeline {
agent {
docker {
image 'maven:3.9-eclipse-temurin-17'
args '-v /root/.m2:/root/.m2'
}
}

stages {
stage('Build in Docker') {
steps {
sh 'mvn clean package'
}
}
}
}

这种方式的优势在于:构建环境完全由 Docker 镜像定义,团队成员和 CI 服务器使用完全一致的环境,消除”在我机器上能运行”的问题。

第九步:安全加固最佳实践

安全措施说明
启用 CSRF 保护默认已启用,不要关闭
配置 Agent → Master 访问控制限制 Agent 节点对 Master 的访问
使用 HTTPS通过 Nginx 反向代理配置 SSL
定期更新保持 Jenkins 和插件为最新版本
最小权限原则为不同用户/团队分配最小所需权限
凭据加密使用 Credentials Binding 插件注入敏感信息
审计日志启用 Jenkins 审计日志功能
备份 $JENKINS_HOME定期备份配置和构建记录

定期备份脚本

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
#!/bin/bash
# /opt/scripts/backup-jenkins.sh
BACKUP_DIR="/backup/jenkins"
DATE=$(date +%Y%m%d_%H%M%S)
JENKINS_HOME="/var/lib/jenkins"

mkdir -p $BACKUP_DIR

# 停止 Jenkins 服务确保数据一致性
sudo systemctl stop jenkins

# 创建压缩备份
tar czf "$BACKUP_DIR/jenkins-backup-$DATE.tar.gz" \
--exclude="$JENKINS_HOME/workspace" \
--exclude="$JENKINS_HOME/caches" \
--exclude="$JENKINS_HOME/builds" \
--exclude="$JENKINS_HOME/jobs/*/builds" \
-C / $JENKINS_HOME

# 重新启动 Jenkins
sudo systemctl start jenkins

# 保留最近 30 天的备份
find $BACKUP_DIR -name "jenkins-backup-*.tar.gz" -mtime +30 -delete

echo "备份完成: $BACKUP_DIR/jenkins-backup-$DATE.tar.gz"

配合 cron 定期执行:

1
2
# 每天凌晨 3 点备份
0 3 * * * /opt/scripts/backup-jenkins.sh

第十步:性能调优

JVM 参数优化

1
2
# 编辑 Jenkins 配置
sudo systemctl edit jenkins

添加 JVM 参数(根据服务器内存调整):

1
2
3
4
5
6
7
[Service]
Environment="JAVA_OPTS=-Djava.awt.headless=true \
-Xms2048m -Xmx4096m \
-XX:+UseG1GC \
-XX:MaxGCPauseMillis=100 \
-XX:+ParallelRefProcEnabled \
-XX:MetaspaceSize=256m"

清理构建记录

1
2
3
# 手动清理,也可以通过 Pipeline 的 buildDiscarder 自动清理
sudo find /var/lib/jenkins/jobs -type d -name "builds" \
-exec rm -rf {}/[0-9]* \;

常见问题排查

问题可能原因解决方法
启动失败:端口占用8080 端口已被其他服务使用修改 /etc/default/jenkins 中的 HTTP_PORT
构建卡死(无输出日志)Agent 连接断开检查 Jenkins Agent 日志,重启 agent 进程
Git 拉取代码失败SSH 密钥或 Token 失效在凭据管理中更新凭证
Docker 构建权限拒绝Jenkins 用户未加入 docker 组运行 usermod -aG docker jenkins 并重启
插件安装失败网络代理问题或插件依赖冲突配置 HTTP 代理或手动下载 .hpi 文件上传
Maven 构建慢本地未配置 Maven 仓库镜像配置 settings.xml 使用阿里云/华为云镜像
Pipeline 语法错误Groovy 语法问题使用片段生成器(Pipeline Syntax)生成代码

常用命令速查

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
# 服务管理
sudo systemctl start jenkins # 启动
sudo systemctl stop jenkins # 停止
sudo systemctl restart jenkins # 重启
sudo systemctl enable jenkins # 开机自启
sudo systemctl status jenkins # 查看状态

# 查看日志
sudo journalctl -u jenkins -f # 实时日志
sudo tail -f /var/log/jenkins/jenkins.log

# 重载配置(不重启)
sudo systemctl reload jenkins

# 测试 Jenkins 配置文件语法
sudo -u jenkins java -jar /usr/share/jenkins/jenkins.war \
--version

总结

本文从零开始搭建了一套完整的 Jenkins CI/CD 自动化部署环境,涵盖了:

  1. 环境准备:Java 安装、Jenkins 安装与解锁
  2. 基础配置:Nginx 反向代理、插件安装、凭据管理
  3. Pipeline 实战:声明式 Pipeline 编写、Git 集成、Docker 构建
  4. 安全加固:备份策略、权限管理、JVM 调优
  5. 故障排查:常见问题速查表

Jenkins 的威力在于灵活可扩展的 Pipeline 机制和丰富的插件生态。推荐从简单的构建任务开始,逐步完善测试、部署和通知环节,建立起适合自己团队的 CI/CD 工作流。

本文由AI辅助生成,内容仅供参考

  • 标题: Jenkins CI/CD 自动化部署环境搭建完全指南
  • 作者: Someone
  • 创建于 : 2026-06-11 18:54:00
  • 更新于 : 2026-06-18 08:39:57
  • 链接: https://demo-blog.qusite.cn/2026-06-11-jenkins-cicd-guide/
  • 版权声明: 本文章采用 CC BY-NC-SA 4.0 进行许可。