简介：这是一份面向DevOps工程师、研发及运维人员的Jenkins CI/CD实战指南，源自Packt Publishing经典书目第三版，内容包含从本地构建到生产部署的全流程实践。全书重点讲解如何搭建安全、弹性且成本可控的持续集成流水线，并贯穿自动化测试、安全扫描与部署策略等关键环节。资源采用PDF格式，共1个文件，包体大小约20.13MB，适合希望系统掌握Jenkins核心操作及DevOps最佳实践的读者阅读。目前已有47人浏览学习，文件排版清晰、章节完整，既可作为工具手册随时查阅，也可作为团队内部培训的参考资料。通过阅读本书，读者能够理解CI/CD体系中的角色分工，学会利用Jenkins Pipeline实现代码提交后的自动构建、测试、制品管理与部署，并结合实际案例排查流程中的常见问题，同时将安全能力融入交付链路，显著提升软件交付效率。建议配合本地搭建的Jenkins环境边读边练，以更好吸收书中示例与排错思路。

1. 先搞懂持续集成与部署解决什么问题，再决定要不要上Jenkins

周一早上十点，开发群里的消息开始刷屏：“这个包是不是没更新？”“预发环境还是昨天的代码。”如果你在这样靠人肉打包传服务器的团队待过，就会明白Jenkins持续集成与部署不是“多装一个工具”，而是把“代码合并到主干之后，自动完成构建、测试、归档、发布”这条链路变成一条可重复、可回溯、不依赖某个同事记忆的自动化产线。反直觉的结论是：持续集成的成功标志不是流水线全绿，而是发布当天团队不需要打开任何终端去敲打包命令。

这篇文章写给两类人。一类是团队里刚被安排搭建集成环境的开发者，想用最小成本把Jenkins跑起来；另一类是已经用了一段时间、但每次发版还是战战兢兢的维护者，想搞明白参数怎么调、故障怎么排查。我会按一条完整路径来讲：先搭环境、再写Pipeline、然后解决部署和回滚、最后列高频踩坑记录。所有示例都以“能复现”为准，不写那些只能在PPT里好看的演示。

2. 环境搭建与全局配置：从装好到能跑流水线要定的四件事

Jenkins本身不复杂，复杂的是它的运行环境。我第一次给内部项目配Jenkins时，光是插件就装了十几个，结果每次启动都要等很久，构建队列还经常卡死。后来把所有插件清掉，只留核心的几个，整个世界安静了。这一章先解决“装好之后该干什么”，再讲凭据和全局工具链，这些决定你后面写流水线是顺风顺水还是一路踩坑。

2.1 安装与初始化：包管理器安装之后，第一次登录先做这三件事

常见做法是在一台Linux服务器上用包管理器安装。以Debian系发行版为例，安装命令大致是：

sudo apt update sudo apt install openjdk-17-jre-headless jenkins sudo systemctl enable --now jenkins sudo cat /var/lib/jenkins/secrets/initialAdminPassword

逻辑说明：Jenkins是Java应用，必须先装JRE。enable --now让服务开机自启并立即启动。初始管理员密码会写入/var/lib/jenkins/secrets/initialAdminPassword，用cat读取后到Web界面粘贴。端口默认8080，第一次访问会进入初始化向导。

参数说明：如果你的服务器内存只有2GB，建议把JVM堆内存调小一点，在/etc/default/jenkins里设置JAVA_ARGS="-Xms256m -Xmx512m"，否则光Jenkins自己就把内存吃光了。插件安装那一步要果断选“跳过”，后面只装需要的，别贪多。

初始化之后有三件事我建议立即做。第一，在“系统管理→系统配置”里把Jenkins URL改成IP或域名，很多webhook失败都是因为URL还留在localhost。第二，创建管理员账号后，把匿名用户的读权限关掉，避免整个内网都能看构建日志。第三，设置构建历史保留策略，我一般保留最近30天或最近50次构建，磁盘爆掉多半是没人管历史产物。

2.2 凭据与权限：把密码从构建脚本里赶出去

很多团队的Jenkinsfile里还写着明文密码，例如sshpass -p '123456'。这种做法在内部网络可能一时没事，但一旦代码仓库权限没控好，就等于把生产服务器的钥匙贴在了公告栏。Jenkins的凭据库就是干这个的：把密码、Token、密钥文件存到Jenkins里，流水线通过ID引用，仓库里没有秘密。

