Jenkins 这东西我第一次接触是在一个只有三台机器的内网测试环境里当时需求朴素到不行开发每次提交完代码得有人手动登服务器mvn package、替换 war 包、重启 Tomcat一来二去谁都嫌烦。后来把 Jenkins 架起来配好任务点一下按钮甚至根本不用点就能出包、发布那种终于不用半夜爬起来发版本的解脱感大概是我走上自动化这条路的起点。这篇文章就把 Jenkins 从零到跑通一条自动化部署流水线的全过程摊开讲安装部署每一步怎么做、插件源怎么治理、凭据怎么管、流水线怎么写才不容易崩还有一堆只有踩过才知道的坑都会讲到。刚入门的朋友可以照着一步步复现已经装过但用得别扭的老手也能从里面的选型说明和排查表里捞到点东西。1. 装之前先想清楚三条安装路线的取舍逻辑1.1 war 包、系统包、容器到底怎么选很多人一上来就问Jenkins 怎么装其实这个问题问得太早。真正该先问的是你的服务器上还有没有别的 Java 应用运维习惯偏哪一边将来要不要做多节点。这三个答案决定了你该走哪条路。我按实际用下来的体感把三条主流路线摆在一起对比。安装方式典型命令/载体升级难度环境隔离适合场景war 包直接跑java -jar jenkins.war换个 war 文件重启即可弱和主机共用 JDK单机、想快速上手、需要灵活指定 JDK 版本系统包yum/apt/deb/rpmyum install jenkins依赖包管理器中等自带 jenkins 用户和 systemd生产环境、希望开机自启、目录规范容器Docker/K8sdocker run jenkins/jenkins换镜像 tag强插件版本可控已有编排平台、需要弹性构建节点我自己的习惯是单机内网测试用 war 包正式生产用系统包或容器二选一。原因很简单war 包最透明出问题一眼能看到日志也方便临时指定某个 JDK 版本跑但它的短板是开机自启和进程守护得自己写 systemd属于能用但不省心。系统包的好处是装完就带jenkins用户、带 systemd 单元、带默认的/var/lib/jenkins家目录运维成本最低。容器方案胜在插件版本能锁死在镜像里升级回滚都是换个 tag 的事代价是你得先把数据卷映射想清楚不然重启一次数据全丢。注意不管选哪条路Jenkins 的配置、任务、凭据、插件全部存在JENKINS_HOME里。这个目录才是真正的命根子安装方式只是外壳。很多人换安装方式时吃大亏就是因为没把JENKINS_HOME单独挂一块盘或者单独备份。1.2 服务器基础环境怎么查、查什么装之前花五分钟把环境摸清楚能省掉后面两小时的排查。要确认的东西不多但每一样缺了都会卡住。第一是JDK。Jenkins 的版本对 JDK 有硬性要求别拿着老环境硬套。粗略记法是Jenkins 2.3xx 之前的 LTS 大概能用 JDK 8/112.4xx 之后的 LTS 基本要求 JDK 11 或 17新版本普遍推荐 17 甚至 21。装之前先java -version看一眼不确定就去官网对应版本的说明里核对。JDK 装在哪、JAVA_HOME指向哪都要记下来后面 systemd 里要写死路径。第二是内存和磁盘。Jenkins 本体不重但构建任务重。一个 Maven 项目跑起来JVM 堆、Maven 本地仓库、工作区快照、归档产物加起来很容易吃掉几个 G。所以我的经验值是单机跑中小项目内存至少 4G磁盘至少留 50G。JENKINS_HOME单独挂盘是加分项因为构建产物和builds/目录膨胀得比你想象中快得多。第三是端口和防火墙。默认 8080被占了就换。netstat -tlnp | grep 8080或者ss -tlnp看一下被占用的话启动参数里改成 8081、9090 都行。防火墙、安全组该放行的放行这部分按各自环境的规矩来。第四是时间同步。这一条最容易被忽略。Jenkins 里的构建时间、Webhook 触发时间都依赖系统时间机器时间漂了会出现我明明刚提交怎么触发时间是半小时前这种诡异现象。timedatectl看下时间同步状态没同步就配上。# 环境体检四连 java -version 21 free -h df -h /data ss -tlnp | grep -E 8080|9090 timedatectl status实操心得目录规划千万别偷懒。我一般这么分/opt/jenkins放 war 包和启动脚本/data/jenkins作为JENKINS_HOME/data/maven-repo作为 Maven 本地仓库。三者分开将来升级只换 war数据不动备份只备JENKINS_HOMEwar 包随时能重下。2. Linux 下的完整安装实操从 war 包到 systemd 托管2.1 下载 war 包与目录初始化先把目录结构建好再动手下载。顺序反了后面到处挪文件容易把权限搞乱。# 建目录 mkdir -p /opt/jenkins /data/jenkins /data/maven-repo # 下载 war 包建议用国内的镜像站速度差别非常明显 cd /opt/jenkins wget -c https://mirrors.tuna.tsinghua.edu.cn/jenkins/war-stable/latest/jenkins.war # 看看下载完的大小正常应该几十上百 MB ls -lh jenkins.war这里有个细节值得说war 包选war-stable还是war目录取决于你要 LTS 还是最新版。war-stable/latest对应的是稳定长期支持版插件生态兼容性最好追新版就用war/latest。生产环境我强烈建议走 LTS新版偶尔会碰上插件跟不上的情况为了一两个新特性去趟这个雷不值。紧接着建一个专用用户。用 root 跑 Jenkins 是能跑但构建脚本里但凡有个rm -rf ${WORKSPACE}写歪了后果你自己想。所以# 建一个不能登录的系统用户 useradd -r -m -d /data/jenkins -s /sbin/nologin jenkins # 把数据目录的属主交给它 chown -R jenkins:jenkins /data/jenkins /opt/jenkins /data/maven-repo-r是系统用户-s /sbin/nologin禁止登录-d /data/jenkins把家目录直接指到数据盘。这三步做完后面 systemd 里直接Userjenkins就行。2.2 首次启动与解锁的全过程先把服务跑起来用最朴素的方式验证一遍确认没问题了再交给 systemd。这属于先手跑通再上正轨的思路。# 用 jenkins 用户身份指定 HOME 和端口前台跑一遍看看输出 export JENKINS_HOME/data/jenkins su -s /bin/bash jenkins -c JENKINS_HOME/data/jenkins java -jar /opt/jenkins/jenkins.war --httpPort8080终端上会刷一大串日志看到类似Jenkins is fully up and running就说明起来了。第一次启动最关键的产物是那个初始管理员密码它写在cat /data/jenkins/secrets/initialAdminPassword把这串字符复制到浏览器里访问http://服务器IP:8080粘贴进去解锁。解锁之后进入自定义 Jenkins页面会问你装哪些插件。这里分两种情况网络通的话可以先选安装推荐的插件让它自己跑网络不通或者很慢的话直接选不安装任何插件先跳过进了主界面再去治理插件源。为什么这么建议因为默认插件源的下载速度在内网环境下经常是几十 KB 每秒几十个插件装下来能等到你怀疑人生中途断一次还得重来。跳过它先把源换好再统一装效率高得多。安装过程如果卡在某个插件上别慌。刷新页面试试实在不行就重启服务。插件下载是不完整的会留下.tmp文件如果反复失败可以去插件目录里清掉残留。# 查看插件目录里的残留 ls -la /data/jenkins/plugins/ | grep -i tmp装完推荐插件、建好管理员账号就进入主界面了。到这一步Jenkins 本体算装完了但离能用还差配置。2.3 用 systemd 把它变成正规服务手跑的进程一关终端就没了必须交给 systemd。配置文件写在/etc/systemd/system/jenkins.service。[Unit] DescriptionJenkins CI Server Afternetwork.target Wantsnetwork-online.target [Service] Typesimple Userjenkins Groupjenkins EnvironmentJENKINS_HOME/data/jenkins EnvironmentJAVA_HOME/usr/lib/jvm/java-17-openjdk EnvironmentJAVA_OPTS-Xms512m -Xmx2048m -Duser.timezoneAsia/Shanghai -Dfile.encodingUTF-8 ExecStart/usr/lib/jvm/java-17-openjdk/bin/java -jar /opt/jenkins/jenkins.war --httpPort8080 Restarton-failure RestartSec10 SuccessExitStatus143 [Install] WantedBymulti-user.target几个参数值得单独解释因为这几行决定了这个服务稳不稳。JAVA_OPTS里的-Xmx2048m是堆上限别不设也别乱设成 8G。堆太大反而会让 Full GC 停顿变长2G 到 4G 对中小规模构建足够。-Duser.timezoneAsia/Shanghai是解决日志时间对不上的老毛病不加的话容器里经常显示 UTC。-Dfile.encodingUTF-8是为了让构建日志里的中文别变成乱码尤其是那种控制台输出带中文的脚本。SuccessExitStatus143这一行是专门处理停服务时被 SIGTERM 杀掉的情况。不加它用systemctl stop停止后状态会被标成 failed看着难受。Restarton-failure加RestartSec10意味着进程意外挂掉后 10 秒自动拉起。为什么不是always因为如果是你主动 stop 的always会把它又拉起来反而麻烦。写完之后systemctl daemon-reload systemctl enable jenkins systemctl start jenkins # 看一眼状态和最近日志 systemctl status jenkins --no-pager journalctl -u jenkins -n 50 --no-pager常见坑Environment和ExecStart里的 JDK 路径一定要用绝对路径。用/usr/bin/java这种软链接有时会因为 systemd 环境变量不完整而找不到。我见过不止一次命令行跑得好好的systemd 一跑就报java: command not found根子都在这。3. Windows 与离线环境的安装补课3.1 Windows 下安装与凭据验证Windows 上的安装包是个.msi双击一路下一步就行比 Linux 还省事。但有几个点必须提前规划否则装完就是一堆麻烦。第一是安装路径不要带空格和中文。默认路径里如果用户名是中文C:\Users\张三\.jenkins这种路径会让某些插件解析出错。装的时候手动改到D:\jenkins这类纯净路径。第二是运行身份。安装向导会问你用本地系统账户还是指定用户。用本地系统账户省事但网络共享、映射盘符这类操作会因为会话隔离而失败指定一个域用户或者本地管理员账号则更贴近真实使用场景缺点是得把该账号的权限配全。第三就是那个很多人踩过的credentials 验证失败。在 Windows 上新建凭据比如 GitLab 的 API Token、SSH 私钥、用户名密码时Jenkins 会做一次连通性验证报错往往长这样Failed to validate the credential、jenkins.plugins.git.GitSCM$2之类。排查顺序我总结成这样现象优先怀疑处理办法凭据保存时报验证失败但内容没写错运行 Jenkins 的账号没有网络出口权限换成有网络权限的账号运行服务GitLab 凭据验证失败Token 权限不足或缺 scope重新生成至少勾上 api 权限SSH 私钥验证失败服务账户的用户目录里没有 known_hosts在服务账户下手工 ssh 一次目标机写入指纹用户名密码模式失败账号启用了双因素或多重校验改用 API Token 或应用专用密码这个表里的第三条特别隐蔽。Windows 服务跑在系统账户下~/.ssh/known_hosts指向的是系统账户的家目录而你在自己的账号里 ssh 过一遍写进去的指纹服务账户根本读不到于是握手直接失败。解决办法就是切到服务账户身份下 ssh 一次或者在构建脚本里加-o StrictHostKeyCheckingno内网可信环境下可以接受公网环境慎重。还有一点Windows 上的JENKINS_HOME默认在安装目录里升级或迁移时容易忘。装完先去系统管理 - 系统配置确认一下家目录位置心里有数。3.2 纯离线环境怎么把插件搬进去内网隔离环境是绕不开的场景Jenkins 天生依赖插件而插件默认在线下载这就成了死结。我的做法是外网备料内网投喂分四步。第一步在外网机器上装一个同版本的 Jenkins把该装的插件全装好。这一步很关键两台机器版本必须一致否则插件包里的元数据对不上。第二步把外网机器上的plugins目录整个打包连同plugins同级的.pluginmanager相关文件一起传到内网机器。# 外网机器上打包 cd /data/jenkins tar czf plugins-offline.tar.gz plugins/ # 传到内网内网机器上解包注意先停服务 systemctl stop jenkins tar xzf plugins-offline.tar.gz -C /data/jenkins/ chown -R jenkins:jenkins /data/jenkins/plugins systemctl start jenkins第三步处理插件依赖的隐藏清单。光拷.jpi文件往往不够因为很多插件会附带依赖其他插件而且可选依赖在离线状态下会变成启动报错。所以更稳的做法是配合一个专门的插件搬运工具把plugins目录加上一个描述文件一起打包内网端用它来批量安装。这类工具的思路都是解压、比对版本、写目录本质上还是搬文件只是省了手工比对的力气。第四步也是最容易被忘的一步把升级站点改成一个不可达的地址或者干脆关掉定期检查更新。离线环境里 Jenkins 每次启动都会去联网检查更新超时一次要等半分钟日志里全是报错。关掉它启动能快不少日志也清爽。离线场景的实操心得内网里JENKINS_HOME/updates/目录下会缓存一份default.json这个文件是插件元数据的来源。离线机器上如果这个文件是空的或者损坏插件管理页面会直接报错打不开。搬家的时候把它一起带上能少走弯路。4. 插件源治理与必备插件清单4.1 把升级站点换成国内源这一步我建议所有非海外网络环境都做收益立竿见影。默认的更新中心在国内访问经常慢到没法用换成国内镜像站速度能从几十 KB 提到几 MB。操作分两步缺一不可。很多人只做了第一步发现速度还是慢就是因为漏了第二步。第一步改升级站点的地址。进系统管理 - 插件管理 - 高级把升级站点的 URL 改成镜像地址。常见的是清华镜像站的更新中心地址把默认的https://updates.jenkins.io/update-center.json换成镜像站对应路径。改完点立即获取会去拉一份新的元数据。第二步改元数据里的实际下载地址。这一步是很多人不知道的关键。update-center.json拿到本地后会存成default.json里面的插件下载链接仍然指向原站域名。只改升级站点不改这个文件插件列表是刷新了但真正下载插件时走的还是慢的那个域名。# 先看下文件在不在 ls -lh /data/jenkins/updates/default.json # 把下载域名批量替换成镜像站 cd /data/jenkins/updates cp default.json default.json.bak sed -i s#https://updates.jenkins.io/download#https://mirrors.tuna.tsinghua.edu.cn/jenkins#g default.json sed -i s#http://updates.jenkins.io/download#https://mirrors.tuna.tsinghua.edu.cn/jenkins#g default.json # 顺手把元数据里的一些连通性检查地址替掉否则会拖慢加载 sed -i s#https://www.google.com#https://www.baidu.com#g default.json替换完重启服务再去插件管理页面搜插件你会明显感觉到列表加载快了很多安装也顺了。注意这个default.json会在每次立即获取时被覆盖。也就是说你换完源、点了一次立即获取刚才的替换就白做了。正确顺序是先改升级站点 URL点立即获取然后马上做default.json的替换之后再重启。或者干脆把立即获取的时机放在替换之后、重启之前。还有一个更省心的思路如果服务器能连到一个内网的 Nexus 或制品库可以自己做插件代理把插件缓存在内网。这个属于进阶做法团队规模上来了才划算单机没必要折腾。4.2 我实际项目里必装的插件插件这东西装多了拖慢启动装少了功能不够。我把自己项目里几乎每个环境都会装的一份清单列出来附上装它的理由。插件作用为什么不能省Git拉取 Git 仓库代码没有它连代码都拉不下来基础中的基础GitLab与 GitLab 集成、Webhook 触发、构建状态回写想要提交即构建就靠它Pipelineworkflow-aggregator支持 Jenkinsfile 声明式流水线现代 Jenkins 的标配不装等于用老古董Credentials Binding在流水线里安全注入凭据避免把密码明文写进脚本Git Parameter构建时下拉选择分支或 Tag手动发版时体验提升巨大Maven Integration提供 Maven 构建类型与依赖缓存支持Java 项目基本都要Publish Over SSH把产物推送到远程服务器并执行命令简单的部署场景够用SSH Agent在流水线里临时加载 SSH 私钥比 Publish Over SSH 更灵活DingTalk把构建结果推到钉钉群通知刚需Role-based Authorization Strategy基于角色的权限控制多人协作时不装就是全员管理员Build Timestamp给构建号加时间戳归档产物命名用得上AnsiColor控制台彩色输出看着舒服排查也快Workspace Cleanup构建前后清理工作区防止磁盘被历史文件撑爆Config File Provider集中管理 Maven settings.xml 等配置多任务共用一份配置Generic Webhook Trigger通用 Webhook 触发灵活解析参数对接各种外部系统装这些插件的顺序有个小技巧先装依赖最深的。比如 Pipeline 系列自带一堆子插件手工一个个点太累直接在可选插件里搜workflow-aggregator装它依赖会自动带上。装完之后进系统管理 - 全局安全配置把授权策略从登录用户可以做任何事改成Role-Based Strategy。这一步不做前面装的权限插件白装。5. 全局工具与 GitLab 对接配置5.1 JDK、Git、Maven 全局工具配置系统管理 - 全局工具配置这个页面是 Jenkins 能不能干活的分水岭。这里配不对后面流水线里mvn、git全找不到。三个工具的配法略有不同。JDK如果你已经在系统里装好了 JDK就选不自动安装然后把JAVA_HOME路径填进去。如果想让 Jenkins 自己管理多版本可以配自动安装但内网环境这条路走不通要去下载。我的做法是统一不自动安装路径写死简单可靠。Git同理填系统里git的可执行文件路径通常是/usr/bin/git。填完 Jenkins 会自动探测版本号能显示出 2.x 就说明通了。Maven可以自动安装也可以手动指定。手动的话填MAVEN_HOME路径Jenkins 会去找bin/mvn。这里配完之后每个任务里就能用别名引用比如后面流水线里的tools { maven maven3.9 }。配 Maven 的时候有个必做动作给它配一份指向国内镜像的settings.xml。不配的话第一次构建能下依赖下到你怀疑网络是不是断了。做法是在系统管理 - Managed files里加一个 Maven settings 文件内容里把mirror指向国内仓库。mirror idaliyun/id mirrorOf*/mirrorOf namealiyun maven/name urlhttps://maven.aliyun.com/repository/public/url /mirror然后在全局工具配置里把这个 Managed file 指定给 Maven。这样所有用这个 Maven 的任务都自动走镜像不用每个项目改一遍。一个小提醒Maven 本地仓库的位置最好单独设一个目录比如/data/maven-repo。默认在~/.m2/repository跟着用户家目录走。家目录迟早会满单独挂盘更好管理也方便多任务共享同一份依赖缓存省磁盘也省下载时间。5.2 GitLab Connection 与凭据管理对接 GitLab 的完整链路是先在 GitLab 生成访问令牌再在 Jenkins 里存成凭据最后配置 GitLab Connection任务里引用它。四步一步都不能漏。第一步去 GitLab 的个人设置里生成一个访问令牌Access Token。权限勾选上api这是 Jenkins 回写构建状态、拉取项目信息要用到的。生成后立刻复制保存页面刷新后就看不到了。第二步在 Jenkins 里加凭据。系统管理 - 凭据 - 系统 - 全局凭据新建时类型选GitLab API token把刚才的令牌粘进去起个好认的 ID比如gitlab-api-token。第三步进系统管理 - 系统配置找到 GitLab 配置区域。填 GitLab 服务地址注意带上协议头和端口选刚刚建的凭据点测试连接显示Success就成了。第四步在具体任务里源码管理选 Git 时填仓库地址建议用 HTTP 地址加凭据比 SSH 好维护凭据选对应的 SSH key 或者用户名密码。如果想让提交自动触发构建在构建触发器里勾上 GitLab 的触发选项它会生成一个 Webhook 地址和一个密钥把这两个填到 GitLab 项目的 Webhook 设置里。步骤位置关键点生成令牌GitLab 个人设置scope 至少勾 api令牌只显示一次存凭据Jenkins 凭据管理类型选 GitLab API tokenID 起易读的名字配连接Jenkins 系统配置地址要带协议和端口测试连接必须成功任务引用任务配置源码管理用 HTTP 凭据Webhook 密钥填回 GitLabWebhook 不触发是最常见的对接问题排查思路是这样先在 GitLab 的 Webhook 页面点测试看返回码。返回 200 说明通了返回 403 多半是密钥不对返回超时就是网络不通得看 Jenkins 地址是不是 GitLab 服务器访问不到的内网地址。这个坑在 Jenkins 和 GitLab 不在同一台机器时特别容易碰到。5.3 可用环境变量清单与常用取值环境变量是写流水线时绕不开的东西。用对了脚本干干净净用错了就是各种路径拼接出错。Jenkins 提供的变量分两类系统内置的和插件注入的。内置的在任何构建里都有插件注入的得对应的插件生效后才存在。变量名含义典型用途JENKINS_HOMEJenkins 数据目录脚本里定位配置JENKINS_URLJenkins 访问地址拼接构建链接发通知BUILD_NUMBER当前构建序号产物命名后缀BUILD_ID构建 ID早期版本是时间戳唯一标识BUILD_URL本次构建的页面地址通知里附链接JOB_NAME任务名日志和通知里标识项目WORKSPACE当前工作区绝对路径执行脚本时定位目录NODE_NAME执行节点名多节点环境下区分EXECUTOR_NUMBER执行器编号并发构建时避免冲突GIT_COMMIT本次构建的提交哈希记录版本、回滚定位GIT_BRANCH拉取的分支区分环境BRANCH_NAME多分支流水线的分支名多分支项目专用用的时候有两个坑要避开。一个是GIT_BRANCH和BRANCH_NAME的区别GIT_BRANCH通常带origin/前缀比如origin/main而BRANCH_NAME是纯粹的main。脚本里要做字符串比较时用哪个必须想清楚否则判断永远不成立。另一个是这些变量在流水线的不同阶段可见性不一样GIT_COMMIT得在checkout scm之后才有值写在前面就是空的。在声明式流水线里访问这些变量的写法是env.BUILD_NUMBER、env.JOB_NAME在 Shell 脚本里就是标准的$BUILD_NUMBER。要往脚本里传自定义变量用environment块声明Jenkins 会自动注入成环境变量。6. Java Web 应用自动化部署流水线实战6.1 自由风格与 Pipeline 该选哪个老项目里大量存在自由风格Freestyle任务就是那种在网页上点选构建步骤、填 Shell 命令的方式。上手快但一多就乱几十个任务每个的 Shell 都是几十行改一个逻辑要挨个改谁也不敢动。Pipeline 把构建逻辑写成代码放在项目仓库里的Jenkinsfile文件中跟着代码一起走版本控制。好处有三个一是可复用多个项目共用同一份逻辑改一处全生效二是可审计谁什么时候改的构建流程Git 里一清二楚三是可回滚构建脚本写坏了回退一个提交就行。我的建议很直接新项目一律用 Pipeline老的自由风格任务按谁改谁迁的原则慢慢搬。一口气全迁风险太大边改边迁最稳。Pipeline 又分脚本式和声明式现在推荐声明式语法结构化stages、steps、post分得清楚读起来像配置文件团队里谁接手都能看懂。6.2 一份可直接抄的 Jenkinsfile下面这份是我在 Java Web 项目里用的模板删掉了业务相关的部分保留了骨架你改几个变量就能用。pipeline { agent any tools { jdk jdk17 maven maven3.9 } options { timestamps() timeout(time: 30, unit: MINUTES) buildDiscarder(logRotator(numToKeepStr: 20, artifactNumToKeepStr: 5)) disableConcurrentBuilds() } environment { APP_NAME demo-web DEPLOY_DIR /opt/apps/demo-web TARGET_HOST 192.168.10.21 MAVEN_OPTS -Dmaven.repo.local/data/maven-repo } parameters { choice(name: ENV, choices: [dev, test, prod], description: 部署环境) string(name: BRANCH, defaultValue: main, description: 构建分支) } stages { stage(拉取代码) { steps { checkout scm sh git log -1 --prettyformat:%h | %an | %s } } stage(单元测试) { steps { sh mvn -B -U clean test } post { always { junit target/surefire-reports/*.xml } } } stage(打包) { steps { sh mvn -B -DskipTests package } } stage(归档产物) { steps { archiveArtifacts artifacts: target/${APP_NAME}.jar, fingerprint: true } } stage(部署) { when { expression { params.ENV ! prod } } steps { sshagent(credentials: [deploy-ssh-key]) { sh scp -o StrictHostKeyCheckingno \ target/${APP_NAME}.jar root${TARGET_HOST}:/tmp/ ssh -o StrictHostKeyCheckingno root${TARGET_HOST} mv /tmp/${APP_NAME}.jar ${DEPLOY_DIR}/app.jar systemctl restart ${APP_NAME} } } } } post { success { echo 构建成功${env.BUILD_NUMBER} } failure { echo 构建失败去 ${env.BUILD_URL}console 看日志 } } }这份模板里有几处设计是刻意为之值得说明。options里的buildDiscarder是防止磁盘爆掉的第一道防线。保留最近 20 次构建的日志、最近 5 次构建的产物其余自动清理。只留 20 次日志这个数字不是拍脑袋定的通常出了线上问题回溯往前看十来次足够了而产物留存更少是因为体积大真要历史版本从制品库里拿更合适。disableConcurrentBuilds()对部署类任务很重要。两次部署同时跑一个正在mv文件一个正在restart服务很容易把服务搞成半死不活的状态。串行化虽然慢一点但稳。tools块里的别名要跟全局工具配置里填的名字一模一样。不是jdk17而是JDK17之类的找不到就直接报错。when { expression { params.ENV ! prod } }这一行是个安全阀。生产环境不自动部署必须人工介入。真正的生产发布我建议拆成独立任务走审批流别和日常构建混在一起。6.3 构建产物上传与远程发布部署环节最容易出问题的不是怎么传而是传完怎么让它生效。很多人只做了scp文件过去了服务还在跑旧版本然后去翻日志说 Jenkins 部署失败。scp只解决文件搬运服务重启得靠远程执行命令。上面模板里用的是ssh加systemctl restart。这套组合有个前提目标机器上得有对应的 systemd 服务单元并且路径跟部署脚本里的完全对上。如果目标上是 Tomcat 这类容器那就是替换webapps下的 war 包然后触发 Tomcat 重载如果目标上是 Docker 容器那就是docker cp加docker restart。产物命名上有个小技巧我习惯把构建号和短提交号拼进去mv target/${APP_NAME}.jar target/${APP_NAME}-${BUILD_NUMBER}-${GIT_COMMIT:0:7}.jar这样服务器上留几份历史产物出问题能直接回滚比从归档里重新下载快得多。但要注意别无限堆积配个定时清理或者干脆只保留最近三份。再补充一个关于部署速度的点。如果产物包很大几十上百 MBscp会明显变慢。这时候可以先把包压缩或者在同一个 IDC 内网里用更快的传输方式。另一个思路是让目标机自己去拉包Jenkins 把产物传到内网的制品库比如 Nexus、MinIO 这类对象存储目标机用wget从内网拉。这样 Jenkins 服务器的出口带宽压力小很多而且产物有集中管理溯源方便。这个方案在包大、机器多的场景下优势很明显。实操心得部署脚本里一定要加回滚点。最简单的做法是部署前把当前正在跑的包改名备份新包启动失败时自动把备份改回来再重启一次。这个逻辑写起来不过十几行 Shell但能让你在半夜出问题时多一条退路。我吃过一次亏新包因为配置缺了个环境变量直接启动失败服务停了二十分钟从此所有部署脚本都带自动回滚。7. 通知集成、故障排查与长期运维7.1 钉钉自定义消息通知构建结果没人看等于没有通知。团队用钉钉的话把构建状态推到群里是最省事的方案。先在钉钉群里加一个自定义机器人。创建的时候会问你安全设置三种方式选一个自定义关键词、加签、IP 白名单。我推荐加签因为它不依赖消息内容也不用维护服务器 IP 列表。关键词方式要求消息里必须包含指定词稍不注意就发不出去IP 白名单方式在服务器 IP 变化时就得改配置。拿到 Webhook 地址和加签密钥后回 Jenkins 的系统管理 - 系统配置找到钉钉通知的配置区把机器人的 ID、名称、Webhook 填进去。加签方式的话密钥也填上。然后在任务的post块里调用post { success { dingtalk( robot: jenkins-robot, type: MARKDOWN, title: 构建成功, text: [ #### 构建成功, 项目${env.JOB_NAME}, 分支${env.BRANCH_NAME}, 编号${env.BUILD_NUMBER}, 提交${env.GIT_COMMIT}, [查看详情](${env.BUILD_URL}) ] ) } failure { dingtalk( robot: jenkins-robot, type: MARKDOWN, title: 构建失败, text: [ #### 构建失败请及时处理, 项目${env.JOB_NAME}, 编号${env.BUILD_NUMBER}, [查看控制台](${env.BUILD_URL}console) ] ) } }几个细节type用MARKDOWN比纯文本可读性高很多链接能点、标题能加粗。失败通知里直接给到控制台链接别只给构建首页链接省得人家还要点一下。消息里别塞太多内容一屏能看完最好塞几十行日志进群没人会看。还有一点是关于通知频率。如果是多分支流水线每个分支的每次提交都发通知群会被刷爆。建议只给主干分支和生产分支配通知其他分支失败了自己去看就行。7.2 高频报错速查表下面这些是我这几年实际碰到过、并且反复被别人问到的报错。整理成表遇到时先对号入座能省下大量搜索时间。报错关键字根本原因处理办法该Jenkins实例似乎已离线插件更新中心不可达换国内镜像站替换default.json里的下载域名docker: error response from daemon: Get https://registry-1.docker.io/v2/: ...构建节点拉不到镜像给构建节点配镜像加速地址或把基础镜像推到内网制品库command not found: mvn全局工具配置的名称对不上检查tools块里的别名和全局工具配置是否一致Permission denied (publickey)SSH 私钥没加载或权限不对用sshagent加载凭据检查私钥权限是否为 600fatal: could not read UsernameGit 凭据缺失或过期重新生成 Token 并更新凭据No space left on deviceJENKINS_HOME或工作区撑满加buildDiscarder装工作区清理插件清理归档产物Timeout after ... minutes构建卡住超过阈值检查是否有交互式命令等待输入加-B参数Unable to access ... Unsupported protocol远程仓库地址写错检查 URL 是 HTTP 还是 SSH凭据类型是否匹配java.lang.OutOfMemoryErrorJVM 堆或 Maven 内存不足调JAVA_OPTS和MAVEN_OPTS的-XmxWorkspace ... is not a directory工作区被外部删除执行一次清理或重新触发构建重建工作区这张表里第一行和第五行的出现频率最高几乎占了所有求助的一半。前者是网络问题后者是凭据问题这两类问题解决之后日常使用基本就顺了。排查思路上我有个习惯先看控制台完整输出别只看最后一行。Jenkins 的报错往往最后一行只是表象真正的原因在上面几十行处。比如mvn package失败最后一行是BUILD FAILURE但根因可能是前面某个依赖下载超时。养成从下往上翻、找第一处 ERROR 的习惯能快很多。7.3 备份、升级与长期运维Jenkins 用久了会变成不敢动的东西因为里面塞了太多配置和凭据迁一次伤筋动骨。这个状态是可以通过前期规划避免的。备份这件事核心就一句备份JENKINS_HOME但别全备。这个目录里几样东西的性质完全不同config.xml、credentials.xml、jobs/下的config.xml、users/、secrets/是核心几十 MB必须备plugins/是能重装的备了省事但不致命workspace/和builds/是构建产物和日志动辄几十上百 G备了纯浪费。# 一个够用的备份脚本思路 BACKUP_DIR/data/backup/jenkins-$(date %Y%m%d) mkdir -p $BACKUP_DIR systemctl stop jenkins tar czf $BACKUP_DIR/jenkins-core.tar.gz \ -C /data/jenkins \ config.xml credentials.xml users secrets jobs nodes systemctl start jenkins # 只保留最近 7 天的备份 find /data/backup -maxdepth 1 -name jenkins-* -mtime 7 -exec rm -rf {} \;停服务再备份是关键。不停服务直接打包可能正好碰上文件写入备出来的是一份损坏的配置。如果做不到停机那至少要用支持一致性的快照方式。升级更重要的是节奏。我的做法是先在测试环境升级验证一遍确认所有插件兼容、所有任务能正常构建再动生产。升级步骤就是把新的 war 包下载下来替换旧的重启服务进页面看有没有插件兼容性告警。Jenkins 升级后经常提示某些插件需要更新这时候别急着全点更新尤其是那些大版本跨越的一个一个来更新完重启验证一次出问题好定位。还有一件容易被忽略的事定期清理构建历史。就算配了buildDiscarder有些老任务可能没配。我一般每个季度看一次磁盘占用重点看jobs/*/builds/和workspace/两个目录。# 看看谁在吃磁盘 du -sh /data/jenkins/jobs/*/builds 2/dev/null | sort -rh | head -20 du -sh /data/jenkins/workspace/* 2/dev/null | sort -rh | head -20顺带聊一句面试常问的东西。很多人准备 Jenkins 相关的问题时会去背Jenkins 有哪些组件这类概念题其实更有价值的是几个实战问题JENKINS_HOME里哪些必须备份、凭据是怎么加密存储的、多节点是怎么调度的、流水线里的变量作用域怎么理解。这几个问题答得出来说明是真的用过不是背过。我在实际运维中最深的一点体会是Jenkins 的稳定性八成取决于你前期把目录、权限、源、凭据这四件事规整到位剩下的两成才是流水线脚本写得好不好。前面偷的懒后面都会以构建莫名其妙失败的形式还回来。所以每次新装一套我都会花上半小时把JENKINS_HOME单独挂盘、把插件源换好、把凭据统一命名规范、把权限模型配上这半小时的投入能省下后面无数个排查的夜晚。