开头前阵子给某公司的开发团队搭了一套内网可用的 Jenkins 自动化部署环境用来构建和发布他们的 Maven 项目。整个过程踩了一圈坑从 JDK 版本兼容到插件安装从 仓库私服配置到构建产物发布每一个环节放到外网环境都稀松平常一旦切到内网所有“默认可用”的东西全都变成了手动活。这篇就把这套内网 Jenkins 搭法和 Maven 项目自动化部署流程完整写出来包括我踩过的坑、调整过的参数、以及一键部署脚本的核心逻辑希望能给正在内网环境里折腾 CI/CD 的朋友少走点弯路。这套方案适合谁主要是 Java 团队、微服务团队以及在隔离网络环境里做持续交付和自动化部署的 DevOps 工程师。如果你是刚接手内网 CI/CD 建设或者正在犹豫 Jenkins 能不能在企业内网玩得转这篇文章可以直接对标参考。1. 需求梳理与整体方案设计1.1 内网环境的特殊性和挑战先说结论内网搭建 Jenkins 本身不难难的是把一整条构建链路全部跑到内网里来。我们在公网上搭建 Jenkins基本就是装好 Jenkins、装好脚手架插件、拉代码、构建、发布几乎每一步都有公共仓库支撑依赖都能实时拉下来。可一旦把网络隔离掉整条链路会断成好几截代码仓库在内网Jenkins 去拉取没问题但是 Jenkins 本身所在服务器的 DNS、代理、防火墙规则都要配好Maven 构建依赖需要的内网仓库源要么自己架一个 Nexus 或者 Artifactory要么离线导入依赖包不能让 Maven 默认去找中央仓库Jenkins 插件需要离线安装公网下载好的插件包要手动传进去构建产物要部署到内网的目标服务器不管是 Tomcat、WildFly 还是裸 Spring Boot 服务都依赖内部网络通道。还有一点容易忽略内网环境的服务器普遍资源偏低如果 Jenkins 构建任务一多内存和磁盘压力上来会直接影响构建稳定性。所以设计的时候就得把 Jenkins 安装目录、构建工作空间、Jenkins 主目录、日志目录这些分开规划不能全堆在系统盘。1.2 目标环境假设为了把整个流程讲清楚我统一用下面的环境假设来说明资源配置假设Jenkins 服务器CentOS 7/84C8G磁盘 100G内网 IP 假设 192.168.10.10目标服务器CentOS 72C4G内网 IP 假设 192.168.10.20代码仓库GitLab 内网服务地址 http://192.168.10.30依赖仓库Nexus 私服地址 http://192.168.10.40JDK 版本1.8Maven3.6.3构建产物Spring Boot 可执行 Jar 包这套结构是很典型的中小型 Java 团队内网 CI 环境。Jenkins 和 GitLab、Nexus 分开部署构建机和部署机分离便于权限控制和故障隔离。如果你的环境有差异配置思路是通用的。1.3 为什么选 Jenkins也许有人会问现在大家都在聊 GitLab CI/CD、Drone、云效、CodePipeline为什么还要玩 Jenkins我的观点是Jenkins 在“内网多项目强自定义”的场景下依然是最稳的选择。第一它不依赖某个特定平台纯 Java 应用哪里都能跑第二插件生态极其丰富哪怕内网环境下也能通过离线插件实现几乎全部 CI/CD 能力第三它不是 SaaS 服务数据全部在自己手里对于很多企业来说这是底线要求第四无论团队里谁接手Jenkins 的文档和社区积累都可以作为参考学习成本相对可控。内网环境里工具链的复杂度不在于“谁更先进”而是在于“谁能先跑起来”。Jenkins 在这方面绝对是非常务实的选择。2. 内网环境基础组件准备2.1 JDK 的安装与版本选择Jenkins 本身是 Java 应用所以 JDK 是第一个需要抠细节的点。Jenkins 不同版本对 JDK 的依赖要求不一样早期版本 8 支持得很好新版 Jenkins比如 2.3xx 以后很多需要 JDK 11 以上。为了省事我一般先把 Jenkins 版本确认好再反推 JDK 版本避免前后倒腾。另外目标开发项目的 Maven 构建环境也可能要求 JDK 8 或 JDK 11这里建议把两套 JDK 都备好通过环境变量切换。我实操当中用的版本组合是这样的组件版本JDK给 Jenkins 用OpenJDK 11JDK给 Maven 构建用OpenJDK 8 OpenJDK 11Jenkins2.375 左右LTS 版本Maven3.6.3在 /usr/local 下建立统一的软件安装目录部署规划如下/usr/local/jdk8 /usr/local/jdk11 /usr/local/maven3 /usr/local/jenkinsJDK 的安装用 tar 包解压就行关键是要把配置文件写对。在 /etc/profile 中设置默认 JDK 为 11同时在 Jenkins 系统配置里单独指定 Maven 构建用的 JDK 路径。# /etc/profile 末尾追加 export JAVA_HOME/usr/local/jdk11 export PATH$JAVA_HOME/bin:$PATH export MAVEN_HOME/usr/local/maven3 export PATH$MAVEN_HOME/bin:$PATH配置完记得执行source /etc/profile验证 java -version 和 mvn -version。这一步出了问题后续所有环节都会跟着挂掉。2.2 Maven 私服仓库的搭建与配置内网环境里Maven 有非常关键的痛点默认仓库地址是公网的 Maven Central内网访问不了构建必然失败。所以我们需要在内网搭建一个 Nexus Repository Manager 作为 Maven 私服。它既充当依赖的代理仓库也充当构建产物的发布仓库还能托管团队内部公共模块。我通常会把 Nexus 仓库规划成三块仓库用途要点maven-public公用仓库组聚合下面几个仓库给 Maven 用maven-central远程代理仓库代理 Maven Central仅外网环境可同步maven-releases正式发布仓库允许部署 releases 版本maven-snapshots快照仓库允许部署 snapshot 版本如果内网完全隔离连外网代理仓库都没有那第三方依赖就必须手动导入 Nexus。没什么捷径就是先在能联网的机器上用 Maven 把依赖下载到本地再把本地 repo 目录整体同步进内网服务器最后用 Nexus 的 Admin 界面上传或通过脚本导入到 maven-central 仓库。我推荐通过 Nexus 的 “Upload” 功能建立完整路径规则是先建好目录再传 jar 与 pom 文件。数量巨大时可以使用 Nexus 提供的 REST API 写脚本批量导入这步以后团队依赖管理会轻松很多。Jenkins 服务器上的 Maven 配置文件 settings.xml 也要指向私服而且仓库地址用内网 IP不要配 localhostsettings localRepository/data/maven_repo/localRepository mirrors mirror idnexus/id mirrorOf*/mirrorOf nameNexus Mirror/name urlhttp://192.168.10.40/repository/maven-public//url /mirror /mirrors /settingsmirrorOf设置为*表示所有依赖都走私服保证内网构建时不会因为网络原因去外网拉取导致超时。注意 localRepository 指定到一个足够大的磁盘分区默认 home 目录容易塞满。2.3 GitLab 联动前的准备工作代码仓库选用的是 GitLab当然你换成 Gerrit、Gitea 甚至 SVN 都行关键是无密钥访问。Jenkins 服务器需要能拉取 GitLab 上的代码一般用 SSH key 或者 Access Token 两种方式。我习惯用 SSH key 这种方式因为它更符合 Git 的使用习惯替换密钥起来也方便。先创建 Jenkins 服务器上的专用密钥sudo -u jenkins ssh-keygen -t rsa -b 4096 -C jenkinslocalhost然后把这把公钥追加到 GitLab 对应用户的 SSH Keys 里同时在 Jenkins 里配置 GitLab 凭据。这里有个重要的权限细节git 用户假设是 jenkins 用户必须有访问目标 Git 仓库的权限所以一定要用服务账号去操作不要图省事用 root 身份拉代码。实际生产环境里如果发现 Jenkins 读取代码时报权限拒绝绝大多数就是这个原因。3. Jenkins 的安装与初始化配置3.1 安装方式选型与目录规划Jenkins 在 Linux 上的安装方式主要有几种官方 RPM/DEB 包、Docker 容器、直接 Java 方式跑 war 包。内网环境我建议直接用 war 包方式或者 RPM 包二选一。如果是老版本习惯RPM 包安装很快它会自动创建 jenkins 用户和基本目录结构。但我个人更推荐 war 包方式原因有两点第一更方便管理目录迁移我可以把所有 Jenkins 相关数据统一放到一个数据盘第二war 包方式重启、升级、备份都直观玩坏了可以快速回退。war 包方式启动mkdir -p /data/jenkins_home export JENKINS_HOME/data/jenkins_home java -jar /usr/local/jenkins/jenkins.war --httpPort8080生产环境建议把 JENKINS_HOME 写到 /etc/default/jenkins 或者 systemd 服务文件里而不是靠 export。如果打算用 systemd 管理写入环境变量即可。目录规划上我的习惯是路径用途/data/jenkins_homeJenkins 配置、任务、插件、构建记录等核心数据/data/jenkins_workspaceJenkins 工作空间存放拉取的代码和中间产物/data/maven_repoMaven 本地仓库/data/jenkins_logsJenkins 运行日志/data/backupsJenkins 备份目录这样即使在同一块磁盘上逻辑上也把数据和程序分开清理或扩展时非常方便。3.2 插件初始化与离线插件安装新装的 Jenkins 默认会要求安装插件Unlock Jenkins 界面会提示从中央插件仓库在线安装。内网环境这个步骤几乎必然卡死因为插件仓库域名无法访问。解决办法是把在线安装流程跳过直接离线安装插件。先在公网可以连通的环境走到安装插件这一步或者在公网环境搭一套同版本 Jenkins然后完整打包plugins目录再把这堆 jpi/hpi 文件拷到内网 Jenkins 的 plugins 目录下。这里要特别注意插件版本和 Jenkins 核心版本的兼容性。如果只有个别插件需要安装用 Jenkins 管理界面的“高级”上传方式安装也行。但内网大规模部署推荐离线批量拷贝法效率最高。我这边按照项目需求准备了这些核心插件。插件名用途git拉取 Git 仓库代码maven-pluginMaven 构建集成publish-over-ssh构建产物通过 SSH 发送到目标服务器ssh-agentSSH 密钥管理credentials-binding凭据绑定的使用parameterized-trigger上下游任务触发build-name-setter自定义构建名timestamper构建日志时间戳thinBackupJenkins 配置备份这里特别强调一下 publish-over-ssh内网部署最简单的模式其实是 Jenkins 通过 SSH 把 Jar/War 包传到目标服务器再执行远程脚本。这个插件支持多个服务器支持密码和密钥方式而且你想在远程服务器执行的命令也能直接在配置里写部署流程会变得非常灵活。3.3 系统级配置凭据、全局工具、SSH server接下来进入 Jenkins 系统配置的核心环节分别对应 “凭据”、“全局工具配置”和“系统设置”。先创建凭据。进入“凭据” - “系统” - “全局凭据” - “添加凭据”类型选择 “SSH Username with private key”填写 GitLab 的 SSH 私钥这个用于拉取代码类型选择 “Username with password”填写 GitLab 用户名、密码或 Access Token这是备用方式对于目标服务器 192.168.10.20同样添加一个 SSH 凭据私钥或密码。然后是全局工具配置。在 “Manage Jenkins” - “Tools” 中JDK 安装选择“新增 JDK”不勾选“自动安装”填好 JDK8 和 JDK11 的路径比如 /usr/local/jdk8、/usr/local/jdk11Git 安装填写 /usr/bin/gitMaven 安装填写 /usr/local/maven3 路径。这里有个细节Jenkins 里的“按名称自动安装”依赖外网下载内网里一定要选择“直接指定路径”。最后在系统设置中配置 SSH Server把目标发布服务器填进去Name: 测试环境发布服务器 Hostname: 192.168.10.20 Username: deploy Remote Directory: /home/deploy/deploy_dir认证方式选刚才创建的 SSH 凭据即可。这步配好之后构建完成就可以直接把产物发过去了。4. Maven 项目的自动化构建与部署实现4.1 创建自由风格任务还是流水线Jenkins 支持两种主流任务类型自由风格和流水线Pipeline。我的建议是入门阶段用自由风格因为界面配置直观适合快速验证等到后面项目多了走向 Pipeline 化会更清晰毕竟流水线脚本能放进代码仓库里做版本管理。如果一开始就上 Pipeline对新手不友好出了问题都不知道从哪里排查。先在自由风格里跑通再把逻辑改写成 Pipeline 脚本是比较平滑的过渡路径。这里我会把自由风格方式的配置讲透同时附上一个基础的 Pipeline 示例。4.2 从 GitLab 拉取代码自由风格任务里源代码管理选择 “Git”Repository URLhttp://192.168.10.30/group/project.gitCredentials选择 SSH 凭据Branches to build*/developAdditional Behaviours 可以加 “Advanced sub-modules behaviors”这一步有几个内网环境独有的核心问题第一GitLab 的 SSL 证书问题。内网很多 GitLab 是自签名证书Jenkins 拉取时默认报证书错误。这时候你在Advanced sub-modules behaviors或者其他地方还不好直接解决通常要给 Jenkins 服务器配置 Git 跳过证书校验git config --global http.sslVerify false虽然是权宜之计但在内网可控环境下这是最高效的。如果公司安全要求严格那就把 GitLab 的自签名证书导入 Jenkins 所在服务器 JDK 的 cacerts 信任库里面。第二分支策略。内网团队通常习惯在 develop 或 release 分支集成所以直接指定分支比用 “**” 通配符更明确避免发生把别人的临时分支部署到测试环境的事故。4.3 Maven 构建从清理到打包构建这一步是核心。构建触发器选 “Poll SCM” 或“远程触发”不过很多内网场景是手动点击立即构建验证阶段这是最快的。构建环境勾选 “Add timestamps to the Console Output”构建日志加时间戳排查问题的时候特别有用。构建步骤选择 “Invoke top-level Maven targets”。Maven Version 选择刚才配置的 Maven-3.6.3Goals 填写clean compile install -Dmaven.test.skiptrue如果你是把构建产物直接发到目标服务器那么 install 可以改成 package区别在于 install 会把 jar 包放上私服如果有部署私服仓库配置package 只在本地生成 tar 包。那很多团队还会再加一条 deploy 到私服的任务这时候 Goals 则是clean deploy -Dmaven.test.skiptrue部署到 Nexus 私服的 settings.xml 需要 server 认证配置servers server idnexus-releases/id usernameadmin/username passwordadmin123/password /server server idnexus-snapshots/id usernameadmin/username passwordadmin123/password /server /servers注意 pom.xml 里 distributionManagement 必须写好对应的 repository id否则 Jenkins 构建会报 401 认证错误。4.4 构建产物发布与远程脚本执行构建完成后用 Publish Over SSH 把 jar 包发到 192.168.10.20 目标服务器。在 “Post-build Actions” 中增加 “Send build artifacts over SSH”。Name选择之前配的 SSH ServerSource filestarget/*.jarRemove prefixtarget/Remote directory/home/deploy/appExec command填写重启服务的脚本命令这里 Exec command 是整个自动化部署的关键。发布之后需要让远端服务器把旧服务停掉替换 jar 包再启动新服务。不能只是把 jar 放过去否则服务一直跑旧版本。示例命令sh /home/deploy/deploy.shdeploy.sh 内容大致是#!/bin/bash APP_NAMEmy-maven-project APP_JAR/home/deploy/app/${APP_NAME}.jar RUN_USERdeploy SERVER_PORT8088 echo Stopping old application ... PID$(pgrep -f ${APP_NAME}.jar) if [ -n $PID ]; then kill -9 $PID sleep 3 fi cp /home/deploy/app/${APP_NAME}.jar /home/deploy/run/${APP_NAME}.jar chown ${RUN_USER}:${RUN_USER} /home/deploy/run/${APP_NAME}.jar cd /home/deploy/run su - ${RUN_USER} -c nohup java -jar ${APP_NAME}.jar --server.port${SERVER_PORT} /dev/null 21 sleep 10 NEW_PID$(pgrep -f ${APP_NAME}.jar) if [ -n $NEW_PID ]; then echo Application started successfully, PID$NEW_PID else echo Application failed to start, please check logs exit 1 fi这套脚本没有用什么高级运维框架但胜在简单稳定。如果目标服务是微服务架构建议后续接入健康检查与确认启动状态的逻辑用 curl 探测 health 接口会更贴合严格上线要求。4.5 参数化构建与一键部署优化当服务不止一个或者部署环境有测试、预发、生产区分的时候每次都去改任务配置太蠢了。我会在 Jenkins 任务中开启 “参数化构建过程”。例如添加一个字符串参数DEPLOY_SERVER192.168.10.20再添加一个选择参数PROJECT_PROFILEtest然后 Maven 构建目标可以变成clean package -DskipTests -P${PROJECT_PROFILE}publish-over-ssh 的 Exec command 可以通过变量动态拼接实现一条流水线对多环境部署。如果再接上 GitLab 的 Webhook 触发 Jenkins实现 push 代码自动构建部署那就齐活了GitLab 项目设置 - Webhooks - 填 Jenkins 地址http://192.168.10.10:8080/job/project/build?tokenTOKENJenkins 任务配置 - 构建触发器 - “触发远程构建”勾选并填同名 token这样就可以做到开发 push 代码到指定分支测试环境自动构建部署整个流程不需要任何人登录 Jenkins。5. Pipeline 方式的自动化部署脚本示例自由风格任务适合快速上手但我也把 Pipeline 脚本贴出来方便有基础的同学参考。把这条脚本放到项目的 Jenkinsfile 里在 GitLab 上和代码一起维护效果最好。pipeline { agent any parameters { choice(name: DEPLOY_ENV, choices: [test, prod], description: Choose deploy environment) } environment { BRANCH develop JAR_NAME my-maven-project.jar SERVER 192.168.10.20 REMOTE_DIR /home/deploy/app } stages { stage(Checkout) { steps { checkout([ $class: GitSCM, branches: [[name: env.BRANCH]], userRemoteConfigs: [[url: http://192.168.10.30/group/project.git, credentialsId: gitlab-ssh-key]] ]) } } stage(Maven Build) { steps { sh mvn clean package -Dmaven.test.skiptrue -P${DEPLOY_ENV} } } stage(Deploy) { steps { sshPublisher( publishers: [ sshPublisherDesc( configName: TEST_SERVER, transfers: [ sshTransfer( sourceFiles: target/*.jar, removePrefix: target, remoteDirectory: app, execCommand: sh /home/deploy/deploy.sh ${JAR_NAME} ) ] ) ] ) } } } post { success { echo Build and deploy success! } failure { echo Build or deploy failed! } } }这里有个体会Pipeline 乱配环境的坑非常多重点在于params.DEPLOY_ENV这一类变量必须在parameters声明后才可以直接使用如果直接在 sh 里用${DEPLOY_ENV}有时会出现未定义变量或者被当成 sh 系统变量的问题所以前十次遇到这种问题都会让人头大。6. 常见问题与排查技巧6.1 构建失败高频原因及处理方式下面这几种错误是我在这套内网环境里踩得最多、也是周围同事问得最多的。现象/报错原因解决办法Host key verification failed.首次访问 GitLab 服务器没有确认主机指纹在 Jenkins 服务器上用 jenkins 用户执行ssh git192.168.10.30手动确认一次或设置StrictHostKeyChecking noFailed to connect to repositoryJenkins 服务器无法解析或访问 GitLab 地址检查 DNS、hosts 文件和防火墙策略。内网建议直接写/etc/hostsCould not transfer artifact from/to centralMaven 依赖拉取走公网仓库强制修改 settings.xml把所有仓库指向 NexusReturn code is 401私服认证信息错误检查 settings.xml 中 server id 与 pom.xml distributionManagement 的仓库 id 是否一致Failed to send build artifactspublish-over-ssh 连接目标服务器失败检查目标服务器 sshd 是否允许密钥认证目录是否存在且有写入权限Port 8080: Address already in useJenkins 端口被占用改用 --httpPort8081 启动6.2 构建日志定位技巧被动等待日志不如主动在系统里埋好观测点。我强烈建议每次构建都在 “Console Output” 里搜索[INFO] BUILD SUCCESS或[ERROR]快速定位阶段开启 timestamper 插件后时间戳能辅助判断是哪一步卡住对于很长的构建日志直接在 Jenkins 页面右上角搜索关键字很实用不用把日志整个拖下来。另外把 Maven 的构建日志和业务日志分开很重要。Jenkins 的构建日志写的是构建过程运行日志写在目标服务器的 nohup.out 或应用日志里。很多新手把这两个概念混了错误排查会浪费非常多的时间。6.3 离线环境的一些长期维护心得最后说几个内网环境长期维护的体验。第一备份计划要从第一天就做。Jenkins 上跑的项目一旦多起来用户权限、插件配置、任务定义都是珍贵的资产。用 thinBackup 插件定期把 JENKINS_HOME 打包备份或者每天凌晨执行一次 tar 压缩加 rsync都能在灾难时刻救命。成本不高收益很大。第二插件版本升级要谨慎。内网环境无法在线自动升级升级的时候不要全部替换插件目录先备份旧版本再逐个更新验证之前的老任务是否还可以正常构建。插件之间很容易出现互相依赖的兼容性变化不验证直接上生产会把自己骗得很惨。第三把部署脚本纳入版本控制。无论是 deploy.sh 还是 Jenkinsfile都放进 Git 仓库管理。脚本和代码一起变更构建时取的是当前分支的脚本就避免了“脚本改了 N 个版本不知道服务器上跑的到底是哪个内容”的混乱局面。第四注意磁盘水位。Jenkins 每构建一次工作空间和构建记录都会增加磁盘占用时间久了磁盘爆炸是必然。定时执行一下旧构建清理逻辑比如保留最近 30 次构建记录把临时产物清掉能省非常多事。第五也就是最重要的一点让开发人员能自查。这套系统如果只有我一个人会用出了问题就会被当成运维瓶颈。把常用部署任务做成参数化构建让开发自己在 Jenkins 页面上选择分支和环境自助式构建部署运维的角色就从“操作员”升级成了“流程设计者”团队效率差别非常大。7. 写在最后这套内网 Jenkins 搭建和 Maven 自动化部署方案本质上就是解决了一个核心问题在没有公网依赖的环境下如何把“代码提交 - 依赖解析 - 构建打包 - 远程部署”这条链路完整地自动化。如果你严格按照步骤走JDK 配置、Maven 私服、插件离线安装、SSH 发布、远程脚本几个环节打通后续再多的项目都只是复制模板的事。我个人实际操作下来体会最深的一点是内网环境下的失败大多数不是“不会配”而是“环境依赖没准备好”。只要把私服仓库、插件库、JDK/Maven 路径、SSH 凭据这些底层设施一次性整利索Jenkins 就是一个非常可靠的自动化引擎。建议你第一套环境尽量用最简单的方式先跑通再去追求流水线、多环境等复杂能力这样无论是排错还是接手的人都会轻松很多。