### [Jenkins怎么配置代理？插件更新、Pipeline、Agent与凭据排查](https://www.jiyueip.com/article/7993)

**Published:** 2026-07-22T18:30:25

**Author:** 斑斓助理

**Excerpt:** Jenkins控制器的插件更新、Pipeline命令和远程Agent可能从不同主机发起请求。本文说明系统代理、JVM参数、任务环境、容器Agent、NO_PROXY、证书与凭据排查。

Jenkins里出现“插件能下载，但流水线里的npm、Maven或curl超时”，通常不是同一个设置失效。Jenkins控制器、静态Agent、临时容器Agent和Pipeline中的子进程可能位于不同机器，读取不同的环境变量与证书。排查第一步应确认请求究竟从哪里发出。

## 一、Jenkins中常见的四类网络请求

| 请求  | 常见执行位置 | 重点检查 |
| --- | --- | --- |
| 插件与更新中心 | 控制器 | Jenkins系统代理、JVM与CA |
| Pipeline里的命令 | 分配到的Agent | 任务环境与具体工具配置 |
| SCM检出 | 控制器或Agent，取决于任务 | Git协议、Git代理和凭据 |
| 容器化构建 | Agent启动的容器 | 容器环境、DNS、证书与网络 |

## 二、插件更新代理不等于全局代理

Jenkins管理界面的代理设置主要服务于控制器访问更新站点等功能。它不会自动改写每个Agent上的Shell环境，也不会替npm、Git、Maven或Docker配置代理。插件更新失败时先检查控制器；构建步骤失败时则回到实际Agent。

## 三、JVM参数适合哪些场景

控制器或Java进程可通过受支持的JVM系统属性设置HTTP和HTTPS代理以及非代理主机。参数应写入服务管理器实际读取的启动配置，而不是只在管理员终端执行一次`export`。修改后通常需要重启相应Java进程，并核对进程参数，但日志中不要显示代理密码。

Java网络栈与`nonProxyHosts`的差异，可参考[Java程序代理配置指南](https://www.jiyueip.com/article/7959)。

## 四、Pipeline环境应该设置在哪一层

只针对一个阶段或一种工具的代理，尽量缩小到相应Stage或步骤。整个Pipeline都需要时，可使用受控的环境注入，但还要确认工具是否读取这些变量。环境变量是一种输入，不是生效证明；必须通过访问授权端点或代理日志验证实际出口。

## 五、远程Agent为什么经常被忽略

Agent可能通过SSH、入站连接、Kubernetes Pod或其他方式启动。它的运行账号、用户目录、CA证书和系统代理都可能与控制器不同。若任务在Agent上执行，控制器浏览器能联网没有诊断价值。应记录节点名称、标签、执行器和工作空间，避免在错误机器上排查。

## 六、容器Agent还要多看两层

镜像拉取通常由容器运行时或节点守护进程完成；容器内部下载依赖则由容器进程完成。前者代理配置正确，不代表后者拥有`HTTP_PROXY`、`HTTPS_PROXY`和CA证书。Docker构建、守护进程与运行容器的区别见[Docker Compose代理配置](https://www.jiyueip.com/article/7951)。

## 七、Git检出失败先看远程协议

HTTPS远程可使用Git的HTTP代理规则，SSH远程则使用SSH自己的连接路径。Jenkins凭据只解决代码托管认证，不等于代理认证。若报407，应检查代理挑战；若报401或403，则检查仓库令牌与权限。

Git配置边界可参考[Git HTTP代理与SSH远程](https://www.jiyueip.com/article/7981)。

## 八、NO\_PROXY不要直接复制一份大列表

内部制品库、代码仓库、控制器地址和回环地址可能需要直连，但不同Java版本、Shell工具和容器对匹配语法的支持不同。应对每个关键目标逐项测试。范围过宽会让外部请求绕过审计出口，范围过窄则会把内部流量送往外部代理。

## 九、代理凭据如何管理

-   使用Jenkins凭据存储，不提交到Jenkinsfile仓库；
-   限制凭据只在需要的阶段和Agent上注入；
-   避免Shell追踪模式输出完整环境变量；
-   不要把带账号的代理URL作为普通构建参数展示；
-   轮换后结束旧任务或旧Agent，防止继续使用旧值。

## 十、证书报错应检查哪台机器

证书错误要在发起请求的控制器、Agent或容器中排查。确认系统时间、实际Java路径、系统CA、JDK信任库与代理返回的证书链。关闭证书验证会掩盖中间证书缺失或域名不匹配，不适合作为正式修复。

## 十一、推荐排查顺序

1.  从失败日志确认Pipeline步骤和Agent节点；
2.  识别请求由Jenkins、Java还是外部工具发送；
3.  检查该进程的代理、绕过列表与CA；
4.  区分DNS、TCP、407、TLS和目标401；
5.  使用最小只读任务验证出口；
6.  重启需要读取新配置的服务或临时Agent；
7.  清理调试凭据并保留脱敏变更记录。

## 十二、结论

Jenkins代理配置不是一个全局开关。把控制器、Agent、容器和Pipeline工具分开看，先定位请求执行位置，再配置相应网络环境，才能避免插件更新正常而业务构建长期失败。

**Tags:** HTTP代理, 服务器运维, 终端代理, 网络故障排查

**Categories:** 行业洞察

---