在開發(fā)交付群里被了一百次“連不上Nexus構建全掛了”大概每個搞過Java后端、跑過Maven私服的人都有過這種經(jīng)歷。Maven連接Nexus報錯的原因五花八門但報錯信息翻來覆去就那么幾行Connection refused、ConnectException、Could not transfer artifact看著像是同一個問題實際上可能差著十萬八千里。這篇東西就是沖著“速查”兩個字去的把我在實際項目里遇到過的、以及幫別的團隊排查過的連接被拒絕場景按根因類別全部列出來每一條都會問你三個問題服務到底起沒起、Maven這邊配置對不對、網(wǎng)絡到底通不通。配置文件、排查命令、坑位提醒都會給到適合正在被構建報錯折騰的開發(fā)和運維同學也適合剛接手Nexus私服、想搞明白連接機制的人。1. 連接被拒絕的第一根因Nexus到底“活著”沒有拿到任何“連接被拒絕”的報錯我從來不會先去翻settings.xml而是先確認一件事Nexus進程到底在不在跑、IP和端口到底能不能通。因為Connection refused這個英文本身就已經(jīng)說得很清楚了——你的請求被操作系統(tǒng)拒絕了也就是說目標機器上根本沒有程序在那個端口等著你。很多時候Maven報錯只是表象真正的根因是Nexus服務壓根沒起來或者是起了但監(jiān)聽地址不對。1.1 最容易被忽略的順序問題先確認服務狀態(tài)很多團隊習慣把Nexus部署在專門的一臺服務器上或者放在某個虛擬機的容器里。Nexus沒起來的原因又特別多進程被kill了、機器重啟以后忘了設置開機自啟、磁盤滿了導致啟動失敗。更隱蔽的情況是服務起來了但還沒完全就緒——Nexus啟動過程中會有一段時間對外端口已經(jīng)打開了但內(nèi)部應用還沒準備好這時候發(fā)過去的請求同樣可能被重置或者被拒絕。排查時用一條命令就能快速定位# 在Nexus服務器本機上檢查進程 ps -ef | grep nexus # 或者查看端口監(jiān)聽狀態(tài)Linux ss -lntp | grep 8081如果進程存在但端口沒有LISTEN說明啟動過程卡住了或者配置的端口不是8081。如果端口在LISTEN但本機訪問仍然失敗先懷疑是不是防火墻攔了回環(huán)地址。這里有個很經(jīng)典的坑很多人把Nexus裝好以后第一次啟動一直報錯后來發(fā)現(xiàn)是啟動腳本參數(shù)里指定了低版本JDK路徑而Nexus版本要求JDK版本更高導致JVM起來后立刻崩掉進程反復重啟。這類問題不能光看Maven的報錯得去Nexus的日志目錄看啟動日志sonatype-work/nexus3/log/下面通常有nexus.log和jvm.log任何啟動階段的異常都會寫在這里。1.2 端口和地址確認8081不是唯一答案Nexus3的默認端口是8081但生產(chǎn)環(huán)境很多團隊會改掉這個端口或者用反向代理把外部8080映射到內(nèi)部8081。排查連接問題之前必須確認Maven訪問的地址和Nexus實際監(jiān)聽地址完全一致。在Nexus服務器上執(zhí)行curl -v http://localhost:8081/service/rest/v1/status這行命令返回JSON并且HTTP狀態(tài)碼是200的話說明服務正常。返回Connection refused說明服務沒起來或端口不對。返回超時說明端口被防火墻靜默丟棄了。需要注意的是Nexus3的REST API路徑在不同版本上略有差異但/service/rest/v1/status這個路徑從Nexus3.20以后一直很穩(wěn)定。提示如果你用Docker啟動Nexus別忘記檢查端口映射。docker ps里顯示的宿主機端口和容器內(nèi)部端口都要確認-p 8081:8081這種映射方式把宿主機的8081映射到容器的8081如果宿主機8081被別的進程占用了容器可能啟動成功但端口沒綁上。2. Maven側配置settings.xml里那些“自作主張”的坑如果Nexus這邊一切正常問題就轉移到Maven這一側。Maven的settings.xml是全局配置文件里面配了mirror、server、proxy等一堆東西任何一個字段寫錯都能造成連接失敗。而且Maven報錯經(jīng)常是嵌套的外層寫著Could not transfer artifact內(nèi)層才藏著你真正需要看的異常信息。很多人只看前兩行就開始懷疑網(wǎng)絡結果折騰半天發(fā)現(xiàn)就是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。第二個坑協(xié)議。有人配了https://開頭的URL但Nexus實際只開了HTTP監(jiān)聽這就會直接握手失敗報出來的錯誤五花八門有時候是SSLHandshakeException有時候直接就是Connection refused。第三個坑hostname解析。你寫的是域名但這個域名在構建機上的DNS和hosts文件里根本沒有映射那請求就是往一個不存在的地址上發(fā)報錯也經(jīng)常是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對外已經(jīng)不可見了。2.2 server認證配置的坑Nexus默認設置了匿名訪問權限但生產(chǎn)環(huán)境通常都會關掉匿名或者只對特定倉庫開匿名。一旦Nexus要求認證而Maven側沒有配置正確的server憑據(jù)報錯可能就不是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匹配憑據(jù)的時候就是通過這個id去servers列表里找對應配置的。id對不上Maven根本不會把用戶名密碼帶上那Nexus返回401或403Maven這邊看到的就是連接失敗或者認證失敗。另外密碼里如果帶有特殊字符比如、、在XML里必須做轉義否則settings.xml直接解析失敗Maven會報錯“malformed POM”或者干脆無法啟動構建很多人遇到這種問題還以為是Java環(huán)境壞了。2.3 HTTP/HTTPS與代理端口還有一個經(jīng)常被忽略的場景你所在的環(huán)境是內(nèi)網(wǎng)開發(fā)環(huán)境但本機也配了HTTP代理比如公司辦公網(wǎng)絡要求所有HTTP請求走代理。settings.xml里的proxies配置會影響到Maven發(fā)起的所有連接。一旦代理服務器本身不通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字段用豎線分隔多個地址支持通配符。如果這里沒把內(nèi)網(wǎng)Nexus地址加進去那么每一次下載依賴都會繞路到外網(wǎng)代理既慢又容易失敗。很多項目連接Nexus時好時壞罪魁禍首就是這臺代理服務器偶爾抽風。建議排查的時候直接先臨時把active改成false再跑一把mvn構建如果問題消失那說明就是代理配置的問題。3. 網(wǎng)絡與環(huán)境從localhost到防火墻的層層關卡前面兩步都排查過了Nexus活著、Maven配置正確但依然連接失敗那問題就出在請求路徑的中間環(huán)境里。這里的“中間環(huán)境”可能是真實的防火墻也可能是容器網(wǎng)絡、云平臺安全組、虛擬機網(wǎng)絡模式甚至只是一個寫錯了的hosts映射。這個階段的排查思路應該分層進行每次只“打通”一層逐步縮小故障范圍。3.1 同一臺機器 vs 遠程訪問bind addressNexus默認會監(jiān)聽所有網(wǎng)卡的8081端口但有些部署方式里啟動參數(shù)會修改成只監(jiān)聽某個IP。比如在nexus.vmoptions文件里或者啟動腳本中設置了-Djava.net.preferIPv4Stacktrue或者Nexus的application.properties如果存在里指定了application-host參數(shù)。如果配置了只監(jiān)聽127.0.0.1那么Maven從另外一臺機器來訪問就是白搭報出來就是Connection refused。驗證方式是在開發(fā)機上執(zhí)行telnet 192.168.1.100 8081能通的話說明Nexus對遠程訪問是開放的。不通的話登錄服務器再執(zhí)行一次ss -lntp | grep 8081看看監(jiān)聽地址是0.0.0.0:8081、*:8081還是具體的局域網(wǎng)IP。如果是127.0.0.1:8081說明配置把綁定地址限制在回環(huán)接口上了。這時候可以到安裝目錄下檢查etc/nexus.properties或者啟動時追加的JVM參數(shù)把application-host的值改成0.0.0.0或者在啟動命令里去掉這個限制。3.2 防火墻、安全組、容器網(wǎng)絡的排查思路Linux服務器上最常見的攔截者是iptables、firewalld或者ufw。很多服務器管理員會把默認策略設為DROP沒有顯式放行8081端口的話外部的連接請求會被靜默丟棄表現(xiàn)不是Connection refused而是timeout。如果你看到的是refused說明對方服務器對你的請求發(fā)了RST包也就是說端口可能沒監(jiān)聽但如果是timeout那大概率就是防火墻把包丟了。容器環(huán)境里還有一個額外的坑Nexus跑在某個Docker容器里容器網(wǎng)絡是bridge模式宿主機做了-p端口映射。此時從宿主機訪問沒問題但從另一臺機器訪問就要看宿主機的防火墻、云安全組是否放行了8081端口。很多人遇到的情況是開發(fā)機的telnet能通Nexus所在服務器IP的8081但是從另一臺網(wǎng)絡環(huán)境奇特的機器上就是不通最后發(fā)現(xiàn)是兩個子網(wǎng)之間的ACL規(guī)則沒放行或者云平臺安全組只允許了辦公網(wǎng)段訪問。注意即使你用Docker跑Nexus也不要忘掉容器內(nèi)部還有一層網(wǎng)絡命名空間。進入容器用docker exec -it [容器ID] curl http://localhost:8081/service/rest/v1/status可以驗證容器內(nèi)部服務本身是否正常這能幫你區(qū)分是容器服務問題還是端口映射問題。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都連不通說明問題出在網(wǎng)絡層再去糾結Maven配置沒有意義。如果telnet通但curl返回異常比如HTTP狀態(tài)碼是400或者500那就進入應用層排查看Nexus的后臺日志。還有一類罕見情況telnet能通curl也能通但mvn構建依然報Connection refused這是因為Maven在解析settings.xml或者pom.xml里的repository URL時做了變量替換實際請求的地址和你在curl里測試的地址根本不一樣。這時候要靠Maven的調(diào)試日志來定位mvn clean install -X -DskipTests日志里會打印出每個依賴下載的實際URL照著那個URL再去curl通常就能發(fā)現(xiàn)問題。4. 常見錯誤信息速查與一攬子解決方案做技術排障不能靠猜得靠“從現(xiàn)象反推原因”。這里把Maven連接Nexus時最常出現(xiàn)的幾類報錯信息整理成一張速查思路表每條列出典型報錯、可能的根因以及首選排查動作。注意這里的報錯信息只是“線索”最終診斷必須結合前文的排查流程綜合判斷。報錯現(xiàn)象關鍵詞典型根因首選排查動作Connection refused / ConnectExceptionNexus服務未啟動、端口錯誤、防火墻拒絕、監(jiān)聽地址受限登錄服務器查進程執(zhí)行 ss -lntpConnection timed out防火墻DROP策略、跨網(wǎng)段ACL攔截、服務器宕機檢查云安全組/防火墻規(guī)則ping和telnet逐步定位SSLHandshakeExceptionNexus使用的HTTPS證書過期或Maven側URL協(xié)議錯誤換成http測試或更新JDK信任庫里的證書HTTP 401 Unauthorized認證憑據(jù)缺失或服務器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后臺查看倉庫狀態(tài)嘗試重新連接遠程倉庫UnknownHostExceptionDNS解析失敗檢查hosts文件或DNS服務器配置MalformedURLExceptionURL地址中協(xié)議、端口或路徑格式錯誤檢查settings.xml中url字段是否缺少斜杠或包含非法字符4.1 Connection refused 與 timeout 的語義區(qū)別這個值得單獨拎出來講。Connection refused和Connection timeout雖然都表現(xiàn)為“連不上”但底層邏輯完全不同。Connection refused是TCP層收到了對方的RST包換句話說目標主機的網(wǎng)絡棧是通的但它告訴你“這個端口我沒法連接”通常是服務沒監(jiān)聽或者防火墻主動拒絕。Connection timeout則是發(fā)出了SYN包但一直沒等到回應多半是包被丟棄了典型場景是防火墻DROP策略、路由器ACL或者目標主機宕機。所以當你拿到報錯時第一反應應該是看“關鍵字”。我的習慣是看到refused優(yōu)先查“服務是否啟動”其次查“端口監(jiān)聽地址”最后查“防火墻是否顯式REJECT”看到timeout優(yōu)先查“網(wǎng)絡路由是否可達”其次查“云安全組”最后查“目標服務器是否宕機”4.2 401、403 等權限類錯誤的聯(lián)動排查權限類錯誤看起來和“連接被拒絕”無關但在Nexus里這兩者經(jīng)常被串在一起。最典型的場景是匿名用戶沒有任何倉庫的查看權限Nexus直接拒絕連接請求表現(xiàn)就是Maven下載依賴時連續(xù)報錯看起來像網(wǎng)絡不可達。第二次遇到類似問題時我會先打開Nexus后臺看一下對應倉庫的“Anonymous Access”是否被勾選了。在Nexus3的管理界面中Settings → Security → Anonymous Access可以控制匿名訪問而每個倉庫的Repository → Settings → Security里還有細粒度的權限控制。生產(chǎn)環(huán)境建議關閉匿名但關閉的同時必須確保所有開發(fā)機上的settings.xml都配了正確的server憑據(jù)否則所有人都會連不上那時候就別談什么“連接被拒絕”了那叫“權限管理事故”。4.3 快速檢查清單三步從報錯到定位為了不讓自己在排障時漏掉細節(jié)我給自己擬了一張“三步走”清單每次都能在十分鐘內(nèi)從報錯信息定位到根因跑一次帶調(diào)試日志的構建把-X輸出的完整報錯截圖或者復制下來重點看最底部的Caused by因為那個才是真正的異常源頭。拿報錯里的URL地址直接去telnet和curl測試服務是否真的“拒絕連接”用最小化手段復現(xiàn)不要帶著Maven的整個依賴解析流程去猜。逐項對照上面表格里的“典型根因”最可疑的候選先驗證驗證方式就是修改一處配置后重新跑一次構建能復現(xiàn)就說明沒改對不能復現(xiàn)就說明命中根因。這三步的核心思想是“剝離層次、逐級排雷”。Maven構建只是客戶端它的報錯信息本質(zhì)上就是HTTP或者網(wǎng)絡層的異常包裝把包裝拆掉底層的真相并不難找。5. 實操記錄一次完整Nexus連接故障的排查復盤前面講了一堆方法不如直接看一次真實排查過程。這個案例發(fā)生在某公司的Java微服務項目里場景是十幾臺構建機器分批執(zhí)行CI構建某天早上突然大面積失敗報錯全部是Connection refused。公司IT環(huán)境屬于內(nèi)網(wǎng)部署Nexus跑在一臺虛擬機里IP地址是192.168.10.20端口8081構建機的Maven配置了統(tǒng)一的settings.xml鏡像指向它。5.1 從報錯到定位分段排查的完整邏輯當天早上故障一報出來我先看的是CI日志連續(xù)翻了十幾個都是同一個錯誤——Could not transfer artifact ... Connection refused。第一反應是Nexus服務掛了。于是登錄192.168.10.20服務器執(zhí)行ps -ef | grep nexus進程存在但再執(zhí)行ss -lntp | grep 8081發(fā)現(xiàn)8081端口根本沒有監(jiān)聽。當時心里“咯噔”一下因為進程在但端口沒綁定這通常意味著Nexus啟動到一半卡住了。緊接著看了日志文件發(fā)現(xiàn)最后的記錄是ES索引初始化失敗導致整個應用無法完成啟動流程Nexus進程雖然在跑但JVM內(nèi)部并沒進入可用狀態(tài)。處理完索引問題重啟Nexus端口正常監(jiān)聽了。但CI重跑依然有部分機器報Connection refused。這時候我卻注意到報錯機器和正常機器之間的差異——報錯的都是最近新擴容的構建機正常的都是老機器。再一查發(fā)現(xiàn)新構建機上的settings.xml是從另一個團隊倉庫里拷來的鏡像URL寫的是http://192.168.10.21:8081/repository/maven-public/把地址寫錯了。高可用方案里Nexus有第二個節(jié)點新機器配置寫的是故障節(jié)點的IP而故障節(jié)點已經(jīng)下線了。只改掉這一處配置后全部構建恢復。這次排查其實踩了一個很典型的“思維定式”坑第一輪看到連接被拒絕我的注意力全在服務狀態(tài)上等確認服務正常后沒有再重新審視“報錯的都是哪些機器、它們和正常機器有什么區(qū)別”。如果把機器分組和配置差異核查提前到第二位至少能省出一輪CI重跑的等待時間。5.2 故障加固建議日志、監(jiān)控與公共配置在排查修復之后我還給團隊做了三件事防止類似問題再次造成大面積故障。第一給Nexus的啟動和運行狀態(tài)做基礎監(jiān)控不需要很復雜的系統(tǒng)只要能每分鐘探測一次/service/rest/v1/status接口并告警就行。第二修改統(tǒng)一分發(fā)settings.xml的方式不再允許各項目組自己復制粘貼配置而是走配置中心統(tǒng)一管理鏡像地址、server憑據(jù)全部做好版本控制。第三在構建腳本里把Maven的調(diào)試日志默認打開一份輸出到固定目錄以后再有連接類報錯別問開發(fā)同學“報什么錯”直接讓他們把日志文件發(fā)過來手工定位的時間至少縮短一半。這套“監(jiān)測配置治理日志留存”的組合拳雖然不是解決“連接被拒絕”的直接操作但屬于事后避免同樣問題再次發(fā)生的有效手段。真正負責Nexus或者CI基礎設施的同學我建議也照著這套思路做不然就算今天把問題修好了下周換一批機器、換一個網(wǎng)段同樣的坑還會再踩一遍。寫在最后我個人在實際排查Nexus連接被拒這類問題時逐漸養(yǎng)成了一個強迫癥永遠先問“服務在哪、監(jiān)聽在哪、通不通”再問“配置寫了什么、憑據(jù)對不對”最后才去懷疑代碼和構建流程本身。這里有一個不太容易從官方文檔里學到的經(jīng)驗——用mvn -X輸出來定位連接問題時請同時關注Maven解析配置的“順序”和“結果”因為有多套鏡像、多個repository存在的時候Maven到底走了哪條路徑往往比報錯內(nèi)容本身更能暴露問題。以后再遇到Connection refused希望你第一反應不是煩躁而是把這篇手冊里的速查表對照一遍。大部分場景下問題都能在十分鐘內(nèi)水落石出。