先说这次要解决的问题。开发团队用 Git 管理代码用 Maven 管理依赖和构建但每次发布都靠手动执行mvn clean install、手动上传服务器、手动重启服务流程长、易出错、难追溯。Jenkins 的出现就是把这些重复工作自动化提交代码后自动拉取、自动构建、自动打包、按需发布。这篇文章围绕“Jenkins 工作流程 Jenkins 安装 Maven 和 Git”这个主题完整梳理一套从零开始的本地 CI 环境搭建流程内容包括工作流程拆解、环境准备、Jenkins 部署、Maven 与 Git 安装配置、任务创建、构建验证、常见问题排查和工程化建议。无论你是刚开始接触持续集成的开发新人还是准备在团队内部搭建自动化构建服务的技术负责人这篇文章可以直接作为操作参考。1. Jenkins 工作流程全景先看 Jenkins 在实际项目中是怎么运转的。一个典型的 Jenkins 自动化构建流程可以拆成六个阶段代码提交、代码拉取、构建编译、测试打包、部署发布、结果通知。从开发者的角度看日常只做一件事把代码推送到 Git 仓库。后面的环节全部由 Jenkins 自动完成。Jenkins 通过触发器感知代码变更然后分配执行节点运行构建任务最终把构建产物部署到目标服务器并把结果通过邮件或即时通讯工具告知相关人员。这里用文字描述一个常见的工作流程图方便对照后续配置开发者推送代码 - Git 仓库收到更新 - Jenkins 触发器轮询 / Webhook - Jenkins 从 Git 拉取最新源码 - Maven 执行 clean compile - 执行单元测试 test - 打包 package - 发布产物到目标服务器 - 发送构建结果通知这个流程中最核心的两个外部工具就是 Maven 和 Git。Git 负责“代码从哪里来”Maven 负责“代码怎么变成可运行的产物”。Jenkins 本身不内置这两样东西需要在 Jenkins 安装后单独装好并配置全局工具路径。这也是本文题目的由来要让 Jenkins 跑通完整工作流必须先让 Jenkins 能用上 Maven 和 Git。2. 核心能力速览能力项说明项目类型持续集成 / 持续交付自动化服务核心功能定时/触发构建、源码拉取、Maven 构建、打包发布、结果通知主要配合工具Git源码管理、Maven构建工具、JDK编译环境支持平台Windows / Linux / macOS也支持 Docker 部署启动方式系统服务启动、java -jar jenkins.war启动、Docker 容器启动是否支持 API支持Jenkins 提供 REST API 和远程构建触发接口是否支持批量任务支持可创建多个任务并编排执行顺序硬件要求2 核 CPU / 4 GB 内存起步实际按任务并发量决定配置复杂度中等核心难点集中在工具链配置和权限管理需要说明的是表里的硬件要求是通用参考。如果你的项目规模很小、并发构建少2 核 4 GB 足够如果团队人数多、构建频繁建议根据实际负载调整机器规格。3. 适用场景与使用边界Jenkins 适合这几类场景个人项目自动化打包每次提交代码后自动执行构建省去手动命令。团队持续集成多人协作时每次合并代码自动编译和跑测试提前发现问题。自动部署到测试环境构建通过后自动上传到测试服务器减少发布等待时间。定时任务比如每天凌晨执行完整测试和报告生成。多环境多分支管理开发分支、测试分支、生产分支用同一个 Jenkins 服务分别构建。不建议直接用 Jenkins 承担的场景也要说清楚生产环境高频发布且需要复杂灰度策略的建议调研专门的发布平台或容器化发布方案。Jenkins 服务本身单点部署时它挂了以后所有构建都会停关键场景要考虑主从架构或高可用方案。Jenkins 所在机器需要严格控制访问权限暴露到公网且无认证的 Jenkins 很容易被当作挖矿或扫描目标。安全与合规方面也必须注意Jenkins 任务执行过程中会拉取代码、执行命令行、上传服务器所有操作都应在合法授权范围内进行。涉及私有仓库、服务器口令、云平台密钥时要使用 Jenkins 的凭证管理功能不要明文写在构建命令里。构建脚本如果涉及生产数据或敏感系统务必做权限隔离和操作审计。4. 环境准备与前置条件在正式安装之前先梳理需要准备的环境项。下面的清单是通用的实际版本按你的操作系统和项目需求调整。4.1 操作系统Jenkins 官方支持主流操作系统实际部署中最常见的是 CentOS 7/8、Ubuntu 20.04/22.04、Windows Server 和 macOS。下面以 Linux 命令为主Windows 用户把安装包换成.msi或.war即可。4.2 JDK 要求Jenkins 本身是 Java 应用运行前必须安装 JDK。不同版本的 Jenkins 对 JDK 版本要求不一样较新版本的 Jenkins 通常要求 JDK 11 或 JDK 17。建议安装前先确认你准备下载的 Jenkins 版本对应的 JDK 要求避免启动时报UnsupportedClassVersionError。java -version如果还没有 JDK可以用系统包管理器安装。下面以 Ubuntu 和 CentOS 为例给出参考命令# Ubuntu sudo apt update sudo apt install openjdk-17-jdk # CentOS sudo yum install java-17-openjdk-devel安装后确认java -version4.3 端口规划Jenkins 默认端口是 8080。如果本机已有其他服务占用启动前可以修改端口。下面是常见的端口调整方式按实际部署方式选择。4.4 磁盘空间Jenkins 会存储构建记录、插件、工作区文件长时间运行会占用不少磁盘。建议预留 20 GB 以上的空间并定期清理旧构建记录。Maven 构建过程中还会下载大量依赖到本地仓库磁盘需求随项目依赖规模增加。4.5 网络准备安装 Jenkins 插件、Maven 下载依赖、Git 拉取代码都需要网络连接。如果是内网环境需要提前准备离线插件包或配置内网镜像源。Maven 仓库建议在settings.xml里配置阿里云镜像加速依赖下载这一步在后面会详细说明。5. Jenkins 安装与启动这一部分给出三种常见安装方式实际选择一种即可。为方便演示我们先从最通用的war 包方式开始。5.1 通过 war 包启动war 包方式适合快速体验和后续迁移。到 Jenkins 官网下载对应的jenkins.war文件后使用 Java 直接启动java -jar jenkins.war --httpPort8080默认情况下Jenkins 会在启动过程中生成一个初始管理员密码并自动安装基础插件。启动日志中会打印Jenkins initial setup is required. An admin user has been created and a password generated.之类的信息密码文件位置一般在/root/.jenkins/secrets/initialAdminPassword也可以直接用命令查看cat /root/.jenkins/secrets/initialAdminPassword5.2 通过系统服务方式安装Linux 系统下更推荐使用官方仓库或系统包安装把 Jenkins 注册成服务方便开机自启。下面是基于 Debian/Ubuntu 的安装流程示意具体命令以官方文档为准sudo wget -O /usr/share/keyrings/jenkins-keyring.asc \ https://pkg.jenkins.io/debian-stable/jenkins.io-2023.key 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 /dev/null sudo apt-get update sudo apt-get install jenkins sudo systemctl start jenkins sudo systemctl enable jenkins安装完成后服务默认监听 8080 端口访问http://服务器IP:8080即可进入初始化页面。5.3 通过 Docker 方式部署如果本机已经安装了 Docker也可以直接用容器方式运行这种方式对环境隔离更友好。下面是一个参考命令docker run -d \ --name jenkins \ -p 8080:8080 \ -p 50000:50000 \ -v jenkins_home:/var/jenkins_home \ jenkins/jenkins:lts这里把宿主机 8080 端口映射到容器内 8080同时把 Jenkins 数据目录挂载到宿主机避免容器删除后配置丢失。实际使用时需要先确认镜像是否可以从你所在的网络环境正常拉取如果是内网环境需要提前准备好镜像文件。5.4 初始化配置启动完成后浏览器打开 Jenkins 页面第一次访问会进入解锁界面。把上面查到的初始密码填进去然后选择“安装推荐插件”或“选择插件来安装”。作为新手建议直接“安装推荐插件”里面已经包含 Git、Pipeline、邮件通知等常用插件。插件安装完成后系统会要求创建管理员用户填写用户名、密码和邮箱即可。之后进入 Jenkins 主界面部署部分就完成了。6. Jenkins 中安装与配置 Maven先明确 Maven 在这里的角色Jenkins 本身不做 Java 编译和打包它只是调度平台。Maven 是真正执行clean install命令的工具所以 Jenkins 构建机必须能够拿到 Maven。这个“拿到”包含两层意思一是机器上确实安装了 Maven二是 Jenkins 知道去哪里调用它。6.1 安装 Maven从 Maven 官网下载二进制压缩包然后解压到指定目录。以 Linux 为例# 下载 Maven 二进制包版本号按需替换 wget https://archive.apache.org/dist/maven/maven-3/3.9.6/binaries/apache-maven-3.9.6-bin.tar.gz # 解压到 /opt 目录 sudo tar -zxvf apache-maven-3.9.6-bin.tar.gz -C /opt # 配置环境变量 sudo vim /etc/profile在文件末尾追加以下内容export MAVEN_HOME/opt/apache-maven-3.9.6 export PATH$MAVEN_HOME/bin:$PATH然后执行source /etc/profile mvn -version如果能看到 Maven 版本号说明安装成功。6.2 配置 Maven 镜像仓库Maven 默认从中央仓库下载依赖国内网络环境下速度不稳定。推荐修改 Maven 的settings.xml配置阿里云镜像。文件位置在 Maven 解压目录下的conf/settings.xml。mirrors mirror idaliyunmaven/id mirrorOfcentral/mirrorOf name阿里云公共仓库/name urlhttps://maven.aliyun.com/repository/public/url /mirror /mirrors保存后后续 Jenkins 构建时使用该 Maven 的settings.xml依赖下载速度会明显提升。6.3 Jenkins 全局工具配置进入 Jenkins 主界面点击“系统管理” - “全局工具配置”找到 Maven 配置区域。这里有两种方式自动安装勾选“自动安装”Jenkins 会自动下载指定版本的 Maven。手动指定选择“本地安装”填写 MAVEN_HOME 路径例如/opt/apache-maven-3.9.6。建议使用手动指定方式能复用你已经配置好镜像源和本地仓库的 Maven 实例避免 Jenkins 再下载一份默认配置的 Maven导致镜像源失效。配置完成后保存Jenkins 就能在构建任务中直接调用 Maven 了。7. Jenkins 中安装与配置 GitGit 的作用是让 Jenkins 从代码仓库拉取源码。Jenkins 自身内置了 Git 客户端插件但系统里仍然需要安装可用的 Git 命令。7.1 安装 GitLinux 环境直接用系统包管理器安装# Ubuntu sudo apt install git -y # CentOS sudo yum install git -y安装后确认版本git --versionWindows 环境需要从 Git 官网下载安装包安装时注意选择“Git from the command line and also from 3rd-party software”确保 Jenkins 能通过命令行找到git.exe。7.2 配置 Git 用户信息在构建机上建议先配置一个通用的 Git 用户和邮箱因为 Jenkins 在拉取某些仓库或执行 Git 操作时可能会用到git config --global user.name jenkins git config --global user.email jenkinsexample.com7.3 在 Jenkins 中添加 Git 凭证如果代码仓库是公开的直接填仓库地址即可。如果是私有仓库需要在 Jenkins 里保存账号密码或 SSH 私钥。点击“系统管理” - “凭证” - “系统” - “全局凭证”然后添加凭证。常见方式有两种Username with password适用于 HTTP/HTTPS 方式访问 Git 仓库。SSH Username with private key适用于 SSH 方式访问 Git 仓库需要把构建机的公钥添加到 Git 仓库的 Deploy Keys 或用户 SSH Keys 里。添加完成后在任务配置里选择对应的凭证即可明文密码不会出现在构建日志中。8. 构建任务配置与工作流验证这一步把 Maven 和 Git 串起来创建第一个 Jenkins 构建任务。8.1 创建自由风格任务在 Jenkins 主界面点击“新建任务”输入任务名称选择“自由风格软件项目”。8.2 配置源码管理在“源码管理”区域选择 Git填写仓库地址选择已添加的凭证再指定要构建的分支。例如Repository URL: https://github.com/your-org/your-project.git Credentials: 选择已添加的凭证 Branches to build: */main8.3 配置构建触发器“构建触发器”决定任务什么时候执行。如果不想做复杂的 Webhook 配置最简单的方式是“轮询 SCM”让 Jenkins 定时检查仓库是否有变更H/5 * * * *意思是每 5 分钟检查一次仓库。如果有新提交就触发构建。这种方式配置简单缺点是存在一定的延迟。如果是内网 GitLab也可以配置 Webhook在代码提交后由 GitLab 主动通知 Jenkins。这需要 Jenkins 开启“远程触发构建”并配置一个 token。8.4 配置构建步骤在“构建”区域点击“增加构建步骤”选择“调用顶层 Maven 目标”。Maven 版本选择前一步配置好的全局 Maven目标填写clean install -DskipTestsfalse如果想跳过测试加快构建可以写clean install -DskipTests更稳妥的做法是让测试阶段先跑一遍确认没有问题后再考虑跳过。如果项目里没有测试用例直接clean package也可以。8.5 执行构建并查看结果保存任务后点击“立即构建”。第一次构建会创建一条构建历史点进去可以看到控制台输出。判断成功的标准是出现BUILD SUCCESS和Finished: SUCCESS。如果出现BUILD FAILURE需要回到控制台输出里找报错信息。这里强调一个习惯构建失败时先看靠后的报错日志再看 Maven 的报错区块不要从第一行日志开始读。常见的失败集中在依赖下载失败、编译错误、测试失败和网络超时。8.6 构建产物位置Maven 执行package或install后会在项目的target目录下生成 jar 包或 war 包。通过 Jenkins 控制台可以拿到工作区路径也可以在后置操作中把构建产物归档到 Jenkins 任务页面。如果需要把 jar 包部署到远程服务器可以添加“构建后操作”比如通过 SSH 插件上传文件并远程执行脚本。这里不展开复杂部署先确保本地构建链路通。8.7 关于 Jenkins 环境变量在构建脚本中可以引用 Jenkins 提供的默认环境变量。常用的几个包括环境变量含义WORKSPACE当前任务的工作区路径JOB_NAME当前任务名称BUILD_NUMBER当前构建编号BUILD_URL当前构建的详情页面地址GIT_COMMIT当前构建对应的 Git 提交号GIT_BRANCH当前构建的分支名这些变量可以在构建步骤的命令行里直接使用例如把构建产物按构建号重命名cp target/my-app.jar target/my-app-${BUILD_NUMBER}.jar9. 接口 API 与批量任务Jenkins 除了页面操作还提供了 REST API支持通过脚本触发构建、查询构建状态、获取控制台输出等能力。这对于把 Jenkins 集成到公司内部平台非常有帮助。9.1 远程触发构建以自由风格任务为例如果配置了“远程触发构建”并设置了 token可以使用下面的命令触发curl -X POST http://JENKINS_URL/job/my-job/build?tokenYOUR_TOKEN如果任务启用了参数化构建可以改用curl -X POST http://JENKINS_URL/job/my-job/buildWithParameters?tokenYOUR_TOKENBRANCHmain这种方式非常利于做批量任务编排。运维平台可以通过一条命令队列多个构建任务。9.2 查询构建状态curl -u username:apiToken http://JENKINS_URL/job/my-job/lastBuild/api/json返回 JSON 中包含result字段可能是SUCCESS、FAILURE或BUILDING。注意这里的用户名和密码建议使用 Jenkins API Token而不是登录密码。API Token 可以在用户设置页面生成。9.3 Python 调用示例import requests jenkins_url http://127.0.0.1:8080 job_name my-job api_token your-api-token username your-username # 构建指定分支 response requests.post( f{jenkins_url}/job/{job_name}/buildWithParameters, params{token: remote-token, BRANCH: main}, auth(username, api_token), timeout10 ) print(response.status_code) # 查询最近一次构建结果 status requests.get( f{jenkins_url}/job/{job_name}/lastBuild/api/json, auth(username, api_token), timeout10 ).json() print(status.get(result))9.4 批量任务设计建议如果有多模块项目或微服务项目建议按模块拆分成多个 Jenkins 任务然后用 Pipeline 或“构建后操作”串起来。例如先构建公共依赖模块再构建服务 A 和服务 B最后汇总部署。批量任务注意两点一是每个任务要加超时控制二是失败的模块要能快速定位和单独重跑。10. 资源占用与性能观察Jenkins 本身比较轻量内存占用主要看 JVM 参数和并发构建数量。默认启动方式下Jenkins 进程占用内存大约在几百 MB 到 1 到 2 GB 之间。但构建时的真实负载并不来自 Jenkins 本体而是来自构建任务里启动的 Maven 进程。Maven 构建 Java 项目时需要启动 JVM默认堆内存可能不够用。如果项目比较大建议在 Maven 的MAVEN_OPTS里做限制export MAVEN_OPTS-Xms512m -Xmx2048m观察性能时重点看两个维度机器整体负载执行top或htop查看 CPU 和内存。构建耗时变化同一个任务连续构建多次对比控制台输出的耗时。影响构建速度的主要因素包括依赖下载速度、是否使用本地仓库缓存、源码编译量、测试用例数量、构建机 CPU 核数。要提高构建效率优先做三件事给 Maven 配置国内镜像、保留本地仓库缓存、控制并发构建数量。降低负载的建议不要开太多并发构建默认同时执行的任务数可以调低。定期清理历史构建记录释放磁盘和内存。使用“丢弃旧的构建”策略只保留最近 N 次构建记录。构建机上不要运行过多其他重型服务。11. 常见问题与排查方法部署和配置过程中遇到问题很常见。下面列了几个高频问题对照排查能省不少时间。问题现象可能原因排查方式解决方案Jenkins 启动后页面打不开端口被占用或服务未成功启动查看启动日志检查端口监听换端口重启或停掉占用进程Maven 目标找不到Jenkins 全局工具配置里的 Maven 路径不对在构建机执行mvn -version查看 Jenkins 系统信息修改全局工具配置改为正确的 MAVEN_HOMEGit 拉取代码失败凭证错误或网络不通查看控制台输出中的 Git 命令和错误信息重新添加凭证检查网络和仓库地址依赖下载很慢未配置镜像源查看 Maven 日志中的下载 URL配置阿里云镜像并重启构建unable to find valid certification path to requested target访问 HTTPS 仓库时证书校验失败查看日志确认目标 URL检查证书链或改用可信镜像仓库构建一直卡在测试阶段测试用例执行时间过长或测试中断查看测试报告和线程 dump调整测试策略按模块拆分执行构建成功但产物体积异常小Maven 未真正完成编译或 package 配置有问题查看 target 目录内容检查 pom.xml 中的 packaging 配置管理员忘记密码认证信息丢失按官方文档重置修改 JENKINS_HOME 下的配置文件并重启这里单独说一下unable to find valid certification path这个问题。它通常出现在 Jenkins 或 Maven 访问需要 HTTPS 证书校验的仓库时。如果仓库证书是自签名的或者 JDK 的 cacerts 里没有对应证书就会报这个错。临时解决可以把 Maven 仓库地址换成使用可信证书的镜像源长期使用则应该把正确的证书导入 JDK 的信任库中。这属于环境合规问题不建议通过关掉证书校验的方式处理。12. 最佳实践与使用建议到这里整套流程已经跑通了最后补充几点工程化建议尽量让这套 CI 环境在团队里稳定运转。第一第一次使用 Jenkins 配置工具链时先在构建机上手动执行一遍 Maven 命令。确认 Maven 本身能正常编译项目后再配置到 Jenkins 里。否则 Jenkins 构建失败时很难判断是 Jenkins 配置问题还是 Maven 环境问题。第二保留一套最小可运行配置。比如一个简单的 Java 项目只需要一条mvn clean package命令就能构建成功。把它作为 Jenkins 的“冒烟测试任务”后面新加的复杂任务出问题时先用它验证 Jenkins 服务本身是否健康。第三模型文件、第三方依赖这类需要长期留存的资源要放在独立目录里管理不要把依赖和构建产物混在 Jenkins 工作区里。Jenkins 清理工作区时会误删文件导致下次构建失败。第四批量任务一定要加日志和失败重试机制。Jenkins 的“构建后操作”支持根据构建结果触发其他任务或发送通知。也可以用 Pipeline 脚本定义完整的失败处理逻辑建议至少做到“失败后停止下游任务并将日志发送到相关人”。第五接口服务要限制访问范围。如果开放了远程触发构建建议把 Jenkins 服务绑定在内网地址不要直接暴露公网。也可以在 Nginx 层做 IP 白名单和访问认证。第六环境变量和账号密码不要写入构建脚本。Git 凭证、服务器部署密码、云密钥统一放到 Jenkins 凭证管理里。第七合规提醒本文所有操作仅适用于自有或已获授权的代码仓库和服务器环境。不要对他人代码库做未经授权的自动化构建不要在未确认授权的情况下处理涉及个人信息、版权内容或敏感数据的任务。生产环境的发布操作应经过测试环境验证和项目负责人确认。第八构建成功不代表业务正确。Jenkins 返回BUILD SUCCESS只说明编译和打包通过代码层面的业务功能还需要配合测试用例和人工复核。在正式发布前建议增加自动化测试覆盖并对产物做一次完整验证。13. 总结与下一步这篇文章从一条完整的 Jenkins 工作流程开始把 Git、Maven 和 Jenkins 三者的关系讲清楚了然后依次完成了 Jenkins 安装启动、Maven 安装与镜像配置、Git 安装与凭证配置、构建任务创建与验证。最后讨论了远程 API 触发、批量任务、性能观察和常见问题。如果你现在还没有装 Jenkins最优先去验证的东西是git 仓库能否正常拉取、mvn 命令能否执行成功、Jenkins 全局工具配置能否正确指向当前环境的 Maven 和 Git。这三个点确认后整套 CI 主链路基本就通了。最容易踩的坑集中在三处证书校验失败、Maven 未配置镜像导致依赖下载超时、Jenkins 凭证与实际仓库不匹配。这三类问题在排查阶段出现频率最高建议收藏本文的排查表备用。后续可以继续扩的方向很明确接入 GitLab/Gitea Webhook 实现推送即构建、增加自动化测试报告展示、配置邮件或飞书通知、使用 Pipeline 从自由风格任务迁移到代码化流水线、添加 SSH 远程部署步骤实现构建后自动发布。这个从“手动打包”到“提交即构建”的过程就是 Jenkins 工作流在实际项目里最重要的价值。