做后端开发的同学对 Jenkins 这个名字应该再熟悉不过了它就是 CI/CD 领域使用最广泛的开源工具。简单说它能在你每次提交代码之后自动完成代码拉取、编译、打镜像、部署这一整套动作让程序员从“手动打包、手动上传、手动重启”的循环里解脱出来。这篇文章我不打算堆概念直接从落地角度把 Jenkins 从下载安装、初始化配置、国内加速优化到对接 GitLab 实现 Java Web 自动部署、再接入钉钉消息通知的完整过程按我自己的实战顺序梳理一遍。安装过程中容易踩的坑比如 Docker 拉取镜像报错、插件装不上、凭据验证失败等等我也会单独拿出来讲清楚解决办法。文章尽量写得细一点新手照着做就能装起来老手也能当速查手册用。1. Jenkins 安装前的环境准备与版本选择1.1 搞清 Jenkins 的运行环境再动手Jenkins 本体是用 Java 写的所以装 Jenkins 之前必须先搞定 Java 运行环境。不同版本的 Jenkins 对 JDK 版本要求不一样这块我的建议很简单装新不装旧能用 JDK 17 就尽量别用 JDK 8。目前 Jenkins 主流的 LTS 版本比如 2.4xx 系列对 Java 11 和 Java 17 都支持得很好如果你的服务器环境里还有其他 Java 应用依赖老版本那就按需求装多个 JDK 或用 docker 方式隔离。除了 JDK还有几个硬性条件要提前确认。内存方面Jenkins 默认启动参数大概占用 256MB 到 512MB 内存但如果你的任务并发高、节点多建议机器至少 2GB 内存否则构建的时候很容易 OOM。磁盘上Jenkins 的 JENKINS_HOME 目录默认 /var/lib/jenkins会存放所有任务配置、构建产物和插件建议预留 10GB 以上空间。最后就是端口默认 8080安装前可以先检查一下端口有没有被占用如果被占用了后面再改也行但提前改更省事。这些看起来都是零碎的小事但恰恰是安装失败和用起来各种卡顿的高频原因。我遇到过很多次明明 Jenkins 装好了结果构建的时候磁盘满了、内存不够任务直接失败排查半天才发现是环境初始准备不到位。所以先把环境确认好后面才顺畅。1.2 LTS 还是周更版怎么选Jenkins 的版本分两种LTS长期支持版和 Weekly每周更新版。生产环境无脑选 LTS因为 LTS 版本只修 bug 不引入大功能变化插件兼容性也经过更长时间的验证不会出现今天更新明天某个插件挂掉的情况。Weekly 版本适合想尝鲜新功能的人比如你特别需要某个最新特性才建议在测试环境装周更版。下载地址就是 Jenkins 官方网站。不过国内的网络访问官网有时候慢下载安装包主要时间都花在等待上建议下载的时候用国内镜像源各主流开源镜像站都有同步速度会稳定很多。下载后用 SHA-256 校验一下文件完整性官网每个版本都会给出对应的校验值这一步别省略之前见过有人下载了损坏的包装到一半各种诡异报错浪费时间。提示选择版本时最好和你的插件需求一起考虑。有些新插件对 Jenkins 核心版本有最低要求LTS 版本太老的话插件装不上或者功能不完整。我一般会选“发布超过 2 个月的 LTS 版本”这样插件生态兼容性最好。1.3 安装包的几种形态先想清楚用哪种Jenkins 的安装形态主要有四种原生服务安装Linux 的 yum/apt、Windows 的 exe/msi、war 包手动部署放到 Tomcat 或者 java -jar 运行、Docker 容器方式运行jenkins/jenkins 镜像、以及 Kubernetes 环境下的 Helm 部署。对大部分团队来说单机 CI 服务器用原生服务或 Docker 都是常见选择。原生服务安装的好处是管理起来简单systemctl 或 Windows 服务可以直接控制启停开机自启也方便升级时用包管理器一行命令搞定。缺点是 Jenkins 和宿主机共享 Java 环境如果机器上还跑着其他 Java 程序版本冲突的可能性就存在。Docker 方式的好处是隔离干净、迁移方便换个机器直接跑同一个 compose 文件就能拉起一套同样的环境升级只需要换镜像 tag。缺点是 docker 构建时如果要用宿主机的 Docker 来构建镜像也就是 docker in docker需要额外挂载 /var/run/docker.sock权限问题要特别注意。这篇文章后面的实操部分我会以原生服务安装为主线Docker 部分在加速配置和排障章节里也会附带提一下因为自动部署场景下很容易碰到 Docker 相关报错。2. Linux 环境下的完整安装过程2.1 安装 JDK先处理掉最底层的依赖Linux 下装 JDK 用发行版自带的包管理器最省心。CentOS/Rocky 系执行 yum install -y java-11-openjdkUbuntu/Debian 执行 apt install -y openjdk-11-jdk 或 openjdk-17-jdk。装完确认一下版本java -version 输出正常再继续。如果你的项目要求 JDK 8也没关系Jenkins 服务本身用 JDK 11/17 跑构建任务里单独配置 JDK 8 给应用用两者并不冲突。这里有个常见误区以为 Jenkins 服务和项目编译用一个 JDK 就行。实际上推荐的做法是Jenkins 服务用一个 JDK构建任务里的编译工具链单独配置。以 Java Web 项目为例如果线上环境跑的是 JDK 8那 Maven 编译的时候就需要 JDK 8但 Jenkins 服务本身可以用 JDK 17 跑完全没问题。后面在全局工具配置章节我会详细说怎么分别设置。2.2 通过包管理器安装 JenkinsLinux 上安装 Jenkins 最正规的方式是从官方仓库安装这样升级的时候也能直接用包管理器处理。以 CentOS/Rocky 为例先把 Jenkins 的仓库信息加到 yum 源里sudo wget -O /etc/yum.repos.d/jenkins.repo https://pkg.jenkins.io/redhat-stable/jenkins.repo sudo rpm --import https://pkg.jenkins.io/redhat-stable/jenkins.io-2023.key sudo yum install -y jenkinsUbuntu/Debian 的对应操作是添加 apt 源curl -fsSL https://pkg.jenkins.io/debian-stable/jenkins.io-2023.key | sudo tee /usr/share/keyrings/jenkins-keyring.arc /dev/null echo deb [signed-by/usr/share/keyrings/jenkins-keyring.arc] https://pkg.jenkins.io/debian-stable binary/ | sudo tee /etc/apt/sources.list.d/jenkins.list /dev/null sudo apt update sudo apt install -y jenkins安装完成后最主要的就是启动服务。systemctl enable jenkins 设置开机自启systemctl start jenkins 启动然后 systemctl status jenkins 看状态。如果启动失败用 journalctl -u jenkins 查日志绝大多数情况是 Java 版本不对或者 JENKINS_HOME 权限问题。这里插一句官方仓库对国内服务器来说访问速度不一定稳定如果安装时卡住或者下载超时可以先把官方 repo 对应的包下载到本地再用 rpm -ivh 或 dpkg -i 手动安装效果是一样的。或者直接绕开仓库源从镜像站下载 Jenkins 的 Linux 包服务器本地安装即可。2.3 首次访问与初始化配置服务启动后浏览器访问 http://服务器IP:8080页面上会要求输入一个初始密码。这个密码存放在 /var/lib/jenkins/secrets/initialAdminPassword直接 cat 出来复制过去。接下来是一个选择页面“Install suggested plugins”和“Select plugins to install”。新手推荐直接选“Install suggested plugins”Jenkins 会自动装上一批最常用的插件。不过这一步在国内网络环境下经常很慢甚至失败因为插件默认从 Jenkins 官方更新中心下载。我自己第一次装的时候在这里就卡了很久后来是先跳过插件安装改完镜像源之后再回来补装插件明显顺畅很多。所以这一步如果感觉卡住了不用等直接跳过后面用我第四章的方法把插件源换成国内镜像再安装。初始化向导最后会让创建一个管理员账号和确认 Jenkins 访问地址按实际填写就行。到这里 Linux 下的核心安装流程就结束了。3. Windows 环境下的安装与凭据处理3.1 使用安装包在 Windows 上安装 JenkinsWindows 下装 Jenkins 是最省心的从官网下载 windows 安装包exe 或 msi解压后双击一路下一步中间会让你选服务端口、JVM 参数和运行服务的 Windows 账号。除非有特殊需求否则保持默认即可。安装包会自动把 Jenkins 注册成 Windows 服务之后在“服务”管理面板里就能看到 jenkins 服务开机自启和手动启停都在这里管理。安装完成后浏览器访问 http://localhost:8080同样会看到解锁页面。Windows 下初始密码的位置在 C:\ProgramData\Jenkins.jenkins\secrets\initialAdminPassword找不到的话说明 JENKINS_HOME 自定义过那就去自定义目录下找。后续创建管理员和插件安装的流程与 Linux 完全一致。3.2 Windows 下配置 Git 凭据经常出问题Windows 安装 Jenkins 之后最常见的高频问题出现在配置 Git 凭据的时候任务里明明是私有仓库代码就是拉不下来构建日志里报 git fetch 失败或者 Authentication failed。这是因为 Windows 下面的 Git 凭据存储方式和 Linux 不完全一样Jenkins 有时候读不到 Windows 凭据管理器里保存的账号。解决办法基本就两种。第一种是推荐做法在 Jenkins 的凭据管理里手动添加一个类型为“Username with password”的凭据填写 GitLab/GitHub 的账号密码或是 Access Token然后在任务里显式指定这个凭据。第二种是使用 SSH Key 方式在 Windows 上的 Git 环境里生成一对密钥公钥配置到 Git 服务器里私钥配置成 Jenkins 的“SSH Username with private key”凭据。两种方式都要注意在凭据页做好之后不要急着跑任务可以先点一下凭据旁边的“Verify”按钮确认凭证验证通过了再继续能节省很多排错时间。3.3 不想装服务也可以直接跑 war 包如果你不想在 Windows 上注册服务只是临时用一用直接下载 jenkins.war 文件然后切到文件所在目录执行 java -jar jenkins.war --httpPort8080几分钟之内就能把 Jenkins 跑起来。CtrlC 就直接停止对测试环境来说非常方便。war 包方式也可以配合 Tomcat 部署但说实话没必要java -jar 足够简单还少一层 Tomcat 的依赖。war 包方式的缺点就是没有自启动和管理功能服务器重启之后你得手动再敲一次命令。所以生产环境还是建议用安装包注册成服务。war 包适合那种“我就在这台 Windows 机器上验证一下效果”的场景真的要用起来还是走服务化比较稳。4. 安装完成后的加速优化与关键配置4.1 把插件更新中心换成国内镜像安装完之后第一个要做的事情是把 Jenkins 的插件更新中心从官方源切换到国内镜像源。原因很简单官方源在国内大多数网络环境下的下载速度都很慢装一个大点的插件等上十分钟是常有的事情甚至直接超时失败。切换方式也不复杂登录 Jenkins进入“Manage Jenkins” - “Plugins” - “Advanced settings”页面里有一个“Update Site”字段把里面的 URL 替换成清华源的地址https://mirrors.tuna.tsinghua.edu.cn/jenkins/updates/update-center.json保存之后最好重启一下 Jenkins然后去“Available”页检查一下插件列表能不能正常加载。如果列表能出来说明镜像配置生效了接下来装插件的速度就非常可观。需要说明的是升级站点镜像只会影响插件中心的下载Jenkins 核心版本升级用的还是官方更新中心但核心版本一年也升不了几次影响不大。4.2 配置 Docker 的镜像加速解决 registry 报错很多 Jenkins 流水线里都会用到 docker build 或者 docker run这时候常见的报错是docker: error response from daemon: Get https://registry-1.docker.io/v2/: net/http: request canceled while waiting for connection这个报错的本质是 Docker 默认连接的官方镜像仓库在国内网络环境下的连通性不稳定。解决办法是给你的 Docker 配置国内的镜像加速器。修改 /etc/docker/daemon.jsonWindows 上 Docker Desktop 在设置里改加入 registry-mirrors 字段{ registry-mirrors: [ https://docker.m.daocloud.io ] }改完执行 systemctl daemon-reload 和 systemctl restart docker 让配置生效然后再跑之前的 docker pull 或流水线任务之前卡住的拉镜像步骤基本就能顺利通过了。配置里可以多填几个镜像加速地址Docker 会在拉取失败时自动切换提升成功率。4.3 全局工具配置与环境变量进入“Manage Jenkins” - “Tools”可以配置 JDK、Maven、Git 等构建工具的默认路径。如果机器上已经装好 JDK 和 Maven选择“Install automatically”反而多此一举直接选择“Local installation”填入 JAVA_HOME 和 MAVEN_HOME 对应的路径就行。这样 Jenkins 在构建任务里调用工具时就能准确找到具体的版本不会出现编译环境与预期不一致的问题。另外在“Manage Jenkins” - “System”里有一项“Global properties”可以设置“Environment variables”。Jenkins 自身暴露了不少可用环境变量比如 BUILD_NUMBER构建序号、JOB_NAME任务名、WORKSPACE工作空间绝对路径、BUILD_URL本次构建的访问 URL等等。这些变量在后续写钉钉消息、做产物归档时非常有用。我通常会把几个关键变量直接配成全局环境变量这样任务里写 sh 命令的时候可以直接引用不用每个任务重复写。注意如果团队里有多个项目共用一台 Jenkins尽量把“全局工具配置”做得收敛一些不要让每个任务都各自指定路径否则换机器的时候维护成本特别大。统一放到 Tools 里任务里引用工具名称即可。4.4 离线和内网环境的安装思路有些公司的生产环境是内网隔离的不能访问外网。这种场景下安装 Jenkins 主要解决两个问题一是基础包的来源二是插件包的来源。基础包可以在有网的环境下载好安装包和 JDK用 rpm -ivh / dpkg -i 或者直接解压的方式拷进内网安装。插件就麻烦一点最常用的做法是找一台外网机器装一个同版本的 Jenkins把需要的插件通过“Download plugin”或者手动把 /var/lib/jenkins/plugins 目录打包再拷进内网对应目录重启 Jenkins 后插件就自动加载了。另外也可以提前下载好插件的 hpi 文件进入 Manage Jenkins - Plugins - Advanced用“Deploy Plugin”手动上传安装。这个方法适合只需少量插件的场景几十个插件的话建议直接整目录打包拷贝效率更高。离线环境下升级站点可以保留默认官方地址反正无法访问只要插件目录里东西齐全功能一样能正常使用。5. 实战Java Web 应用自动部署全流程5.1 需要准备哪些插件自动部署一个 Java Web 应用通常需要这几类插件Git 插件拉取代码、Maven Integration调用 Maven 构建、SSH Pipeline Steps 或 Publish Over SSH把产物传到目标服务器、GitLab 插件建立 GitLab 连接与触发 Webhook、以及钉钉 DingTalk 插件发送构建结果消息。我建议先按需安装不要一口气装一堆用不上的插件插件多了启动慢、升级还容易冲突。基础三件套 Git Maven Integration SSH Pipeline Steps 先装上等把基本流水线跑通了再接 GitLab 和钉钉通知。这样每一步出问题都容易定位。5.2 配置 GitLab 连接与系统凭据装完 GitLab 插件后进入“Manage Jenkins” - “System” - “GitLab”配置区域点击“Add GitLab connection”。名称随便起GitLab Host URL 填公司 GitLab 的地址Credentials 添加一种“GitLab API token”类型的凭据Token 在 GitLab 的“用户设置 - Access Tokens”里生成需要勾上 api、read_repository、write_repository 这几个权限。配置完后可以点“Test Connection”显示 Success 就说明连接成功。同一页面里还要配置其他类型的凭据代码仓库的账号密码或 SSH Key、目标服务器的 SSH 用户名与私钥、Docker Registry 的用户名密码。这些凭据都放在“Manage Jenkins - Credentials - System - Global credentials (unrestricted)”里统一管理后续任务里都用 ID 引用而不是直接把账号密码写死在脚本里。这样即使任务脚本要在多个项目里复制也不会泄露敏感信息。5.3 写一条最简单的 Pipeline 构建任务建立任务的时候选择“New Item” - “Pipeline”。下面是一段最小可用的 Pipeline 脚本实现拉代码、Maven 打包、SSH 传到服务器并重启服务pipeline { agent any environment { NODE_NAME java-web } stages { stage(拉取代码) { steps { checkout scm } } stage(Maven 构建) { steps { sh mvn -B clean package -DskipTests } } stage(部署) { steps { sshPublisher( publishers: [ sshPublisherDesc( configName: prod-server, transfers: [ sshTransfer( sourceFiles: target/*.war, remoteDirectory: /opt/tomcat/webapps, execCommand: sudo systemctl restart tomcat ) ] ) ] ) } } } }把这段脚本复制到任务的“Pipeline script”输入框保存后点“Build Now”试一下。如果一切正常第一次构建就会帮你完成从代码到部署的全部动作。这段脚本里的 sshPublisher 依赖 Publish Over SSH 插件插件里需要先配置好“prod-server”这个 SSH Server如果没有用这套也可以改用 SSH Pipeline Steps 的 sshCommand 一步到位。5.4 配置 GitLab Webhook 实现自动触发手动触发构建只是第一步真正的持续集成是开发者 push 代码后自动触发构建。用 GitLab 的话在 GitLab 项目里打开“Settings - Webhooks”URL 填 Jenkins 的 GitLab 插件地址http://jenkins地址:8080/project/任务名Secret token 填 Jenkins 那边配置的 token然后勾选 Push events保存。之后每一次 push 代码GitLab 就会通知 Jenkins 自动开始构建。Jenkins 这边要确保任务配置里勾选了“GitLab 触发器”Build when a change is pushed to GitLab并填写与 Webhook 一致的 Secret token。两边 token 对不上会报 401这个是最容易踩的坑。调试的时候可以在 GitLab 的 Webhook 页面点击“Test”按钮然后看 Jenkins 任务的“GitLab hook log”有没有收到请求用这个方法快速定位问题。5.5 钉钉自定义消息推送构建完成了怎么通知到人用 DingTalk 插件把构建结果推送到钉钉群是很常见的方式。先在钉钉群里添加一个“自定义机器人”安全设置建议用“加签”方式Webhook 地址和加签密钥保存好。然后在 Jenkins 的“System”配置里找到“钉钉”区域添加一个机器人填写 Webhook 和密钥。Pipeline 里可以这样调用stage(钉钉通知) { steps { dingtalk( robot: default, type: MARKDOWN, title: 构建通知, text: [ ### ${env.JOB_NAME} 构建${currentBuild.currentResult}, - 构建编号${env.BUILD_NUMBER}, - 构建地址[点击查看](${env.BUILD_URL}) ].join(\n) ) } }DingTalk 插件支持自定义消息模板上面这种把环境变量和当前构建结果拼进去的写法能让你在群里一眼看到关键信息。想更进阶一点可以在流水线里用 try/catch 或 post 块实现构建成功、失败时发送不同内容的消息。6. 常见问题排查与避坑速查6.1 构建时 Docker 拉镜像报错registry-1.docker.io 连接不上这是我这几年回答频率最高的问题之一。报错信息通常是前面提到过的 Get https://registry-1.docker.io/v2/ 连接被取消或者是“manifest for xxx:latest not found”。前者大概率是网络连通性问题先检查 Docker 是否配置了镜像加速再检查构建机器能不能正常访问外网。后者则是镜像 tag 写错了或者镜像真的不存在先到镜像仓库页面确认一下 tag。我自己的处理顺序是先 docker pull 单独拉一次镜像看能不能复现能复现就确认是网络问题然后改 daemon.json、重启 Docker如果单独拉没问题就是 Jenkins 任务里镜像地址写错检查环境变量或凭据里的仓库地址。记住最容易忽略的是“Docker 服务本身是用旧配置启动的”改完 daemon.json 不重启等于没改。6.2 插件安装失败、升级站点失效的排查思路插件安装失败的常见原因有两个网络连不上官方源或者插件版本与 Jenkins 核心版本不兼容。第一个问题用国内镜像源解决第二个问题需要去插件的 GitHub 页面查看它支持的 Jenkins 最低版本。如果插件列表已经加载出来了安装时却报“Failed to download”多半是镜像站临时抽风换个镜像地址再试。升级站点镜像配置好后如果发现“Available”插件列表还是空的可以清理一下 Jenkins 的本机缓存。在 JENKINS_HOME/updates 目录下有个 default.json 文件把它删掉再重启 Jenkins让它重新从镜像源拉取一次插件列表。这样操作之后插件列表一般就能正常显示。6.3 端口占用、权限不足与服务自动退出启动失败或者访问不了的时候先看 systemctl status jenkins 的状态。8080 端口被占用的话修改 /etc/default/jenkinsDebian 系或 /etc/sysconfig/jenkinsRedHat 系里的 HTTP_PORT 改成其他端口。50000 端口是 Jenkins 的 agent 通信端口如果跑 agent 也记得检查这个端口没被防火墙拦。权限类问题最常见的表现是任务执行报“Permission denied”。检查 JENKINS_HOME 目录的所有者是否正确默认是 jenkins 用户再看任务里涉及的命令有没有写文件到 Jenkins 用户无权限的目录。特别是用 sudo 重启服务这种情况一定要在 sudoers 里配置 jenkins 用户免密执行对应的命令否则流水线跑到重启那一步会一直卡在等待密码输入。6.4 忘记管理员密码、凭据验证失败这类“密码问题”忘记管理员密码这事不难解决修改 JENKINS_HOME/users 目录下对应用户的 config.xml把 password_hash 那行替换成一段新的 bcrypt 或者 SHA-256 哈希即可网上有现成的哈希生成工具。改完保存重启 Jenkins 再用新密码登录。不过更推荐的做法是提前把管理员账号绑定到自己的企业账号系统用 LDAP 或者 OIDC 统一登录省去维护这套密码。凭据验证失败在 Windows 上出现得最多第三章提过在 Linux 上则要检查是不是凭据类型选错了。如果拉代码用的是 SSH URL凭据类型必须选“SSH Username with private key”如果用的是 HTTPS URL选“Username with password”或“GitLab API token”。类型不对点 Verify 永远过不了。6.5 Jenkins MCP把 AI 引入构建流程的扩展方向最后提一个比较新的玩法Jenkins 也开始支持 MCPModel Context Protocol了。简单理解MCP 是给 AI 工具提供统一接口的协议装上相关的 MCP 配置之后你可以让 AI 助手直接查询 Jenkins 的构建状态、触发构建、拉取任务日志。这属于把 Jenkins 和 AI 结合的前沿方向在测试环境体验一下还挺有意思但生产环境建议等社区方案更成熟之后再统一评估。除了 AI 结合Jenkins 后续还可以往这几个方向扩展多节点 agent 横向扩容、流水线加上代码扫描和自动化测试环节、部署产物发到制品仓库Nexus/Artifactory、构建历史定时清理防止磁盘膨胀等等。6.6 常见报错速查表报错现象可能原因推荐解决方式浏览器无法访问 Jenkins 页面服务未启动、端口被占、防火墙拦截systemctl start jenkins确认 8080/50000 端口放行Git 拉代码报 Authentication failed凭据类型错误、Token 失效重新配置凭据并点击 Verify 验证插件下载失败或列表为空官方源不稳定、镜像源未生效切换为国内升级站点删除 default.json 后重启Docker 拉镜像超时或连接取消Docker 未配置镜像加速修改 daemon.json填入 registry-mirrors 后重启 Docker构建提示 target/*.war 找不到Maven 输出路径不对确认 pom.xml 的 packaging 类型和输出目录部署阶段 Permission deniedJenkins 用户无目标目录写权限调整目录属主或配置 sudoers 免密我在实际部署环境里踩过不少回坑最深的体会就是Jenkins 安装本身并不是难事难的是把整个体系搭得“顺手”。安装前多花十分钟做好环境规划装完后第一时间处理镜像加速和凭据管理比后面遇到问题再返工要高效得多。目前这套流程我团队已经稳定跑了大半年期间除了偶尔的镜像源抖动几乎没有再出过大的故障。如果你照着这篇文章搭好自己的第一套 CI 环境建议先从一个小项目开始跑起先跑通再优化逐步加上代码检查、制品归档、多分支流水线这些能力机器和任务多了之后再考虑迁移到容器化部署。到那时候你会发现Jenkins 的核心价值根本不是“装起来”而是“用起来”之后的持续集成流程真的能帮团队省下大量重复劳动。