谁还没被部署全靠手动、发布次次提心吊胆的日子折磨过我当初学 Jenkins 的时候翻遍各种教程发现要么太长要么太旧折腾一星期才把第一个流水线跑通。后来带团队、给客户搭 CI/CD才慢慢总结出一套真正能一天上手、不绕弯子的路径。这篇 Jenkins 教程就是按这个思路写的不讲废话直接告诉你从安装、配 GitLab、写 Pipeline 到自动部署 Java Web 应用每一步怎么做、为什么这么做、坑在哪。标题敢说史上最简单不是吹。我的目标很简单让一个完全没接触过 Jenkins 的人照着这篇文章操作一天之内能搭好环境、跑通自动构建、把部署流程跑起来。文章覆盖 Windows 和 Linux 环境也会讲离线安装、国内镜像源、钉钉通知这些实际工作中一定会遇到的问题。1. 为什么 Jenkins 值得花一天来学以及它到底解决什么问题1.1 没碰过 CI/CD 的人最常有的误解先纠正三个我见过无数次的误解尤其是刚入行的同学。误解一Jenkins 是一个部署工具点了按钮就能把代码发布到服务器。实际上 Jenkins 的核心是调度和自动化它本身不会部署它负责的是在什么条件下、按什么顺序、执行哪些命令。部署动作是靠脚本完成的Jenkins 只是个靠谱的管家。误解二Jenkins 必须装在服务器上Windows 电脑上玩不了。这个错得离谱。本地开发机、Windows 笔记本都能装 Jenkins学习阶段在自己电脑上搭完全没问题。很多同学卡在安装这一步多半是没搞明白 JDK 版本和 Windows 服务权限。误解三学了 Jenkins 就得写复杂的 Groovy 脚本。早期插件生态不完善时确实麻烦但现在有流水线即代码、有大量图形化操作入门阶段根本不需要写太复杂的脚本能看懂官方文档里的例子就够了。1.2 Jenkins 在部署流水线里的实际位置我习惯把一条完整的交付链路拆成这样你一看就明白 Jenkins 在哪里干活代码提交GitLab/GitHub→ 触发构建Jenkins→ 单元测试 → 打包Maven/Gradle/npm→ 上传服务器或构建镜像 → 执行远程部署脚本 → 通知结果钉钉/邮件Jenkins 站在中间负责把整个流程串起来。它干活的载体叫Job任务新版里更推荐用Pipeline流水线因为流水线把配置写在 Jenkinsfile 里跟着代码仓库走哪台机器都能跑不会出现这台机器能构建、换一台就不行的玄学问题。有个核心概念你必须 get构建触发器。最常见的有三种轮询 SCM定时去 GitLab 拉代码看有没有变化、WebhookGitLab 主动推送通知 Jenkins、定时构建比如每天凌晨跑打包任务。新手最容易把前两个搞混。轮询是 Jenkins 主动去问 GitLab代码变了吗Webhook 是 GitLab 主动告诉 Jenkins代码变了。Webhook 实时性好、不占资源是生产环境首选但需要网络通、需要配凭证。学习阶段用轮询最省事。2. 安装前必须想清楚的几件事从本机练手到服务器正式使用的选型2.1 Linux 服务器安装Docker 方式还是原生包方式我推荐新手用 Docker 方式装 Jenkins这句话对不同基础的人意义不一样。如果你 Docker 用得不熟可以先用原生包方式先把 Jenkins 跑起来再说如果你已经熟悉 Docker直接上容器迁移、备份、升级都省心。Docker 部署命令官方镜像是最省心的选择mkdir -p /data/jenkins_home chown -R 1000:1000 /data/jenkins_home docker run -d \ --name jenkins \ -p 8080:8080 \ -p 50000:50000 \ -v /data/jenkins_home:/var/jenkins_home \ -v /var/run/docker.sock:/var/run/docker.sock \ jenkins/jenkins:lts两个细节很多人会忽略第一/var/run/docker.sock挂载进去之后容器里的 Jenkins 才能调用宿主机 Docker 帮你去构建镜像、跑容器。不挂这个你在 Pipeline 里写docker build会直接报错。如果你用 Windows 或 Mac 的 Docker Desktop路径稍有不同但原理一样。第二chown -R 1000:1000这步不能省。Jenkins 官方镜像内部运行用户 UID 是 1000宿主机上如果不把目录权限交给 1000容器启动时会因为写不了/var/jenkins_home而失败。踩过这个坑的人不少。原生包方式在 CentOS 上一般是先装 JDK再下载 Jenkins 的 rpm 包或 apt 包。以 Ubuntu/Debian 为例sudo apt update sudo apt install -y openjdk-11-jdk curl -fsSL https://pkg.jenkins.io/debian-stable/jenkins.io-2023.key | sudo tee /usr/share/keyrings/jenkins-keyring.asc 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 sudo apt update sudo apt install -y jenkins装完后访问http://服务器IP:8080初始管理员密码在/var/lib/jenkins/secrets/initialAdminPassword。记得把首次安装插件页面的默认项改了别直接点 Install suggested plugins因为默认插件列表里有一堆你用不上的下载又慢又浪费时间我后面会单独讲国内镜像源配置。2.2 Windows 安装与 Credentials 验证踩坑Windows 上装 Jenkins 有两种方式MSI 安装包和图表通过 Docker Desktop 跑容器。我建议老实用 MSI 安装包它会帮你把 Jenkins 注册成 Windows 服务开机自启省心。但 Windows 上有两个高频坑一个是 JDK 版本一个是 Credentials。先说 JDK。新版 Jenkins2.400 之后要求 Java 11 或 17你机器上如果只有 Java 8直接把 Jenkins 安装器打开就会报错退出。先用java -version检查不是 11/17 就先装一个或者配JAVA_HOME环境变量让 Jenkins 找到正确版本。再说到验证 Credentials 失败这个问题几乎每个在 Windows 上配过 GitLab 或 GitHub 的人都会遇到一次。你按教程创建了一个 Username with password 类型的凭证点Test Connection对面报错说不通眼睛一看用户名密码明明是对的。我排过很多次这种问题链路是Jenkins 在 Windows 上如果是服务方式运行默认登录账号是 LocalSystem 或者你指定的服务账号它去访问 GitLab 时用的是自己的用户态不是你的登录账号。所以你在 Jenkins 界面里填的凭证没问题但 Jenkins 拿它去连 GitLab 时可能因为网络代理设置、SSL 证书、或者 GitLab 侧开了双重验证导致握手失败。排查步骤建议按这个顺序来确认 GitLab 仓库地址在浏览器里能正常访问排除网络不通和 GitLab 抽风。在 Jenkins 全局配置里找到 Git确认Path to Git executable指向有效路径Windows 上经常配错。Credentials 里区分Username with password和SSH Username with private key。HTTP 方式用账号密码SSH 方式用私钥。别混。如果 GitLab 是自签名证书要在 Jenkins 的全局工具配置里把证书链配好或者在 Jenkins 启动参数里加-Djsse.enableSNIExtensionfalse之类的调试参数这个看具体版本。最常见的其实还是 GitLab 账号开了 2FA。这时候你填登录密码是没用的得用 Access TokenGitLab 里叫 Personal Access Token。复制 token 当作密码填进去就好了。凡是遇到密码明明对但验证失败先想 token。2.3 离线环境安装的方式以及国内源配置企业内网部署 Jenkins 的时候经常碰到这台机器上不了外网网上搜会看到该 Jenkins 实例似乎已离线这样的字样。这个其实是插件管理页面的警告不是 Jenkins 挂了是 Jenkins 默认去官方更新中心拉取插件列表拉不到。离线安装分两个层面装 Jenkins 本体和装插件。Jenkins 本体离线安装不算复杂你把安装包rpm/deb/war拷贝到内网机器上装好就行。麻烦的是插件因为默认插件一大堆手动下载 .hpi 文件再上传真的很折磨。我的建议是在能上网的机器上把 Jenkins 装一遍用官方源把需要的插件装完然后把整个 JENKINS_HOME 目录打成 tar 包拷贝到离线机器解压。这个办法屡试不爽尤其是你的插件依赖一多一个个下载 .hpi 文件要被依赖关系逼疯。云厂商或者国内网络环境下还有一种做法是利用镜像站。更新的核心是换 Update Center URL。在 Manage Jenkins → Plugins → Advanced settings 里把 Update Site 换成国内镜像地址比如清华 TUNA 的 Jenkins 更新中心https://mirrors.tuna.tsinghua.edu.cn/jenkins/updates/update-center.json换完后点 Check now插件列表就能正常拉下来了。这是一个公开、常规的镜像服务配置方法适合内网无法访问官方更新中心、或网络不稳定的场景。如果你嫌 UI 上操作慢也可以直接改$JENKINS_HOME/hudson.model.UpdateCenter.xml把 url 字段替换成镜像地址然后重启 Jenkins。本质上和 UI 操作一样。3. 第一个 Pipeline 从哪里入手从新建任务到跑通 Hello World 构建3.1 Freestyle job 与流水线项目怎么选新手打开 Jenkins 首页点新建任务会出现 Freestyle project、Pipeline、Multi-branch Pipeline 等一堆类型很容易懵。我的建议非常直接新项目一律用 Pipeline。Freestyle 是 Jenkins 上古时代的设计适合在网页上点一点配置但它的所有配置都留在 Jenkins 里换台机器就没了也没法代码 review。Pipeline 把流程写进 Jenkinsfile 放进代码库Team 里任何一个人改了共同维护这是现代化的标准做法。当然如果是临时测个东西、只想快速跑一条命令Freestyle 拖几个构建步骤确实快。所以不是不能用只是别拿它当长期主力。第一个 Pipeline 建议这样建新建任务 → 选 Pipeline → 在 Pipeline 脚本框里粘贴下面内容pipeline { agent any stages { stage(Hello) { steps { echo Hello Jenkins! } } } }点击 Build Now蓝色对号出来代表构建成功点进去看 Console Output里面会出现 Hello Jenkins!。这就算跑通了。别小看这一步Jenkins 的 Agent、Stage、Step、Console Output 这四大基本概念你全接触了一遍。3.2 配置 GitLab 连接Credentials 到底怎么填跑通 Hello 之后就进入正题把你的代码拉下来。这步绕不开 GitLab 连接配置。先在 Manage Jenkins → Credentials → System → Global credentials 里新增一个凭证。常见的是 GitLab Personal Access Token 方式Kind 选 GitLab API token需要装 GitLab 插件或 Username with passwordUsername 写你的 GitLab 用户名Password 填 Personal Access Token 而不是登录密码ID 给一个好认的名字比如gitlab-token如果是 SSH 方式Kind 选 SSH Username with private key把私钥粘贴进去公钥放到 GitLab 账号的 SSH Keys 里。配置完了在 Pipeline 里拉代码pipeline { agent any stages { stage(Checkout) { steps { checkout([$class: GitSCM, userRemoteConfigs: [[url: gitgitlab.example.com:yourgroup/yourproject.git, credentialsId: gitlab-token]], branches: [[name: */main]]]) } } } }用credentialsId引用凭证别把账号密码写死在脚本里。写死等于裸奔一旦代码仓库泄露所有服务器都被脱走。如果你前面配置正确但这里还是拉不下来优先检查 Jenkins 所在机器能不能 ssh 通 GitLab 的 22 端口。ssh -T gitgitlab.example.com试一下通了再回来排查 Jenkins 配置。3.3 常用可用的环境变量清单Jenkins 内置了大量环境变量Pipeline 里通过env.变量名读取。我把新手最常用的列一个表这是网上各种 Jenkins 面试题也爱考的东西建议收藏变量名含义典型用途BUILD_NUMBER当前构建号每次递增产物版本号、Docker TagBUILD_ID构建唯一 ID老版本格式带时间戳日志文件名JOB_NAME任务名区分多个任务产物路径WORKSPACE工作区绝对路径脚本定位文件GIT_COMMIT当前构建对应的 Git 提交 SHA记录版本、回滚定位GIT_URL代码仓库地址排查分支来源BRANCH_NAME分支名Pipeline 中常用按分支走不同部署策略NODE_NAME执行节点名判断在哪台机器上构建JENKINS_URLJenkins 访问地址拼接构建页链接给钉钉/邮件通知具体到 Pipeline 里这样用pipeline { agent any environment { IMAGE_TAG ${BUILD_NUMBER}-${GIT_COMMIT?.take(7)} } stages { stage(Show Env) { steps { echo 当前任务: ${JOB_NAME} echo 当前构建号: ${BUILD_NUMBER} echo 当前代码提交: ${GIT_COMMIT} echo 镜像标签: ${IMAGE_TAG} } } } }有个容易出错的小地方env.GIT_COMMIT只有在用了 Git 插件、且实际拉取了代码之后才有值。如果你脚本里在代码还没 checkout 时就打印GIT_COMMIT输出会是 null别慌调整 stage 顺序就行。4. 自动部署 Java Web 应用的完整链路从构建到发布的全流程4.1 Maven 构建与部署包生成的关键参数学 Jenkins 最典型的应用场景就是把 Java Web 应用自动部署到服务器。假设你的项目是 Maven 管理Jenkins 里要做的事就是拉代码、跑 Maven 打包、拿产物做部署。在 Pipeline 里配置 Maven 之前先确认全局工具配置里有没有 JDK 和 Maven。Manage Jenkins → Tools 里可以新增 JDK 安装、Maven 安装一般选自动安装Jenkins 会自己去下载。内网环境就要你手动填本地路径了。一个实际 Java Web 项目的 Pipeline 长这样pipeline { agent any tools { maven maven-3.9 jdk jdk-17 } stages { stage(Checkout) { steps { checkout([$class: GitSCM, userRemoteConfigs: [[url: gitgitlab.example.com:yourgroup/yourproject.git, credentialsId: gitlab-token]], branches: [[name: */main]]]) } } stage(Maven Build) { steps { sh mvn clean package -DskipTests -Dmaven.test.skiptrue } } stage(Archive) { steps { archiveArtifacts artifacts: target/*.war, fingerprint: true } } } }这里-DskipTests表示跳过测试编译-Dmaven.test.skiptrue是跳过测试执行。两者有细微差别多数快速集成场景用-DskipTests就够但如果你追求极致速度两个加一起用。构建产物如果是 war后续部署到 Tomcat如果是 jar可以直接 java -jar 或者做成 Docker 镜像。Windows 和 Linux 上路径分隔符不一样在 Pipeline 里尽量用相对路径target/*.war不要写死/home/admin/xxx。4.2 通过 SSH 把部署包传到服务器的常见姿势打包完成之后下一步是把产物发到目标服务器。这个环节生产环境常用两种方案一种是用 Publish Over SSH 插件配置简单直观。先在 Manage Jenkins → Configure System 里配置 SSH Server填目标服务器 IP、用户名、私钥/密码Pipeline 里这样用stage(Deploy) { steps { sshPublisher( publishers: [ sshPublisherDesc( configName: prod-server, transfers: [ sshTransfer( sourceFiles: target/app.war, remoteDirectory: /opt/app, execCommand: sudo systemctl restart tomcat ) ] ) ] ) } }这个插件每次同步文件后可以执行一段远程命令注意execCommand里的命令是你 SSH 用户有权限执行的否则重启 Tomcat 时会报 Permission denied。如果目标路径是 root 所有建议在目标机器上给部署用户配置 sudo 免密。另一种方案是纯 sh 命令适合你不想装插件或者已经有一套运维脚本的情况sh scp target/app.war deploy10.0.1.10:/home/deploy/app/ ssh deploy10.0.1.10 cd /home/deploy/app ./deploy.sh app.war 前提是 Jenkins 所在机器和目标服务器之间已经配好了 SSH 免密私钥放在 Jenkins 用户的 ~/.ssh/id_rsa。这种方式直白出了问题也好排查因为日志里能直接看到 scp 和 ssh 的原始输出。这里有个很容易踩的细节sshPublisher的remoteDirectory路径是相对于远程用户主目录的不是绝对路径。比如你配置remoteDirectory: /opt/app实际传过去可能是/home/ubuntu/opt/app除非加useSftp或调整prefix参数。所以传送完用ls -l去验证一下文件到底落到哪了别想当然。你要是都传到主目录了部署脚本又找不到 war 包排查起来会非常沮丧。4.3 Docker 部署时的 Registry 配置与常见报错处理越来越多的团队选择把应用打成 Docker 镜像来部署。Jenkins Pipeline 里可以做镜像构建和推送但新手很容易遇到一个经典报错docker: error response from daemon: Get https://registry-1.docker.io/v2/: net/http: request canceled while waiting for connection这个报错一出现先看下时间是不是发生在拉取基础镜像或者 push 镜像的时候。它背后的常见原因是 Docker daemon 去访问默认的 Docker Hub registry 时网络不通或不稳定尤其在对 Docker Hub 访问受限的内网环境更常见。解决办法是在 Docker 的/etc/docker/daemon.json里配置 registry 镜像加速器{ registry-mirrors: [ https://docker.m.daocloud.io, https://docker.mirrors.ustc.edu.cn ] }改完之后执行systemctl daemon-reload systemctl restart docker再重试。这是纯技术层面的配置目的是让 Docker 客户端从更稳定的镜像站点拉取公共镜像。如果你的内网有自己的 Harbor 或者 Nexus 仓库直接把image地址指向内部仓库更稳妥。Pipeline 里 push 镜像的典型写法stage(Build Image) { steps { script { docker.withRegistry(https://registry.example.com, harbor-credentials) { docker.image(registry.example.com/library/myapp:latest).push(${BUILD_NUMBER}) } } } }docker.withRegistry第一个参数是镜像仓库地址第二个参数是 Jenkins 里保存的凭证 ID。这里有个坑如果你只写registry.example.com不带https://前缀一些 Docker 版本会认为你是非安全仓库连接时报错。统一带上协议头最省事。如果 Pipeline 里写docker build报Got permission denied while trying to connect to the Docker daemon socket说明当前用户不在 docker 用户组里。把 Jenkins 执行用户加进 docker 组sudo usermod -aG docker jenkins然后重启 Jenkins 服务。如果是容器方式跑的 Jenkins检查你是不是把/var/run/docker.sock挂进去了没挂进去也是同样的报错。5. 再往上走钉钉通知、插件源、升级与新玩法5.1 DingTalk 自定义消息推送配置构建和部署跑完之后总不能让大家都盯着 Jenkins 页面看结果把结果推送到钉钉群是最常见的需求。Jenkins 官方没有钉钉插件但第三方插件很成熟在插件管理里搜DingTalk安装即可。配置分三步第一步在钉钉群添加一个自定义机器人。群设置 → 智能群助手 → 添加机器人 → 自定义。钉钉会给你一个 Webhook 地址格式类似https://oapi.dingtalk.com/robot/send?access_tokenxxxxxxxx。第二步在 Jenkins 的 Manage Jenkins → Configure System 里找到 DingTalk 配置项把 Webhook 填进去设置一个 ID 和名称。第三步在 Pipeline 里调用post { success { dingtalk( robot: default, type: MARKDOWN, title: 构建成功通知, text: [ ### 部署成功, # 任务: ${env.JOB_NAME}, # 构建号: ${env.BUILD_NUMBER}, # 结果: 成功 ], atAll: false ) } failure { dingtalk( robot: default, type: TEXT, text: [ 构建失败 ${env.JOB_NAME} #${env.BUILD_NUMBER}, 点击查看: ${env.JENKINS_URL}job/${env.JOB_NAME}/${env.BUILD_NUMBER} ], atAll: true ) } }这个插件支持 MARKDOWN 和 TEXT 两种格式。发成功消息用 MARKDOWN 显得整齐失败消息用 TEXT 加上 所有人提醒力度大。注意手机端钉钉对 MARKDOWN 消息里的某些字符渲染有限制#别用太多不然在手机上看着像报错了。5.2 插件源与升级站点切换、离线升级插件管理长期不维护积累的问题比 Jenkins 主程序升级还麻烦。更新插件或升级站点时我最怕的就是从官方源下载超时半路失败后插件列表变成红叉。所以国内网络环境或内网环境第一件事就是换更新中心方法在 2.3 节已经说过这里不重复。升级 Jenkins 版本本身流程相对固定备份JENKINS_HOME→ 停服务 → 替换 jenkins.war 或者安装包 → 起服务。用 Docker 方式更简单直接拉新版本镜像挂载同一个 volume 重启容器。但升级前有个重点看兼容性列表。Jenkins 主版本升级后旧插件可能不再兼容轻则功能失效重则 Jenkins 启动直接失败。我的习惯是升级前先查 Jenkins 官方的版本升级指引尤其关注大的版本跳变比如 2.3xx 到 2.4xx 要注意 Java 版本要求。如果已经因为升级导致 Jenkins 起不来不要慌把 JENKINS_HOME 里plugins目录中刚升级过的插件.jpi文件删掉恢复旧插件再慢慢一个个升级找出有问题的插件来。这是最笨但最有效的回滚方法。5.3 Jenkins MCP 与面试高频题整理最后聊几个新东西和面试里常见的问题算是给想进一步深入的人一个方向。先说 Jenkins MCP。MCP 是 Model Context Protocol 的缩写不同场景下理解不同。在 Jenkins 生态里Jenkins MCP通常指通过协议把 Jenkins 的 API 能力暴露给 AI 编程助手或智能体让 AI 能帮你触发构建、查询构建状态、读取日志、分析失败原因。它的思路是把 Jenkins 的 REST API 结构化封装AI 通过标准协议就能调用而不需要为每个工具写一堆胶水代码。现在很多团队在探索用 AI Agent 做自动修复、自动定位失败构建底层就是这类能力。不过这块还比较新插件和工具链变更快你感兴趣的话可以关注官方插件市场的更新不用急着在生产环境上。再说面试高频题。我挑了几道出现频率比较高的附上简要思路Q1Jenkins 中 Freestyle Job 和 Pipeline 的区别是什么面试官想听的不是一个古老一个新而是可维护性、可扩展性、代码化程度。Pipeline 用代码描述整个交付流程可以版本管理、并行执行、复用逻辑Freestyle 配置存在 Jenkins 里难审计。如果项目中还在大规模用 Freestyle可以说为了兼容旧任务可以保留但新任务应统一 Pipeline。Q2强密码、Credential 绑定、权限矩阵是真安全吗这个问题在面试里可能换个说法Jenkins 凭证安全怎么做。核心点是凭证不落地、不建议明文写进 Jenkinsfile用 credentialsId 引用给不同团队分配不同视图和任务权限别所有人都是 Admin构建节点最小权限原则Jenkins 服务账号不给服务器 root。Q3如何做到多分支构建和按 tag 发布用 Multi-branch PipelineJenkins 自动扫描仓库里的分支和 tag。分支名匹配 dev 或 feature/* 时可以只构建不发布匹配 master/main 或 tag 时走完整发布流程。在 Jenkinsfile 里用env.BRANCH_NAME判断当前分支。Q4大规模多个项目共用一套 Jenkins怎么保证隔离和资源不互相影响常见做法是 Jenkins 多节点Master Agent架构把不同项目分配到不同 Agent 标签上限制每个 Agent 的并发执行数和可用资源。还有一种是每个团队一套独立 Jenkins测试、预发、生产环境分开。后者隔离性更好但运维成本高。Q5一次构建失败后你的排查顺序是什么先看 Console Output 中最后的报错关键字再看是代码编译问题、依赖拉取问题、还是测试/部署环节异常。如果是容器构建先区分是 Docker daemon 问题、镜像拉取问题还是应用启动问题。排查链路想得清比背结论管用得多。说到最后学 Jenkins 最忌讳的是只看不练。开头听我说再多不如自己装一个实例、创建第一个 Pipeline、故意制造一次构建失败然后把它修好这个过程中积累的手感和排查思路才是真正能在一天之内沉淀下来的东西。如果你照着这篇文章把环境搭起来、跑通一次自动部署你会发现从前所谓不会部署怕发布其实只是卡在几个没想清楚的细节上。剩下的就是多踩坑、多记录了。