凭据的创建方法是：系统管理→凭据→系统→全局凭据→添加凭据。类型选“Username with password”或“SSH key”，关键是记住凭据ID，代码里要用。引用的写法如下：

pipeline { agent any environment { // DEPLOY_SSH_PASSWORD 是凭据ID，运行时会被注入成变量 DEPLOY_SSH_PASSWORD = credentials('deploy-ssh-password') DEPLOY_HOST = '192.0.2.10' DEPLOY_USER = 'deploy' } stages { stage('Deploy') { steps { sh ''' set -e sshpass -p "${DEPLOY_SSH_PASSWORD}" ssh -o StrictHostKeyChecking=no ${DEPLOY_USER}@${DEPLOY_HOST} \ "systemctl stop app && cp /opt/app/app.jar /opt/app/app.jar.bak" sshpass -p "${DEPLOY_SSH_PASSWORD}" scp target/app.jar ${DEPLOY_USER}@${DEPLOY_HOST}:/opt/app/app.jar sshpass -p "${DEPLOY_SSH_PASSWORD}" ssh ${DEPLOY_USER}@${DEPLOY_HOST} "systemctl start app" ''' } } } }

逻辑说明：credentials('deploy-ssh-password')会在运行时把该ID对应的密码注入到DEPLOY_SSH_PASSWORD变量里。构建日志只显示变量引用，不显示实际密码，这是凭据库最基本的安全收益。StrictHostKeyChecking=no是为了避免首次SSH连接时出现交互式确认把流水线卡住，真正严格的环境应该把目标服务器的公钥提前写入known_hosts。

参数说明：凭据ID建议用环境-用途-类型这样的命名方式，例如prod-ssh-password、staging-api-token。后续维护多个环境时，看到ID就知道是什么。另外注意credentials()注入的变量如果包含用户名:密码格式，普通密码用credentials()没问题，但碰到特殊字符多的Token，建议改用withCredentials块做更精确的控制。

2.3 全局工具链：JDK、Maven、Git与四个容易被忽略的开关

全局工具配置是新手最容易忽略的一环。很多人在构建节点上手动装了JDK和Maven，然后在Jenkinsfile里写死路径，结果换一台Agent就报“找不到mvn”。正确做法是在“系统管理→全局工具配置”里统一声明工具链，由Jenkins自己管理版本和路径。

下面是四个我每次搭环境都会调的开关，表格里给了推荐值：

逻辑说明：执行者数量不是越大越好。虽然看起来“并发构建”能提升效率，但在没有独立Workspace策略的情况下，多个构建同时清理和写入同一个目录会引发随机失败。先调成1，等后面有需要再按项目维度开并发。

参数说明：全局工具配置里的“自动安装”会让Jenkins去官方源下载工具，内网环境经常超时。我在内网环境一般是手动下载JDK和Maven到指定目录，然后在这里填路径，禁止Jenkins联网下载。另外“环境变量”里要加PATH，确保流水线里执行mvn、git不用写全路径。

3. 用Jenkinsfile写第一条流水线：最小可用版本与参数化配置

环境搭好之后，最关键的环节就是用Jenkinsfile定义构建过程。Pipeline是Jenkins的核心，它把构建、测试、部署步骤写成一个文本文件，放进代码仓库，这样每次改构建逻辑都走代码评审，而不是在Web界面里点来点去。这一章从选型讲到最小可用版本，再讲参数化，是整篇文章最值得反复看的部分。

3.1 声明式Pipeline和脚本式Pipeline：按团队协作方式做选择

Jenkins Pipeline有两种写法：声明式和脚本式。很多初学者纠结选哪个，我给出一个简单标准：如果你的团队多数人是后来才接触CI/CD，选声明式，它结构固定、可读性强，报错信息也友好；如果流水线里有大量的循环、条件分支、动态计算，脚本式更灵活，但维护成本高。

我的习惯是：整个团队统一用声明式，遇到复杂逻辑就写一个共享库函数，而不是放开让大家写脚本代码。否则半年之后，Jenkinsfile会变成每个人风格不同的 Groovy 拼盘，谁也看不懂。

3.2 最小可用Jenkinsfile：从拉取代码到归档产物的一段完整流水线

下面是一份我平时搭新项目时用的最小模板，包含拉代码、跑测试、打包、归档四个阶段。复制到项目根目录作为Jenkinsfile，然后在Jenkins里新建任务指向它即可。

pipeline { agent any options { timestamps() // 日志加上时间戳，排查时能分清时序 timeout(time: 20, unit: 'MINUTES') // 超时保护，防止构建卡死占着Executor disableConcurrentBuilds() // 同一项目同时只跑一个构建，避免冲突 } environment { APP_NAME = 'order-service' JAVA_HOME = '/usr/lib/jvm/java-17' MAVEN_HOME = '/opt/maven/apache-maven-3.9' } stages { stage('Checkout') { steps { checkout scm // 拉取当前分支最新代码 } } stage('Unit Test') { steps { sh 'mvn test' // 跑单元测试，失败则中断 } } stage('Build') { steps { sh 'mvn clean package' // 打包，跳过测试是因为上面已经跑过 } } stage('Archive') { steps { archiveArtifacts artifacts: 'target/*.jar', fingerprint: true } } } post { always { junit 'target/surefire-reports/*.xml' // 收集测试报告，红色展示在任务页 } failure { echo "构建失败，请查看测试报告定位问题" } } }

逻辑说明：environment里设置的是环境变量，供后续sh步骤调用。checkout scm是声明式Pipeline的内置行为，它会根据任务配置的Git地址自动拉取对应分支，不需要手写git clone。archiveArtifacts把产物归档到Jenkins Master，而不是留在Agent的工作目录，避免Agent清理后产物丢失。fingerprint: true用于生成指纹，后面可以用它追溯某个构建产物来自哪次提交。

参数说明：timeout的单位是MINUTES，时间长短按项目大小调整，普通服务20分钟足够。mvn clean package里我没有加-DskipTests，因为测试阶段已经跑过了，这里重复执行也能保证打包前的代码状态与已测代码一致。如果你的项目同时产生多个jar，artifacts可以写target/*.jar，但要注意归档前清理dubious文件。

3.3 参数化构建与触发策略：版本号、目标环境和定时任务一次配好

固定流程的流水线只能算半自动，真正好用需要支持参数和多种触发方式。参数化构建的作用是让同一套Jenkinsfile在不同环境、不同版本间复用。我常用的是string、choice和booleanParam三种：

pipeline { agent any parameters { string(name: 'VERSION', defaultValue: '1.0.0', description: '本次发布版本号') choice(name: 'ENV', choices: ['test', 'staging', 'prod'], description: '目标环境') booleanParam(name: 'RUN_TEST', defaultValue: true, description: '是否执行测试阶段') } stages { stage('Prepare') { steps { echo "准备发布 ${params.VERSION} 到 ${params.ENV}" } } stage('Conditional Test') { when { expression { return params.RUN_TEST } } steps { sh 'mvn test' } } } }

逻辑说明：params是内置的全局对象，${params.VERSION}、${params.ENV}把参数值传到阶段内部。when块做条件执行，比在Groovy里写if/else更符合声明式风格。实际用到部署时，这些参数会被传给发布脚本，实现在不同环境发布不同版本。

触发策略方面，常见的有四种：手动触发、定时触发、轮询SCM、Webhook触发。定时任务用triggers { cron('H 2 * * *') }，表示每天凌晨两点左右跑一次，注意H是Jenkins的哈希值，用来分散负载。Webhook触发适合代码仓库在内网的场景，配置好钩子后每次push会自动触发构建，但需要在Jenkins里设置token，防止外部乱调。

需要特别说明的是cron与pollSCM的区别。cron是到点就构建，不管代码有没有变化；pollSCM是Jenkins定期去仓库看有没有新提交，有变化才构建。如果是想让“提交代码自动触发构建”，正确方式是Webhook，而不是cron。还有一个很容易忽略的坑：定时任务默认不会自动清理历史构建，长时间跑下来磁盘会慢慢变满，配合第2章的构建历史保留策略一起设置。

4. 部署到服务器：脚本放置位置、环境参数与发布闸门

流水线跑到“构建产物归档”这一步，只是半个持续集成。真正落到目标服务器，才是持续部署。很多团队的Jenkins停在“能出包”的阶段，部署依然靠人手动scp到服务器，这就失去了自动化的意义。这一章讲部署脚本放在哪里、环境参数怎么管，以及如何加一道人工审核的闸门。

4.1 部署动作放哪：独立发布脚本加上下游调用，比在流水线里写ssh更稳

部署动作有两种常见写法：第一种是把scp和ssh命令直接写在Jenkinsfile里；第二种是把部署动作写成独立的shell脚本，放进应用仓库或运维仓库，Jenkinsfile里只负责调用它。我强烈推荐第二种。

一个独立的deploy.sh大致长这样：

#!/usr/bin/env bash set -euo pipefail # 参数：应用名、目标环境、jar包路径 APP_NAME="${1:-app}" ENV="${2:-test}" JAR_FILE="${3:-target/app.jar}" DEPLOY_DIR="/opt/${APP_NAME}" BACKUP_DIR="${DEPLOY_DIR}/backup" echo "开始部署 ${APP_NAME} 到 ${ENV} 环境" systemctl stop "${APP_NAME}" # 清理旧备份，保留最近两个版本 mkdir -p "${BACKUP_DIR}" if [ -f "${DEPLOY_DIR}/${APP_NAME}.jar" ]; then mv "${DEPLOY_DIR}/${APP_NAME}.jar" "${BACKUP_DIR}/${APP_NAME}-$(date +%Y%m%d%H%M%S).jar" ls -t "${BACKUP_DIR}"/*.jar | tail -n +3 | xargs rm -f fi cp "${JAR_FILE}" "${DEPLOY_DIR}/${APP_NAME}.jar" systemctl start "${APP_NAME}" echo "部署完成"

逻辑说明：set -euo pipefail让脚本在出现任何错误或未定义变量时立即退出，避免半成品部署被误判成功。先停服再替换jar，再启动，这是Java应用最常见的平滑切换方式。备份只保留最近两个版本，防止备份目录无限膨胀。

参数说明：脚本的三个参数分别是应用名、环境和产物路径，流水线里通过参数传过来。这样同一个脚本可以同时给test、staging、prod三个环境用，只是传入的ENV不同。Jenkinsfile里调用它的地方就变成了一个简单的sh步骤，本质上比直接在流水线里写一长串ssh命令干净得多。

4.2 环境信息不硬编码：用参数表和配置文件管理测试、预发、生产

部署脚本里最忌讳把IP、端口、用户名写死在代码里。环境一多，改一处漏一处，最后发布错了环境，要找半天原因。我的做法是把环境信息集中到一个配置目录里，每个环境一个文件，部署脚本按参数读取对应文件。

# 配置文件示例：config/test.conf DEPLOY_HOST=192.0.2.20 DEPLOY_USER=deploy APP_PORT=8080 JVM_HEAP="-Xms256m -Xmx1024m"

# 脚本中读取配置的片段 source "config/${ENV}.conf" echo "目标主机: ${DEPLOY_HOST}:${APP_PORT}"

逻辑说明：source命令把配置文件中的变量导入当前shell环境，后续所有命令都能直接使用。这样新增环境只需要新建一个conf文件，不需要改脚本逻辑，也不会把不同环境的配置混在一个文件里改乱。

参数说明：配置文件的命名与ENV参数强一致，Jenkinsfile里不允许出现具体IP。这样可以保证同一个流水线在test环境验证过之后，切到prod只是换个参数，执行的动作是同一套逻辑，不会出现“测试环境手写命令，生产环境忘改IP”的低级事故。

4.3 发布闸门与回滚：input人工确认和备份还原的工程实践

持续部署不等于“全自动发布生产”。我见过很多团队把生产也做成全自动，结果一次误触发直接导致线上故障。合理的做法是：非生产环境可以全自动流转，生产环境加一道人工确认闸门。用声明式Pipeline的input指令实现：

stage('Pre Prod Check') { when { environment name: 'ENV', value: 'prod' } steps { input message: "确认发布到生产环境？本次版本：${params.VERSION}", ok: '开始生产发布', parameters: [ booleanParam(defaultValue: false, name: 'confirm', description: '我已确认操作时间窗') ] } }

逻辑说明：input会让流水线暂停，等待人工点击确认。点击后流水线继续，点击中止则发布中断。when限定了只有ENV=prod才会出现这个阶段，测试环境发布不会受打扰。

回滚也是部署里绕不开的话题。部署脚本里做了备份，回滚动作就很简单，在脚本中加一个rollback参数分支：

if [ "${1}" = "rollback" ]; then ROLLBACK_JAR=$(ls -t "${BACKUP_DIR}"/*.jar | head -1) cp "${ROLLBACK_JAR}" "${DEPLOY_DIR}/${APP_NAME}.jar" systemctl start "${APP_NAME}" exit 0 fi

逻辑说明：回滚的本质是找到最近一次备份并恢复。ls -t按时间倒序排列，head -1取最新备份。这里需要注意：如果部署后应用运行了一段时间才被发现异常，最新备份可能已经是坏版本，回滚的目标应该是更早的备份。因此备份保留数量不要只留一个，建议像前面脚本那样保留最近三个左右。

参数说明：生产发布时，Jenkinsfile里建议把confirm参数设成“必须勾选才能继续”，比单纯的点击按钮多一层显式确认。另外input有一个缺点：如果没人点，它会一直卡在队列里占用Executor。配合第2章建议的timeout设置，给整个流水线加超时，防止周五下班忘记确认，周一回来卡死所有构建。

5. 避坑手册：Jenkins持续交付里最常见的五个故障排查记录

Jenkins用的时间越长，越会发现很多问题不是技术复杂，而是细节没做好。我整理了自己踩过和帮同事排过的五个高频故障，按“现象→原因→解决”的方式记录。每条都有明确的排查入口，比在网上翻半天答案高效。

5.1 测试环境偶发拿到旧包，构建历史看起来却全绿

现象：流水线显示成功，测试人员说测试环境跑的还是上个版本的功能。回看构建日志，打包时间确实是新的，但目标服务器上的jar始终是旧时间戳。

原因：最常见的是构建节点和目标服务器存在多个目录，发布脚本读取的jar路径配置串了，或者agent上Workspace清理不干净，旧文件被残留备份重新拷贝覆盖。更隐蔽的情况是服务器时间不对，文件时间戳看起来旧，实际内容已更新。

解决：第一步，登录目标服务器检查实际运行的jar路径和启动命令里的路径是否一致，用realpath查看软链接目标。第二步，在发布脚本里增加版本校验，部署前读取jar包内的META-INF/MANIFEST.MF并打印，部署后再校验一次。第三步，确认目标服务器用NTP同步时间，避免时间漂移导致日志与构建时间对不上。

5.2 日志里的中文全变乱码，测试报告文件名也跟着乱

现象：构建日志里的中文显示成??或乱码，JUnit测试报告里带中文用例名全丢，看不了失败详情。

原因：Jenkins自身编码不是UTF-8，或者Agent节点上的文件编码与Master不一致。很多项目在Windows或GBK编码环境下写代码，Maven打包时未指定编码，默认用了系统编码。

解决：在启动Jenkins的JVM参数里显式指定-Dfile.encoding=UTF-8，同时把Maven的pom.xml里project.build.sourceEncoding设为UTF-8。更保险的做法是在Jenkinsfile的构建命令前加一句export JAVA_TOOL_OPTIONS="-Dfile.encoding=UTF-8"，确保子进程也继承相同编码。改完之后，清掉历史构建重新跑一次验证，老日志不需要管。

5.3 服务器重启后构建队列卡住，定时任务反复排队

现象：一台Agent重启之后，Jenkins上的构建任务开始排队不执行，点进去显示“Waiting for next available executor”，甚至多次重启后任务越积越多。

原因：Agent断开后，Jenkins没有自动清理掉旧的Executor记录，导致节点状态显示在线但实际连接已断开。定时任务设置的并发锁还占着，新的构建进不来。

解决：节点管理里把该Agent标记为“断开”，等待Jenkins释放Executor之后重新连接。同时给Jenkinsfile加上disableConcurrentBuilds()和timeout，防止一个挂死的构建永久占坑。长期维护建议：给Agent配置进程守护，并开启Jenkins的“节点离线自动恢复”相关配置，减少人工介入。

5.4 内网环境依赖下载超时，Maven构建频繁失败

现象：构建报错Could not transfer artifact ... Connection timed out，多台机器随机失败，增量构建偶尔能过，全量构建必挂。

原因：Maven仓库配置默认指向公网中央仓库，内网出口带宽不稳定，传大jar包时连接超时。还有可能是某个插件或依赖只存在于特定仓库，没配置镜像源。

解决：在内网搭建Maven私服，设置settings.xml的mirrorOf为central，让所有中央仓库请求走本地镜像。如果暂时没有私服，临时方案是在Jenkins的MAVEN_OPTS里加上超时参数并开启重试机制，但这不是长久之计。还要注意私服配置不要只放在Jenkins这台机器上，开发者本地也要同步，否则会出现“Jenkins能构建、本地构建失败”的奇怪现象。

5.5 并发构建互相污染，Workspace残留让构建时好时坏

现象：同一个项目，单独构建每次都成功，两个构建同时跑就出现随机编译报错。更奇怪的是，有时候改了代码却不生效，构建产物里混着旧内容。

原因：多个Executor共享同一个Workspace目录，并行构建时一个在清理，另一个在写文件，互相踩踏。另外构建完成后没有清理Workspace，下一次构建开始时目录里还残留着上一次的class文件，增量编译时没用新代码。

解决：项目级加上disableConcurrentBuilds()，彻底禁掉同一项目的并发。在Jenkinsfile的post里增加cleanWs()清理工作区，或者用deleteDir()。如果团队确实需要并发，为每个分支配置独立的Workspace，用String BUILD_TAG区分目录。这里有一个血泪经验：无论哪种方案，发布前的最终构建请不要开启增量编译，打包阶段用mvn clean package，保证产物是全新的。

6. 进阶习惯：用构建指纹和发布检核把一次发布压到三次点击

前面几章解决了“怎么搭、怎么写、怎么避坑”，最后一章讲怎么验证这套机制真的可靠。很多团队的流水线看起来绿油油，真到发版还是手忙脚乱，原因是没有建立“发布信任”。我给一个具体方法：让一次发布只靠Jenkins界面三次点击完成，并且每次都要能看到本次发布对应的源码提交。

6.1 用构建指纹核对每次发布对应的源码提交

在Jenkinsfile里开启fingerprint: true之后，每次构建产物会生成一个指纹，指纹里记录了产物来自哪次提交、被哪个构建使用过。发布之后，我一般会打开产物的指纹页面，确认它对应的上游提交号与代码仓库里合并到主干的最新提交一致。这一步是发布前的核心核对项，比看一眼“构建成功”四个字可靠得多。

配合指纹，在流水线里把提交号写进产物名也是一个好习惯。例如归档命名用${APP_NAME}-${params.VERSION}-${GIT_COMMIT_SHORT}.jar，这样传到服务器上光看文件名就能知道是哪个版本哪次提交，排查问题时不需要翻Jenkins历史。Git插件会提供GIT_COMMIT环境变量，取前七位作为短提交号：

environment { COMMIT_SHORT = sh(script: "git rev-parse --short HEAD", returnStdout: true).trim() br /> APP_ARTIFACT = "${APP_NAME}-${params.VERSION}-${COMMIT_SHORT}.jar" }

6.2 给自己定一个“只靠界面完成一次发布”的验证习惯

我自己的习惯是：每个迭代挑一次发布，全程只在Jenkins的Web界面操作，不打开终端。流程是固定的：先点开构建历史，确认本次发布触发了对应分支的构建；再检查指纹，确认提交号正确；然后跑一遍非生产环境的流水线，确认测试、打包、部署三个阶段都完成；最后走到生产环境的input闸门，核对版本号和确认勾选框，点击开始发布。发布完成后，再回到指纹页面，看生产服务器上记录的指纹是否与本次构建产物匹配。

这套流程第一次跑通常会暴露不少问题：可能有某个环境没接流水线，可能有人绕过了闸门手动部署，也可能构建产物根本没被生产服务器使用。把这些洞都补上之后，发布就成了一个大多数时候不需要人盯着的动作。我见过一个内部项目从“发版当天全员在线盯群”变成“发布只需要一个值班人点三次按钮”，靠的不是更复杂的自动化平台，而是把这套Jenkins持续集成与部署的链路做扎实，并养成了每次发布都验证指纹的习惯。希望这篇实战笔记能帮你少走几个弯路，也希望你能尽早体验那种“点了开始发布之后可以安心去接杯水”的踏实感。

本文还有配套的精品资源，点击获取