尧图网站建设 
简介针对内网环境下部署Jenkins 2.346.1时无法从官方插件中心在线下载的问题这套离线部署包提供了完整的插件文件与初始化配置面向需要搭建或维护内网CI/CD环境的运维人员可直接用于插件批量安装与版本校验适合网络受限、无外网接入的生产环境。包内共2000个文件体积314.4MB其中包含750个js脚本、651个html页面、366个jar包及各类hpi、jpi插件组件同时还有xml、properties等大量配置信息兼顾界面资源与依赖库基本覆盖离线安装时的常见需求可避免因缺包导致的服务启动异常。当前已有3161人学习下载其目录结构经过整理插件文件与配置项对应清晰配合初始化状态文件可快速完成插件加载验证也便于后续升级维护与安全加固能显著降低内网环境集成部署的试错成本。1. 为什么内网 Jenkins 的插件问题这么头疼这几年做持续集成见过太多团队在内网环境部署 Jenkins 时卡在同一个地方Jenkins 本体装好了、服务能起来了、端口也通了可一进“系统管理 → 插件管理”就傻眼了——页面空空如也搜索不到任何插件或者点了安装按钮后一直转圈最后超时失败。说白了就是内网机器没办法访问 Jenkins 官方的插件更新中心而 Jenkins 这座“毛坯房”不装插件根本住不了人——没有 Git Plugin 拉不了代码没有 Credentials Binding 配不了凭据没有 Pipeline 相关的插件流水线连最基本的语法提示都出不来。这个问题的适用范围非常广政务内网、医院内网、军工科研单位的隔离网段、只允许访问内部源的企业办公网凡是不能直连外网的 Jenkins 部署场景基本都会遇到。尤其版本还是 2.346.1 这种相对经典的 LTS 版本在离线插件安装上有一个隐藏的“依赖匹配”问题不是简单拿一个 .hpi 文件丢进去就完事后面我会专门讲。写这篇文章的目的就是把我实际在离线环境部署 Jenkins 2.346.1 并手动安装全部所需插件的过程、踩过的坑、用到的命令和验证方法完整复盘出来。不管你是在 CentOS 7.9、Ubuntu 还是 Windows Server 上跑 Jenkins插件离线安装的核心逻辑都是通用的。不需要你有多深的 Jenkins 源码功底跟着这篇文章一步步操作基本能解决 90% 的插件离线安装需求。注意文章里所有操作都基于 Jenkins 2.346.1 LTS 版本展开。如果你用的是更新或更老的版本个别目录结构、配置文件字段可能有差异但整体思路不变。2. 离线安装前必须想清楚的几件事2.1 明确需求到底需要哪些插件内网部署 Jenkins最忌讳的事情就是“先装一个 Jenkins再慢慢看需要什么插件”。联网环境下你可以随意搜索安装内网环境必须提前列清单。我在动手之前先把团队实际使用场景梳理了一遍最终确认这几类插件是必须的源码管理类Git Plugin、Git Client Plugin用于从内网 GitLab 拉取代码。认证凭据类Credentials Plugin、Credentials Binding Plugin用于在流水线中安全使用账号密码、Token。流水线相关PipelineWorkflow Aggregator、Pipeline Stage View、Pipeline Utility Steps用于编写和可视化 Jenkinsfile。构建工具相关Maven Integration 或直接通过 Pipeline 调用 Maven、JDK Parameter Plugin按需选择。制品与发布类Publish Over SSH如果内网环境需要通过 SSH 发布到应用服务器、HTML Publisher用于展示测试报告。其他常用Timestamper构建日志显示时间戳、Build Name and Description Setter、Config File Provider管理配置文件模板。以我这边的实际需求为例最终确定的核心插件清单大概 20 个左右。你不需要一次装太多装多了反而增加依赖冲突的概率。建议先按最小集安装跑通一条最简单的流水线后再按需增加。2.2 理解 Jenkins 插件的依赖机制这是离线安装最容易翻车的地方我特意单独拎出来讲。Jenkins 插件不是独立的“孤岛”插件与插件之间、插件与 Jenkins 核心之间都有依赖关系。比如你装 Git Plugin它可能依赖 Git Client Plugin、Apache HttpComponents Client、SSH Credentials Plugin 等。如果只上传了 Git Plugin 的 .hpi 文件没有把它的依赖插件一起放进去Jenkins 通常会报一个依赖缺失错误而且有时候报错信息还很隐晦比如提示某个类找不到或者干脆提醒你安装的插件版本与 Jenkins 核心版本不兼容。所以在离线环境我的建议是采用“全量上传让 Jenkins 自动处理依赖”的方式而不是手动一个个挑。具体做法后面会讲到。2.3 版本匹配2.346.1 对应的插件版本怎么选Jenkins 2.346.1 是 2022 年 6 月发布的 LTS 版本。LTS 版本的优势是稳定但代价是官方插件更新中心里很多新版本插件的Required Core版本已经高于 2.346.1直接装新版插件Jenkins 会提示“该插件需要更高版本的 Jenkins”。这种情况在联网环境下通常直接升级 Jenkins 就行内网环境下升级 Jenkins 本身也是个麻烦事所以最好是下载插件的时候就特意选择与 Jenkins 2.346.1 兼容的版本。怎么选找到插件在更新中心对应的版本记录查看其 Manifest 文件里的Jenkins-Version字段。如果你不想一个个翻有个取巧的办法直接下载与 Jenkins 版本发布日期相近的插件版本。比如 Jenkins 2.346.1 发布在 2022 年年中那你就找 2022 年 6 月前后发布的插件版本依赖冲突的概率会小很多。3. 离线安装插件的两种主流方案3.1 方案一手工上传 .hpi / .jpi 文件这是最直观的思路从联网机器上下载插件文件然后拷贝到内网机器上通过 Jenkins 的“高级设置”上传或者直接放插件目录。听起来简单实际操作中有两个容易踩的坑必须把依赖插件一起下载。你光下载 Git Plugin 一个文件是不够的它的依赖如 Git Client、SSH Credentials 等也得手动搞定少一个都启动不了。插件文件放到$JENKINS_HOME/plugins目录后必须重启 Jenkins 才能加载。有时候你以为放进去就完事了实际 Jenkins 启动时才扫描插件目录并做依赖校验。这个方案适合插件数量少、依赖关系清晰的情形。插件超过 10 个就不推荐了因为手动整理依赖图谱会让人怀疑人生。3.2 方案二内网搭建本地更新中心推荐这个方案的核心思路很简单在内网部署一个静态文件服务模拟 Jenkins 官方插件更新中心的目录结构然后把 Jenkins 的更新中心地址指到内网这台机器上。这样 Jenkins 的插件管理页面就能正常显示插件列表、搜索、安装体验和在线环境几乎一致。这个方案的优势特别明显不用手动逐个上传 .hpi 文件可以一键安装多个插件及依赖。插件依赖关系由 Jenkins 自己处理不用人工维护。后续团队新增插件需求只需要在内网更新中心补文件即可不需要再碰 Jenkins 服务器。我在实际项目中用的就是方案二。下面详细讲操作步骤。4. 手把手实操从外网机器到内网服务器的完整链路4.1 第一步在一台能上外网的机器上准备插件包准备一台可以访问外网的 Linux 或 Windows 机器专门用来“搬运”插件文件。这一步的核心是获取完整且版本匹配的插件包不要只是手动去官网一个个下载效率太低。我推荐用 Jenkins 官方提供的工具脚本思路用命令行批量下载确保依赖完整。以 Linux 机器为例先用 wget 或 curl 下载一个叫jenkins-plugin-manager的小工具这个工具专门解决“批量下载插件及其依赖”的问题。我举个例子假设你已经有了一个plugins.txt文件每一行写一个插件名git credentials-binding pipeline-stage-view htmlpublisher timestamper然后在联网机器上执行java -jar jenkins-plugin-manager.jar \ --war /path/to/jenkins.war \ --plugin-download-directory ./plugins \ --plugins plugins.txt注意这里--war参数建议指向与内网一致版本的jenkins.war也就是 2.346.1 的 war 包。这个参数的作用是让工具以对应 Jenkins 核心版本来解析依赖兼容性避免下载到要求更高 Jenkins 版本的插件。执行完./plugins目录下会出现一批.jpi文件这些就是全部插件及其依赖。提示jenkins-plugin-manager工具的详细使用方式在 GitHub 上有说明需要离线环境使用的话预先在联网环境把工具和插件包都下载好。4.2 第二步检查插件清单是否完整用上面的工具下载完插件之后不要急着拷贝进内网。先检查一下目录里的文件数量和plugins.txt里的数量是否一致。一般情况下工具会自动下载依赖所以最终文件数会大于你写的插件数。比如你写 20 个插件最终目录里可能有 40 多个 .jpi 文件这属于正常现象说明依赖被正确拉取了。检查完毕把整个plugins目录打包tar -czf jenkins-plugins-2.346.1.tar.gz ./plugins如果是 Windows 环境用压缩软件直接压成 zip 也行。4.3 第三步在内网机器上创建本地更新中心目录结构这一步是方案二的核心。Jenkins 的插件更新中心有一个约定俗成的目录结构它包含两个关键文件update-center.json和plugin-versions.json以及插件文件本体。先说明一下要完全自己构造一个合法合规的插件更新中心元数据是非常繁琐的因为你得为每一个插件生成版本信息、依赖信息、SHA256 校验值等。我在实际工作中找到了一个更节省时间的方法——利用联网机器上真实存在的更新中心数据结构。具体做法是在能联网的机器上先访问一下 Jenkins 官方更新中心的地址把update-center.json下载下来但这个文件是处理过的里面每个插件条目都带 sha256 和 url。注意下载时带上版本参数选择与 Jenkins 2.346.1 对应的更新中心快照这样生成的元数据和离线包才是匹配的。下载命令参考curl -o update-center.json https://updates.jenkins.io/stable/update-center.json curl -o plugin-versions.json https://updates.jenkins.io/stable/plugin-versions.json然后把update-center.json里面所有插件的下载地址替换为内网更新中心自己的地址。这个操作如果不写脚本手动改会疯掉。我一般用一段 Python 脚本批量替换。4.4 第四步搭建内网静态文件服务有了插件文件和元数据接下来需要在内网找一台机器可以是 Jenkins 服务器本身也可以是单独的文件服务器搭建静态文件服务。我推荐使用 Nginx因为它配置简单、性能好、内网环境足够用了。假设我们将所有文件放在/data/jenkins-update-center目录下目录结构如下/data/jenkins-update-center/ ├── update-center.json ├── plugin-versions.json └── downloads/ └── plugins/ ├── git.jpi ├── credentials-binding.jpi └── ...Nginx 配置示例server { listen 8081; server_name _; root /data/jenkins-update-center; location / { autoindex on; autoindex_exact_size off; autoindex_localtime on; index update-center.json; add_header Cache-Control no-cache; add_header Access-Control-Allow-Origin *; } }关键点有两个autoindex on很重要Jenkins 在解析插件列表的时候可能需要列目录。跨域响应头 Access-Control-Allow-Origin 建议加上不然某些情况下 Jenkins 前端请求可能被浏览器拦截。配置好后执行nginx -t验证语法然后systemctl reload nginx或nginx -s reload内网更新中心的 URL 就是http://内网IP:8081。4.5 第五步Jenkins 配置指向内网更新中心更新中心搭好之后登录 Jenkins 管理后台进入“系统管理 → 插件管理 → 高级”页面。这里有个“更新站点”配置项把默认的官方地址改成你的内网地址http://内网IP:8081/update-center.json然后点击“提交”并“检查”。注意这里有个小坑。Jenkins 在点击“立即获取最新元数据”之后它会先下载update-center.json然后解析出各个插件的下载地址。在update-center.json里插件的 url 字段如果是官方的https://updates.jenkins.io/...即使更新中心地址改成了内网地址插件下载还是会走官方地址然后超时。所以之前说的“替换 JSON 里所有插件下载地址”这步一定要做扎实不能漏。4.6 第六步在线式安装插件实质是走内网完成前两步后重新进入“系统管理 → 插件管理 → 可选插件”你会发现插件列表能正常加载了。搜索需要安装的插件勾选后点击“直接安装”Jenkins 就会从你的内网更新中心下载插件。这个过程本质上还是“在线”流程但流量全走内网速度很快依赖也能自动解析。如果插件比较多建议勾选“安装完成后重启 Jenkins”一次性把插件全装上。重启完成后进入“已安装插件”列表确认所有插件状态正常、没有红色告警基本就大功告成了。4.7 补充方案小规模插件直接丢目录如果你的内网环境连 Nginx 都不想搭插件数量又少完全可以走“直接丢目录”的方案。把 .hpi 或 .jpi 文件拷贝到$JENKINS_HOME/plugins目录下然后重启 Jenkins。但注意两件事插件文件权限要正确尤其是用非 root 用户启动 Jenkins 的情况下文件属主要对。如果 Jenkins 已经在运行只把文件放进去而重启插件是不会被加载的必须重启进程。这种方式适合应急、临时验证长期维护还是建议用更新中心方案。5. 实操过程中的典型报错与排除经验5.1 问题一Could not initialize class hudson.util.RobustReflectionConverter这是非常经典的 Jenkins 2.346.1 在 JDK 8 下安装某些新版插件时会遇到的异常。核心原因通常是插件与 Jenkins 核心版本不兼容某个插件调用了新版 Jenkins 才有的 API。解决办法很简单不要用最新版插件换用与 2.346.1 发布时期匹配的版本。用jenkins-plugin-manager指定--war之后下载的插件版本一般不会踩这个雷如果你手动下载就要注意版本选择。5.2 问题二依赖插件缺失导致插件加载失败比如安装 Pipeline 相关插件时少了workflow-api、workflow-step-api这些基础库Jenkins 会在系统日志里写出“Plugin ... is missing. To fix, install version ... or newer”这样的错误。这种情况就是依赖没拉全。没有用jenkins-plugin-manager而是手工下载插件的话请仔细查看插件详细信息里的 Dependencies 列表逐个补齐。5.3 问题三更新中心 JSON 解析失败如果 Jenkins 插件管理页提示无法解析更新中心数据首先用浏览器访问一下你配的update-center.json地址确认能正常下载。其次确认 JSON 里的每条插件 url 是否已经替换为内网地址有没有遗漏https://开头的官方链接。还有一种可能是 JSON 太大Nginx 服务端或浏览器缓存了旧内容可以加个无缓存响应头规避。5.4 问题四重启后插件没生效这种情况十有八九是插件目录放错了。Jenkins 读取插件默认路径是$JENKINS_HOME/plugins而不是 Jenkins 安装目录下的 plugins。如果你在系统里启动时设置了JENKINS_HOME环境变量就要确认echo $JENKINS_HOME的实际值然后把插件放到正确目录下。5.5 快速排查小窍门遇到问题不要只盯 Jenkins 网页界面打开系统日志往往能直接看到根因。日志位置一般在$JENKINS_HOME/logs/jenkins.log如果是 systemd 启动的服务还可以用journalctl -u jenkins查看。我在排查离线插件问题时90% 的错误都能从这两处日志里找到明确的插件名和缺失依赖名效率非常高。6. 离线插件部署中的独家避坑技巧6.1 第一次启动先带--enable-future-jobs或只初始化最小配置很多人在装完 Jenkins 之后急着配插件结果基础配置没做好后面反反复复出问题。我的习惯是Jenkins 刚启动完成先不安装插件先把管理员账号、JENKINS_HOME 目录权限、JDK 路径这些基础信息确认好再进插件安装流程。这样插件安装时产生的配置文件都在一个干净、已知的环境中排错会简单很多。6.2 保留一份插件的“版本快照”内网环境没有外网时间久了很容易忘记当时装的是哪些版本。建议在打包插件目录时顺便把plugins.txt和最终生成的插件列表导出保存下来甚至可以把整个.jpi文件名清单存成一个文本文件。这样以后要扩容 Jenkins 节点或者重装同一版本 Jenkins直接按清单再走一遍流程就恢复了。我自己的做法是把这个清单文件放在 Nginx 更新中心的根目录下命名README-plugin-list.txt方便其他同事查阅。6.3 更新中心 JSON 替换 URL 时注意保留路径写脚本替换update-center.json里的 url 字段时不要把官方的路径后缀也替换掉。比如原来是https://updates.jenkins.io/downloads/plugins/git/4.11.0/git.hpi你要替换的只是域名部分https://updates.jenkins.io替换成http://内网IP:8081保留后面的/downloads/plugins/...。这样才能和 Nginx 根目录下的目录结构对上。替换域名后再检查一下 JSON 里的connectionCheckUrl字段这个字段 Jenkins 用来检测更新中心连通性的建议也改成内网地址或者指向一个内网可访问的静态页面否则插件管理页可能会提示“连接失败”。6.4 关于 SHA256 校验Jenkins 在下载插件时会比对update-center.json里声明的 sha256 与文件实际校验值。如果你是从官方快照里拿到的 JSON 和插件包这个值天然是对的。但如果自己手动做修改又改动了插件文件校验就会失败。遇到“插件下载后校验失败”的情况优先怀疑插件包本身是不是被改动过、下载是否完整其次再检查 JSON 中的 sha256 字段是否与文件一致。一个小技巧是在 Linux 下用 sha256sum 命令算一下插件文件的校验值和 JSON 里的对比即可。7. 从 2.346.1 延伸后续升级与维护建议7.1 保持插件版本基线统一内网环境最大的问题是“信息闭环”一旦插件出了问题排查路径要比联网环境长很多。所以我的建议是所有 Jenkins 节点包括测试环境和生产环境尽量保持同样的 Jenkins 核心版本和插件版本基线。你在测试环境验证过的插件组合不要轻易在生产环境改动。真要升级也先在测试环境完整跑一遍回归。7.2 离线更新中心也要定期更新快照前面搭的离线更新中心不是一劳永逸的。每隔几个月建议在联网机器上重新拉一次对应版本的update-center.json和plugin-versions.json并同步升级插件包。这样可以拉取到安全修复和 bug fix 版本。更新完刷新内网 Nginx 目录即可Jenkins 端不需要额外操作只要重新“检查更新中心”就能看到新版本。7.3 权限和备份内网环境的管理往往没有专门的安全团队盯着但 Jenkins 本身就是代码仓库和构建环境的集合敏感度很高。建议在离线插件目录做好只读权限控制避免非管理员意外修改或删除插件文件。同时在 Jenkins 服务器上定期备份$JENKINS_HOME尤其是里面的plugins目录和config.xml。真出了事故可以用备份快速恢复。8. 写在最后这事的核心思想是什么内网 Jenkins 离线安装插件说到底就一件事把联网环境里 Jenkins 信任的更新中心完整地“搬”到内网环境里。无论你是选择硬盘拷贝插件文件还是搭一个 Nginx 静态服务核心逻辑都是让 Jenkins 在“看似联网”的状态下拿到它想要的文件和元数据。我自己经历过好几次离线部署现场最大的体会是准备工作决定成败。插件清单列得清楚、依赖拉取得完整、更新中心 JSON 替换得干净整个过程就会非常顺利反之任何一步偷懒后面都用更多的加班来偿还。如果你所在的内网环境比文章里提到的场景更复杂比如 Jenkins 本身是通过 Docker 跑在离线服务器上的或者内网还有多级代理其实思路也一样——先把插件包准备好再解决 Jenkins 访问更新中心的路由问题。多试几次摸清规律之后你会发现内网部署 Jenkins 插件这件事并没有一开始想象的那么可怕。本文还有配套的精品资源点击获取 内网Jenkins离线安装插件指南：搭建本地更新中心实战
简介针对内网环境下部署Jenkins 2.346.1时无法从官方插件中心在线下载的问题这套离线部署包提供了完整的插件文件与初始化配置面向需要搭建或维护内网CI/CD环境的运维人员可直接用于插件批量安装与版本校验适合网络受限、无外网接入的生产环境。包内共2000个文件体积314.4MB其中包含750个js脚本、651个html页面、366个jar包及各类hpi、jpi插件组件同时还有xml、properties等大量配置信息兼顾界面资源与依赖库基本覆盖离线安装时的常见需求可避免因缺包导致的服务启动异常。当前已有3161人学习下载其目录结构经过整理插件文件与配置项对应清晰配合初始化状态文件可快速完成插件加载验证也便于后续升级维护与安全加固能显著降低内网环境集成部署的试错成本。1. 为什么内网 Jenkins 的插件问题这么头疼这几年做持续集成见过太多团队在内网环境部署 Jenkins 时卡在同一个地方Jenkins 本体装好了、服务能起来了、端口也通了可一进“系统管理 → 插件管理”就傻眼了——页面空空如也搜索不到任何插件或者点了安装按钮后一直转圈最后超时失败。说白了就是内网机器没办法访问 Jenkins 官方的插件更新中心而 Jenkins 这座“毛坯房”不装插件根本住不了人——没有 Git Plugin 拉不了代码没有 Credentials Binding 配不了凭据没有 Pipeline 相关的插件流水线连最基本的语法提示都出不来。这个问题的适用范围非常广政务内网、医院内网、军工科研单位的隔离网段、只允许访问内部源的企业办公网凡是不能直连外网的 Jenkins 部署场景基本都会遇到。尤其版本还是 2.346.1 这种相对经典的 LTS 版本在离线插件安装上有一个隐藏的“依赖匹配”问题不是简单拿一个 .hpi 文件丢进去就完事后面我会专门讲。写这篇文章的目的就是把我实际在离线环境部署 Jenkins 2.346.1 并手动安装全部所需插件的过程、踩过的坑、用到的命令和验证方法完整复盘出来。不管你是在 CentOS 7.9、Ubuntu 还是 Windows Server 上跑 Jenkins插件离线安装的核心逻辑都是通用的。不需要你有多深的 Jenkins 源码功底跟着这篇文章一步步操作基本能解决 90% 的插件离线安装需求。注意文章里所有操作都基于 Jenkins 2.346.1 LTS 版本展开。如果你用的是更新或更老的版本个别目录结构、配置文件字段可能有差异但整体思路不变。2. 离线安装前必须想清楚的几件事2.1 明确需求到底需要哪些插件内网部署 Jenkins最忌讳的事情就是“先装一个 Jenkins再慢慢看需要什么插件”。联网环境下你可以随意搜索安装内网环境必须提前列清单。我在动手之前先把团队实际使用场景梳理了一遍最终确认这几类插件是必须的源码管理类Git Plugin、Git Client Plugin用于从内网 GitLab 拉取代码。认证凭据类Credentials Plugin、Credentials Binding Plugin用于在流水线中安全使用账号密码、Token。流水线相关PipelineWorkflow Aggregator、Pipeline Stage View、Pipeline Utility Steps用于编写和可视化 Jenkinsfile。构建工具相关Maven Integration 或直接通过 Pipeline 调用 Maven、JDK Parameter Plugin按需选择。制品与发布类Publish Over SSH如果内网环境需要通过 SSH 发布到应用服务器、HTML Publisher用于展示测试报告。其他常用Timestamper构建日志显示时间戳、Build Name and Description Setter、Config File Provider管理配置文件模板。以我这边的实际需求为例最终确定的核心插件清单大概 20 个左右。你不需要一次装太多装多了反而增加依赖冲突的概率。建议先按最小集安装跑通一条最简单的流水线后再按需增加。2.2 理解 Jenkins 插件的依赖机制这是离线安装最容易翻车的地方我特意单独拎出来讲。Jenkins 插件不是独立的“孤岛”插件与插件之间、插件与 Jenkins 核心之间都有依赖关系。比如你装 Git Plugin它可能依赖 Git Client Plugin、Apache HttpComponents Client、SSH Credentials Plugin 等。如果只上传了 Git Plugin 的 .hpi 文件没有把它的依赖插件一起放进去Jenkins 通常会报一个依赖缺失错误而且有时候报错信息还很隐晦比如提示某个类找不到或者干脆提醒你安装的插件版本与 Jenkins 核心版本不兼容。所以在离线环境我的建议是采用“全量上传让 Jenkins 自动处理依赖”的方式而不是手动一个个挑。具体做法后面会讲到。2.3 版本匹配2.346.1 对应的插件版本怎么选Jenkins 2.346.1 是 2022 年 6 月发布的 LTS 版本。LTS 版本的优势是稳定但代价是官方插件更新中心里很多新版本插件的Required Core版本已经高于 2.346.1直接装新版插件Jenkins 会提示“该插件需要更高版本的 Jenkins”。这种情况在联网环境下通常直接升级 Jenkins 就行内网环境下升级 Jenkins 本身也是个麻烦事所以最好是下载插件的时候就特意选择与 Jenkins 2.346.1 兼容的版本。怎么选找到插件在更新中心对应的版本记录查看其 Manifest 文件里的Jenkins-Version字段。如果你不想一个个翻有个取巧的办法直接下载与 Jenkins 版本发布日期相近的插件版本。比如 Jenkins 2.346.1 发布在 2022 年年中那你就找 2022 年 6 月前后发布的插件版本依赖冲突的概率会小很多。3. 离线安装插件的两种主流方案3.1 方案一手工上传 .hpi / .jpi 文件这是最直观的思路从联网机器上下载插件文件然后拷贝到内网机器上通过 Jenkins 的“高级设置”上传或者直接放插件目录。听起来简单实际操作中有两个容易踩的坑必须把依赖插件一起下载。你光下载 Git Plugin 一个文件是不够的它的依赖如 Git Client、SSH Credentials 等也得手动搞定少一个都启动不了。插件文件放到$JENKINS_HOME/plugins目录后必须重启 Jenkins 才能加载。有时候你以为放进去就完事了实际 Jenkins 启动时才扫描插件目录并做依赖校验。这个方案适合插件数量少、依赖关系清晰的情形。插件超过 10 个就不推荐了因为手动整理依赖图谱会让人怀疑人生。3.2 方案二内网搭建本地更新中心推荐这个方案的核心思路很简单在内网部署一个静态文件服务模拟 Jenkins 官方插件更新中心的目录结构然后把 Jenkins 的更新中心地址指到内网这台机器上。这样 Jenkins 的插件管理页面就能正常显示插件列表、搜索、安装体验和在线环境几乎一致。这个方案的优势特别明显不用手动逐个上传 .hpi 文件可以一键安装多个插件及依赖。插件依赖关系由 Jenkins 自己处理不用人工维护。后续团队新增插件需求只需要在内网更新中心补文件即可不需要再碰 Jenkins 服务器。我在实际项目中用的就是方案二。下面详细讲操作步骤。4. 手把手实操从外网机器到内网服务器的完整链路4.1 第一步在一台能上外网的机器上准备插件包准备一台可以访问外网的 Linux 或 Windows 机器专门用来“搬运”插件文件。这一步的核心是获取完整且版本匹配的插件包不要只是手动去官网一个个下载效率太低。我推荐用 Jenkins 官方提供的工具脚本思路用命令行批量下载确保依赖完整。以 Linux 机器为例先用 wget 或 curl 下载一个叫jenkins-plugin-manager的小工具这个工具专门解决“批量下载插件及其依赖”的问题。我举个例子假设你已经有了一个plugins.txt文件每一行写一个插件名git credentials-binding pipeline-stage-view htmlpublisher timestamper然后在联网机器上执行java -jar jenkins-plugin-manager.jar \ --war /path/to/jenkins.war \ --plugin-download-directory ./plugins \ --plugins plugins.txt注意这里--war参数建议指向与内网一致版本的jenkins.war也就是 2.346.1 的 war 包。这个参数的作用是让工具以对应 Jenkins 核心版本来解析依赖兼容性避免下载到要求更高 Jenkins 版本的插件。执行完./plugins目录下会出现一批.jpi文件这些就是全部插件及其依赖。提示jenkins-plugin-manager工具的详细使用方式在 GitHub 上有说明需要离线环境使用的话预先在联网环境把工具和插件包都下载好。4.2 第二步检查插件清单是否完整用上面的工具下载完插件之后不要急着拷贝进内网。先检查一下目录里的文件数量和plugins.txt里的数量是否一致。一般情况下工具会自动下载依赖所以最终文件数会大于你写的插件数。比如你写 20 个插件最终目录里可能有 40 多个 .jpi 文件这属于正常现象说明依赖被正确拉取了。检查完毕把整个plugins目录打包tar -czf jenkins-plugins-2.346.1.tar.gz ./plugins如果是 Windows 环境用压缩软件直接压成 zip 也行。4.3 第三步在内网机器上创建本地更新中心目录结构这一步是方案二的核心。Jenkins 的插件更新中心有一个约定俗成的目录结构它包含两个关键文件update-center.json和plugin-versions.json以及插件文件本体。先说明一下要完全自己构造一个合法合规的插件更新中心元数据是非常繁琐的因为你得为每一个插件生成版本信息、依赖信息、SHA256 校验值等。我在实际工作中找到了一个更节省时间的方法——利用联网机器上真实存在的更新中心数据结构。具体做法是在能联网的机器上先访问一下 Jenkins 官方更新中心的地址把update-center.json下载下来但这个文件是处理过的里面每个插件条目都带 sha256 和 url。注意下载时带上版本参数选择与 Jenkins 2.346.1 对应的更新中心快照这样生成的元数据和离线包才是匹配的。下载命令参考curl -o update-center.json https://updates.jenkins.io/stable/update-center.json curl -o plugin-versions.json https://updates.jenkins.io/stable/plugin-versions.json然后把update-center.json里面所有插件的下载地址替换为内网更新中心自己的地址。这个操作如果不写脚本手动改会疯掉。我一般用一段 Python 脚本批量替换。4.4 第四步搭建内网静态文件服务有了插件文件和元数据接下来需要在内网找一台机器可以是 Jenkins 服务器本身也可以是单独的文件服务器搭建静态文件服务。我推荐使用 Nginx因为它配置简单、性能好、内网环境足够用了。假设我们将所有文件放在/data/jenkins-update-center目录下目录结构如下/data/jenkins-update-center/ ├── update-center.json ├── plugin-versions.json └── downloads/ └── plugins/ ├── git.jpi ├── credentials-binding.jpi └── ...Nginx 配置示例server { listen 8081; server_name _; root /data/jenkins-update-center; location / { autoindex on; autoindex_exact_size off; autoindex_localtime on; index update-center.json; add_header Cache-Control no-cache; add_header Access-Control-Allow-Origin *; } }关键点有两个autoindex on很重要Jenkins 在解析插件列表的时候可能需要列目录。跨域响应头 Access-Control-Allow-Origin 建议加上不然某些情况下 Jenkins 前端请求可能被浏览器拦截。配置好后执行nginx -t验证语法然后systemctl reload nginx或nginx -s reload内网更新中心的 URL 就是http://内网IP:8081。4.5 第五步Jenkins 配置指向内网更新中心更新中心搭好之后登录 Jenkins 管理后台进入“系统管理 → 插件管理 → 高级”页面。这里有个“更新站点”配置项把默认的官方地址改成你的内网地址http://内网IP:8081/update-center.json然后点击“提交”并“检查”。注意这里有个小坑。Jenkins 在点击“立即获取最新元数据”之后它会先下载update-center.json然后解析出各个插件的下载地址。在update-center.json里插件的 url 字段如果是官方的https://updates.jenkins.io/...即使更新中心地址改成了内网地址插件下载还是会走官方地址然后超时。所以之前说的“替换 JSON 里所有插件下载地址”这步一定要做扎实不能漏。4.6 第六步在线式安装插件实质是走内网完成前两步后重新进入“系统管理 → 插件管理 → 可选插件”你会发现插件列表能正常加载了。搜索需要安装的插件勾选后点击“直接安装”Jenkins 就会从你的内网更新中心下载插件。这个过程本质上还是“在线”流程但流量全走内网速度很快依赖也能自动解析。如果插件比较多建议勾选“安装完成后重启 Jenkins”一次性把插件全装上。重启完成后进入“已安装插件”列表确认所有插件状态正常、没有红色告警基本就大功告成了。4.7 补充方案小规模插件直接丢目录如果你的内网环境连 Nginx 都不想搭插件数量又少完全可以走“直接丢目录”的方案。把 .hpi 或 .jpi 文件拷贝到$JENKINS_HOME/plugins目录下然后重启 Jenkins。但注意两件事插件文件权限要正确尤其是用非 root 用户启动 Jenkins 的情况下文件属主要对。如果 Jenkins 已经在运行只把文件放进去而重启插件是不会被加载的必须重启进程。这种方式适合应急、临时验证长期维护还是建议用更新中心方案。5. 实操过程中的典型报错与排除经验5.1 问题一Could not initialize class hudson.util.RobustReflectionConverter这是非常经典的 Jenkins 2.346.1 在 JDK 8 下安装某些新版插件时会遇到的异常。核心原因通常是插件与 Jenkins 核心版本不兼容某个插件调用了新版 Jenkins 才有的 API。解决办法很简单不要用最新版插件换用与 2.346.1 发布时期匹配的版本。用jenkins-plugin-manager指定--war之后下载的插件版本一般不会踩这个雷如果你手动下载就要注意版本选择。5.2 问题二依赖插件缺失导致插件加载失败比如安装 Pipeline 相关插件时少了workflow-api、workflow-step-api这些基础库Jenkins 会在系统日志里写出“Plugin ... is missing. To fix, install version ... or newer”这样的错误。这种情况就是依赖没拉全。没有用jenkins-plugin-manager而是手工下载插件的话请仔细查看插件详细信息里的 Dependencies 列表逐个补齐。5.3 问题三更新中心 JSON 解析失败如果 Jenkins 插件管理页提示无法解析更新中心数据首先用浏览器访问一下你配的update-center.json地址确认能正常下载。其次确认 JSON 里的每条插件 url 是否已经替换为内网地址有没有遗漏https://开头的官方链接。还有一种可能是 JSON 太大Nginx 服务端或浏览器缓存了旧内容可以加个无缓存响应头规避。5.4 问题四重启后插件没生效这种情况十有八九是插件目录放错了。Jenkins 读取插件默认路径是$JENKINS_HOME/plugins而不是 Jenkins 安装目录下的 plugins。如果你在系统里启动时设置了JENKINS_HOME环境变量就要确认echo $JENKINS_HOME的实际值然后把插件放到正确目录下。5.5 快速排查小窍门遇到问题不要只盯 Jenkins 网页界面打开系统日志往往能直接看到根因。日志位置一般在$JENKINS_HOME/logs/jenkins.log如果是 systemd 启动的服务还可以用journalctl -u jenkins查看。我在排查离线插件问题时90% 的错误都能从这两处日志里找到明确的插件名和缺失依赖名效率非常高。6. 离线插件部署中的独家避坑技巧6.1 第一次启动先带--enable-future-jobs或只初始化最小配置很多人在装完 Jenkins 之后急着配插件结果基础配置没做好后面反反复复出问题。我的习惯是Jenkins 刚启动完成先不安装插件先把管理员账号、JENKINS_HOME 目录权限、JDK 路径这些基础信息确认好再进插件安装流程。这样插件安装时产生的配置文件都在一个干净、已知的环境中排错会简单很多。6.2 保留一份插件的“版本快照”内网环境没有外网时间久了很容易忘记当时装的是哪些版本。建议在打包插件目录时顺便把plugins.txt和最终生成的插件列表导出保存下来甚至可以把整个.jpi文件名清单存成一个文本文件。这样以后要扩容 Jenkins 节点或者重装同一版本 Jenkins直接按清单再走一遍流程就恢复了。我自己的做法是把这个清单文件放在 Nginx 更新中心的根目录下命名README-plugin-list.txt方便其他同事查阅。6.3 更新中心 JSON 替换 URL 时注意保留路径写脚本替换update-center.json里的 url 字段时不要把官方的路径后缀也替换掉。比如原来是https://updates.jenkins.io/downloads/plugins/git/4.11.0/git.hpi你要替换的只是域名部分https://updates.jenkins.io替换成http://内网IP:8081保留后面的/downloads/plugins/...。这样才能和 Nginx 根目录下的目录结构对上。替换域名后再检查一下 JSON 里的connectionCheckUrl字段这个字段 Jenkins 用来检测更新中心连通性的建议也改成内网地址或者指向一个内网可访问的静态页面否则插件管理页可能会提示“连接失败”。6.4 关于 SHA256 校验Jenkins 在下载插件时会比对update-center.json里声明的 sha256 与文件实际校验值。如果你是从官方快照里拿到的 JSON 和插件包这个值天然是对的。但如果自己手动做修改又改动了插件文件校验就会失败。遇到“插件下载后校验失败”的情况优先怀疑插件包本身是不是被改动过、下载是否完整其次再检查 JSON 中的 sha256 字段是否与文件一致。一个小技巧是在 Linux 下用 sha256sum 命令算一下插件文件的校验值和 JSON 里的对比即可。7. 从 2.346.1 延伸后续升级与维护建议7.1 保持插件版本基线统一内网环境最大的问题是“信息闭环”一旦插件出了问题排查路径要比联网环境长很多。所以我的建议是所有 Jenkins 节点包括测试环境和生产环境尽量保持同样的 Jenkins 核心版本和插件版本基线。你在测试环境验证过的插件组合不要轻易在生产环境改动。真要升级也先在测试环境完整跑一遍回归。7.2 离线更新中心也要定期更新快照前面搭的离线更新中心不是一劳永逸的。每隔几个月建议在联网机器上重新拉一次对应版本的update-center.json和plugin-versions.json并同步升级插件包。这样可以拉取到安全修复和 bug fix 版本。更新完刷新内网 Nginx 目录即可Jenkins 端不需要额外操作只要重新“检查更新中心”就能看到新版本。7.3 权限和备份内网环境的管理往往没有专门的安全团队盯着但 Jenkins 本身就是代码仓库和构建环境的集合敏感度很高。建议在离线插件目录做好只读权限控制避免非管理员意外修改或删除插件文件。同时在 Jenkins 服务器上定期备份$JENKINS_HOME尤其是里面的plugins目录和config.xml。真出了事故可以用备份快速恢复。8. 写在最后这事的核心思想是什么内网 Jenkins 离线安装插件说到底就一件事把联网环境里 Jenkins 信任的更新中心完整地“搬”到内网环境里。无论你是选择硬盘拷贝插件文件还是搭一个 Nginx 静态服务核心逻辑都是让 Jenkins 在“看似联网”的状态下拿到它想要的文件和元数据。我自己经历过好几次离线部署现场最大的体会是准备工作决定成败。插件清单列得清楚、依赖拉取得完整、更新中心 JSON 替换得干净整个过程就会非常顺利反之任何一步偷懒后面都用更多的加班来偿还。如果你所在的内网环境比文章里提到的场景更复杂比如 Jenkins 本身是通过 Docker 跑在离线服务器上的或者内网还有多级代理其实思路也一样——先把插件包准备好再解决 Jenkins 访问更新中心的路由问题。多试几次摸清规律之后你会发现内网部署 Jenkins 插件这件事并没有一开始想象的那么可怕。本文还有配套的精品资源点击获取