Jenkins配置正确代理后下载插件报IOException代理隧道403 Forbidden

故障基础信息 #

• 触发场景：Jenkins运行环境下执行插件下载操作时，系统抛出java.io.IOException异常
• 完整报错信息：Unable to tunnel through proxy. Proxy returns "HTTP/1.1 403 Forbidden"
• 已完成前置排查：用户已核对Jenkins全局安全配置页填写的代理地址、端口、认证账号、密码信息，确认配置参数完全准确，代理隧道触发的相关报错界面已留存截图参考。

常见故障原因 #

• 代理访问权限范围不匹配：当前使用的代理账号虽然认证信息正确，但代理服务端未给该账号开放HTTPS CONNECT隧道的目标域名访问权限。Jenkins拉取插件资源基于HTTPS协议传输，需要代理支持CONNECT方法建立加密隧道，多数企业代理默认仅放行特定域名的隧道请求，未将Jenkins插件仓库域名加入白名单时，代理会直接返回403拒绝建立连接。
• 代理认证机制不兼容：Jenkins插件下载流程依托Java原生网络栈实现，部分企业代理要求的NTLM、Negotiate等认证方式，和Jenkins默认透传Basic认证的逻辑不兼容，即使填写的账号密码完全正确，代理服务端也会因无法识别到合法有效凭证返回403。
• 本地层面流量拦截：Jenkins运行节点所在服务器的操作系统层面，存在本地防火墙、全局安全代理进程的规则拦截，未将Jenkins对应的Java进程流量加入放行列，导致流量在到达目标代理服务前就被本地层拦截返回403，这类问题和Jenkins界面填写的代理配置没有直接关联。
• 代理缓存规则异常：代理服务端针对历史失败的请求缓存了403响应规则，即便后续修正了配置参数，新请求命中旧缓存规则时，也会持续返回403错误。

可落地的排查解决步骤 #

• 联动代理服务管理员核实账号权限：
  • 确认当前代理账号的隧道权限覆盖范围，确保支持443端口的HTTPS流量转发能力
  • 将Jenkins插件更新中心、官方/第三方插件镜像的对应域名加入代理白名单，排除策略拦截
• 调整Jenkins端JVM与代理配置的兼容逻辑：
  • 核对Jenkins全局代理配置页的规则，确认没有错误配置绕过代理的内网地址段，避免Jenkins绕开配置直接发请求触发403
  • 修改Jenkins服务的JVM启动参数，追加-Djdk.http.auth.tunneling.disabledSchemes=""，移除Java版本默认对Basic代理认证建立隧道的限制；如果代理要求NTLM认证，可同步追加对应JVM认证参数，匹配代理的认证交互逻辑
• 跨层验证定位故障点：
  • 在Jenkins运行节点的服务器上，直接用curl命令模拟走代理访问插件仓库地址，验证隧道连通性，执行命令为curl -x [代理地址:端口] -U [代理账号:密码] https://updates.jenkins-ci.org/download/。如果curl请求同样返回403，说明问题出在代理服务端策略或本地系统规则层面，与Jenkins本身配置无关
  • 检查服务器本地防火墙、安全管控软件的进程白名单，确认Java进程的出站流量不受拦截
• 清理缓存排除临时异常：
  • 重启Jenkins服务后重新触发插件下载流程，排除代理端临时缓存导致的403响应
  • 可临时关闭Jenkins内置的代理配置，在服务器系统层面配置全局代理，验证Jenkins是否能正常拉取插件，反向定位故障是Jenkins代理模块本身的问题，还是代理服务端的策略限制

内容的提问来源于stack exchange，提问作者Yenike Raghu Ram