在开发交付群里被了一百次“连不上Nexus构建全挂了”大概每个搞过Java后端、跑过Maven私服的人都有过这种经历。Maven连接Nexus报错的原因五花八门但报错信息翻来覆去就那么几行Connection refused、ConnectException、Could not transfer artifact看着像是同一个问题实际上可能差着十万八千里。这篇东西就是冲着“速查”两个字去的把我在实际项目里遇到过的、以及帮别的团队排查过的连接被拒绝场景按根因类别全部列出来每一条都会问你三个问题服务到底起没起、Maven这边配置对不对、网络到底通不通。配置文件、排查命令、坑位提醒都会给到适合正在被构建报错折腾的开发和运维同学也适合刚接手Nexus私服、想搞明白连接机制的人。1. 连接被拒绝的第一根因Nexus到底“活着”没有拿到任何“连接被拒绝”的报错我从来不会先去翻settings.xml而是先确认一件事Nexus进程到底在不在跑、IP和端口到底能不能通。因为Connection refused这个英文本身就已经说得很清楚了——你的请求被操作系统拒绝了也就是说目标机器上根本没有程序在那个端口等着你。很多时候Maven报错只是表象真正的根因是Nexus服务压根没起来或者是起了但监听地址不对。1.1 最容易被忽略的顺序问题先确认服务状态很多团队习惯把Nexus部署在专门的一台服务器上或者放在某个虚拟机的容器里。Nexus没起来的原因又特别多进程被kill了、机器重启以后忘了设置开机自启、磁盘满了导致启动失败。更隐蔽的情况是服务起来了但还没完全就绪——Nexus启动过程中会有一段时间对外端口已经打开了但内部应用还没准备好这时候发过去的请求同样可能被重置或者被拒绝。排查时用一条命令就能快速定位# 在Nexus服务器本机上检查进程 ps -ef | grep nexus # 或者查看端口监听状态Linux ss -lntp | grep 8081如果进程存在但端口没有LISTEN说明启动过程卡住了或者配置的端口不是8081。如果端口在LISTEN但本机访问仍然失败先怀疑是不是防火墙拦了回环地址。这里有个很经典的坑很多人把Nexus装好以后第一次启动一直报错后来发现是启动脚本参数里指定了低版本JDK路径而Nexus版本要求JDK版本更高导致JVM起来后立刻崩掉进程反复重启。这类问题不能光看Maven的报错得去Nexus的日志目录看启动日志sonatype-work/nexus3/log/下面通常有nexus.log和jvm.log任何启动阶段的异常都会写在这里。1.2 端口和地址确认8081不是唯一答案Nexus3的默认端口是8081但生产环境很多团队会改掉这个端口或者用反向代理把外部8080映射到内部8081。排查连接问题之前必须确认Maven访问的地址和Nexus实际监听地址完全一致。在Nexus服务器上执行curl -v http://localhost:8081/service/rest/v1/status这行命令返回JSON并且HTTP状态码是200的话说明服务正常。返回Connection refused说明服务没起来或端口不对。返回超时说明端口被防火墙静默丢弃了。需要注意的是Nexus3的REST API路径在不同版本上略有差异但/service/rest/v1/status这个路径从Nexus3.20以后一直很稳定。提示如果你用Docker启动Nexus别忘记检查端口映射。docker ps里显示的宿主机端口和容器内部端口都要确认-p 8081:8081这种映射方式把宿主机的8081映射到容器的8081如果宿主机8081被别的进程占用了容器可能启动成功但端口没绑上。2. Maven侧配置settings.xml里那些“自作主张”的坑如果Nexus这边一切正常问题就转移到Maven这一侧。Maven的settings.xml是全局配置文件里面配了mirror、server、proxy等一堆东西任何一个字段写错都能造成连接失败。而且Maven报错经常是嵌套的外层写着Could not transfer artifact内层才藏着你真正需要看的异常信息。很多人只看前两行就开始怀疑网络结果折腾半天发现就是URL少写了一个字母。2.1 mirrors和repositories的address纠错Maven查找依赖的顺序是先读settings.xml里的mirror配置如果不匹配再读pom.xml里的repository。连接被拒绝最常见的原因是settings.xml里的mirror配置指向了一个错误的仓库地址。mirror idlocal-nexus/id mirrorOf*/mirrorOf urlhttp://192.168.1.100:8081/repository/maven-public//url /mirror这段配置看起来人畜无害但出问题的点往往不在格式而在URL本身。第一个坑末尾的斜杠。Nexus的repository路径必须以斜杠结尾如果漏掉了Maven拼接路径时会直接拼出一个奇怪的URL比如repository/maven-public/com/example/xxx.jar前者正常后者却会报404而不是Connection refused。第二个坑协议。有人配了https://开头的URL但Nexus实际只开了HTTP监听这就会直接握手失败报出来的错误五花八门有时候是SSLHandshakeException有时候直接就是Connection refused。第三个坑hostname解析。你写的是域名但这个域名在构建机上的DNS和hosts文件里根本没有映射那请求就是往一个不存在的地址上发报错也经常是Connection refused。排查方式很简单把配的URL直接复制到浏览器或curl里访问curl -I http://192.168.1.100:8081/repository/maven-public/如果返回HTTP/1.1 200说明地址没问题。如果返回301或302说明Nexus配置了HTTP→HTTPS重定向那你Maven里的URL也得跟着改成https。这个情况比大家想象中要多很多团队在Nexus前面挂了Nginx或者自己买了SSL证书HTTP的8081对外已经不可见了。2.2 server认证配置的坑Nexus默认设置了匿名访问权限但生产环境通常都会关掉匿名或者只对特定仓库开匿名。一旦Nexus要求认证而Maven侧没有配置正确的server凭据报错可能就不是401 Unauthorized那么直白。Maven在某些版本、某些传输场景下会把401包装成Could not transfer artifact甚至显示为Repository blocked。正确的配置方式是servers server idlocal-nexus/id usernamedeployer/username passwordpassword/password /server /servers这里有一个极其隐蔽的坑id必须和mirror或者repository配置里的id完全一致。你看好了是“完全一致”包括大小写和字符。因为Maven匹配凭据的时候就是通过这个id去servers列表里找对应配置的。id对不上Maven根本不会把用户名密码带上那Nexus返回401或403Maven这边看到的就是连接失败或者认证失败。另外密码里如果带有特殊字符比如、、在XML里必须做转义否则settings.xml直接解析失败Maven会报错“malformed POM”或者干脆无法启动构建很多人遇到这种问题还以为是Java环境坏了。2.3 HTTP/HTTPS与代理端口还有一个经常被忽略的场景你所在的环境是内网开发环境但本机也配了HTTP代理比如公司办公网络要求所有HTTP请求走代理。settings.xml里的proxies配置会影响到Maven发起的所有连接。一旦代理服务器本身不通Maven访问Nexus也会报Connection refused但这个refused的对象其实是代理服务器而不是Nexus本身。proxies proxy idoffice-proxy/id activetrue/active protocolhttp/protocol hostproxy.company.com/host port8080/port nonProxyHosts192.168.1.*|localhost/nonProxyHosts /proxy /proxiesnonProxyHosts字段用竖线分隔多个地址支持通配符。如果这里没把内网Nexus地址加进去那么每一次下载依赖都会绕路到外网代理既慢又容易失败。很多项目连接Nexus时好时坏罪魁祸首就是这台代理服务器偶尔抽风。建议排查的时候直接先临时把active改成false再跑一把mvn构建如果问题消失那说明就是代理配置的问题。3. 网络与环境从localhost到防火墙的层层关卡前面两步都排查过了Nexus活着、Maven配置正确但依然连接失败那问题就出在请求路径的中间环境里。这里的“中间环境”可能是真实的防火墙也可能是容器网络、云平台安全组、虚拟机网络模式甚至只是一个写错了的hosts映射。这个阶段的排查思路应该分层进行每次只“打通”一层逐步缩小故障范围。3.1 同一台机器 vs 远程访问bind addressNexus默认会监听所有网卡的8081端口但有些部署方式里启动参数会修改成只监听某个IP。比如在nexus.vmoptions文件里或者启动脚本中设置了-Djava.net.preferIPv4Stacktrue或者Nexus的application.properties如果存在里指定了application-host参数。如果配置了只监听127.0.0.1那么Maven从另外一台机器来访问就是白搭报出来就是Connection refused。验证方式是在开发机上执行telnet 192.168.1.100 8081能通的话说明Nexus对远程访问是开放的。不通的话登录服务器再执行一次ss -lntp | grep 8081看看监听地址是0.0.0.0:8081、*:8081还是具体的局域网IP。如果是127.0.0.1:8081说明配置把绑定地址限制在回环接口上了。这时候可以到安装目录下检查etc/nexus.properties或者启动时追加的JVM参数把application-host的值改成0.0.0.0或者在启动命令里去掉这个限制。3.2 防火墙、安全组、容器网络的排查思路Linux服务器上最常见的拦截者是iptables、firewalld或者ufw。很多服务器管理员会把默认策略设为DROP没有显式放行8081端口的话外部的连接请求会被静默丢弃表现不是Connection refused而是timeout。如果你看到的是refused说明对方服务器对你的请求发了RST包也就是说端口可能没监听但如果是timeout那大概率就是防火墙把包丢了。容器环境里还有一个额外的坑Nexus跑在某个Docker容器里容器网络是bridge模式宿主机做了-p端口映射。此时从宿主机访问没问题但从另一台机器访问就要看宿主机的防火墙、云安全组是否放行了8081端口。很多人遇到的情况是开发机的telnet能通Nexus所在服务器IP的8081但是从另一台网络环境奇特的机器上就是不通最后发现是两个子网之间的ACL规则没放行或者云平台安全组只允许了办公网段访问。注意即使你用Docker跑Nexus也不要忘掉容器内部还有一层网络命名空间。进入容器用docker exec -it [容器ID] curl http://localhost:8081/service/rest/v1/status可以验证容器内部服务本身是否正常这能帮你区分是容器服务问题还是端口映射问题。3.3 用telnet/curl/nc快速定位故障层级连接问题的排查一定要用“最小化命令”去定位不要一上来就mvn clean package。我自己习惯这样一层层试# 第一层DNS/域名解析 ping my-nexus.example.com # 或者 nslookup my-nexus.example.com # 第二层端口连通性 telnet my-nexus.example.com 8081 # 或者 nc -vz my-nexus.example.com 8081 # 第三层HTTP服务可达性 curl -v http://my-nexus.example.com:8081/repository/maven-public/如果telnet都连不通说明问题出在网络层再去纠结Maven配置没有意义。如果telnet通但curl返回异常比如HTTP状态码是400或者500那就进入应用层排查看Nexus的后台日志。还有一类罕见情况telnet能通curl也能通但mvn构建依然报Connection refused这是因为Maven在解析settings.xml或者pom.xml里的repository URL时做了变量替换实际请求的地址和你在curl里测试的地址根本不一样。这时候要靠Maven的调试日志来定位mvn clean install -X -DskipTests日志里会打印出每个依赖下载的实际URL照着那个URL再去curl通常就能发现问题。4. 常见错误信息速查与一揽子解决方案做技术排障不能靠猜得靠“从现象反推原因”。这里把Maven连接Nexus时最常出现的几类报错信息整理成一张速查思路表每条列出典型报错、可能的根因以及首选排查动作。注意这里的报错信息只是“线索”最终诊断必须结合前文的排查流程综合判断。报错现象关键词典型根因首选排查动作Connection refused / ConnectExceptionNexus服务未启动、端口错误、防火墙拒绝、监听地址受限登录服务器查进程执行 ss -lntpConnection timed out防火墙DROP策略、跨网段ACL拦截、服务器宕机检查云安全组/防火墙规则ping和telnet逐步定位SSLHandshakeExceptionNexus使用的HTTPS证书过期或Maven侧URL协议错误换成http测试或更新JDK信任库里的证书HTTP 401 Unauthorized认证凭据缺失或服务器id不匹配检查settings.xml中的servers配置确保id一致HTTP 403 Forbidden用户权限不足登录Nexus检查该用户是否有对应仓库的访问权限HTTP 404 Not Foundrepository名称或路径拼写错误在Nexus Web界面查看实际仓库名并核对URLCould not transfer artifact多种原因最常见是镜像URL错误或代理配置错误查看Maven -X日志中打印的最终下载地址Repository blocked远程仓库被Nexus误判为不可用登录Nexus后台查看仓库状态尝试重新连接远程仓库UnknownHostExceptionDNS解析失败检查hosts文件或DNS服务器配置MalformedURLExceptionURL地址中协议、端口或路径格式错误检查settings.xml中url字段是否缺少斜杠或包含非法字符4.1 Connection refused 与 timeout 的语义区别这个值得单独拎出来讲。Connection refused和Connection timeout虽然都表现为“连不上”但底层逻辑完全不同。Connection refused是TCP层收到了对方的RST包换句话说目标主机的网络栈是通的但它告诉你“这个端口我没法连接”通常是服务没监听或者防火墙主动拒绝。Connection timeout则是发出了SYN包但一直没等到回应多半是包被丢弃了典型场景是防火墙DROP策略、路由器ACL或者目标主机宕机。所以当你拿到报错时第一反应应该是看“关键字”。我的习惯是看到refused优先查“服务是否启动”其次查“端口监听地址”最后查“防火墙是否显式REJECT”看到timeout优先查“网络路由是否可达”其次查“云安全组”最后查“目标服务器是否宕机”4.2 401、403 等权限类错误的联动排查权限类错误看起来和“连接被拒绝”无关但在Nexus里这两者经常被串在一起。最典型的场景是匿名用户没有任何仓库的查看权限Nexus直接拒绝连接请求表现就是Maven下载依赖时连续报错看起来像网络不可达。第二次遇到类似问题时我会先打开Nexus后台看一下对应仓库的“Anonymous Access”是否被勾选了。在Nexus3的管理界面中Settings → Security → Anonymous Access可以控制匿名访问而每个仓库的Repository → Settings → Security里还有细粒度的权限控制。生产环境建议关闭匿名但关闭的同时必须确保所有开发机上的settings.xml都配了正确的server凭据否则所有人都会连不上那时候就别谈什么“连接被拒绝”了那叫“权限管理事故”。4.3 快速检查清单三步从报错到定位为了不让自己在排障时漏掉细节我给自己拟了一张“三步走”清单每次都能在十分钟内从报错信息定位到根因跑一次带调试日志的构建把-X输出的完整报错截图或者复制下来重点看最底部的Caused by因为那个才是真正的异常源头。拿报错里的URL地址直接去telnet和curl测试服务是否真的“拒绝连接”用最小化手段复现不要带着Maven的整个依赖解析流程去猜。逐项对照上面表格里的“典型根因”最可疑的候选先验证验证方式就是修改一处配置后重新跑一次构建能复现就说明没改对不能复现就说明命中根因。这三步的核心思想是“剥离层次、逐级排雷”。Maven构建只是客户端它的报错信息本质上就是HTTP或者网络层的异常包装把包装拆掉底层的真相并不难找。5. 实操记录一次完整Nexus连接故障的排查复盘前面讲了一堆方法不如直接看一次真实排查过程。这个案例发生在某公司的Java微服务项目里场景是十几台构建机器分批执行CI构建某天早上突然大面积失败报错全部是Connection refused。公司IT环境属于内网部署Nexus跑在一台虚拟机里IP地址是192.168.10.20端口8081构建机的Maven配置了统一的settings.xml镜像指向它。5.1 从报错到定位分段排查的完整逻辑当天早上故障一报出来我先看的是CI日志连续翻了十几个都是同一个错误——Could not transfer artifact ... Connection refused。第一反应是Nexus服务挂了。于是登录192.168.10.20服务器执行ps -ef | grep nexus进程存在但再执行ss -lntp | grep 8081发现8081端口根本没有监听。当时心里“咯噔”一下因为进程在但端口没绑定这通常意味着Nexus启动到一半卡住了。紧接着看了日志文件发现最后的记录是ES索引初始化失败导致整个应用无法完成启动流程Nexus进程虽然在跑但JVM内部并没进入可用状态。处理完索引问题重启Nexus端口正常监听了。但CI重跑依然有部分机器报Connection refused。这时候我却注意到报错机器和正常机器之间的差异——报错的都是最近新扩容的构建机正常的都是老机器。再一查发现新构建机上的settings.xml是从另一个团队仓库里拷来的镜像URL写的是http://192.168.10.21:8081/repository/maven-public/把地址写错了。高可用方案里Nexus有第二个节点新机器配置写的是故障节点的IP而故障节点已经下线了。只改掉这一处配置后全部构建恢复。这次排查其实踩了一个很典型的“思维定式”坑第一轮看到连接被拒绝我的注意力全在服务状态上等确认服务正常后没有再重新审视“报错的都是哪些机器、它们和正常机器有什么区别”。如果把机器分组和配置差异核查提前到第二位至少能省出一轮CI重跑的等待时间。5.2 故障加固建议日志、监控与公共配置在排查修复之后我还给团队做了三件事防止类似问题再次造成大面积故障。第一给Nexus的启动和运行状态做基础监控不需要很复杂的系统只要能每分钟探测一次/service/rest/v1/status接口并告警就行。第二修改统一分发settings.xml的方式不再允许各项目组自己复制粘贴配置而是走配置中心统一管理镜像地址、server凭据全部做好版本控制。第三在构建脚本里把Maven的调试日志默认打开一份输出到固定目录以后再有连接类报错别问开发同学“报什么错”直接让他们把日志文件发过来手工定位的时间至少缩短一半。这套“监测配置治理日志留存”的组合拳虽然不是解决“连接被拒绝”的直接操作但属于事后避免同样问题再次发生的有效手段。真正负责Nexus或者CI基础设施的同学我建议也照着这套思路做不然就算今天把问题修好了下周换一批机器、换一个网段同样的坑还会再踩一遍。写在最后我个人在实际排查Nexus连接被拒这类问题时逐渐养成了一个强迫症永远先问“服务在哪、监听在哪、通不通”再问“配置写了什么、凭据对不对”最后才去怀疑代码和构建流程本身。这里有一个不太容易从官方文档里学到的经验——用mvn -X输出来定位连接问题时请同时关注Maven解析配置的“顺序”和“结果”因为有多套镜像、多个repository存在的时候Maven到底走了哪条路径往往比报错内容本身更能暴露问题。以后再遇到Connection refused希望你第一反应不是烦躁而是把这篇手册里的速查表对照一遍。大部分场景下问题都能在十分钟内水落石出。