1.1 自由风格项目最让我头疼的三个场景先说结论我个人完全赞成在绝大多数新建项目里用 Pipeline 替代传统的自由风格项目Freestyle Project。请注意我不是说自由风格项目一无是处而是它到一定规模之后维护成本会急剧上升。我最早接触 Jenkins 时用的就是自由风格项目界面上一堆勾选框构建、后置操作、邮件通知、归档产物全部靠鼠标点点点。前几十个 Job 还好一旦规模上来三个场景会立刻让你焦头烂额第一个是部署流程不可见。自由风格项目的构建过程就是一个黑盒你说不清当前构建走到哪一步了。尤其是那种构建后操作里串了很多脚本的 Job一旦出问题排查起来只能看控制台日志慢慢翻每一步执行了什么、卡在哪里完全靠猜。第二个是配置即资产改起来有心理负担。自由风格项目的所有配置都存在 Jenkins 的 config.xml 里团队成员想改一个步骤只能进 Web 界面点改完还不能走代码评审。哪天 Jenkins 服务挂了、数据目录损坏恢复这套配置简直是噩梦。第三个是环境迁移极麻烦。Jenkins 从一台机器迁到另一台或者从测试环境迁到生产环境自由风格项目很难做到拷贝即用。插件版本不一致、全局配置丢失、路径写死各种问题层出不穷。这三个痛点叠加起来团队越大越明显。后来我切到 Pipeline 之后感受最深的不是自动化跑通了而是整个部署流程从散落在 UI 里的勾选变成了代码仓库里一份可评审、可追溯的部署说明书。1.2 Pipeline 的思维转变把部署当代码写很多人第一次接触 Jenkins Pipeline 会困惑它和以前的 Job 到底有什么区别我的理解是自由风格项目是在配置一件事而 Pipeline 是在描述一条流程。Pipeline 把你在 Jenkins 里要做的事情变成一段文本Groovy 语言描述的 DSL这段文本可以放到 Git 仓库里进行版本管理可以走 Merge Request 评审可以随项目代码一起升级。这个理念现在大家叫 Pipeline as Code本质上是把 DevOps 工程实践和软件工程实践对齐。这个转变不仅仅是形式上的。把它当代码写之后你自然就会开始思考几个以前根本不会想的问题这条流水线有哪些阶段每个阶段需要什么环境哪些环境变量需要外部注入失败之后怎么收场构建产物怎么归档这些思考过程本身就能让部署流程变得严谨很多。而且 Pipeline 的灵活性远超自由风格项目。你可以用条件判断决定某个阶段是否执行可以并行跑测试可以在不同 agent 上调度任务可以跟 Git 分支策略联动。自由风格项目做到这些会非常别扭Pipeline 却几乎是为这些场景量身定制的。1.3 什么时候你暂时不需要 Pipeline坦白说Pipeline 不是银弹短平快的场景没必要硬上。我自己的判断标准是这样的如果你的项目只需要做拉代码 编译 归档产物今天建明天用团队就你一个人维护那自由风格项目完全够用不用为了用 Pipeline 而用 Pipeline。学 Pipeline 有学习成本尤其是刚开始接触 Groovy DSL 的时候明明几行脚本能搞定的事折腾半天 Pipeline 语法确实挫败感很强。但只要你满足下面任意一条我建议你直接切 Pipeline第一部署流程超过五个步骤而且这五个步骤里还有判断和循环第二需要跟多个环境测试、预发布、生产联动第三希望部署流程能版本化管理并且经过 Code Review第四需要在多个 Jenkins 实例或团队之间复用部署逻辑。我自己切 Pipeline 的导火索是有一次生产环境回滚我在自由风格项目里一层一层翻历史配置翻到最后发现某个关键的构建后操作在两个月前被某个同事不小心改掉了谁都没注意到。当时我就下定决心这种看不见摸不着的配置不能再用了。2. 声明式还是脚本式我选择声明式的理由以及两者的本质差异Pipeline 脚本有两种书写风格声明式Declarative和脚本式Scripted。这俩的差异如果你没搞明白后面写脚本时大概率会被各种语法错误折磨到怀疑人生。2.1 声明式是一条规定动作的流水线脚本式是一份 Groovy 程序声明式 Pipeline 的语法结构是固定的你必须在规定的位置填内容比如pipeline块里必须声明agentstages里必须声明stagestage里必须声明steps。写的时候有种填表格的感觉虽然灵活度受限但结构一目了然出错早IDE 提示友好团队成员不容易写出风格迥异的脚本。脚本式 Pipeline 就不一样了它本质就是一段 Groovy 代码没有那么多硬性结构想怎么写就怎么写。看起来自由度很高但实际上很容易写出一堆不可维护的逻辑而且报错信息往往不够直观。我见过有人把脚本式 Pipeline 写成几百行的 Groovy 类——对于大部分团队来说这种复杂度根本没必要。这里用一个表格快速对比对比维度声明式 Pipeline脚本式 Pipeline语法结构固定模板段落清晰自由 Groovy 代码学习曲线低基本靠查文档就能写高需要熟悉 Groovy代码评审体验结构一致评审容易风格差异大评审心累动态逻辑支持支持但有限制完全自由官方推荐程度官方主推官方建议只在复杂场景用适用场景绝大多数 CI/CD复杂流程编排工具类逻辑我个人的结论很直接除非你确实需要大量自定义函数、循环、异常捕获等复杂逻辑否则一律用声明式 Pipeline。声明式写法会让你自然而然地把每个阶段要做什么清晰表达出来这比炫技重要得多。2.2 一个最小声明式 Pipeline 的基本骨架先看一个最基础的声明式 Pipeline 骨架我建议所有人都把这个结构背下来它几乎是所有后续复杂写法的地基pipeline { agent any stages { stage(Checkout) { steps { echo 拉取代码 } } stage(Build) { steps { echo 构建中 } } stage(Test) { steps { echo 测试中 } } } }这个骨架里有三个核心部分agent决定在哪个执行环境里跑stages里按顺序列出各个阶段stage里是每个阶段的名字这个名字会显示在 Jenkins Web 界面上steps里是具体的操作命令。你先把这个结构跑通后面再往steps里面塞真实的构建命令、部署命令思路就会很清晰。我不建议一上来就啃完整语法手册先用最小骨架跑通一次再去查具体指令效率会高非常多。2.3 什么时候需要回到脚本式声明式 Pipeline 虽然好用但确实有些场景力不从心。比如你想在流水线里导入第三方库或者写很多分支判断和循环逻辑又比如你需要把某个复杂的部署逻辑封装成一个可复用的工具方法这时候声明式的script块可以帮你包裹一些 Groovy 代码但如果你发现自己需要大量使用script块那不如干脆整体用脚本式。我现在的习惯是默认声明式遇到特别复杂的流程再单独评估。如果流程的复杂度已经高到声明式很难表达那么问题大概率不在语法而在于流程本身该拆分了——这种时候强行用一段脚本式大 Pipeline 包打天下后期维护比拆分成多个服务或子流水线还要痛苦。3. 声明式 Pipeline 的核心指令覆盖日常自动化 90% 场景的语法清单在完整讲语法之前先给个心态建设Pipeline 语法看着多但你日常用到的最多十来个指令。我把这些指令按用途分了几组每一组搞明白基本上就能覆盖大多数自动化需求了。3.1 pipeline、agent、stages、steps四个必须搞明白的顶层指令pipeline声明式 Pipeline 的根节点所有内容都包裹在里面。agent指定流水线的执行节点。agent any表示任意可用的执行节点agent { label docker }表示使用带有docker标签的节点agent { docker { image maven:3.8 } }则表示直接在 Docker 容器里跑这个我在后面容器化构建章节会专门展开。stages阶段集合流水线的主体部分。stage一个阶段必须有名字。建议起名时带上明确的动词比如Build、Test、Deploy而不是Step1、Step2这样构建进度页在视觉上更容易看懂。steps阶段内的具体步骤一行一步。这里的命令可以直接是sh、echo、bat也可以是调用其他插件提供的方法比如withCredentials、junit等。这里有一个初学者特别容易踩的坑在声明式 Pipeline 的steps里多个sh步骤之间要保证每个sh都是独立的一次 shell 调用默认工作目录是一样的但环境变量不一定继承。如果你需要在一个上下文中执行多行 shell可以写成一个sh指令里面用换行符分隔或者直接写一个打包脚本文件。否则你会发现上一个sh里export的变量下一个sh里根本读不到。3.2 environment 的环境变量管理不要把秘密塞进 Jenkins 配置environment指令用来设置环境变量它既可以放在pipeline顶层做全局变量也可以放在stage内部做阶段局部变量。我常用的写法有两种pipeline { agent any environment { APP_NAME demo-app VERSION 1.0.0 } stages { stage(Build) { environment { BRANCH main } steps { echo 构建 ${APP_NAME}:${VERSION} } } } }关于敏感信息密码、Token、密钥我强烈建议不要直接写在脚本里也不要写进 Jenkins 的系统配置里明文保存。Jenkins 提供了Credentials凭据管理Pipeline 里通过withCredentials来引用。比如我们要拉取私有仓库代码或者推送镜像到私有仓库stage(Build) { steps { withCredentials([string(credentialsId: dockerhub-token, variable: DOCKER_TOKEN)]) { sh docker login -u myuser -p $DOCKER_TOKEN registry.example.com } } }这种做法的好处是什么凭据加密存储在 Jenkins 里代码库里只出现一个credentialsId即使 Pipeline 脚本泄露也不会直接暴露密码。而且凭据可以在 Jenkins 全局统一管理过期轮换时不用改代码。关于环境变量还有一个很多人忽略的点environment里的字符串内容是支持$引用的但如果你在双引号里引用 Groovy 变量需要区分 Groovy 字符串插值和 Shell 环境变量。比如echo 版本是 ${env.VERSION}和sh echo $VERSION是完全不同的东西。3.3 post 块与构建状态处理成功、失败、始终三种情况都要考虑post块是声明式 Pipeline 最好用的特性之一它让你可以针对构建的不同结果给出一套收尾动作。常见的条件有success、failure、unstable、always四种用法示例pipeline { agent any stages { stage(Build) { steps { sh make build } } } post { always { cleanWs() } success { echo 构建成功开始后续处理 } failure { echo 构建失败请查看日志 } } }很多人写流水线只顾着定义stages完全不写post。结果是构建失败后工作区里残留一堆文件下次构建时状态不干净导致各种诡异问题。我现在写任何 Pipeline 都会强制要求有always收尾至少把工作区清理掉。post块还有一个隐藏价值它可以跟构建状态联动做通知。比如failure里调用企业微信、钉钉、邮件插件发送通知success里归档产物。把通知逻辑集中在post里比之前自由风格项目里到处配邮件通知要清爽得多。3.4 parameters 与 triggers手动、定时、SCM 触发怎么选流水线的触发方式也是常见到爆炸的需求。声明式 Pipeline 里手动触发参数用parameters定义定时触发和代码变更触发用triggers定义。先看parameters。它的作用相当于在自由风格项目里勾选参数化建构过程pipeline { agent any parameters { string(name: ENVIRONMENT, defaultValue: dev, description: 部署环境) choice(name: DEPLOY_MODE, choices: [rolling, recreate], description: 更新方式) booleanParam(name: SKIP_TEST, defaultValue: false, description: 是否跳过测试) } stages { stage(Deploy) { steps { echo 部署环境${params.ENVIRONMENT} echo 部署方式${params.DEPLOY_MODE} } } } }注意params这个内置对象它承载了所有参数值。使用的时候${params.xxx}如果在 Groovy 字符串插值里记得用双引号。注意不要跟env混了env是 Jenkins 内置环境变量集合params是构建参数集合两个都经常用。再看triggers。声明式 Pipeline 支持几种触发方式triggers { cron(H 2 * * *) pollSCM(H/5 * * * *) }cron是固定时间触发和 Linux crontab 类似但我建议用H这种哈希值让 Jenkins 自动分散负载避免多个 Job 同一秒挤在一起。pollSCM是定时轮询代码仓库发现变更才触发构建。说句题外话轮询 SCM 本质上还是轮询不够实时现在主流的做法是让 Git 服务端配置 Webhook 告诉 Jenkins 有变更了这样效率高很多。Pipeline 本身不做 Webhook 的代码配置但你在 Git 仓库管理后台里创建一个 Jenkins Webhook 地址即可配合triggers里的SCM类型监听对应事件。3.5 options 是 Pipeline 的保险丝options指令用来设置流水线运行时选项我每次新建 Pipeline 都会加上几个保命选项options { timeout(time: 30, unit: MINUTES) buildDiscarder(logRotator(numToKeepStr: 20)) disableConcurrentBuilds() skipDefaultCheckout() }timeout给整个流水线设超时时间防止某个步骤卡死导致构建资源被一直占用buildDiscarder设置构建记录保留数量避免 Jenkins 的构建历史无限膨胀disableConcurrentBuilds禁止同一流水线并发执行非常适合部署类流水线避免两个构建同时操作同一台服务器产生竞态skipDefaultCheckout跳过默认的代码检出适合某些不需要 Jenkins 拉代码、而是靠自己脚本控制的场景。这些选项看着不起眼但都是我在生产环境踩过坑之后才补上的。有一次构建任务因为远端服务无响应流水线整整挂了十个小时才被发现从那以后凡是没有timeout的流水线我都不让上线。4. 实战从零搭建一套 Java 项目的自动构建与部署流水线前面讲了那么多语法很多朋友可能还是觉得虚。这一节我就拿一个真实的、我日常在用的 Java 项目自动化构建部署流程作为例子从需求到完整代码一步步拆给你看。4.1 场景需求假设我们有一个基于 Maven 构建的 Spring Boot 项目需要实现以下自动流程从 Git 仓库拉取指定分支代码使用 Maven 进行编译打包跳过单元测试为了演示加速流程构建 Docker 镜像并推送到私有镜像仓库通过 SSH 登录到测试服务器拉取新镜像并重启容器。这个流程在自由风格项目里至少需要三个 Job 拼接而在 Pipeline 里可以一气呵成。团队最终希望在 Git 仓库里维护这份流水线脚本开发人员只需要关心代码提交部署动作完全自动化。4.2 完整 Jenkinsfile 示例以下是一份可以直接参考的 Jenkinsfile 示例pipeline { agent { docker { image maven:3.8-openjdk-11 args -v /var/run/docker.sock:/var/run/docker.sock -v /root/.m2:/root/.m2 } } options { timeout(time: 30, unit: MINUTES) buildDiscarder(logRotator(numToKeepStr: 30)) disableConcurrentBuilds() } environment { REGISTRY registry.example.com IMAGE_NAME demo-app CONTAINER_NAME demo-app-server } parameters { string(name: BRANCH, defaultValue: main, description: 代码分支) string(name: SERVER_HOST, defaultValue: 10.10.10.10, description: 目标服务器地址) } stages { stage(Checkout) { steps { checkout([$class: GitSCM, branches: [[name: ${params.BRANCH}]], userRemoteConfigs: [[url: gitexample.com:group/demo.git, credentialsId: git-ssh-key]]]) } } stage(Build) { steps { sh mvn -B -DskipTests clean package } } stage(Docker Build Push) { steps { script { def version sh(script: cat pom.xml | grep version | head -1 | sed s/.*version\\(.*\\)\\/version.*/\\1/, returnStdout: true).trim() env.IMAGE_TAG ${params.BRANCH}-${BUILD_NUMBER}-${version} } withCredentials([usernamePassword(credentialsId: registry-auth, usernameVariable: REGISTRY_USER, passwordVariable: REGISTRY_PASSWORD)]) { sh docker login -u ${REGISTRY_USER} -p ${REGISTRY_PASSWORD} ${REGISTRY} docker build -t ${REGISTRY}/${IMAGE_NAME}:${IMAGE_TAG} . docker push ${REGISTRY}/${IMAGE_NAME}:${IMAGE_TAG} } } } stage(Deploy) { when { expression { params.SERVER_HOST ! } } steps { withCredentials([usernamePassword(credentialsId: server-ssh, usernameVariable: SSH_USER, passwordVariable: SSH_PASSWORD)]) { sh sshpass -p ${SSH_PASSWORD} ssh -o StrictHostKeyCheckingno ${SSH_USER}${SERVER_HOST} docker pull ${REGISTRY}/${IMAGE_NAME}:${IMAGE_TAG} docker stop ${CONTAINER_NAME} || true docker rm ${CONTAINER_NAME} || true docker run -d --name ${CONTAINER_NAME} -p 8080:8080 ${REGISTRY}/${IMAGE_NAME}:${IMAGE_TAG} } } } } post { always { cleanWs() } failure { echo 部署失败请检查日志并回滚上一个稳定版本。 } } }别急着复制粘贴这份脚本里有几个地方是故意写成需要你根据实际环境调整的我下面逐个解释。4.3 关键步骤逐行解读先看agent。这里我让流水线直接跑在一个maven:3.8-openjdk-11的 Docker 容器里省去了在 Jenkins 节点上单独安装 JDK 和 Maven 的麻烦。镜像可以按项目需求替换比如前端项目用node:16Python 项目用python:3.9。注意我挂载了/var/run/docker.sock这是为了让容器内的docker命令能够跟宿主机的 Docker 守护进程通信。这一步如果不做后面docker build会报无法连接 Docker daemon。挂载 socket 的方式比 Docker in Docker 轻量很多是当前容器内构建镜像的主流做法但要注意安全能访问 Docker socket 基本等于能控制宿主机所以不要在不可信的 Pipeline 环境里这么干。再看Checkout阶段。这里用checkout步骤手动指定 Git 地址和分支而不是依赖 Jenkins 默认的 SCM 配置好处是我能动态使用params.BRANCH来选择分支。Maven 包里解析版本号的思路是读取pom.xml里的version标签生成镜像标签时把分支、构建号、代码版本拼在一起这样每个镜像都有唯一标识回滚时能直接定位到具体构建。Docker Build Push阶段用withCredentials拉取仓库凭据。镜像标签里我特意用了env.IMAGE_TAG这是通过script块给当前流水线环境变量赋值。注意这里env.IMAGE_TAG是可以在后续 stage 里直接读取的因为env是整个流水线生命周期内可读写的环境变量集合跨 stage 传递参数的首选方式之一。Deploy阶段用了when表达式来判断是否执行部署条件就是参数SERVER_HOST不为空。这样同一个 Pipeline 脚本既能做纯构建不传服务器地址就只构建到镜像推送也能做部署日常非常实用。SSH 远程执行命令这块我用了sshpass配合密码登录如果服务器配置了密钥认证你完全可以不传密码直接指定私钥来连接。生产环境我强烈建议用密钥而非密码登录安全性高一个量级。4.4 与自由风格项目的能力对比如果你之前在自由风格项目里实现这套流程你会发现需要拆分任务一个 Job 做 Maven 构建一个 Job 做 Docker 镜像推送一个 Job 做远程服务器部署三个 Job 之间还要靠复制产物或远程触发来串联。一旦部署顺序要调整就得去三个 Job 的配置里改了一遍又一遍。而 Pipeline 版本把这些流程按顺序写在一个文件里任何一个步骤都是显示的。后期想加一个静默起一个临时容器跑 smoke test直接在Deploy前插入一个新stage就行代码评审也一目了然。这就是我为什么坚持把复杂部署流迁移到 Pipeline 的根本原因。5. 环境变量与内置上下文用好 Jenkins 给你的默认能力Pipeline 真正上手之后你会发现大量时间其实花在跟环境变量和上下文对象打交道。Jenkins 提供了非常多的内置变量和对象用好了能省很多自己解析的功夫。5.1 常用内置环境变量最常见的全局环境变量可以通过${env.变量名}或直接在 Groovy 环境里用env.变量名来访问。下面这些是我几乎每条流水线都会用到的变量名说明使用场景BUILD_NUMBER当前构建编号生成唯一标签BUILD_ID当前构建 ID以前是时间戳定位日志JOB_NAME当前 Jenkins Job 名称日志和通知WORKSPACE当前工作区路径拼接文件路径JENKINS_HOMEJenkins 主目录读取全局配置EXECUTOR_NUMBER当前执行器编号区分并发执行NODE_NAME当前节点名判断执行环境举个例子我要给每个构建生成一个带时间戳的日志文件名可以这样写sh touch build-${BUILD_NUMBER}.logJenkins 内置变量在 Shell 里和 Groovy 里都能访问但注意 Shell 里访问要加$前缀。上面这个写法里BUILD_NUMBER是环境变量所以 Shell 能识别。5.2 params 和 env 的区别与配合这是一个高频混淆点。params是你在parameters指令中定义的构建参数集合而env是 Jenkins 内置环境变量集合。两者之间有一定重叠但含义不同。比如你定义了一个名为BRANCH的参数访问方式应该是${params.BRANCH}但如果你尝试${env.BRANCH}大概率取不到值反过来BUILD_NUMBER你通过${params.BUILD_NUMBER}通常是拿不到的。我习惯的做法是在 Jenkinsfile 开头把需要用的参数统一赋值给局部变量然后再往下用可以有效避免搞混environment { DEPLOY_ENV ${params.ENVIRONMENT} }5.3 currentBuild管道构建状态的核心对象currentBuild是 Jenkins Pipeline 里极其重要的内建对象它代表当前构建的各种元数据。我最常用的是它的result、number、description、absoluteUrl这几个属性。比如我想在构建失败后给企业微信通知里带一个包含构建编号和流水线地址的消息post { failure { script { echo 流水线失败Job ${env.JOB_NAME} 构建 #${currentBuild.number} echo 详情${currentBuild.absoluteUrl} } } }还可以用currentBuild.description动态更新构建描述方便在 Jenkins Web 界面上直接看到这次构建里的关键信息。我在部署流水线里经常这么做currentBuild.description 分支 ${params.BRANCH} - 镜像 ${IMAGE_TAG}这样在构建历史列表里扫一眼就知道每一行构建对应的是什么分支、什么镜像排查问题速度直线提升。5.4 自定义工具路径与环境准备Pipeline 执行时默认加载的是 Jenkins 节点上的 PATH。如果你在某个节点上自定义安装了工具建议在 Pipeline 里显式指定工具路径或者用 Jenkins 的 Tools 配置后通过tool步骤来获取路径。比如配置了 JDK 工具可以这样用stage(Java Env) { steps { script { def javaHome tool name: OpenJDK-11, type: hudson.model.JDK sh JAVA_HOME${javaHome} java -version } } }如果你干脆把整个流水线放进 Docker 容器像我前面 4.2 的示例那样这一步基本可以省略因为镜像里已经装好了全套环境。这也是为什么我越来越喜欢用容器化 agent 的原因团队里不需要每个 Jenkins 节点安装各种版本的工具链一个镜像就能保证环境一致。6. 落地的踩坑清单从 SSH 异常到容器内构建写 Pipeline 这件事语法层面其实不难真正的坑往往是你以为语法没问题了、跑起来却各种告警。我在生产环境里踩过好几轮下面挑最有代表性的五个常见问题分享出来。6.1 SSH 连接异常Connection is not established 的排查路径有朋友在阅读我前面的部署脚本时可能会问为什么不用 Jenkins 自带的 SSH 插件而是自己在 Shell 里 ssh 一把这里我要展开一个非常值得讲的坑。Jenkins 的 SSH 插件SSH Pipeline Steps 或 Publish Over SSH在版本更新过程中我曾经遇到过java.lang.IllegalStateException: Connection is not established!这样的报错。这个报错本身很有意思它不是说你密码错了、也不是说密钥不对而是 SSH 连接对象压根没有建立起链路插件就尝试发送命令了。我排查这个问题的完整链路是这样的第一步先确认是不是网络问题。手动在 Jenkins 机器上用命令行执行ssh userhost echo ok看能不能通。很多情况下这一步就能发现目标服务器的防火墙是否放行、端口是否可达。第二步检查主机密钥校验。新版本的 Jenkins SSH 插件默认会做 known_hosts 校验如果你用的服务器不在 known_hosts 里连接会在第一步就被拒绝表现就是Connection is not established。临时解法是关闭校验-o StrictHostKeyCheckingno长期解法是把目标服务器密钥加入 Jenkins 所在机器的 known_hosts。第三步确认认证方式。如果你的 SSH 插件配置的是私钥但私钥格式不被 JSch 支持比如 OpenSSH 的新格式也会导致连接建立不起来。我见过很多人被这个卡住解法是把密钥转成 RSA 格式或换成密码认证。在走完这三步之后我最终放弃了在 Jenkins 插件层面配置一堆 SSH 服务器转而直接在 Pipeline 里用sshpass ssh命令控制远程执行。这样做的好处是流程完全透明、可复用、不依赖插件自身的连接状态管理。坏处也很明显密码会出现在命令行里所以我总是配合withCredentials把它从 Jenkins 凭据中注入避免明文硬编码。总的来说如果你也频繁遇到 SSH 插件的连接状态问题不妨换这个思路。6.2 容器里调用 Docker 命令socket 挂载与权限处理有一段时间我在 Jenkins 容器里尝试直接执行 Docker 构建经常遇到这个报错Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?这背后的原因很简单容器内的docker命令只是一个客户端它需要跟 Docker daemon 通信而容器内默认根本没有/var/run/docker.sock这个文件。解决办法就是我在 4.3 里提到的启动 Jenkins 容器或 Agent 容器时挂载宿主机的 Docker socketdocker run -d -p 8080:8080 \ -v /var/run/docker.sock:/var/run/docker.sock \ -v /usr/bin/docker:/usr/bin/docker \ jenkins/jenkins:lts挂载之后还要注意宿主机 Docker daemon 的权限。如果容器内用户对 socket 没有访问权限会报 permission denied。一般做法是把 Jenkins 容器内用户加入宿主机 docker 组或者直接调整 socket 文件权限但后者安全性差一点。在生产环境我更推荐的方式是不在 Jenkins 容器里直接操作 Docker而是让流水线跑在带docker命令的专用 Agent 容器上或使用 Kubernetes 动态 Agent。这能让构建环境和Jenkins 控制面彻底分离权限边界清晰出问题也好隔离。6.3 构建目录膨胀与清理这是一个不痛不痒但迟早出事的问题。默认情况下每次构建的产物都会落在WORKSPACE下时间长了磁盘空间会被大量旧产物和陈旧工作区吃掉。我之前给你看的 Pipeline 脚本里post里的cleanWs()就是清工作区用的但光靠它还远远不够。更完整的方案是组合使用两个手段第一Pipeline 里options配置buildDiscarder(logRotator(numToKeepStr: 20))只保留最近 20 次构建记录旧构建的产物自动清理第二管理员层面开启 Jenkins 全局的工作空间清理策略Workspace Cleanup Plugin或者定期跑一个维护 Job把超过 N 天没更新的工作区清掉。我还喜欢把大型中间产物放到构建目录之外比如单独挂载一个数据盘目录然后通过WORKSPACE_TMP或者自定义环境变量来引用。这样最终用户目录和 Jenkins 工作区都不会被巨型产物拖垮。6.4 插件下载慢怎么处理国内团队经常反馈 Jenkins 插件安装慢得让人怀疑人生。这不是 Jenkins 本身的问题而是默认插件源在国外。解决思路很简单把 Jenkins 的升级站点 URL 替换成国内镜像地址。在 Jenkins 的管理插件 - 高级页面有一个升级站点配置项默认值是https://updates.jenkins.io/update-center.json。把它换成国内镜像源的对应地址保存后点击立即检查再用可选插件页签搜索安装就会快很多。具体镜像地址我就不在这里列了大家搜一下Jenkins 国内镜像就能找到选择自己网络环境测试下来最稳定的那个即可。这里有个教训改完镜像源之后如果之前装了一半的插件状态异常最好重启一次 Jenkins 再重新尝试否则可能一直提示某些依赖无效。另外插件版本兼容矩阵也要留意不要盲目把插件全部升到最新版有些插件整体升级后会在 Pipeline 语法上产生 breaking change。6.5 Jenkins 2.x 里的 Kubernetes 配置要点很多团队现在把 Jenkins 的构建节点迁到 Kubernetes 上实现有构建任务时开一个 Pod任务结束自动销毁的效果。这套方案在弹性伸缩和节省成本上非常有优势但初始配置有几个容易错的地方。第一Jenkins 需要安装 Kubernetes Plugin然后在系统配置里添加 Kubernetes Cloud。填 Kubernetes API 地址时如果 Jenkins 部署在集群外部要用集群的 API 外网地址如果 Jenkins 本身在集群内部用 Service DNS 地址即可。填错是连接不上的最常见原因。第二Pod Template 里指定镜像时不要只写一个工具镜像。构建容器通常会需要多个容器协作一个容器跑 Maven一个容器跑 Docker CLI还有一个容器跑 Shell 脚本。Pod Template 支持定义多个 Container每个 Container 有不同的镜像和资源配额。这个设计比单容器 Agent 要灵活很多。第三别漏了 JNLP 容器。Kubernetes 集成里Jenkins Master 是通过 JNLP 协议跟 Agent Pod 通信的Pod Template 里必须有一个 jnlp 容器默认会自动生成。如果你自定义了 Pod Template 却删掉了 jnlp 容器Agent 大概率会一直处于等待连接状态。在我实际配置的过程中最有效的调试手段就是看 Pod 的 Event 日志。如果 Pod 一直 CrashLoopBackOff基本就是镜像拉取失败或者 JNLP 启动命令参数不对。把imagePullPolicy设成IfNotPresent可以避免频繁拉取镜像造成的超时。7. Pipeline as Code把流水线放进 Git 仓库后的三个进阶方向到这里Pipeline 的基本语法和实战套路已经讲得差不多了。最后一个部分我想聊聊进阶方向也是我现在在团队里重点推广的东西。7.1 Jenkinsfile 的存放与多分支策略把 Jenkinsfile 放在项目代码库根目录是目前最主流的方式。好处是流水线跟代码一起演进改部署逻辑就像改代码一样走评审、走标签代码回滚时流水线也跟着回滚不会出现代码回去了、Pipeline 还是新版本的错位。配合多分支流水线Multibranch PipelineGit 仓库的每个分支会自动生成对应的 Jenkins Job。这样你在分支上改 Jenkinsfile直接推上去就能在对应分支的任务里验证效果主分支上的流水线完全不受影响。我先在 feature 分支上调整部署步骤验证通过后再合并到主干部署逻辑的变更风险被压到最低。这里有一个需要注意的细节在 Jenkinsfile 里判断当前分支时别用固定的${env.BRANCH_NAME}硬编码判断它只在多分支流水线里才有意义。如果你的流水线是普通 Pipeline Job 且通过参数指定分支那BRANCH_NAME可能取到的值跟你想的不一样。我通常用params.BRANCH作为分支唯一可信来源在多分支场景里再把BRANCH_NAME映射到params.BRANCH上。7.2 共享库把通用逻辑抽出来当你维护的流水线多起来你会发现大量代码是重复的克隆代码、构建镜像、推送私仓、清理工作区全是同一套逻辑。如果每个 Jenkinsfile 里都复制一份改一处要换遍所有项目非常痛苦。共享库Shared Library就是用来解决这个问题的。你可以在一个独立的 Git 仓库里维护 Jenkins 共享库里面定义一堆可复用的全局变量和函数然后在 Jenkins 的系统配置里把这个仓库注册为 Global Shared Library。之后任何 Pipeline 脚本都可以这么用Library(my-lib) _ pipeline { stages { stage(Build) { steps { buildDockerImage(demo-app) } } } }buildDockerImage这个函数就定义在共享库里所有项目共用同一份实现。改推送逻辑只需改库的代码所有引用它的流水线全部生效。这个抽象层级我建议循序渐进一开始别过度设计等确实有两三个项目复用同一段逻辑时再抽共享库否则你会为了抽象而抽象反而增加了维护成本。7.3 AI 辅助生成和排查 Pipeline说句实在话Pipeline 语法虽然不复杂但刚开始写的时候查文档查得还是有点烦躁。现在很多 AI 辅助编程工具已经能比较准确地根据需求生成 Jenkinsfile 了比如写一个基于 Maven 的 Java 项目 Jenkinsfile要求构建 Docker 镜像并推送到私仓AI 能直接给你一份能跑的脚本。我的经验是AI 生成的脚本拿过来后不要直接上线至少要在本地或测试环境跑一次因为生成式 AI 对 Jenkins 插件的具体参数名有时记得并不准确容易产生运行时错误。更实用的场景是用 AI 排查报错。Pipeline 运行报错时把报错日志复制给 AI让它帮你分析是语法错误还是环境问题、提供排查思路这个效率提升是非常明显的。我现在遇到 Jenkins 相关异常时第一个动作就是把完整日志丢给 AI让它给我列出可能原因再逐条对照实际环境验证通常能省掉一半的排查时间。我自己也在持续关注 Jenkins 官方的 AI Agent 插件方向这类工具未来大概率会让 Pipeline 的编写和维护门槛再降一档。7.4 我的实际体会从自由风格项目切到 Pipeline 已经好几年了我最大的体会是Pipeline 给自己带来的不是自动化本身而是部署流程可以像代码一样被思考和演进。自动化程度再高只要流程本身不可见、不可评审、不可版本化它依然是脆弱的。如果你现在还在自由风格项目里挣扎我的建议很简单找一个最简单的项目用声明式 Pipeline 把它重新实现一遍。不用追求一开始就覆盖所有细节先把拉码 - 构建 - 归档这条路跑通然后再一步步加上部署、通知、清理。这个过程走下来你对 Jenkins 的理解会比看任何教程都深得多。 1.1 自由风格项目最让我头疼的三个场景先说结论我个人完全赞成在绝大多数新建项目里用 Pipeline 替代传统的自由风格项目Freestyle Project。请注意我不是说自由风格项目一无是处而是它到一定规模之后维护成本会急剧上升。我最早接触 Jenkins 时用的就是自由风格项目界面上一堆勾选框构建、后置操作、邮件通知、归档产物全部靠鼠标点点点。前几十个 Job 还好一旦规模上来三个场景会立刻让你焦头烂额第一个是部署流程不可见。自由风格项目的构建过程就是一个黑盒你说不清当前构建走到哪一步了。尤其是那种构建后操作里串了很多脚本的 Job一旦出问题排查起来只能看控制台日志慢慢翻每一步执行了什么、卡在哪里完全靠猜。第二个是配置即资产改起来有心理负担。自由风格项目的所有配置都存在 Jenkins 的 config.xml 里团队成员想改一个步骤只能进 Web 界面点改完还不能走代码评审。哪天 Jenkins 服务挂了、数据目录损坏恢复这套配置简直是噩梦。第三个是环境迁移极麻烦。Jenkins 从一台机器迁到另一台或者从测试环境迁到生产环境自由风格项目很难做到拷贝即用。插件版本不一致、全局配置丢失、路径写死各种问题层出不穷。这三个痛点叠加起来团队越大越明显。后来我切到 Pipeline 之后感受最深的不是自动化跑通了而是整个部署流程从散落在 UI 里的勾选变成了代码仓库里一份可评审、可追溯的部署说明书。1.2 Pipeline 的思维转变把部署当代码写很多人第一次接触 Jenkins Pipeline 会困惑它和以前的 Job 到底有什么区别我的理解是自由风格项目是在配置一件事而 Pipeline 是在描述一条流程。Pipeline 把你在 Jenkins 里要做的事情变成一段文本Groovy 语言描述的 DSL这段文本可以放到 Git 仓库里进行版本管理可以走 Merge Request 评审可以随项目代码一起升级。这个理念现在大家叫 Pipeline as Code本质上是把 DevOps 工程实践和软件工程实践对齐。这个转变不仅仅是形式上的。把它当代码写之后你自然就会开始思考几个以前根本不会想的问题这条流水线有哪些阶段每个阶段需要什么环境哪些环境变量需要外部注入失败之后怎么收场构建产物怎么归档这些思考过程本身就能让部署流程变得严谨很多。而且 Pipeline 的灵活性远超自由风格项目。你可以用条件判断决定某个阶段是否执行可以并行跑测试可以在不同 agent 上调度任务可以跟 Git 分支策略联动。自由风格项目做到这些会非常别扭Pipeline 却几乎是为这些场景量身定制的。1.3 什么时候你暂时不需要 Pipeline坦白说Pipeline 不是银弹短平快的场景没必要硬上。我自己的判断标准是这样的如果你的项目只需要做拉代码 编译 归档产物今天建明天用团队就你一个人维护那自由风格项目完全够用不用为了用 Pipeline 而用 Pipeline。学 Pipeline 有学习成本尤其是刚开始接触 Groovy DSL 的时候明明几行脚本能搞定的事折腾半天 Pipeline 语法确实挫败感很强。但只要你满足下面任意一条我建议你直接切 Pipeline第一部署流程超过五个步骤而且这五个步骤里还有判断和循环第二需要跟多个环境测试、预发布、生产联动第三希望部署流程能版本化管理并且经过 Code Review第四需要在多个 Jenkins 实例或团队之间复用部署逻辑。我自己切 Pipeline 的导火索是有一次生产环境回滚我在自由风格项目里一层一层翻历史配置翻到最后发现某个关键的构建后操作在两个月前被某个同事不小心改掉了谁都没注意到。当时我就下定决心这种看不见摸不着的配置不能再用了。2. 声明式还是脚本式我选择声明式的理由以及两者的本质差异Pipeline 脚本有两种书写风格声明式Declarative和脚本式Scripted。这俩的差异如果你没搞明白后面写脚本时大概率会被各种语法错误折磨到怀疑人生。2.1 声明式是一条规定动作的流水线脚本式是一份 Groovy 程序声明式 Pipeline 的语法结构是固定的你必须在规定的位置填内容比如pipeline块里必须声明agentstages里必须声明stagestage里必须声明steps。写的时候有种填表格的感觉虽然灵活度受限但结构一目了然出错早IDE 提示友好团队成员不容易写出风格迥异的脚本。脚本式 Pipeline 就不一样了它本质就是一段 Groovy 代码没有那么多硬性结构想怎么写就怎么写。看起来自由度很高但实际上很容易写出一堆不可维护的逻辑而且报错信息往往不够直观。我见过有人把脚本式 Pipeline 写成几百行的 Groovy 类——对于大部分团队来说这种复杂度根本没必要。这里用一个表格快速对比对比维度声明式 Pipeline脚本式 Pipeline语法结构固定模板段落清晰自由 Groovy 代码学习曲线低基本靠查文档就能写高需要熟悉 Groovy代码评审体验结构一致评审容易风格差异大评审心累动态逻辑支持支持但有限制完全自由官方推荐程度官方主推官方建议只在复杂场景用适用场景绝大多数 CI/CD复杂流程编排工具类逻辑我个人的结论很直接除非你确实需要大量自定义函数、循环、异常捕获等复杂逻辑否则一律用声明式 Pipeline。声明式写法会让你自然而然地把每个阶段要做什么清晰表达出来这比炫技重要得多。2.2 一个最小声明式 Pipeline 的基本骨架先看一个最基础的声明式 Pipeline 骨架我建议所有人都把这个结构背下来它几乎是所有后续复杂写法的地基pipeline { agent any stages { stage(Checkout) { steps { echo 拉取代码 } } stage(Build) { steps { echo 构建中 } } stage(Test) { steps { echo 测试中 } } } }这个骨架里有三个核心部分agent决定在哪个执行环境里跑stages里按顺序列出各个阶段stage里是每个阶段的名字这个名字会显示在 Jenkins Web 界面上steps里是具体的操作命令。你先把这个结构跑通后面再往steps里面塞真实的构建命令、部署命令思路就会很清晰。我不建议一上来就啃完整语法手册先用最小骨架跑通一次再去查具体指令效率会高非常多。2.3 什么时候需要回到脚本式声明式 Pipeline 虽然好用但确实有些场景力不从心。比如你想在流水线里导入第三方库或者写很多分支判断和循环逻辑又比如你需要把某个复杂的部署逻辑封装成一个可复用的工具方法这时候声明式的script块可以帮你包裹一些 Groovy 代码但如果你发现自己需要大量使用script块那不如干脆整体用脚本式。我现在的习惯是默认声明式遇到特别复杂的流程再单独评估。如果流程的复杂度已经高到声明式很难表达那么问题大概率不在语法而在于流程本身该拆分了——这种时候强行用一段脚本式大 Pipeline 包打天下后期维护比拆分成多个服务或子流水线还要痛苦。3. 声明式 Pipeline 的核心指令覆盖日常自动化 90% 场景的语法清单在完整讲语法之前先给个心态建设Pipeline 语法看着多但你日常用到的最多十来个指令。我把这些指令按用途分了几组每一组搞明白基本上就能覆盖大多数自动化需求了。3.1 pipeline、agent、stages、steps四个必须搞明白的顶层指令pipeline声明式 Pipeline 的根节点所有内容都包裹在里面。agent指定流水线的执行节点。agent any表示任意可用的执行节点agent { label docker }表示使用带有docker标签的节点agent { docker { image maven:3.8 } }则表示直接在 Docker 容器里跑这个我在后面容器化构建章节会专门展开。stages阶段集合流水线的主体部分。stage一个阶段必须有名字。建议起名时带上明确的动词比如Build、Test、Deploy而不是Step1、Step2这样构建进度页在视觉上更容易看懂。steps阶段内的具体步骤一行一步。这里的命令可以直接是sh、echo、bat也可以是调用其他插件提供的方法比如withCredentials、junit等。这里有一个初学者特别容易踩的坑在声明式 Pipeline 的steps里多个sh步骤之间要保证每个sh都是独立的一次 shell 调用默认工作目录是一样的但环境变量不一定继承。如果你需要在一个上下文中执行多行 shell可以写成一个sh指令里面用换行符分隔或者直接写一个打包脚本文件。否则你会发现上一个sh里export的变量下一个sh里根本读不到。3.2 environment 的环境变量管理不要把秘密塞进 Jenkins 配置environment指令用来设置环境变量它既可以放在pipeline顶层做全局变量也可以放在stage内部做阶段局部变量。我常用的写法有两种pipeline { agent any environment { APP_NAME demo-app VERSION 1.0.0 } stages { stage(Build) { environment { BRANCH main } steps { echo 构建 ${APP_NAME}:${VERSION} } } } }关于敏感信息密码、Token、密钥我强烈建议不要直接写在脚本里也不要写进 Jenkins 的系统配置里明文保存。Jenkins 提供了Credentials凭据管理Pipeline 里通过withCredentials来引用。比如我们要拉取私有仓库代码或者推送镜像到私有仓库stage(Build) { steps { withCredentials([string(credentialsId: dockerhub-token, variable: DOCKER_TOKEN)]) { sh docker login -u myuser -p $DOCKER_TOKEN registry.example.com } } }这种做法的好处是什么凭据加密存储在 Jenkins 里代码库里只出现一个credentialsId即使 Pipeline 脚本泄露也不会直接暴露密码。而且凭据可以在 Jenkins 全局统一管理过期轮换时不用改代码。关于环境变量还有一个很多人忽略的点environment里的字符串内容是支持$引用的但如果你在双引号里引用 Groovy 变量需要区分 Groovy 字符串插值和 Shell 环境变量。比如echo 版本是 ${env.VERSION}和sh echo $VERSION是完全不同的东西。3.3 post 块与构建状态处理成功、失败、始终三种情况都要考虑post块是声明式 Pipeline 最好用的特性之一它让你可以针对构建的不同结果给出一套收尾动作。常见的条件有success、failure、unstable、always四种用法示例pipeline { agent any stages { stage(Build) { steps { sh make build } } } post { always { cleanWs() } success { echo 构建成功开始后续处理 } failure { echo 构建失败请查看日志 } } }很多人写流水线只顾着定义stages完全不写post。结果是构建失败后工作区里残留一堆文件下次构建时状态不干净导致各种诡异问题。我现在写任何 Pipeline 都会强制要求有always收尾至少把工作区清理掉。post块还有一个隐藏价值它可以跟构建状态联动做通知。比如failure里调用企业微信、钉钉、邮件插件发送通知success里归档产物。把通知逻辑集中在post里比之前自由风格项目里到处配邮件通知要清爽得多。3.4 parameters 与 triggers手动、定时、SCM 触发怎么选流水线的触发方式也是常见到爆炸的需求。声明式 Pipeline 里手动触发参数用parameters定义定时触发和代码变更触发用triggers定义。先看parameters。它的作用相当于在自由风格项目里勾选参数化建构过程pipeline { agent any parameters { string(name: ENVIRONMENT, defaultValue: dev, description: 部署环境) choice(name: DEPLOY_MODE, choices: [rolling, recreate], description: 更新方式) booleanParam(name: SKIP_TEST, defaultValue: false, description: 是否跳过测试) } stages { stage(Deploy) { steps { echo 部署环境${params.ENVIRONMENT} echo 部署方式${params.DEPLOY_MODE} } } } }注意params这个内置对象它承载了所有参数值。使用的时候${params.xxx}如果在 Groovy 字符串插值里记得用双引号。注意不要跟env混了env是 Jenkins 内置环境变量集合params是构建参数集合两个都经常用。再看triggers。声明式 Pipeline 支持几种触发方式triggers { cron(H 2 * * *) pollSCM(H/5 * * * *) }cron是固定时间触发和 Linux crontab 类似但我建议用H这种哈希值让 Jenkins 自动分散负载避免多个 Job 同一秒挤在一起。pollSCM是定时轮询代码仓库发现变更才触发构建。说句题外话轮询 SCM 本质上还是轮询不够实时现在主流的做法是让 Git 服务端配置 Webhook 告诉 Jenkins 有变更了这样效率高很多。Pipeline 本身不做 Webhook 的代码配置但你在 Git 仓库管理后台里创建一个 Jenkins Webhook 地址即可配合triggers里的SCM类型监听对应事件。3.5 options 是 Pipeline 的保险丝options指令用来设置流水线运行时选项我每次新建 Pipeline 都会加上几个保命选项options { timeout(time: 30, unit: MINUTES) buildDiscarder(logRotator(numToKeepStr: 20)) disableConcurrentBuilds() skipDefaultCheckout() }timeout给整个流水线设超时时间防止某个步骤卡死导致构建资源被一直占用buildDiscarder设置构建记录保留数量避免 Jenkins 的构建历史无限膨胀disableConcurrentBuilds禁止同一流水线并发执行非常适合部署类流水线避免两个构建同时操作同一台服务器产生竞态skipDefaultCheckout跳过默认的代码检出适合某些不需要 Jenkins 拉代码、而是靠自己脚本控制的场景。这些选项看着不起眼但都是我在生产环境踩过坑之后才补上的。有一次构建任务因为远端服务无响应流水线整整挂了十个小时才被发现从那以后凡是没有timeout的流水线我都不让上线。4. 实战从零搭建一套 Java 项目的自动构建与部署流水线前面讲了那么多语法很多朋友可能还是觉得虚。这一节我就拿一个真实的、我日常在用的 Java 项目自动化构建部署流程作为例子从需求到完整代码一步步拆给你看。4.1 场景需求假设我们有一个基于 Maven 构建的 Spring Boot 项目需要实现以下自动流程从 Git 仓库拉取指定分支代码使用 Maven 进行编译打包跳过单元测试为了演示加速流程构建 Docker 镜像并推送到私有镜像仓库通过 SSH 登录到测试服务器拉取新镜像并重启容器。这个流程在自由风格项目里至少需要三个 Job 拼接而在 Pipeline 里可以一气呵成。团队最终希望在 Git 仓库里维护这份流水线脚本开发人员只需要关心代码提交部署动作完全自动化。4.2 完整 Jenkinsfile 示例以下是一份可以直接参考的 Jenkinsfile 示例pipeline { agent { docker { image maven:3.8-openjdk-11 args -v /var/run/docker.sock:/var/run/docker.sock -v /root/.m2:/root/.m2 } } options { timeout(time: 30, unit: MINUTES) buildDiscarder(logRotator(numToKeepStr: 30)) disableConcurrentBuilds() } environment { REGISTRY registry.example.com IMAGE_NAME demo-app CONTAINER_NAME demo-app-server } parameters { string(name: BRANCH, defaultValue: main, description: 代码分支) string(name: SERVER_HOST, defaultValue: 10.10.10.10, description: 目标服务器地址) } stages { stage(Checkout) { steps { checkout([$class: GitSCM, branches: [[name: ${params.BRANCH}]], userRemoteConfigs: [[url: gitexample.com:group/demo.git, credentialsId: git-ssh-key]]]) } } stage(Build) { steps { sh mvn -B -DskipTests clean package } } stage(Docker Build Push) { steps { script { def version sh(script: cat pom.xml | grep version | head -1 | sed s/.*version\\(.*\\)\\/version.*/\\1/, returnStdout: true).trim() env.IMAGE_TAG ${params.BRANCH}-${BUILD_NUMBER}-${version} } withCredentials([usernamePassword(credentialsId: registry-auth, usernameVariable: REGISTRY_USER, passwordVariable: REGISTRY_PASSWORD)]) { sh docker login -u ${REGISTRY_USER} -p ${REGISTRY_PASSWORD} ${REGISTRY} docker build -t ${REGISTRY}/${IMAGE_NAME}:${IMAGE_TAG} . docker push ${REGISTRY}/${IMAGE_NAME}:${IMAGE_TAG} } } } stage(Deploy) { when { expression { params.SERVER_HOST ! } } steps { withCredentials([usernamePassword(credentialsId: server-ssh, usernameVariable: SSH_USER, passwordVariable: SSH_PASSWORD)]) { sh sshpass -p ${SSH_PASSWORD} ssh -o StrictHostKeyCheckingno ${SSH_USER}${SERVER_HOST} docker pull ${REGISTRY}/${IMAGE_NAME}:${IMAGE_TAG} docker stop ${CONTAINER_NAME} || true docker rm ${CONTAINER_NAME} || true docker run -d --name ${CONTAINER_NAME} -p 8080:8080 ${REGISTRY}/${IMAGE_NAME}:${IMAGE_TAG} } } } } post { always { cleanWs() } failure { echo 部署失败请检查日志并回滚上一个稳定版本。 } } }别急着复制粘贴这份脚本里有几个地方是故意写成需要你根据实际环境调整的我下面逐个解释。4.3 关键步骤逐行解读先看agent。这里我让流水线直接跑在一个maven:3.8-openjdk-11的 Docker 容器里省去了在 Jenkins 节点上单独安装 JDK 和 Maven 的麻烦。镜像可以按项目需求替换比如前端项目用node:16Python 项目用python:3.9。注意我挂载了/var/run/docker.sock这是为了让容器内的docker命令能够跟宿主机的 Docker 守护进程通信。这一步如果不做后面docker build会报无法连接 Docker daemon。挂载 socket 的方式比 Docker in Docker 轻量很多是当前容器内构建镜像的主流做法但要注意安全能访问 Docker socket 基本等于能控制宿主机所以不要在不可信的 Pipeline 环境里这么干。再看Checkout阶段。这里用checkout步骤手动指定 Git 地址和分支而不是依赖 Jenkins 默认的 SCM 配置好处是我能动态使用params.BRANCH来选择分支。Maven 包里解析版本号的思路是读取pom.xml里的version标签生成镜像标签时把分支、构建号、代码版本拼在一起这样每个镜像都有唯一标识回滚时能直接定位到具体构建。Docker Build Push阶段用withCredentials拉取仓库凭据。镜像标签里我特意用了env.IMAGE_TAG这是通过script块给当前流水线环境变量赋值。注意这里env.IMAGE_TAG是可以在后续 stage 里直接读取的因为env是整个流水线生命周期内可读写的环境变量集合跨 stage 传递参数的首选方式之一。Deploy阶段用了when表达式来判断是否执行部署条件就是参数SERVER_HOST不为空。这样同一个 Pipeline 脚本既能做纯构建不传服务器地址就只构建到镜像推送也能做部署日常非常实用。SSH 远程执行命令这块我用了sshpass配合密码登录如果服务器配置了密钥认证你完全可以不传密码直接指定私钥来连接。生产环境我强烈建议用密钥而非密码登录安全性高一个量级。4.4 与自由风格项目的能力对比如果你之前在自由风格项目里实现这套流程你会发现需要拆分任务一个 Job 做 Maven 构建一个 Job 做 Docker 镜像推送一个 Job 做远程服务器部署三个 Job 之间还要靠复制产物或远程触发来串联。一旦部署顺序要调整就得去三个 Job 的配置里改了一遍又一遍。而 Pipeline 版本把这些流程按顺序写在一个文件里任何一个步骤都是显示的。后期想加一个静默起一个临时容器跑 smoke test直接在Deploy前插入一个新stage就行代码评审也一目了然。这就是我为什么坚持把复杂部署流迁移到 Pipeline 的根本原因。5. 环境变量与内置上下文用好 Jenkins 给你的默认能力Pipeline 真正上手之后你会发现大量时间其实花在跟环境变量和上下文对象打交道。Jenkins 提供了非常多的内置变量和对象用好了能省很多自己解析的功夫。5.1 常用内置环境变量最常见的全局环境变量可以通过${env.变量名}或直接在 Groovy 环境里用env.变量名来访问。下面这些是我几乎每条流水线都会用到的变量名说明使用场景BUILD_NUMBER当前构建编号生成唯一标签BUILD_ID当前构建 ID以前是时间戳定位日志JOB_NAME当前 Jenkins Job 名称日志和通知WORKSPACE当前工作区路径拼接文件路径JENKINS_HOMEJenkins 主目录读取全局配置EXECUTOR_NUMBER当前执行器编号区分并发执行NODE_NAME当前节点名判断执行环境举个例子我要给每个构建生成一个带时间戳的日志文件名可以这样写sh touch build-${BUILD_NUMBER}.logJenkins 内置变量在 Shell 里和 Groovy 里都能访问但注意 Shell 里访问要加$前缀。上面这个写法里BUILD_NUMBER是环境变量所以 Shell 能识别。5.2 params 和 env 的区别与配合这是一个高频混淆点。params是你在parameters指令中定义的构建参数集合而env是 Jenkins 内置环境变量集合。两者之间有一定重叠但含义不同。比如你定义了一个名为BRANCH的参数访问方式应该是${params.BRANCH}但如果你尝试${env.BRANCH}大概率取不到值反过来BUILD_NUMBER你通过${params.BUILD_NUMBER}通常是拿不到的。我习惯的做法是在 Jenkinsfile 开头把需要用的参数统一赋值给局部变量然后再往下用可以有效避免搞混environment { DEPLOY_ENV ${params.ENVIRONMENT} }5.3 currentBuild管道构建状态的核心对象currentBuild是 Jenkins Pipeline 里极其重要的内建对象它代表当前构建的各种元数据。我最常用的是它的result、number、description、absoluteUrl这几个属性。比如我想在构建失败后给企业微信通知里带一个包含构建编号和流水线地址的消息post { failure { script { echo 流水线失败Job ${env.JOB_NAME} 构建 #${currentBuild.number} echo 详情${currentBuild.absoluteUrl} } } }还可以用currentBuild.description动态更新构建描述方便在 Jenkins Web 界面上直接看到这次构建里的关键信息。我在部署流水线里经常这么做currentBuild.description 分支 ${params.BRANCH} - 镜像 ${IMAGE_TAG}这样在构建历史列表里扫一眼就知道每一行构建对应的是什么分支、什么镜像排查问题速度直线提升。5.4 自定义工具路径与环境准备Pipeline 执行时默认加载的是 Jenkins 节点上的 PATH。如果你在某个节点上自定义安装了工具建议在 Pipeline 里显式指定工具路径或者用 Jenkins 的 Tools 配置后通过tool步骤来获取路径。比如配置了 JDK 工具可以这样用stage(Java Env) { steps { script { def javaHome tool name: OpenJDK-11, type: hudson.model.JDK sh JAVA_HOME${javaHome} java -version } } }如果你干脆把整个流水线放进 Docker 容器像我前面 4.2 的示例那样这一步基本可以省略因为镜像里已经装好了全套环境。这也是为什么我越来越喜欢用容器化 agent 的原因团队里不需要每个 Jenkins 节点安装各种版本的工具链一个镜像就能保证环境一致。6. 落地的踩坑清单从 SSH 异常到容器内构建写 Pipeline 这件事语法层面其实不难真正的坑往往是你以为语法没问题了、跑起来却各种告警。我在生产环境里踩过好几轮下面挑最有代表性的五个常见问题分享出来。6.1 SSH 连接异常Connection is not established 的排查路径有朋友在阅读我前面的部署脚本时可能会问为什么不用 Jenkins 自带的 SSH 插件而是自己在 Shell 里 ssh 一把这里我要展开一个非常值得讲的坑。Jenkins 的 SSH 插件SSH Pipeline Steps 或 Publish Over SSH在版本更新过程中我曾经遇到过java.lang.IllegalStateException: Connection is not established!这样的报错。这个报错本身很有意思它不是说你密码错了、也不是说密钥不对而是 SSH 连接对象压根没有建立起链路插件就尝试发送命令了。我排查这个问题的完整链路是这样的第一步先确认是不是网络问题。手动在 Jenkins 机器上用命令行执行ssh userhost echo ok看能不能通。很多情况下这一步就能发现目标服务器的防火墙是否放行、端口是否可达。第二步检查主机密钥校验。新版本的 Jenkins SSH 插件默认会做 known_hosts 校验如果你用的服务器不在 known_hosts 里连接会在第一步就被拒绝表现就是Connection is not established。临时解法是关闭校验-o StrictHostKeyCheckingno长期解法是把目标服务器密钥加入 Jenkins 所在机器的 known_hosts。第三步确认认证方式。如果你的 SSH 插件配置的是私钥但私钥格式不被 JSch 支持比如 OpenSSH 的新格式也会导致连接建立不起来。我见过很多人被这个卡住解法是把密钥转成 RSA 格式或换成密码认证。在走完这三步之后我最终放弃了在 Jenkins 插件层面配置一堆 SSH 服务器转而直接在 Pipeline 里用sshpass ssh命令控制远程执行。这样做的好处是流程完全透明、可复用、不依赖插件自身的连接状态管理。坏处也很明显密码会出现在命令行里所以我总是配合withCredentials把它从 Jenkins 凭据中注入避免明文硬编码。总的来说如果你也频繁遇到 SSH 插件的连接状态问题不妨换这个思路。6.2 容器里调用 Docker 命令socket 挂载与权限处理有一段时间我在 Jenkins 容器里尝试直接执行 Docker 构建经常遇到这个报错Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?这背后的原因很简单容器内的docker命令只是一个客户端它需要跟 Docker daemon 通信而容器内默认根本没有/var/run/docker.sock这个文件。解决办法就是我在 4.3 里提到的启动 Jenkins 容器或 Agent 容器时挂载宿主机的 Docker socketdocker run -d -p 8080:8080 \ -v /var/run/docker.sock:/var/run/docker.sock \ -v /usr/bin/docker:/usr/bin/docker \ jenkins/jenkins:lts挂载之后还要注意宿主机 Docker daemon 的权限。如果容器内用户对 socket 没有访问权限会报 permission denied。一般做法是把 Jenkins 容器内用户加入宿主机 docker 组或者直接调整 socket 文件权限但后者安全性差一点。在生产环境我更推荐的方式是不在 Jenkins 容器里直接操作 Docker而是让流水线跑在带docker命令的专用 Agent 容器上或使用 Kubernetes 动态 Agent。这能让构建环境和Jenkins 控制面彻底分离权限边界清晰出问题也好隔离。6.3 构建目录膨胀与清理这是一个不痛不痒但迟早出事的问题。默认情况下每次构建的产物都会落在WORKSPACE下时间长了磁盘空间会被大量旧产物和陈旧工作区吃掉。我之前给你看的 Pipeline 脚本里post里的cleanWs()就是清工作区用的但光靠它还远远不够。更完整的方案是组合使用两个手段第一Pipeline 里options配置buildDiscarder(logRotator(numToKeepStr: 20))只保留最近 20 次构建记录旧构建的产物自动清理第二管理员层面开启 Jenkins 全局的工作空间清理策略Workspace Cleanup Plugin或者定期跑一个维护 Job把超过 N 天没更新的工作区清掉。我还喜欢把大型中间产物放到构建目录之外比如单独挂载一个数据盘目录然后通过WORKSPACE_TMP或者自定义环境变量来引用。这样最终用户目录和 Jenkins 工作区都不会被巨型产物拖垮。6.4 插件下载慢怎么处理国内团队经常反馈 Jenkins 插件安装慢得让人怀疑人生。这不是 Jenkins 本身的问题而是默认插件源在国外。解决思路很简单把 Jenkins 的升级站点 URL 替换成国内镜像地址。在 Jenkins 的管理插件 - 高级页面有一个升级站点配置项默认值是https://updates.jenkins.io/update-center.json。把它换成国内镜像源的对应地址保存后点击立即检查再用可选插件页签搜索安装就会快很多。具体镜像地址我就不在这里列了大家搜一下Jenkins 国内镜像就能找到选择自己网络环境测试下来最稳定的那个即可。这里有个教训改完镜像源之后如果之前装了一半的插件状态异常最好重启一次 Jenkins 再重新尝试否则可能一直提示某些依赖无效。另外插件版本兼容矩阵也要留意不要盲目把插件全部升到最新版有些插件整体升级后会在 Pipeline 语法上产生 breaking change。6.5 Jenkins 2.x 里的 Kubernetes 配置要点很多团队现在把 Jenkins 的构建节点迁到 Kubernetes 上实现有构建任务时开一个 Pod任务结束自动销毁的效果。这套方案在弹性伸缩和节省成本上非常有优势但初始配置有几个容易错的地方。第一Jenkins 需要安装 Kubernetes Plugin然后在系统配置里添加 Kubernetes Cloud。填 Kubernetes API 地址时如果 Jenkins 部署在集群外部要用集群的 API 外网地址如果 Jenkins 本身在集群内部用 Service DNS 地址即可。填错是连接不上的最常见原因。第二Pod Template 里指定镜像时不要只写一个工具镜像。构建容器通常会需要多个容器协作一个容器跑 Maven一个容器跑 Docker CLI还有一个容器跑 Shell 脚本。Pod Template 支持定义多个 Container每个 Container 有不同的镜像和资源配额。这个设计比单容器 Agent 要灵活很多。第三别漏了 JNLP 容器。Kubernetes 集成里Jenkins Master 是通过 JNLP 协议跟 Agent Pod 通信的Pod Template 里必须有一个 jnlp 容器默认会自动生成。如果你自定义了 Pod Template 却删掉了 jnlp 容器Agent 大概率会一直处于等待连接状态。在我实际配置的过程中最有效的调试手段就是看 Pod 的 Event 日志。如果 Pod 一直 CrashLoopBackOff基本就是镜像拉取失败或者 JNLP 启动命令参数不对。把imagePullPolicy设成IfNotPresent可以避免频繁拉取镜像造成的超时。7. Pipeline as Code把流水线放进 Git 仓库后的三个进阶方向到这里Pipeline 的基本语法和实战套路已经讲得差不多了。最后一个部分我想聊聊进阶方向也是我现在在团队里重点推广的东西。7.1 Jenkinsfile 的存放与多分支策略把 Jenkinsfile 放在项目代码库根目录是目前最主流的方式。好处是流水线跟代码一起演进改部署逻辑就像改代码一样走评审、走标签代码回滚时流水线也跟着回滚不会出现代码回去了、Pipeline 还是新版本的错位。配合多分支流水线Multibranch PipelineGit 仓库的每个分支会自动生成对应的 Jenkins Job。这样你在分支上改 Jenkinsfile直接推上去就能在对应分支的任务里验证效果主分支上的流水线完全不受影响。我先在 feature 分支上调整部署步骤验证通过后再合并到主干部署逻辑的变更风险被压到最低。这里有一个需要注意的细节在 Jenkinsfile 里判断当前分支时别用固定的${env.BRANCH_NAME}硬编码判断它只在多分支流水线里才有意义。如果你的流水线是普通 Pipeline Job 且通过参数指定分支那BRANCH_NAME可能取到的值跟你想的不一样。我通常用params.BRANCH作为分支唯一可信来源在多分支场景里再把BRANCH_NAME映射到params.BRANCH上。7.2 共享库把通用逻辑抽出来当你维护的流水线多起来你会发现大量代码是重复的克隆代码、构建镜像、推送私仓、清理工作区全是同一套逻辑。如果每个 Jenkinsfile 里都复制一份改一处要换遍所有项目非常痛苦。共享库Shared Library就是用来解决这个问题的。你可以在一个独立的 Git 仓库里维护 Jenkins 共享库里面定义一堆可复用的全局变量和函数然后在 Jenkins 的系统配置里把这个仓库注册为 Global Shared Library。之后任何 Pipeline 脚本都可以这么用Library(my-lib) _ pipeline { stages { stage(Build) { steps { buildDockerImage(demo-app) } } } }buildDockerImage这个函数就定义在共享库里所有项目共用同一份实现。改推送逻辑只需改库的代码所有引用它的流水线全部生效。这个抽象层级我建议循序渐进一开始别过度设计等确实有两三个项目复用同一段逻辑时再抽共享库否则你会为了抽象而抽象反而增加了维护成本。7.3 AI 辅助生成和排查 Pipeline说句实在话Pipeline 语法虽然不复杂但刚开始写的时候查文档查得还是有点烦躁。现在很多 AI 辅助编程工具已经能比较准确地根据需求生成 Jenkinsfile 了比如写一个基于 Maven 的 Java 项目 Jenkinsfile要求构建 Docker 镜像并推送到私仓AI 能直接给你一份能跑的脚本。我的经验是AI 生成的脚本拿过来后不要直接上线至少要在本地或测试环境跑一次因为生成式 AI 对 Jenkins 插件的具体参数名有时记得并不准确容易产生运行时错误。更实用的场景是用 AI 排查报错。Pipeline 运行报错时把报错日志复制给 AI让它帮你分析是语法错误还是环境问题、提供排查思路这个效率提升是非常明显的。我现在遇到 Jenkins 相关异常时第一个动作就是把完整日志丢给 AI让它给我列出可能原因再逐条对照实际环境验证通常能省掉一半的排查时间。我自己也在持续关注 Jenkins 官方的 AI Agent 插件方向这类工具未来大概率会让 Pipeline 的编写和维护门槛再降一档。7.4 我的实际体会从自由风格项目切到 Pipeline 已经好几年了我最大的体会是Pipeline 给自己带来的不是自动化本身而是部署流程可以像代码一样被思考和演进。自动化程度再高只要流程本身不可见、不可评审、不可版本化它依然是脆弱的。如果你现在还在自由风格项目里挣扎我的建议很简单找一个最简单的项目用声明式 Pipeline 把它重新实现一遍。不用追求一开始就覆盖所有细节先把拉码 - 构建 - 归档这条路跑通然后再一步步加上部署、通知、清理。这个过程走下来你对 Jenkins 的理解会比看任何教程都深得多。