Jenkins 更新中心连不上速查：证书过期、代理拦截与镜像源切换
更新时间：2026-10-24。FAQ 速查页，面向插件管理页一片红字「There were errors checking the update sites」、装插件卡在下载环节不动的同学。Jenkins 更新中心连不上的本质是「网络 × 证书 × 源」三层的任意一层断了：控制器到更新站点的网络通不通（防火墙、代理、DNS）、HTTPS 握手时证书验不验得过（JDK 证书库过期、代理做了 TLS 拦截）、以及你配的那个源本身是不是活的（官方站点抖动、镜像源不同步）。控制器地址以
jenkins.example.com占位，更新站点以「官方更新中心」与镜像源文字表述，不出现真实地址。如果是装完插件后流水线报错而不是装不上，转 Jenkins 插件版本不兼容速查。
本文要回答的问题
Signature verification failed是站点被劫持了吗，还是本地证书库过期？- 浏览器能打开更新中心页面，为什么 Jenkins 里还是连不上？
- 企业代理环境下，Jenkins 的代理在哪配、为什么配了还不通？
- 换镜像源该改哪个文件，改完为什么有的插件还是拉不下来？
- 完全离线的内网环境，插件怎么装进去？
一、报错原文与典型现象
更新中心报错集中在三处：插件管理页的横幅、系统日志里的握手异常、以及下载环节的连接超时：
# 插件管理页横幅
There were errors checking the update sites:
Signature verification failed in the update site 'default'# 系统日志：TLS 握手失败
javax.net.ssl.SSLHandshakeException:
PKIX path building failed:
unable to find valid certification path to requested target# 下载插件时：连接超时
java.net.SocketTimeoutException: Connect timed out
# 或 DNS 解析失败
java.net.UnknownHostException: updates.jenkins.example.com读现象先分三层：PKIX path building failed 是证书层——握手都没完成，与站点死活无关；Connect timed out 和 UnknownHostException 是网络层——包根本到不了对端；Signature verification failed 是内容层——文件拉下来了但验签不过，说明链路中间有人动过或者本地信任锚过期。
二、病因处置速查表
| 报错现象 / 场景 | 可能原因 | 快速验证 | 处置 |
|---|---|---|---|
| PKIX path building failed | 控制器 JDK 证书库缺根证书或已过期 | 用同 JDK 的 keytool 列证书库有效期 | 升级 JDK 或导入缺失根证书 |
| Signature verification failed | 企业代理做了 TLS 拦截替换证书 | curl -v 看握手证书颁发者是谁 | 把代理根证书导入 JDK 信任库 |
| Connect timed out | 防火墙未放行出站 443 或代理未配 | 在控制器上 curl 更新站点地址 | 放行出站；管理页配 HTTP 代理 |
| UnknownHostException | 内网 DNS 解析不了外部域名 | nslookup 更新站点域名 | 修 DNS 或换可解析的镜像源 |
| 官方源慢/抖动拉不动 | 跨境链路拥塞 | 直接 curl 测下载速度 | 切换国内镜像源或离线安装 |
| 镜像源部分插件 404 | 镜像未全量同步元数据 | 对比镜像源与官方元数据时间戳 | 换回官方源补齐，或离线装缺的 |
三、排查决策图
下面这张图是标准排查路线，颜色按角色区分：红是报错入口与命中的根因，蓝是排查动作，绿是通过分支，橙是修复动作，紫是防复发沉淀。
读这张图抓分水岭：报错原文里带 PKIX、SSLHandshake、Signature 的走左支查证书与 TLS 拦截；带 timed out、UnknownHost 的走右支查网络连通与 DNS。两条支路汇到同一个修复口：要么把链路修通，要么绕开它换源、离线装。
四、逐条排查展开
PKIX 报错：锅在本地 JDK 证书库，不在站点。 unable to find valid certification path 的意思是握手时对方出示的证书链，在你本地信任库里找不到可锚定的根。两种典型成因：一是控制器跑在老 JDK 上，证书库里某些根证书已过期或被移除，升级 JDK 或单独导入新根证书即可；二是企业出口的 TLS 检查设备把原站点证书换成了自签证书，本地库自然不认——这种情况 curl -v 看握手返回的证书颁发者，不是预期 CA 而是公司名，就实锤了代理拦截。
Signature verification failed：文件拉到了但不敢用。 更新中心的元数据带签名，Jenkins 下载后会用内置公钥验签。验签失败的常见剧本是中间链路对响应做了改写（内容过滤、缓存注入），或本地信任锚与当前官方签名钥不匹配。处置：先确认不是代理在改写内容（绕过代理直连一次验证），再考虑升级 Jenkins 本体——新版内置了更新的验签材料。
Connect timed out 先查出站，再查 Jenkins 代理配置。 Jenkins 走代理不是在系统环境变量里设了就够，要在「系统管理 → 插件管理 → 高级」里填 HTTP 代理服务器与端口，需要认证的代理还要填用户名口令。配了还不通，在控制器本机用同样的代理参数 curl 一次更新站点——curl 通而 Jenkins 不通，是 Jenkins 侧配置没生效（改过要刷新或重启）；curl 也不通，是防火墙或代理本身的事，找网络组放行出站 443。
UnknownHostException 是 DNS 的事。 内网 DNS 服务器不解析外部域名、或解析结果被污染。nslookup 一下更新站点域名就知道；改不了内网 DNS 就换镜像源——镜像源通常有国内可解析的域名，顺手还解决了跨境慢的问题。
换镜像源：改的是更新中心 URL。 位置在插件管理页的「高级」里，把更新中心地址换成镜像源提供的地址，保存后点「立即检查」强制刷新元数据。两个坑：一是镜像源的元数据不是实时同步官方，刚发布的插件版本可能查不到；二是部分镜像只镜像了元数据没镜像全部 hpi 文件，下载时 404——这种就对该插件走离线安装。
离线安装：hpi 文件手动上传。 完全离网的内网环境，在外网机器从官方插件页或镜像站下载插件的 .hpi（或 .jpi）文件，注意把它的依赖插件也一并下齐（插件详情页列了 Dependencies，依赖还有传递依赖，建议按依赖清单整包下载而不是一个一个试）。然后在 Jenkins 插件管理 → 高级 → 「上传插件」处逐个上传，重启后生效。依赖顺序错了会在启动日志里看到 Failed to load: xxx，按提示补装缺失依赖即可。版本选择上有个朴素原则：优先挑「与你的 Jenkins 本体版本兼容」的插件版本，插件详情页标注了要求的最低本体版本，本体太老时新插件装上也不加载。
五、规范做法与预防
- JDK 版本跟上维护线：证书库随 JDK 更新，老 JDK 是 PKIX 报错的温床。
- 代理配置写进装机清单：企业网内新装控制器，HTTP 代理与根证书导入是标准步骤。
- 镜像源做主、官方源做备：国内团队默认走镜像源，遇元数据不同步再临时切回官方补齐。
- 离线环境建内部插件仓：常用插件的 hpi 与依赖打包归档，装新机不依赖外网。
- 证书与域名到期监控：更新链路涉及的自签代理证书、内部镜像域名证书纳入到期告警。
- 装插件留清单：每次安装记录插件名与版本，出问题时能对回到具体变更。
这一篇在知识体系里的位置
本篇是 Jenkins 排错速查簇的「插件供应链」入口：插件装上了但版本互相打架看 Jenkins 插件版本不兼容速查；控制器本身网络不通的更大范围排查看 Jenkins 连接被拒绝速查；节点而不是控制器连不上看 Jenkins 节点离线速查。「证书层 → 网络层 → 内容层」三层定位法对一切更新中心类报错通用。
一句话总结
Jenkins 更新中心连不上先按报错定层：PKIX、SSLHandshake、Signature 走证书层——升级 JDK、导入代理根证书，curl -v 看颁发者实锤 TLS 拦截；timed out、UnknownHost 走网络层——查出站防火墙、在插件管理页配代理、修 DNS；都修不通就绕开它：切镜像源、离线传 hpi。镜像源要防元数据不同步与部分插件缺失，离线环境建内部插件仓，证书到期纳入监控，更新中心类报错基本绝迹。