简介本资源面向在内网、隔离网等无外网环境中部署 Jenkins 的运维与开发人员针对 Jenkins 2.346.1 无法在线拉取插件的问题提供一套完整的离线插件安装方案。压缩包共约 2000 个文件整体 314.4MB以 90 个 jpi、30 个 hpi 插件包为核心辅以 366 个 jar、192 个 xml 配置、750 个 js 与 651 个 html 页面资源并包含 svg、png、gif 等界面素材及 properties、timestamp 等元数据文件基本覆盖插件运行所需的依赖与描述信息。资源围绕离线插件包制作、初始化脚本配置、启动加载与安装验证等环节展开可帮助读者理解 Jenkins 在断网条件下的插件加载机制与目录组织方式。目前已有 3171 人学习下载适合需要快速搭建内网 CI/CD 环境、排查插件缺失与版本兼容问题的技术人员参考。1. 内网 Jenkins 离线装插件为什么你的 2.346.1 总是卡在“正在下载”很多团队的内网构建机跑着 Jenkins 2.346.1版本不算新但足够稳平时编译打包一切正常。直到某天需要装一个插件——比如凭据绑定、流水线工具或者某个通知插件——页面转了半天最后弹出一行红字无法连接更新中心。这不是 Jenkins 坏了而是它默认要去外网拉插件索引和 hpi 包而内网环境根本没有这条通路。离线部署插件要解决的核心问题就一个把插件及其依赖从一台能访问外网的机器完整搬到内网 Jenkins 的插件目录里并让 Jenkins 认账。适合谁看负责内网 CI/CD 维护、手上有 Jenkins 2.346.1 且不能改网络策略的工程师。下面按“先搞懂依赖关系再动手搬包最后排错”的顺序讲透。2. 离线插件包的依赖链为什么只下 hpi 文件十有八九会翻车2.1 Jenkins 插件不是独立个体而是一棵依赖树Jenkins 插件体系有一个容易被忽略的事实你搜到的那个插件它自己往往还依赖五六个甚至十几个其他插件。比如装一个“Git 参数插件”它可能依赖 git 客户端插件、凭据插件、结构描述插件等等。如果只把目标插件的 hpi 文件丢进插件目录重启后 Jenkins 会报“依赖缺失”插件状态显示为失败甚至导致整个插件管理页面加载异常。所以离线部署的第一步不是下载而是解析依赖树。Jenkins 更新中心提供了一个元数据接口返回的是 JSON 格式的插件索引里面每个插件都列出了它的依赖项和版本范围。你需要根据这个索引从目标插件开始递归找出所有依赖形成一个完整的下载清单。常见做法是在一台能访问外网的机器上用脚本读取更新中心的update-center.json输入目标插件名输出它和所有传递依赖的下载地址。这个脚本不需要装 Jenkins用 Python 或 shell 都能写。2.2 用脚本解析依赖并生成下载清单下面这段 Python 脚本演示了如何从更新中心元数据里提取某个插件及其全部依赖。注意这里用的是 Jenkins 官方更新中心的公开 JSON 地址内网机器无法访问所以脚本必须在外网机器上跑。import json import urllib.request # 更新中心元数据地址外网机器可访问 UPDATE_CENTER https://updates.jenkins.io/update-center.json def fetch_update_center(): # 官方返回的 JSON 前面有 updateCenter.post( 前缀需要去掉 with urllib.request.urlopen(UPDATE_CENTER) as resp: raw resp.read().decode(utf-8) # 去掉 JSONP 包装 raw raw.replace(updateCenter.post(, ).rstrip();) return json.loads(raw) def resolve_deps(plugins, name, resolvedNone, visitingNone): if resolved is None: resolved {} if visiting is None: visiting set() if name in resolved or name in visiting: return resolved visiting.add(name) info plugins.get(name) if not info: print(f[警告] 插件 {name} 不在更新中心索引中) return resolved # 先递归依赖 for dep_name, dep_info in info.get(dependencies, {}).items(): # dep_info 里 optional 为 true 的依赖可以跳过 if dep_info.get(optional): continue resolve_deps(plugins, dep_name, resolved, visiting) resolved[name] info visiting.discard(name) return resolved if __name__ __main__: data fetch_update_center() plugins data[plugins] target git-parameter # 替换成你要装的插件名 result resolve_deps(plugins, target) print(f共需下载 {len(result)} 个插件) for name, info in result.items(): version info[version] url info[url] print(f{name}:{version} - {url})逻辑说明fetch_update_center负责拉取并清洗 JSONP 格式的元数据resolve_deps是一个递归函数先处理依赖再记录自身避免循环依赖optional为 true 的依赖通常可以不装减少下载量。参数方面target换成你实际要装的插件名比如credentials-binding、pipeline-utility-steps。运行后会打印出每个插件的精确版本和下载 URL这就是你的离线包清单。2.3 下载 hpi 文件时版本号必须锁死拿到清单后用wget或curl批量下载。注意 URL 里的版本号必须和清单一致不要手动改成“最新版”。因为 Jenkins 2.346.1 对插件版本有兼容性要求某些新插件要求 Jenkins 核心版本 2.400装上去直接报“需要更高版本的 Jenkins”。所以下载时严格按脚本输出的版本走。# 假设清单输出到 plugins.txt每行格式name:version url while IFS read -r line; do url$(echo $line | awk {print $3}) wget -q --show-progress $url done plugins.txt下载完成后你会得到一堆.hpi文件。把它们放到一个目录里准备传入内网。如果内网机器和外部机器之间有文件摆渡流程建议把 hpi 文件和一份plugins.txt清单一起打包方便核对。3. 把插件搬进内网三种落地方式与目录权限的坑3.1 方式一直接拷贝到 JENKINS_HOME/plugins 并重启这是最直接的做法。找到内网 Jenkins 的JENKINS_HOME目录通常在/var/lib/jenkins或~/.jenkins。把下载好的 hpi 文件全部复制到plugins子目录下然后重启 Jenkins。# 停止 Jenkins根据你的启动方式选择 systemctl stop jenkins # 或者 service jenkins stop # 备份原有插件目录出问题可回滚 cp -r /var/lib/jenkins/plugins /var/lib/jenkins/plugins.bak.$(date %Y%m%d) # 拷贝新插件 cp /tmp/offline-plugins/*.hpi /var/lib/jenkins/plugins/ # 修正权限Jenkins 运行用户通常是 jenkins chown -R jenkins:jenkins /var/lib/jenkins/plugins # 启动 systemctl start jenkins逻辑说明备份是后悔药插件目录一旦被写坏Jenkins 可能起不来。权限问题非常常见——用 root 拷贝的文件属主是 rootJenkins 进程读不了启动日志会报Permission denied。参数上JENKINS_HOME的位置可以通过ps -ef | grep jenkins看启动参数里的-DJENKINS_HOME确认。3.2 方式二用 Jenkins 的插件管理页面上传 hpi如果 Jenkins 还能正常启动只是更新中心不可用可以进“系统管理 - 插件管理 - 高级”在“上传插件”区域逐个选择 hpi 文件上传。这种方式的好处是 Jenkins 会自己校验依赖缺什么会提示。缺点是插件多的时候非常耗时而且上传过程中如果依赖顺序不对可能先报错再让你重试。我一般会先把所有依赖插件按“被依赖优先”的顺序排好再逐个上传。比如 A 依赖 B就先传 B 再传 A。脚本解析出的依赖树其实已经隐含了顺序按递归返回的顺序反过来传就行。3.3 方式三搭建内网更新中心镜像如果内网 Jenkins 不止一台或者以后还要经常装插件值得搭一个内网更新中心。核心思路是在外网机器上把更新中心的元数据和所有 hpi 文件同步下来放到内网 HTTP 服务上然后修改 Jenkins 的更新中心地址指向内网。具体做法是下载update-center.json和updates/目录下的插件文件保持目录结构用 Nginx 或 Apache 暴露一个静态站点。然后在 Jenkins 的“插件管理 - 高级”里把“更新站点”改成内网地址。这样 Jenkins 就能像访问外网一样访问内网更新中心依赖解析和下载全自动。这个方案前期投入大但一劳永逸。注意内网更新中心的元数据文件需要定期同步否则新插件版本对不上。4. 避坑与排查离线装插件最常见的五个翻车现场4.1 重启后插件加载失败日志报 NoClassDefFoundError现象Jenkins 能启动但部分插件显示红色失败日志里出现NoClassDefFoundError或ClassNotFoundException。原因依赖插件没装全或者依赖插件的版本不对。比如目标插件依赖structs插件的 1.20 版本但你下载的是 1.10类名对不上。解决回到外网机器用 2.2 的脚本重新解析依赖确认每个依赖的版本号。特别注意optional为 false 的依赖一个都不能少。把缺失的 hpi 补进 plugins 目录重启。4.2 插件目录权限不对导致 Jenkins 启动卡死现象重启后 Jenkins 一直卡在启动页面日志最后一行是Permission denied或Unable to create ...。原因拷贝 hpi 文件时用了 root文件属主变成 root而 Jenkins 以 jenkins 用户运行无法读取或写入插件目录。解决chown -R jenkins:jenkins $JENKINS_HOME/plugins然后重启。如果已经卡死先停掉进程修正权限再启动。血泪经验每次拷贝完都顺手改权限别等出问题再查。4.3 插件版本与 Jenkins 2.346.1 不兼容现象插件装上了但 Jenkins 启动时报Jenkins (2.346.1) or higher required或者插件页面提示“需要更新 Jenkins”。原因下载了为更高版本 Jenkins 编译的插件。更新中心里每个插件都有requiredCore字段表示最低 Jenkins 版本要求。解决在解析依赖的脚本里增加过滤跳过requiredCore大于 2.346.1 的插件版本。如果目标插件本身要求更高核心只能升级 Jenkins 或找旧版本插件。旧版本可以在更新中心的download/plugins目录下按版本号手动拼 URL 下载。4.4 上传 hpi 时提示“依赖插件未安装”但明明已经拷了现象用页面上传方式装插件提示缺少某个依赖但去插件目录看那个依赖的 hpi 文件确实在。原因Jenkins 在启动时才会加载插件目录里的 hpi运行中上传新插件不会自动扫描目录里已有的未加载插件。也就是说你拷进去但没重启Jenkins 不认。解决要么先重启让目录里的插件生效再上传目标插件要么全部用目录拷贝方式一次性重启。别混用两种方式。4.5 离线包下载不全漏了传递依赖的传递依赖现象按脚本输出下载了所有插件装完还是报缺依赖。原因脚本可能只解析了一层或两层依赖没有递归到底。或者某些插件的依赖是动态的元数据里没写全。解决检查脚本的递归逻辑确保resolve_deps对每个依赖都继续调用自身。另外可以在外网找一台测试 Jenkins先在线装一遍目标插件然后去它的 plugins 目录里看实际下载了哪些 hpi用这个列表作为最终清单。这是最笨但最可靠的办法。5. 验证与进阶用一行命令确认插件真正生效装完插件重启后怎么确认它真的可用最直接的方法是看 Jenkins 的插件管理页面搜索目标插件状态显示为“已启用”且没有黄色警告图标。但页面有时会缓存更可靠的是看日志和 API。用 curl 调 Jenkins 的插件管理 API# 替换成你的 Jenkins 地址和凭据 curl -s -u admin:token http://localhost:8080/pluginManager/api/json?depth1 | \ python -c import sys,json; datajson.load(sys.stdin); [print(p[shortName], p[version], p[enabled]) for p in data[plugins] if p[shortName]git-parameter]如果输出里enabled为true说明插件已加载。如果为false去日志里搜插件名通常有具体原因。进阶技巧把整个离线部署流程脚本化。外网机器上跑一个脚本完成“解析依赖 - 下载 hpi - 打包 tar”内网机器上跑另一个脚本完成“解包 - 备份 - 拷贝 - 改权限 - 重启 - 验证”。这样每次装新插件只需要改一个插件名参数减少手工操作带来的玄学问题。我自己的习惯是每次离线装插件前先在内网 Jenkins 上打一个快照如果是虚拟机或者备份JENKINS_HOME整个目录。插件这东西装好了是生产力装坏了就是黑匣子——启动日志几千行翻起来很痛苦。有备份就有后悔药大不了回滚重来。希望帮到你。本文还有配套的精品资源点击获取