一、前置环境准备(必做)
自动化流程的稳定运行依赖基础环境支撑,需提前完成以下配置,避免后续环节出现权限、依赖缺失等问题。
1.1 核心环境部署
- Jenkins 部署:推荐 2 种主流方式(新手优先 Docker,快速避坑)
- Docker 部署(推荐):执行命令
docker run -d -p 8080:8080 -p 50000:50000 -v jenkins_home:/var/jenkins_home --name jenkins jenkins/jenkins:lts;启动后访问 http://服务器 IP:8080,根据页面提示输入容器内初始密码(命令:docker exec -it jenkins cat /var/jenkins_home/secrets/initialAdminPassword)。
- WAR 包部署:下载 Jenkins WAR 包(https://www.jenkins.io/download/),执行
java -jar jenkins.war --httpPort=8080,后续访问和初始化步骤同上。
- 基础依赖安装:Jenkins 服务器需安装 JDK、Maven(或在 Jenkins 内配置自动安装),版本需与项目匹配(如 JDK 1.8/11、Maven 3.6+)。
- Git 环境:Jenkins 服务器安装 Git(命令:CentOS
yum install git -y;Ubuntu apt install git -y),确保能正常执行 git clone 命令。
1.2 必备插件安装
Jenkins 默认插件不足以支撑完整流程,需在「系统管理」→「插件管理」→「可选插件」中搜索安装以下插件,安装后重启 Jenkins 生效:
- Git Plugin:核心插件,实现 Git 代码拉取
- Maven Integration Plugin:支持 Maven 项目构建,提供 Maven 命令执行入口
- Pipeline Plugin:流水线核心插件,支持用 Jenkinsfile 定义自动化流程(进阶必备)
- Publish Over SSH:通过 SSH 将构建产物上传到远程部署服务器(核心部署插件)
- Credentials Binding Plugin:安全管理凭证(Git 账号密码、SSH 密钥等)
- Email Extension Plugin:构建结果邮件通知(可选,用于故障告警)
1.3 全局工具配置(关键)
在 Jenkins「系统管理」→「全局工具配置」中,配置 JDK、Maven,确保 Jenkins 能找到对应工具(避免构建时出现'命令未找到'错误):
- JDK 配置:点击「JDK 安装」,取消'自动安装'(推荐使用服务器已安装的 JDK),输入'名称'(如 JDK_1.8),'JAVA_HOME'填写服务器 JDK 路径(如
/usr/local/jdk1.8.0_301),保存。
- Maven 配置:点击「Maven 安装」,取消'自动安装',输入'名称'(如 Maven_3.8),'MAVEN_HOME'填写服务器 Maven 路径(如
/usr/local/apache-maven-3.8.8);额外配置「Maven 设置」,选择'文件系统中的 settings.xml 路径'(如 /usr/local/apache-maven-3.8.8/conf/settings.xml),确保 settings.xml 中配置了镜像源(如阿里云),加速依赖下载,保存。
1.4 权限与网络准备
- Git 仓库权限:Jenkins 需要能访问 Git 仓库(GitHub/Gitee/GitLab),推荐配置 SSH 密钥(免密拉取):
- 在 Jenkins 服务器执行
ssh-keygen -t rsa -C "[email protected]",一路回车生成密钥(默认路径 ~/.ssh/id_rsa)。
- 查看公钥
cat ~/.ssh/id_rsa.pub,将公钥添加到 Git 仓库的「个人设置」→「SSH 密钥」中(如 Gitee 的「安全设置」→「SSH 公钥」)。
- 在 Jenkins 中添加凭证:「系统管理」→「管理凭证」→「全局凭证」→「添加凭证」,选择「SSH 用户名和私钥」,'用户名'填写 Git 用户名(如 Gitee 账号名),'私钥'选择'直接输入',粘贴
~/.ssh/id_rsa 中的私钥(完整内容,包括 -----BEGIN RSA PRIVATE KEY----- 和 -----END RSA PRIVATE KEY-----),点击确定。
- 部署服务器权限:若需将产物部署到远程服务器,需确保 Jenkins 服务器能通过 SSH 连接部署服务器:将 Jenkins 服务器的 SSH 公钥(
~/.ssh/id_rsa.pub)添加到部署服务器的 ~/.ssh/authorized_keys 文件中,测试连接 ssh 部署服务器用户名@部署服务器 IP,确保无需输入密码即可登录。
- 网络连通性:Jenkins 服务器需能访问 Git 仓库(测试
ping github.com 或 git clone 仓库地址)、部署服务器(测试 ping 部署服务器 IP),若有防火墙,需开放 8080(Jenkins 端口)、22(SSH 端口)、443(HTTPS 仓库)等端口。
二、Freestyle 模式:基础自动化构建部署(新手入门)
Freestyle 项目是 Jenkins 最基础、易上手的类型,适合快速搭建简单的自动化流程(单模块项目、无复杂流程依赖),核心链路:拉取 Git 代码 → Maven 编译打包 → 部署到远程服务器。
2.1 创建 Freestyle 项目
- 登录 Jenkins 首页,点击「新建任务」,输入任务名称(如
java-maven-demo-auto-deploy),选择「自由风格软件项目」,点击「确定」。
- 进入项目配置页面,后续步骤均在此页面完成。
2.2 配置源码管理(拉取 Git 代码)
- 在「源码管理」模块,选择「Git」,在「Repository URL」中输入 Git 仓库地址(如
[email protected]:xxx/java-maven-demo.git,SSH 地址需配置上述 SSH 凭证;HTTPS 地址需输入 Git 账号密码)。
- 在「Credentials」下拉框中,选择已配置的 Git 凭证(SSH 或账号密码)。
- 「Branches to build」:指定需要构建的分支,默认
*/main(主分支),可改为 */dev(开发分支)等。
- 可选配置:「Additional Behaviours」→「Add」→「Check out to a sub-directory」,可指定代码拉取到项目目录下的子文件夹(避免文件混乱)。
2.3 配置构建触发器(自动化触发时机)
根据实际需求选择触发方式,新手建议先选手动触发,熟悉后再配置自动触发:
- 手动触发:无需配置,保存项目后,点击「立即构建」即可触发流程(适合调试阶段)。
- 定时触发:勾选「构建触发器」→「定期构建」,输入 Cron 表达式,实现定时自动构建。例如:
Cron 表达式格式:分 时 日 月 周(如
0 12 * * 1-5 表示工作日中午 12 点构建)。
H 2 * * *:每天凌晨 2 点构建(H 表示随机时间,避免多项目同时触发导致服务器压力大)。
H/30 * * * *:每 30 分钟构建一次(适合开发阶段频繁测试)。
- 代码提交触发(WebHook):实现「代码提交/合并后自动构建」,核心步骤:
- Jenkins 配置:勾选「构建触发器」→「触发远程构建(例如,使用脚本)」,在「身份验证令牌」中输入自定义令牌(如
java-demo-2024),记录触发地址:http://Jenkins 服务器 IP:8080/job/项目名称/build?token=令牌(如 http://192.168.1.100:8080/job/java-maven-demo-auto-deploy/build?token=java-demo-2024)。
- Git 仓库配置:进入 Git 仓库(如 Gitee)→「管理」→「WebHook」→「添加 WebHook」,「URL」填写上述 Jenkins 触发地址,「事件」选择「Push 事件」(代码提交触发)和「Merge Request 事件」(合并请求触发),「内容格式」选择「application/json」,点击「添加」。
- 测试:修改项目代码并提交到 Git 仓库,查看 Jenkins 是否自动触发构建。
2.4 配置构建步骤(Maven 编译打包)
此步骤实现 Java 项目的编译、清理、打包,核心是执行 Maven 命令:
- 在「构建」模块,点击「增加构建步骤」,选择「Invoke top-level Maven targets」(Maven 项目专属步骤)。
- 在「Maven Version」下拉框中,选择之前在「全局工具配置」中配置的 Maven(如 Maven_3.8)。
- 在「Goals and options」中输入 Maven 命令,核心命令说明:
clean package -DskipTests:清理旧构建产物(clean)→ 编译源码 → 打包(生成 jar/war 包,默认在 target 目录下)→ 跳过单元测试(-DskipTests,适合快速构建;正式环境建议去掉此参数,执行测试)。
clean install -DskipTests:在打包的基础上,将产物安装到本地 Maven 仓库(适合多模块项目,依赖本地其他模块)。
- 若项目有自定义 settings.xml,可在「Advanced」→「Settings file」中选择自定义配置文件。
- 可选:若需要执行单元测试并生成报告,可添加「增加构建步骤」→「Execute shell」(Linux),输入命令
mvn test,并在后续「构建后操作」中配置测试报告展示。
2.5 配置构建后操作(部署到远程服务器)
通过「Publish Over SSH」插件将 target 目录下的 jar/war 包上传到远程部署服务器,并执行启动脚本,完成部署:
- 先配置 SSH 服务器信息:进入 Jenkins「系统管理」→「系统设置」,下拉找到「Publish over SSH」→「SSH Servers」→「Add」,配置部署服务器信息:
- 「Name」:自定义名称(如
demo-deploy-server,后续项目中选择使用)。
- 「Hostname」:部署服务器 IP 地址(如
192.168.1.101)。
- 「Username」:部署服务器登录用户名(如
root)。
- 「Remote Directory」:默认上传根目录(如
/opt/deploy,可自定义,需确保该目录已存在)。
- 「Authentication」:选择「Use password」(输入部署服务器密码)或「Use key」(粘贴 Jenkins 服务器的 SSH 私钥,已配置免密则无需密码)。
- 点击「Test Configuration」,显示「Success」则配置成功,点击「Save」保存。
- 回到项目配置的「构建后操作」模块,点击「增加构建后操作步骤」,选择「Send build artifacts over SSH」。
- 在「SSH Server」下拉框中,选择上述配置的部署服务器(如
demo-deploy-server)。
- 可选:配置构建结果通知,添加「增加构建后操作步骤」→「Editable Email Notification」,配置收件人邮箱、邮件主题(如
[Jenkins 构建通知] ${JOB_NAME} - 构建${BUILD_STATUS})、邮件内容(包含构建日志、失败原因等),实现构建成功/失败的邮件告警。
2.6 保存并测试流程
- 点击项目配置页面底部的「保存」按钮,回到项目详情页。
- 点击「立即构建」,触发第一次自动化流程,构建记录会显示在「构建历史」中(如 #1、#2)。
- 查看构建日志:点击构建记录(如 #1)→「Console Output」,查看流程执行详情:
- 若日志最后显示「Finished: SUCCESS」,说明构建部署成功;若显示「Finished: FAILURE」,则根据日志中的错误信息排查问题(如凭证错误、Maven 命令错误、服务器连接失败等)。
- 验证部署:登录部署服务器,进入部署目录(如
/opt/deploy/demo),执行 ps -ef | grep java,查看项目进程是否存在;访问项目接口(如 http://部署服务器 IP:端口/接口路径),验证服务是否正常。
三、Pipeline 模式:企业级灵活部署(进阶)
Freestyle 模式适合简单流程,但对于多模块、多环境(开发/测试/生产)、复杂依赖的项目,推荐使用 Pipeline 模式。Pipeline 通过 Jenkinsfile(Groovy 语法)定义全流程,支持版本化管理(将 Jenkinsfile 存入 Git 仓库)、流程可视化、多步骤联动等,是企业级 Jenkins 部署的主流方案。
3.1 Pipeline 核心概念
- Jenkinsfile:存储在 Git 仓库中的流程定义文件,分为「声明式 Pipeline」(语法简洁,推荐新手)和「脚本式 Pipeline」(灵活度高,适合复杂逻辑)。
- Stage:流程阶段(如拉取代码、编译打包、部署测试环境、部署生产环境),每个 Stage 可独立配置执行条件。
- Step:每个 Stage 中的具体操作(如 git 拉取、sh 执行命令、ssh 上传文件)。
3.2 创建 Pipeline 项目
- Jenkins 首页→「新建任务」→ 输入项目名称(如
java-maven-demo-pipeline)→ 选择「流水线」→「确定」。
- 进入项目配置页面,重点配置「流水线」模块。
3.3 配置 Pipeline 流程(声明式 Jenkinsfile)
推荐将 Jenkinsfile 存入 Git 仓库(「Pipeline script from SCM」),实现流程的版本化管理;调试阶段可先使用「直接输入脚本」(「Pipeline script」)。
3.3.1 方式 1:Jenkinsfile 存入 Git 仓库(推荐)
- 将 Jenkinsfile 提交到 Git 仓库:
git add Jenkinsfile && git commit -m "add jenkinsfile for pipeline" && git push。
- 回到 Jenkins 项目配置的「流水线」模块,选择「Pipeline script from SCM」→ 选择「Git」→ 填写「Repository URL」(Git 仓库地址)和「Credentials」(Git 凭证)→ 「Script Path」填写
Jenkinsfile(默认根目录,若在子目录需指定路径,如 docs/Jenkinsfile)→ 保存。
在 Java/Maven 项目的 Git 仓库根目录下,创建文件 Jenkinsfile,写入以下声明式脚本(根据实际项目修改参数):
// 声明式 Pipeline,指定运行节点(any 表示任意可用节点)
pipeline {
agent any
// 环境变量配置(集中管理,便于修改)
environment {
GIT_URL = '[email protected]:xxx/java-maven-demo.git' // Git 仓库地址
GIT_BRANCH = '*/main' // 构建分支
MAVEN_CMD = 'clean package -DskipTests' // Maven 构建命令
DEPLOY_SERVER = 'demo-deploy-server' // Jenkins 配置的 SSH 服务器名称
DEPLOY_DIR = '/opt/deploy/demo' // 部署服务器目录
JAR_NAME = 'java-maven-demo-1.0-SNAPSHOT.jar' // 项目 jar 包名称(pom.xml 中 finalName)
}
// 构建触发器(与 Freestyle 一致,可配置定时、WebHook)
triggers {
// 定时构建:每天凌晨 2 点
cron('H 2 * * *')
// WebHook 触发:需配合 Git 仓库配置,令牌与 Freestyle 一致
upstream('java-maven-demo-auto-deploy') // 可选:依赖其他项目构建完成后触发
}
// 构建阶段定义(可视化流程)
stages {
// 阶段 1:拉取 Git 代码
stage('拉取代码') {
steps {
echo "===== 开始拉取${GIT_BRANCH}分支代码 ====="
// 拉取代码,指定凭证(Jenkins 中配置的 Git SSH 凭证 ID)
git url: env.GIT_URL, branch: env.GIT_BRANCH, credentialsId: 'git-ssh-key'
}
}
// 阶段 2:Maven 编译打包
stage('编译打包') {
steps {
echo "===== 开始编译打包 ====="
// 执行 Maven 命令,指定 Maven 版本(全局工具配置中的名称)
withMaven(maven: 'Maven_3.8', mavenSettingsConfig: 'maven-settings') {
sh env.MAVEN_CMD
}
// 验证打包结果,若 target 目录下无 jar 包则构建失败
sh "if [ ! -f target/${JAR_NAME} ]; then echo '打包失败,未生成 jar 包'; exit 1; fi"
}
}
// 阶段 3:部署到远程服务器
stage('部署到服务器') {
steps {
echo "===== 开始部署到${DEPLOY_DIR} ====="
// 通过 SSH 上传文件并执行部署命令
sshPublisher(publishers: [
sshPublisherDesc(
configName: env.DEPLOY_SERVER,
transfers: [
sshTransfer(
sourceFiles: "target/${JAR_NAME}",
removePrefix: 'target',
remoteDirectory: env.DEPLOY_DIR,
// 部署命令:停止旧服务→启动新服务
execCommand: """
cd ${DEPLOY_DIR}
ps -ef | grep ${JAR_NAME} | grep -v grep | awk '{print $2}' | xargs -r kill -9
nohup java -jar ${JAR_NAME} > nohup.out 2>&1 &
echo '部署完成,查看日志:tail -f ${DEPLOY_DIR}/nohup.out'
"""
)
]
)
])
}
}
}
// 构建后操作(成功/失败的后续处理)
post {
// 构建成功时执行
success {
echo "===== 构建部署成功!项目地址:http://部署服务器 IP:端口 ="
// 可选:发送成功邮件
// emailext(to: '[email protected]', subject: '【成功】Jenkins 构建通知', body: '项目${JOB_NAME}构建成功,构建编号:${BUILD_NUMBER}')
}
// 构建失败时执行
failure {
echo "===== 构建部署失败!查看日志:${BUILD_URL}console ====="
// 可选:发送失败邮件
// emailext(to: '[email protected]', subject: '【失败】Jenkins 构建通知', body: '项目${JOB_NAME}构建失败,构建编号:${BUILD_NUMBER},请查看日志排查问题')
}
// 无论成功/失败都执行
always {
echo "===== 构建流程结束 ====="
}
}
}
3.3.2 方式 2:直接输入脚本(调试用)
在项目配置的「流水线」模块,选择「Pipeline script」,将上述 Jenkinsfile 中的脚本直接粘贴到输入框中,修改环境变量(如 GIT_URL、JAR_NAME 等),保存后即可测试构建。
3.4 测试 Pipeline 流程
- 回到项目详情页,点击「立即构建」,触发 Pipeline 流程。
- 查看流程可视化:点击构建记录→「流水线可视化」,可直观看到每个 Stage 的执行状态(成功绿色、失败红色)。
- 查看日志:点击「Console Output」,查看每个步骤的执行详情,排查问题(与 Freestyle 一致)。
四、关键注意事项(避坑指南)
- 凭证安全管理:所有账号密码、SSH 密钥均通过 Jenkins「凭证」管理,禁止直接写在脚本或配置中(避免泄露);凭证 ID 需准确,否则会导致权限校验失败。
- 依赖下载加速:Maven 的 settings.xml 中务必配置阿里云镜像(
<mirror>),否则依赖下载缓慢或失败;示例镜像配置:
<mirror> <id>aliyunmaven</id> <name>阿里云中央仓库</name> <url>https://maven.aliyun.com/repository/public</url> <mirrorOf>central</mirrorOf> </mirror>
- jar 包名称固定:在项目 pom.xml 中配置
<finalName>java-maven-demo</finalName>,固定 jar 包名称(避免生成带版本号的 jar 包,导致部署命令失效)。
- 部署命令健壮性:停止服务时,使用
xargs -r kill -9(-r 表示无进程时不执行 kill 命令,避免报错);启动服务时,使用 nohup(后台运行),并指定日志输出路径(便于排查启动问题)。
- 多环境部署隔离:若需区分开发、测试、生产环境,可在 Jenkinsfile 中通过「参数化构建」配置环境参数(如
ENV = dev/test/prod),不同环境对应不同的部署服务器和配置文件。
- 日志排查优先:所有流程失败,优先查看「Console Output」日志,关键错误信息会标红;常见错误:Git 仓库访问失败(凭证错误、网络不通)、Maven 命令错误(工具未配置、依赖缺失)、SSH 连接失败(服务器 IP/密码错误、端口未开放)。
五、常见问题排查
5.1 问题 1:Git 拉取代码失败
- 现象:日志显示「Permission denied (publickey)」或「Could not read from remote repository」。
- 排查:
- 验证 Jenkins 服务器的 SSH 公钥是否已添加到 Git 仓库(重新添加公钥测试)。
- 检查 Jenkins 中配置的 Git 凭证是否正确(重新添加凭证,选择正确的密钥/账号密码)。
- 测试 Jenkins 服务器是否能直接拉取代码:在 Jenkins 服务器执行
git clone 仓库地址,若失败则排查网络或权限问题。
5.2 问题 2:Maven 构建失败,提示'mvn: 未找到命令'
- 现象:日志显示「mvn: command not found」。
- 排查:
- 检查 Jenkins「全局工具配置」中是否正确配置了 Maven 路径(MAVEN_HOME)。
- 在 Jenkins 服务器执行
echo $PATH,确认 Maven 的 bin 目录(如 /usr/local/apache-maven-3.8.8/bin)已添加到环境变量。
- Freestyle 项目中,确认构建步骤选择的是「Invoke top-level Maven targets」(而非直接执行 shell 命令
mvn)。
5.3 问题 3:部署后服务未启动
- 现象:Jenkins 日志显示部署成功,但部署服务器无项目进程。
- 排查:
- 登录部署服务器,查看日志文件
nohup.out,排查启动错误(如端口被占用、配置文件错误、依赖缺失)。
- 验证 jar 包是否上传成功(进入部署目录,查看 jar 包是否存在,大小是否正常)。
- 检查部署命令中的 jar 包名称是否正确(与实际上传的 jar 包名称一致)。
六、总结
本文覆盖了 Java/Maven 项目 + Git 源码管理 + Jenkins 自动化构建部署的全流程,核心分为三个层面:
- 基础层:环境准备(Jenkins 部署、插件安装、工具配置)和权限配置(Git、部署服务器),是流程稳定运行的前提。
- 实践层:Freestyle 模式适合新手快速上手,Pipeline 模式适合企业级复杂流程,可根据项目规模选择。
- 优化层:通过环境变量、凭证管理、多环境隔离、日志告警等,提升流程的健壮性和可维护性。
按照本文步骤配置后,即可实现「代码提交→自动构建→自动部署」的全链路自动化,减少手动操作,提升开发部署效率。若项目有特殊需求(如多模块构建、Docker 容器化部署、K8s 部署),可基于本文基础进行扩展。