简介针对内网环境离线部署Jenkins 2.346.1的运维与开发人员该资源聚焦因网络隔离无法直连插件中心的场景提供一套完整可落地的离线插件部署方案适合有一定Jenkins基础、需要在内网完成插件交付的中高级平台管理员参考。压缩包共2000个文件包体大小约314.4MB其中jpi/hpi为可直接安装的插件包jar为插件运行时依赖库xml保存安装与初始化配置js/css/html/svg/png对应Web控制台的静态资源与界面图标方便按需定位和补充。内容覆盖Git、Maven、Ant等常用插件及其依赖同时整理了jenkins.xml初始化脚本、offline-plugins离线插件包的目录组织方式、安装后的验证方法以及后续版本升级与SSL/TLS访问控制等安全加固建议借助该包可快速构建离线插件仓库规避插件依赖缺失、版本不匹配等典型问题。已有3161人学习下载适合需要在内网环境中搭建、迁移或升级Jenkins的团队参考能有效缩短部署周期降低离线安装过程中的踩坑风险。 “你负责的这套系统部署到内网 Jenkins服务器连不了外网插件给我搞定。”如果你经历过这种需求应该能瞬间体会背后的麻烦。最近我刚好帮一个项目组把 Jenkins 2.346.1 完整部署到内网服务器并且解决了离线下载插件的问题。整个过程踩了不少坑尤其是插件依赖这块真不是把几个 .hpi 文件拷进去就能跑的。这篇文章就围绕“内网 Jenkins 2.346.1 离线部署 离线下载插件”这件事把完整的操作步骤、依赖处理原理和排错经验写清楚。适合准备在无外网环境搭建 Jenkins 的运维、开发、DevOps 同学参考。我尽量把这次实操中的细节都交代明白包括为什么要这么干、哪些坑不能踩。1. 部署前必须想清楚的三件事1.1 为什么偏偏是 2.346.1 这个版本如果你去翻 Jenkins 版本发布记录会发现 2.346.1 是 2022 年 4 月发布的 LTS长期支持版本。它有一个很关键的特性仍然完整支持 Java 8。很多企业内部系统尤其是用了多年的 CentOS 7、老 JDK 环境升到 Java 11 是有历史包袱的。而 Jenkins 从 2.357 开始要求 Java 11下一个 LTS 版本 2.361 也把 Java 8 彻底拒之门外。所以如果你的内网服务器里装的是 JDK 1.8选 2.346.1 几乎是唯一省心的选择。另外2.346.1 是 2.346.x 系列的第一个修复版本稳定性比 2.346 原始版本好。官方在 2023 年初结束了该系列的维护周期但社区插件对这代核心的兼容性覆盖非常全面你在离线场景下想找“和它匹配的插件版本”也相对容易。1.2 先分清你的“内网”是哪种内网部署前先确认一个关键问题内网到底能不能访问外网我经历过两种典型情况。第一种是完全物理隔离服务器除了内网 IP 之外没有任何出网能力上不了公网。这种场景最简单的方案就是准备一台有外网的“摆渡机器”把 Jenkins 主程序和插件下载好然后通过 U 盘、跳板机、文件服务器等方式传进内网。第二种是内网能访问一个受限的代理或白名单通道只能访问特定域名。这种情况相对好办可以直接把 Jenkins 的更新中心地址指向公司内部的镜像源或者用代理访问官方源。动手之前先把网络拓扑和出口策略问清楚。这个决定了你后面是走“离线包拷贝”还是走“内网镜像源”路线两者配置方式完全不同。1.3 外网摆渡机器上需要准备什么我这次用的是完全隔离的内网所以需要提前在另一台联网机器上准备以下文件Jenkins 主程序jenkins.war版本 2.346.1JDK 安装包如果内网机器没装 Java需要准备对应版本的离线 rpm 或 tar 包插件文件根据业务需求列清单这一步是大头update-center.json这个别忘后面解析插件版本和依赖时全靠它把文件准备好之后记得用 sha256sum 对每个文件做校验。内网传输过程中文件损坏的情况并不少见尤其是通过不稳定的共享目录拷贝时一个损坏的 hpi 插件会让 Jenkins 在启动阶段反复报错排查起来非常耗时。2. 插件离线下载最容易卡住的一步2.1 理解插件的依赖关系是解决问题的前提每个 Jenkins 插件不是一个孤立的文件。比如你要装 Git 插件它依赖 credentials、ssh-credentials、plain-credentials、structs、workflow-step-api 等一堆底层插件。这些依赖自身又有依赖最后会形成一棵依赖树。我习惯把这件事类比成做饭你不是买一条鱼就完事还得准备葱姜蒜、酱油、料酒、锅碗瓢盆。插件也是这样光把 Git 插件的 hpi 拖进去启动后 Jenkins 会说“缺少 xxx 插件”构建功能根本没法用。在线安装时 Jenkins 会自动解析依赖并全部下载但离线环境没有这个便利。所以你要走的路是在摆渡机上把所有需要的插件连同依赖一起下载完整然后统一传进内网。2.2 方法一从现成的外网 Jenkins 环境里打包如果你手边正好有一个已经联网安装好、且插件列表和你目标环境基本一致的 Jenkins 实例这是最省事的方法。Jenkins 插件在服务器上的默认路径是$JENKINS_HOME/plugins通常是/var/lib/jenkins/plugins。在那个目录下一个插件对应一个.jpi文件比如git.jpi、credentials.jpi。你只需要挑出需要的文件打包传到内网放到内网 Jenkins 的相同目录下即可。这个方法的优势是插件版本已经经过实战验证依赖基本齐全——注意是“基本”而不是“绝对”。因为外网实例可能安装了一些内网不需要的插件而某些插件只装了主体、缺少可选依赖迁移过去后仍可能出现功能缺失。所以传完也要注意看日志不能拷完就认为万事大吉。2.3 方法二从更新中心镜像手动下载 hpi当没有现成外网实例可用时就得到更新中心按名字找插件了。官方插件包的下载地址格式是https://updates.jenkins.io/download/plugins/插件名/版本号/插件名.hpi比如下载 git 插件的某个版本URL 就是https://updates.jenkins.io/download/plugins/git/5.2.1/git.hpi国内访问官方更新中心有时不稳定更推荐用清华镜像或华为云镜像。清华镜像的地址结构是https://mirrors.tuna.tsinghua.edu.cn/jenkins/plugins/插件名/版本号/插件名.hpi手动下载的痛点是版本选择。每个插件页面上会标注“Required Jenkins version”也就是这个插件要求的最低 Jenkins 主版本。你用的 2.346.1 是相对老的版本如果下载了最新插件很可能因为要求 Java 11 或更高 Jenkins 核心而无法加载。所以看到版本列表时优先挑发布日期在 2022 年 6 月之前的版本或者直接看版本号旁边标注的依赖要求。2.4 方法三用 update-center.json 自动解析依赖推荐手动下载插件加依赖插件数量少还好说一旦要装二三十个插件就会疯掉。我这次最终采用的是解析 update-center.json 的自动化方式。update-center.json 是 Jenkins 更新中心的元数据文件里面记录了当前所有插件的最新版本、下载地址、依赖关系、兼容性信息。你可以在联网机器上下载一份wget https://updates.jenkins.io/update-center.json这个文件有几十 MB内容很庞大但结构很规整。每个插件条目下有一个dependencies数组记录了它依赖的插件名和版本范围。我写了一个简单的 Python 脚本递归解析出所有依赖并批量生成下载任务import json, os, urllib.request with open(update-center.json, r, encodingutf-8) as f: text f.read() # 官方文件第一行是一段 js 赋值语句需要去掉前缀 text text[text.index({):] data json.loads(text) plugins data[plugins] download_dir ./jenkins_plugins os.makedirs(download_dir, exist_okTrue) # 这里改成你实际需要的插件名 targets [git, pipeline, configuration-as-code, build-timeout, timestamper] collected {} def collect_deps(name, stackNone): if stack is None: stack [] if name in stack or name in collected: return p plugins.get(name) if not p: print(f[warn] 无法在更新中心找到插件: {name}) return collected[name] p for dep in p.get(dependencies, []): if dep.get(optional): # 可选依赖跳过按需手动补充 continue collect_deps(dep[name], stack [name]) for t in targets: collect_deps(t) for name, p in collected.items(): version p[version] filename f{name}.hpi url p.get(url) or fhttps://updates.jenkins.io/download/plugins/{name}/{version}/{name}.hpi print(f下载插件: {name} {version}) urllib.request.urlretrieve(url, os.path.join(download_dir, filename))脚本里我跳过了 optional 依赖因为这些可选依赖只影响插件的部分扩展功能核心功能通常不依赖它们。第一次跑完脚本后我会再单独检查一遍输出结果把确实需要的可选依赖补充下载避免后续某些功能用不了。这个方案的另一个好处是版本一致性。update-center.json 中每个插件都对应了一个默认兼容版本只要 Jenkins 版本和 update-center.json 的发布时间接近这批插件装上去基本不会出现版本冲突。2.5 插件传到内网后的两种安装姿势插件文件进入内网服务器后有两条路可以走。第一条是用 Jenkins 管理台的上传功能登录 Jenkins进入“Manage Jenkins” - “Plugins” - “Advanced settings”找到“Deploy Plugin”直接上传 .hpi 文件。这种方式会在上传完成后的下次启动时安装插件。注意这里叫 hpi实际上 Jenkins 装好之后在 plugins 目录里是 .jpi两者只是扩展名不同内容格式没有区别。第二条是直接把插件文件拷进$JENKINS_HOME/plugins目录然后重启 Jenkins。我这次用的是这种方式因为插件文件有几十个一个个上传太累。具体做法是把打包好的插件目录整体拷贝过去然后执行chown -R jenkins:jenkins $JENKINS_HOME/plugins最后重启服务。这里要特别提醒如果你通过共享目录或者 U 盘拷贝插件进入 plugins 目录后先检查文件权限。如果文件属主是 root 而 Jenkins 以 jenkins 用户运行启动时可能读不到插件报错却不直观。手动执行chmod -R 644和上面的chown是标准操作。3. Jenkins 2.346.1 的安装与初始化配置3.1 JDK 与运行环境检查内网机器如果没有外网不能直接用 yum 在线安装 JDK需要在摆渡机上提前下载好 rpm 包。比如 CentOS 7 环境我这次用的就是jdk-8u202-linux-x64.rpm放到内网后执行rpm -ivh jdk-8u202-linux-x64.rpm java -version确认输出是 1.8 系列即可。如果你的内网机器本身已经装了 Java 11也完全没事2.346.1 同时支持 8 和 11。内存方面插件数量在二十个左右时Jenkins JVM 堆内存建议至少给 2GB。如果后续要多节点构建、跑流水线建议直接给 4GB。这个在启动参数里设置下节的 service 配置里会体现。3.2 用 systemd 把 Jenkins 变成一个可靠的后台服务很多人图省事直接java -jar jenkins.war在终端里跑一旦终端关了就断掉。生产环境不应该这样。我为 2.346.1 写了一个标准的 systemd 服务文件放在/etc/systemd/system/jenkins.service[Unit] DescriptionJenkins Server Afternetwork.target [Service] Typesimple Userjenkins Groupjenkins WorkingDirectory/var/lib/jenkins EnvironmentJAVA_HOME/usr/lib/jvm/java-1.8.0-openjdk EnvironmentJENKINS_HOME/var/lib/jenkins ExecStart/usr/bin/java -Xms512m -Xmx2048m -jar /usr/local/jenkins/jenkins.war --httpPort8080 Restartalways RestartSec10 [Install] WantedBymulti-user.target写完后执行systemctl daemon-reload systemctl enable jenkins systemctl start jenkins systemctl status jenkins这里有几个细节需要注意。JENKINS_HOME环境变量我显式设置为/var/lib/jenkins避免 Jenkins 默认路径和你预期的位置不一致。WorkingDirectory也设成和 JENKINS_HOME 相同防止某些流水线脚本里用的相对路径解析出错。--httpPort8080可以根据实际改成 8081、8090 等但要确保端口没被其他服务占用。如果默认端口被占用启动会直接失败日志里会看到Port already in use。这时可以改端口也可以使用--httpPort-1关闭 HTTP、只用 HTTPS但内网环境通常没必要那么复杂。3.3 初始化配置强制跳过在线插件安装向导Jenkins 首次启动后访问http://内网IP:8080会进入解锁页面。解锁管理员密码在/var/lib/jenkins/secrets/initialAdminPassword查看并复制密码后来到自定义 Jenkins 页面。这时候如果点“安装推荐的插件”离线环境会卡在下载界面很久最后全部失败非常浪费时间。正确的操作是选择“选择插件来安装”然后在下拉列表里不要勾选任何插件直接点安装。这样可以快速通过初始化进入 Jenkins 主界面。后续再通过前文介绍的离线插件安装方式把 hpi 传进来。初始化完成后进入“Manage Jenkins” - “Plugins” - “Advanced settings”把最下方的“Update Site” URL 改成一个能访问的镜像地址或者保持默认不动。离线环境下如果点击“Check now”去检查更新一定会超时这个没有关系不要因此去反复重试。3.4 修改更新中心和 JENKINS_HOME 目录如果你在内网有 Nexus、Artifactory 之类的私服并且已经同步了 Jenkins 插件源那可以在/var/lib/jenkins/hudson.model.UpdateCenter.xml中修改更新中心地址?xml version1.1 encodingUTF-8? sites site iddefault/id urlhttp://nexus.internal.com/repository/jenkins-updates/update-center.json/url /site /sites改完重启 Jenkins 才会生效。不过说实话绝大多数完全隔离的内网环境没有这种私服我更推荐的做法是不要过度依赖更新中心直接用离线上传插件的方式解决维护成本反而更低。另外JENKINS_HOME 默认在/var/lib/jenkins如果你的系统盘比较小构建日志、插件、工作区文件会把根分区塞满。最好一开始就把 JENKINS_HOME 指到一个独立的、容量充足的数据盘上比如/data/jenkins然后在 service 文件里把 Environment 字段的路径改成对应地址。这个改动一定要在第一次启动前完成否则中途迁移 JENKINS_HOME 会很痛苦。4. 上线和使用中的高频问题与排查技巧4.1 快速定位问题的排错速查表我在这次部署过程中遇到过不少问题下面把这些典型现象和解决办法整理成表格方便你遇到问题时直接对照现象可能原因处理方式启动后插件管理页为空插件目录权限不对检查$JENKINS_HOME/plugins属主是否为 jenkins执行 chown 后重启上传 hpi 后不生效依赖插件缺失查看 Jenkins 日志确认缺哪些依赖补传依赖插件启动报 ClassNotFoundExceptionhpi 文件损坏或版本不兼容用 sha256 校验文件换与 2.346.1 匹配的插件版本首次向导安装插件卡死离线环境尝试访问外网重启 Jenkins初始化时选择“无”插件更新中心 Check now 超时无外网出口或代理未配置忽略使用离线上传插件方式访问 8080 端口超时防火墙未放行firewall-cmd --add-port8080/tcp --permanent firewall-cmd --reload构建任务找不到 git 命令服务器未安装 Git离线安装 git rpm 包或调整构建工具链构建日志乱码字符集问题在 service 里增加EnvironmentLANGen_US.UTF-8上传大体积插件响应缓慢内存不足增大 JVM 堆参数并确保系统有足够内存4.2 插件版本兼容性是离线环境最大的暗坑在线安装插件时Jenkins 会主动拒绝与主版本不兼容的插件。离线上传则没有这层保险装进去之后才发现加载失败。判断插件版本是否兼容最可靠的方式是看插件的“Required Jenkins version”。在官方插件站点或 update-center.json 里每个插件条目都有requiredCore字段。比如某个插件写着requiredCore: 2.60.3那它运行在 2.346.1 上没问题如果写2.346.3那就意味着这个插件要求 Jenkins 核心版本至少 2.346.3而你本机是 2.346.1版本不够需要升级核心或换插件版本。我在准备插件清单时会同时下载 update-center.json 作为参考然后让脚本按插件列表逐项比对 requiredCore 与主版本的大小关系。这样能在摆渡机上下载阶段就过滤掉不兼容版本而不是等传到内网后再返工。4.3 重启是离线插件安装最廉价有效的工具插件上传完成后我见过不少人直接在管理台点“升级/安装”后就开始用然后定位到功能异常。其实 Jenkins 加载插件是一个完整的类加载过程很多插件需要重启后才会完全生效。安全的上线顺序是先把所有 hpi 文件传入 plugins 目录然后执行systemctl restart jenkins等日志输出Jenkins is fully up and running再登录系统逐个验证功能。不要在一个插件刚上传完、还没重启的状态下强行测试容易得到误导性的错误信息。另外如果插件数量多第一次重启会明显偏慢因为 Jenkins 要对所有插件做安装、依赖解析和类校验。这时候不要反复 kill 进程耐心等两到三分钟或者用journalctl -u jenkins -f看实时日志。5. 离线插件的持续维护心得5.1 建立插件版本基线清单离线环境最怕的一件事是“不知道当前环境装了哪些插件、什么版本”。因为不能在线看到可升级列表时间一长环境版本就变成一个黑盒。我建议在首次部署完成后立刻导出一份插件清单ls /var/lib/jenkins/plugins/*.jpi | sed s/.*\///; s/\.jpi$// /data/jenkins_backup/plugins_baseline_$(date %Y%m%d).txt如果有条件更精确的方式是通过 Jenkins 的 Script Console 执行以下 Groovy 脚本Jenkins.instance.pluginManager.plugins.sort { it.getShortName() }.each { println ${it.getShortName()}:${it.getVersion()} }拿到清单后保存到一个 Git 仓库或共享文档里后续每次新增插件、升级插件都更新这份基线。配合 update-center.json 里的元数据你可以随时回溯“当前环境到底是哪一套插件版本组合”。5.2 维护一个外网插件同步站如果你有多个内网环境都要部署 Jenkins不建议每次都在摆渡机上重新下载插件。更好的方式是在一台长期联网的机器上建一个“插件同步目录”把常用插件和 update-center.json 固化下来。我自己的做法是在摆渡机上用 cron 定期执行脚本同步指定插件版本到本地目录同时让内网的同事通过共享目录直接拷贝。这样虽然不能完全自动化但至少保证了每次拿到的插件版本是可复现的不会出现上周能用、这周下载了一个新版本就崩掉的情况。5.3 别漏掉 JENKINS_HOME 的备份插件是部署的一部分但不是全部。真正需要持续备份的是整个 JENKINS_HOME包括config.xml全局配置、jobs/任务定义、credentials.xml凭据、plugins/插件以及secrets/密钥目录。离线环境通常没有现成的备份工具最简单的做法是用 tar 打包tar czf /data/jenkins_backup/jenkins_home_$(date %Y%m%d_%H%M).tar.gz -C /var/lib jenkins恢复到新机器时解压后注意修改配置中的绝对路径同时确认目录属主是 jenkins。不要只备份 plugins 目录而忽略配置和任务那样恢复出来的 Jenkins 等于一个空壳所有构建任务和权限都要重新配置。回看这次内网部署经历我把整个流程跑通后最大的感触是离线部署 Jenkins 本身不难难的是把“插件依赖关系”理清楚。如果能提前把 update-center.json 拿到手再写个小脚本自动解析依赖后面基本不会遇到大问题。另一个经验是不要嫌麻烦跳过版本基线的记录内网环境排查问题时一份准确的插件清单能救你不少时间。希望这篇文章能帮你少走一些弯路。本文还有配套的精品资源点击获取 内网Jenkins 2.346.1离线部署与插件下载全流程解析
简介针对内网环境离线部署Jenkins 2.346.1的运维与开发人员该资源聚焦因网络隔离无法直连插件中心的场景提供一套完整可落地的离线插件部署方案适合有一定Jenkins基础、需要在内网完成插件交付的中高级平台管理员参考。压缩包共2000个文件包体大小约314.4MB其中jpi/hpi为可直接安装的插件包jar为插件运行时依赖库xml保存安装与初始化配置js/css/html/svg/png对应Web控制台的静态资源与界面图标方便按需定位和补充。内容覆盖Git、Maven、Ant等常用插件及其依赖同时整理了jenkins.xml初始化脚本、offline-plugins离线插件包的目录组织方式、安装后的验证方法以及后续版本升级与SSL/TLS访问控制等安全加固建议借助该包可快速构建离线插件仓库规避插件依赖缺失、版本不匹配等典型问题。已有3161人学习下载适合需要在内网环境中搭建、迁移或升级Jenkins的团队参考能有效缩短部署周期降低离线安装过程中的踩坑风险。 “你负责的这套系统部署到内网 Jenkins服务器连不了外网插件给我搞定。”如果你经历过这种需求应该能瞬间体会背后的麻烦。最近我刚好帮一个项目组把 Jenkins 2.346.1 完整部署到内网服务器并且解决了离线下载插件的问题。整个过程踩了不少坑尤其是插件依赖这块真不是把几个 .hpi 文件拷进去就能跑的。这篇文章就围绕“内网 Jenkins 2.346.1 离线部署 离线下载插件”这件事把完整的操作步骤、依赖处理原理和排错经验写清楚。适合准备在无外网环境搭建 Jenkins 的运维、开发、DevOps 同学参考。我尽量把这次实操中的细节都交代明白包括为什么要这么干、哪些坑不能踩。1. 部署前必须想清楚的三件事1.1 为什么偏偏是 2.346.1 这个版本如果你去翻 Jenkins 版本发布记录会发现 2.346.1 是 2022 年 4 月发布的 LTS长期支持版本。它有一个很关键的特性仍然完整支持 Java 8。很多企业内部系统尤其是用了多年的 CentOS 7、老 JDK 环境升到 Java 11 是有历史包袱的。而 Jenkins 从 2.357 开始要求 Java 11下一个 LTS 版本 2.361 也把 Java 8 彻底拒之门外。所以如果你的内网服务器里装的是 JDK 1.8选 2.346.1 几乎是唯一省心的选择。另外2.346.1 是 2.346.x 系列的第一个修复版本稳定性比 2.346 原始版本好。官方在 2023 年初结束了该系列的维护周期但社区插件对这代核心的兼容性覆盖非常全面你在离线场景下想找“和它匹配的插件版本”也相对容易。1.2 先分清你的“内网”是哪种内网部署前先确认一个关键问题内网到底能不能访问外网我经历过两种典型情况。第一种是完全物理隔离服务器除了内网 IP 之外没有任何出网能力上不了公网。这种场景最简单的方案就是准备一台有外网的“摆渡机器”把 Jenkins 主程序和插件下载好然后通过 U 盘、跳板机、文件服务器等方式传进内网。第二种是内网能访问一个受限的代理或白名单通道只能访问特定域名。这种情况相对好办可以直接把 Jenkins 的更新中心地址指向公司内部的镜像源或者用代理访问官方源。动手之前先把网络拓扑和出口策略问清楚。这个决定了你后面是走“离线包拷贝”还是走“内网镜像源”路线两者配置方式完全不同。1.3 外网摆渡机器上需要准备什么我这次用的是完全隔离的内网所以需要提前在另一台联网机器上准备以下文件Jenkins 主程序jenkins.war版本 2.346.1JDK 安装包如果内网机器没装 Java需要准备对应版本的离线 rpm 或 tar 包插件文件根据业务需求列清单这一步是大头update-center.json这个别忘后面解析插件版本和依赖时全靠它把文件准备好之后记得用 sha256sum 对每个文件做校验。内网传输过程中文件损坏的情况并不少见尤其是通过不稳定的共享目录拷贝时一个损坏的 hpi 插件会让 Jenkins 在启动阶段反复报错排查起来非常耗时。2. 插件离线下载最容易卡住的一步2.1 理解插件的依赖关系是解决问题的前提每个 Jenkins 插件不是一个孤立的文件。比如你要装 Git 插件它依赖 credentials、ssh-credentials、plain-credentials、structs、workflow-step-api 等一堆底层插件。这些依赖自身又有依赖最后会形成一棵依赖树。我习惯把这件事类比成做饭你不是买一条鱼就完事还得准备葱姜蒜、酱油、料酒、锅碗瓢盆。插件也是这样光把 Git 插件的 hpi 拖进去启动后 Jenkins 会说“缺少 xxx 插件”构建功能根本没法用。在线安装时 Jenkins 会自动解析依赖并全部下载但离线环境没有这个便利。所以你要走的路是在摆渡机上把所有需要的插件连同依赖一起下载完整然后统一传进内网。2.2 方法一从现成的外网 Jenkins 环境里打包如果你手边正好有一个已经联网安装好、且插件列表和你目标环境基本一致的 Jenkins 实例这是最省事的方法。Jenkins 插件在服务器上的默认路径是$JENKINS_HOME/plugins通常是/var/lib/jenkins/plugins。在那个目录下一个插件对应一个.jpi文件比如git.jpi、credentials.jpi。你只需要挑出需要的文件打包传到内网放到内网 Jenkins 的相同目录下即可。这个方法的优势是插件版本已经经过实战验证依赖基本齐全——注意是“基本”而不是“绝对”。因为外网实例可能安装了一些内网不需要的插件而某些插件只装了主体、缺少可选依赖迁移过去后仍可能出现功能缺失。所以传完也要注意看日志不能拷完就认为万事大吉。2.3 方法二从更新中心镜像手动下载 hpi当没有现成外网实例可用时就得到更新中心按名字找插件了。官方插件包的下载地址格式是https://updates.jenkins.io/download/plugins/插件名/版本号/插件名.hpi比如下载 git 插件的某个版本URL 就是https://updates.jenkins.io/download/plugins/git/5.2.1/git.hpi国内访问官方更新中心有时不稳定更推荐用清华镜像或华为云镜像。清华镜像的地址结构是https://mirrors.tuna.tsinghua.edu.cn/jenkins/plugins/插件名/版本号/插件名.hpi手动下载的痛点是版本选择。每个插件页面上会标注“Required Jenkins version”也就是这个插件要求的最低 Jenkins 主版本。你用的 2.346.1 是相对老的版本如果下载了最新插件很可能因为要求 Java 11 或更高 Jenkins 核心而无法加载。所以看到版本列表时优先挑发布日期在 2022 年 6 月之前的版本或者直接看版本号旁边标注的依赖要求。2.4 方法三用 update-center.json 自动解析依赖推荐手动下载插件加依赖插件数量少还好说一旦要装二三十个插件就会疯掉。我这次最终采用的是解析 update-center.json 的自动化方式。update-center.json 是 Jenkins 更新中心的元数据文件里面记录了当前所有插件的最新版本、下载地址、依赖关系、兼容性信息。你可以在联网机器上下载一份wget https://updates.jenkins.io/update-center.json这个文件有几十 MB内容很庞大但结构很规整。每个插件条目下有一个dependencies数组记录了它依赖的插件名和版本范围。我写了一个简单的 Python 脚本递归解析出所有依赖并批量生成下载任务import json, os, urllib.request with open(update-center.json, r, encodingutf-8) as f: text f.read() # 官方文件第一行是一段 js 赋值语句需要去掉前缀 text text[text.index({):] data json.loads(text) plugins data[plugins] download_dir ./jenkins_plugins os.makedirs(download_dir, exist_okTrue) # 这里改成你实际需要的插件名 targets [git, pipeline, configuration-as-code, build-timeout, timestamper] collected {} def collect_deps(name, stackNone): if stack is None: stack [] if name in stack or name in collected: return p plugins.get(name) if not p: print(f[warn] 无法在更新中心找到插件: {name}) return collected[name] p for dep in p.get(dependencies, []): if dep.get(optional): # 可选依赖跳过按需手动补充 continue collect_deps(dep[name], stack [name]) for t in targets: collect_deps(t) for name, p in collected.items(): version p[version] filename f{name}.hpi url p.get(url) or fhttps://updates.jenkins.io/download/plugins/{name}/{version}/{name}.hpi print(f下载插件: {name} {version}) urllib.request.urlretrieve(url, os.path.join(download_dir, filename))脚本里我跳过了 optional 依赖因为这些可选依赖只影响插件的部分扩展功能核心功能通常不依赖它们。第一次跑完脚本后我会再单独检查一遍输出结果把确实需要的可选依赖补充下载避免后续某些功能用不了。这个方案的另一个好处是版本一致性。update-center.json 中每个插件都对应了一个默认兼容版本只要 Jenkins 版本和 update-center.json 的发布时间接近这批插件装上去基本不会出现版本冲突。2.5 插件传到内网后的两种安装姿势插件文件进入内网服务器后有两条路可以走。第一条是用 Jenkins 管理台的上传功能登录 Jenkins进入“Manage Jenkins” - “Plugins” - “Advanced settings”找到“Deploy Plugin”直接上传 .hpi 文件。这种方式会在上传完成后的下次启动时安装插件。注意这里叫 hpi实际上 Jenkins 装好之后在 plugins 目录里是 .jpi两者只是扩展名不同内容格式没有区别。第二条是直接把插件文件拷进$JENKINS_HOME/plugins目录然后重启 Jenkins。我这次用的是这种方式因为插件文件有几十个一个个上传太累。具体做法是把打包好的插件目录整体拷贝过去然后执行chown -R jenkins:jenkins $JENKINS_HOME/plugins最后重启服务。这里要特别提醒如果你通过共享目录或者 U 盘拷贝插件进入 plugins 目录后先检查文件权限。如果文件属主是 root 而 Jenkins 以 jenkins 用户运行启动时可能读不到插件报错却不直观。手动执行chmod -R 644和上面的chown是标准操作。3. Jenkins 2.346.1 的安装与初始化配置3.1 JDK 与运行环境检查内网机器如果没有外网不能直接用 yum 在线安装 JDK需要在摆渡机上提前下载好 rpm 包。比如 CentOS 7 环境我这次用的就是jdk-8u202-linux-x64.rpm放到内网后执行rpm -ivh jdk-8u202-linux-x64.rpm java -version确认输出是 1.8 系列即可。如果你的内网机器本身已经装了 Java 11也完全没事2.346.1 同时支持 8 和 11。内存方面插件数量在二十个左右时Jenkins JVM 堆内存建议至少给 2GB。如果后续要多节点构建、跑流水线建议直接给 4GB。这个在启动参数里设置下节的 service 配置里会体现。3.2 用 systemd 把 Jenkins 变成一个可靠的后台服务很多人图省事直接java -jar jenkins.war在终端里跑一旦终端关了就断掉。生产环境不应该这样。我为 2.346.1 写了一个标准的 systemd 服务文件放在/etc/systemd/system/jenkins.service[Unit] DescriptionJenkins Server Afternetwork.target [Service] Typesimple Userjenkins Groupjenkins WorkingDirectory/var/lib/jenkins EnvironmentJAVA_HOME/usr/lib/jvm/java-1.8.0-openjdk EnvironmentJENKINS_HOME/var/lib/jenkins ExecStart/usr/bin/java -Xms512m -Xmx2048m -jar /usr/local/jenkins/jenkins.war --httpPort8080 Restartalways RestartSec10 [Install] WantedBymulti-user.target写完后执行systemctl daemon-reload systemctl enable jenkins systemctl start jenkins systemctl status jenkins这里有几个细节需要注意。JENKINS_HOME环境变量我显式设置为/var/lib/jenkins避免 Jenkins 默认路径和你预期的位置不一致。WorkingDirectory也设成和 JENKINS_HOME 相同防止某些流水线脚本里用的相对路径解析出错。--httpPort8080可以根据实际改成 8081、8090 等但要确保端口没被其他服务占用。如果默认端口被占用启动会直接失败日志里会看到Port already in use。这时可以改端口也可以使用--httpPort-1关闭 HTTP、只用 HTTPS但内网环境通常没必要那么复杂。3.3 初始化配置强制跳过在线插件安装向导Jenkins 首次启动后访问http://内网IP:8080会进入解锁页面。解锁管理员密码在/var/lib/jenkins/secrets/initialAdminPassword查看并复制密码后来到自定义 Jenkins 页面。这时候如果点“安装推荐的插件”离线环境会卡在下载界面很久最后全部失败非常浪费时间。正确的操作是选择“选择插件来安装”然后在下拉列表里不要勾选任何插件直接点安装。这样可以快速通过初始化进入 Jenkins 主界面。后续再通过前文介绍的离线插件安装方式把 hpi 传进来。初始化完成后进入“Manage Jenkins” - “Plugins” - “Advanced settings”把最下方的“Update Site” URL 改成一个能访问的镜像地址或者保持默认不动。离线环境下如果点击“Check now”去检查更新一定会超时这个没有关系不要因此去反复重试。3.4 修改更新中心和 JENKINS_HOME 目录如果你在内网有 Nexus、Artifactory 之类的私服并且已经同步了 Jenkins 插件源那可以在/var/lib/jenkins/hudson.model.UpdateCenter.xml中修改更新中心地址?xml version1.1 encodingUTF-8? sites site iddefault/id urlhttp://nexus.internal.com/repository/jenkins-updates/update-center.json/url /site /sites改完重启 Jenkins 才会生效。不过说实话绝大多数完全隔离的内网环境没有这种私服我更推荐的做法是不要过度依赖更新中心直接用离线上传插件的方式解决维护成本反而更低。另外JENKINS_HOME 默认在/var/lib/jenkins如果你的系统盘比较小构建日志、插件、工作区文件会把根分区塞满。最好一开始就把 JENKINS_HOME 指到一个独立的、容量充足的数据盘上比如/data/jenkins然后在 service 文件里把 Environment 字段的路径改成对应地址。这个改动一定要在第一次启动前完成否则中途迁移 JENKINS_HOME 会很痛苦。4. 上线和使用中的高频问题与排查技巧4.1 快速定位问题的排错速查表我在这次部署过程中遇到过不少问题下面把这些典型现象和解决办法整理成表格方便你遇到问题时直接对照现象可能原因处理方式启动后插件管理页为空插件目录权限不对检查$JENKINS_HOME/plugins属主是否为 jenkins执行 chown 后重启上传 hpi 后不生效依赖插件缺失查看 Jenkins 日志确认缺哪些依赖补传依赖插件启动报 ClassNotFoundExceptionhpi 文件损坏或版本不兼容用 sha256 校验文件换与 2.346.1 匹配的插件版本首次向导安装插件卡死离线环境尝试访问外网重启 Jenkins初始化时选择“无”插件更新中心 Check now 超时无外网出口或代理未配置忽略使用离线上传插件方式访问 8080 端口超时防火墙未放行firewall-cmd --add-port8080/tcp --permanent firewall-cmd --reload构建任务找不到 git 命令服务器未安装 Git离线安装 git rpm 包或调整构建工具链构建日志乱码字符集问题在 service 里增加EnvironmentLANGen_US.UTF-8上传大体积插件响应缓慢内存不足增大 JVM 堆参数并确保系统有足够内存4.2 插件版本兼容性是离线环境最大的暗坑在线安装插件时Jenkins 会主动拒绝与主版本不兼容的插件。离线上传则没有这层保险装进去之后才发现加载失败。判断插件版本是否兼容最可靠的方式是看插件的“Required Jenkins version”。在官方插件站点或 update-center.json 里每个插件条目都有requiredCore字段。比如某个插件写着requiredCore: 2.60.3那它运行在 2.346.1 上没问题如果写2.346.3那就意味着这个插件要求 Jenkins 核心版本至少 2.346.3而你本机是 2.346.1版本不够需要升级核心或换插件版本。我在准备插件清单时会同时下载 update-center.json 作为参考然后让脚本按插件列表逐项比对 requiredCore 与主版本的大小关系。这样能在摆渡机上下载阶段就过滤掉不兼容版本而不是等传到内网后再返工。4.3 重启是离线插件安装最廉价有效的工具插件上传完成后我见过不少人直接在管理台点“升级/安装”后就开始用然后定位到功能异常。其实 Jenkins 加载插件是一个完整的类加载过程很多插件需要重启后才会完全生效。安全的上线顺序是先把所有 hpi 文件传入 plugins 目录然后执行systemctl restart jenkins等日志输出Jenkins is fully up and running再登录系统逐个验证功能。不要在一个插件刚上传完、还没重启的状态下强行测试容易得到误导性的错误信息。另外如果插件数量多第一次重启会明显偏慢因为 Jenkins 要对所有插件做安装、依赖解析和类校验。这时候不要反复 kill 进程耐心等两到三分钟或者用journalctl -u jenkins -f看实时日志。5. 离线插件的持续维护心得5.1 建立插件版本基线清单离线环境最怕的一件事是“不知道当前环境装了哪些插件、什么版本”。因为不能在线看到可升级列表时间一长环境版本就变成一个黑盒。我建议在首次部署完成后立刻导出一份插件清单ls /var/lib/jenkins/plugins/*.jpi | sed s/.*\///; s/\.jpi$// /data/jenkins_backup/plugins_baseline_$(date %Y%m%d).txt如果有条件更精确的方式是通过 Jenkins 的 Script Console 执行以下 Groovy 脚本Jenkins.instance.pluginManager.plugins.sort { it.getShortName() }.each { println ${it.getShortName()}:${it.getVersion()} }拿到清单后保存到一个 Git 仓库或共享文档里后续每次新增插件、升级插件都更新这份基线。配合 update-center.json 里的元数据你可以随时回溯“当前环境到底是哪一套插件版本组合”。5.2 维护一个外网插件同步站如果你有多个内网环境都要部署 Jenkins不建议每次都在摆渡机上重新下载插件。更好的方式是在一台长期联网的机器上建一个“插件同步目录”把常用插件和 update-center.json 固化下来。我自己的做法是在摆渡机上用 cron 定期执行脚本同步指定插件版本到本地目录同时让内网的同事通过共享目录直接拷贝。这样虽然不能完全自动化但至少保证了每次拿到的插件版本是可复现的不会出现上周能用、这周下载了一个新版本就崩掉的情况。5.3 别漏掉 JENKINS_HOME 的备份插件是部署的一部分但不是全部。真正需要持续备份的是整个 JENKINS_HOME包括config.xml全局配置、jobs/任务定义、credentials.xml凭据、plugins/插件以及secrets/密钥目录。离线环境通常没有现成的备份工具最简单的做法是用 tar 打包tar czf /data/jenkins_backup/jenkins_home_$(date %Y%m%d_%H%M).tar.gz -C /var/lib jenkins恢复到新机器时解压后注意修改配置中的绝对路径同时确认目录属主是 jenkins。不要只备份 plugins 目录而忽略配置和任务那样恢复出来的 Jenkins 等于一个空壳所有构建任务和权限都要重新配置。回看这次内网部署经历我把整个流程跑通后最大的感触是离线部署 Jenkins 本身不难难的是把“插件依赖关系”理清楚。如果能提前把 update-center.json 拿到手再写个小脚本自动解析依赖后面基本不会遇到大问题。另一个经验是不要嫌麻烦跳过版本基线的记录内网环境排查问题时一份准确的插件清单能救你不少时间。希望这篇文章能帮你少走一些弯路。本文还有配套的精品资源点击获取