Jenkins 连接被拒速查：SCM 拉取、agent 回连端口与防火墙代理
更新时间：2026-10-24。FAQ 速查页，面向流水线第一行
git clone就红、或 agent 上线一秒变红叉、控制台只有一句Connection refused的同学。Connection refused 的意思是：TCP 三次握手走到对端、对端端口上没有进程在 listen，协议栈直接回 RST——连接根本没建起来，后面的鉴权、协议谈判一概没发生。所以它与认证失败、超时是两码事，排查方向完全不同：refused 查「端口通不通、进程在不在」，超时查「链路丢不丢包」，认证失败才查账号密钥。Jenkins 里 Connection refused 的病位收敛在六根轴上：SCM 仓库服务端口不通（git/http）、agent 回连控制器的入站端口（JNLP/Inbound TCP）没开或被拦、防火墙与安全组规则、公司代理只配了一半、SSH 用了非 22 端口而 URL 没写、目标服务进程压根没起。顺着报错里出现的主机与端口逐层确认，基本必中。如果端口通了但卡在握手，转 Jenkins 构建超时卡死速查。
本文要回答的问题
git clone报Connection refused，是仓库挂了还是 Jenkins 的问题？- agent 节点日志里
Connection refused，端口到底该开哪个？ - 浏览器能访问的仓库，Jenkins 拉取为什么还是 refused？
- 控制器与 agent 不在同一个网段，端口要怎么放行？
- 仓库 SSH 端口改成了非 22，Jenkins 里要怎么配？
一、报错原文与典型现象
Connection refused 的现场按「谁连谁」分三类：流水线连仓库、agent 连控制器、控制器连外部服务（控制器地址以 jenkins.example.com 占位，路径以 /proj/demo 占位）：
# 现场一：流水线 SCM 拉取（git 走 http）
Cloning the remote Git repository
ERROR: Error cloning remote repo 'origin'
Failed to connect to git.example.com port 443: Connection refused# 现场二：Inbound agent 回连控制器
INFO: Remoting server accepts the following protocols: [JNLP4-connect]
SEVERE: Failed to connect to jenkins.example.com:50000
java.net.ConnectException: Connection refused# 现场三：git 走 SSH（非默认端口场景）
ssh: connect to host git.example.com port 22: Connection refused
fatal: Could not read from remote repository.三个现场里出现的「主机名 + 端口号」就是排查坐标：refused 永远指向某个具体的 host:port，先把它抄下来，再去确认对端有没有人监听、中间有没有人拦截。
二、病因处置速查表
| 报错现象 / 场景 | 可能原因 | 快速验证 | 处置 |
|---|---|---|---|
| git http 拉取 443/80 refused | 仓库服务未监听该端口或反向代理掉了 | 节点上 curl -v <仓库地址> 复现 | 确认仓库进程与端口，恢复服务 |
| git SSH 默认 22 refused | 仓库 SSH 实际监听非 22 | ssh -p <端口> git@<仓库> 测试 | URL 或 ssh config 里写端口号 |
| agent 回连 refused | 控制器 Inbound agent TCP 端口没启用 | 控制器全局安全配置里看端口 | 启用固定端口并在防火墙放行 |
| 仅跨网段 refused、本网段正常 | 中间防火墙/安全组拦截 | 两端同网段节点对比测试 | 找网络侧放行 host:port |
| 浏览器通、Jenkins 不通 | 系统代理生效而 Jenkins 代理未配 | 看节点是否走代理出网 | 管理面板配 HTTP 代理或 agent JVM 加 -D 参数 |
| 一切配置正确仍 refused | 目标进程根本没启动 | 对端 ss -lnt 看监听 | 先让服务 listen，再谈网络 |
三、排查决策图
下面这张图是标准排查路线，颜色按角色区分：红是报错入口与命中的根因，蓝是排查动作，绿是通过分支，橙是修复动作，紫是防复发沉淀。
读这张图抓分水岭：第一步不是修，而是把报错里的主机与端口抄下来、判清「谁连谁」——流水线日志里的 refused 指向仓库服务，agent 日志里的 refused 指向控制器入站端口，两者的修复动作完全不在一个面板上。第二步分服务端病位与链路病位：对端端口没人监听是服务端问题，监听了但连不上才是防火墙与代理的活。这一步划分能省掉一大半无效排查。
四、逐条排查展开
SCM 拉取的 refused 先在对端确认监听。 报错里写明 Failed to connect to git.example.com port 443，第一件事是登录或询问仓库侧确认服务在跑、端口在 listen；第二件事是在 Jenkins 执行节点上手动 curl -v https://git.example.com 复现——能复现说明病位在节点到仓库之间，不能复现说明流水线环境（容器内、代理配置）与本机不同。很多「仓库挂了」的工单，真相是仓库 http 服务监听的是 8443 或走了反向代理，URL 里的端口没跟上。
Inbound agent 的回连端口是独立开关。 JNLP/Inbound agent 模式下，agent 主动回连控制器的 TCP 端口（默认 50000），这个端口在「全局安全配置 → Agents → TCP port for inbound agents」里配置，默认是禁用的——选了「禁用」agent 永远 refused，选了「随机」每次重启变端口、防火墙规则追不上。处置：设成固定端口，然后在控制器主机防火墙与云安全组里放行。改完端口后存量 agent 的启动命令里端口号要同步改。
跨网段 refused 九成是防火墙。 控制器在办公网、agent 在机房网这类拓扑里，本机 curl 通不代表跨网段通。验证方法：在同网段找一台机器测、在 agent 所在网段测，对比结果。处置不是「开全部端口」，而是精确放行 host:port 对：agent 到控制器入站端口、控制器与 agent 到仓库端口，写进防火墙工单。安全组同理，云上环境网络 ACL 与安全组两层都要看。
代理配一半是最隐蔽的 refused 来源。 公司网络里出网要走代理：浏览器有系统代理所以能开仓库页面，但 Jenkins 控制器 JVM 和 agent 进程默认不读系统代理。症状是「浏览器能开、Jenkins 拉不动」且报 refused（代理不存在时的回包也被记成 refused 一族）。处置：控制器在「插件管理 → Advanced → HTTP Proxy Configuration」配代理；agent 侧在启动命令加 -Dhttp.proxyHost=... -Dhttp.proxyPort=...；git 走 SSH 的还要配 ssh 的 ProxyCommand。
SSH 非 22 端口要在 URL 或 config 里写死。 仓库把 SSH 挪到 2222 之类端口后，git@git.example.com:proj/demo.git 这种 SCP 风格 URL 没法带端口，必须改成 ssh://git@git.example.com:2222/proj/demo.git，或在节点 /root/.ssh/config（注意是 Jenkins 进程的 HOME）里写 Host git.example.com / Port 2222。Jenkins 凭据里配的私钥路径与 known_hosts 也要跟着该 HOME 走。
进程没起是所有网络排查的前提。 最朴素的一类：对端服务升级后没拉起来、端口被别的进程占了监听失败。ss -lnt | grep <端口> 一秒确认。把这条放最后不是它不重要，而是它该最先做——对端没监听时，你在防火墙面板上点的每一次放行都是无用功。
五、规范做法与预防
- 端口清单文档化：控制器 UI 端口、inbound agent 端口、仓库 http/ssh 端口列成一张表，变更先改表再改配置。
- inbound 端口固定：禁用「随机端口」，固定值纳入防火墙基线规则。
- 代理配置三处同步：控制器面板、agent JVM 参数、SSH config 三处，漏一处就表现为间歇性 refused。
- 非标准端口写进连接串：URL 带端口优先于 ssh config，减少「换台机器又挂」的隐性依赖。
- 上线顺序：先对端 listen、再放防火墙、最后开 Jenkins 任务；排障时反过来查。
- 变更评审带上网络面：仓库迁移、端口调整、网段变更时同步评估 CI 链路，别等流水线红了才发现。
这一篇在知识体系里的位置
本篇是 Jenkins 排错速查簇的「网络连通性」入口：端口通了但构建卡住不动看 Jenkins 构建超时卡死速查；连接建立后认证被拒看 Jenkins 权限不足速查；agent 连上了又频繁掉线看 Jenkins 节点离线速查；仓库拉到后命令找不到看 Jenkins 命令找不到速查；同簇速查还有 Jenkins 环境变量不生效速查、Jenkins 中文乱码速查。「先抄下报错里的 host:port、判谁连谁、再分服务端与链路病位」这条主线对一切分布式 CI 系统的连通性问题通用。
一句话总结
Jenkins Connection refused 先抄下报错里的主机与端口、判清是流水线连仓库还是 agent 连控制器，然后分服务端与链路两侧查：服务端确认进程在监听（ss -lnt），链路侧确认防火墙、安全组、代理三处；inbound agent 端口要固定并放行，SSH 非 22 端口写进 ssh:// URL，代理要控制器面板、agent JVM、SSH config 三处同步。refused 是握手前的失败，别在认证与协议层浪费时间，端口清单文档化后这类问题基本绝迹。