雅停機(jī)實(shí)戰(zhàn)：從SIGTERM到K8s滾動(dòng)發(fā)布全解析)
凌晨十二點(diǎn)盯著發(fā)布流水線一條kill -15發(fā)下去業(yè)務(wù)群里瞬間冒出好幾條“接口報(bào)錯(cuò)了”“剛才提交的訂單沒返回”。這個(gè)場(chǎng)景是我對(duì) SpringBoot 停機(jī)機(jī)制最初的記憶。默認(rèn)情況下SpringBoot 收到 SIGTERM 并不代表它會(huì)等手頭的事干完而是“幾乎立刻”把 Web 容器和 Spring 容器拆掉所有在途請(qǐng)求直接被 Reset。SpringBoot 優(yōu)雅停機(jī)機(jī)制是解決這類問題的標(biāo)準(zhǔn)方案它從 Spring Boot 2.3 開始由官方原生支持。這篇文章我會(huì)帶你搞清楚優(yōu)雅停機(jī)到底在哪一層生效、兩行配置背后發(fā)生了什么事、實(shí)測(cè)中請(qǐng)求表現(xiàn)差多少、以及真正上線時(shí)最容易忽略的注冊(cè)中心和容器編排坑。適合正在做服務(wù)發(fā)布、彈性伸縮、壓測(cè)驗(yàn)證的 Java 開發(fā)者收藏。1. 從最慘的一次發(fā)布事故說起默認(rèn)停機(jī)到底停掉了什么1.1 kill -15 并不溫柔JVM 鉤子與 Web 容器的同步關(guān)閉很多人有個(gè)誤解以為給 Java 進(jìn)程發(fā)kill -15SIGTERM之后JVM 會(huì)“把當(dāng)前請(qǐng)求處理完再退出”。這個(gè)說法只說對(duì)了一半。JVM 確實(shí)會(huì)執(zhí)行 ShutdownHookSpring Boot 也注冊(cè)了自己的SpringApplicationShutdownHook但問題在于默認(rèn)停機(jī)模式下Spring 容器關(guān)閉 WebServer 時(shí)并不會(huì)等待活躍請(qǐng)求。你可以把那次事故的現(xiàn)場(chǎng)還原一下。Tomcat 收到 stop 指令后Connector 直接進(jìn)入關(guān)閉流程還在執(zhí)行中的 Servlet 線程會(huì)被打斷正在讀取響應(yīng)體的 Nginx 突然收到一個(gè)空的 FIN 包客戶端表現(xiàn)就是 Connection reset by peer。如果你在寫訂單接口可能已經(jīng)完成了數(shù)據(jù)庫事務(wù)提交但響應(yīng)沒送到客戶端調(diào)用方就會(huì)選擇重試于是重復(fù)下單、重復(fù)扣庫存、對(duì)賬不平全都來了。1.2 粗暴關(guān)停的典型故障清單這類問題在線上有非常固定的模式我整理了一張表基本覆蓋了絕大部分事故場(chǎng)景故障現(xiàn)象真實(shí)原因涉及模塊客戶端提示 Connection resetTomcat 在請(qǐng)求進(jìn)行中直接關(guān)閉連接Web 容器下游收到 502/504Nginx 在 Upstream 節(jié)點(diǎn)關(guān)閉瞬間轉(zhuǎn)發(fā)請(qǐng)求失敗負(fù)載均衡消息重復(fù)消費(fèi)消費(fèi)到一半進(jìn)程退出offset 未提交Kafka/RocketMQ事務(wù)已提交但響應(yīng)丟失業(yè)務(wù)邏輯完成響應(yīng)未寫回客戶端Servlet 線程定時(shí)任務(wù)重復(fù)執(zhí)行集群多實(shí)例同時(shí)停機(jī)任務(wù)調(diào)度沒做搶占任務(wù)調(diào)度注冊(cè)中心出現(xiàn)異常實(shí)例服務(wù)端進(jìn)程已死但心跳還沒過期Eureka/Nacos這些故障有個(gè)共同點(diǎn)都不是代碼邏輯錯(cuò)誤而是進(jìn)程退出順序問題。業(yè)務(wù)代碼跑得好好的純粹因?yàn)橥C(jī)姿勢(shì)不對(duì)把“正常完成的請(qǐng)求”變成“客戶端感知到的失敗請(qǐng)求”這才是最虧的。1.3 先分清三個(gè)概念JVM ShutdownHook、Actuator Shutdown 與優(yōu)雅停機(jī)網(wǎng)上搜“SpringBoot 優(yōu)雅停機(jī)”經(jīng)?？吹絻煞N做法混在一起容易踩坑。第一種是 JVM 層面的 ShutdownHook代碼里Runtime.getRuntime().addShutdownHook(new Thread(...))它只保證“JVM 退出時(shí)我能執(zhí)行一段代碼”但改變不了 Web 容器已經(jīng)在關(guān)閉的事實(shí)。你用這個(gè)方式做“通知注冊(cè)中心摘流”因?yàn)轫樞虿粚?duì)往往還沒來得及發(fā)請(qǐng)求容器已經(jīng)斷了。第二種是 Actuator 的/actuator/shutdown端點(diǎn)需要手動(dòng)打開并 POST 觸發(fā)。它本質(zhì)上也是觸發(fā)ApplicationContext.close()在 Spring Boot 2.3 之前它是實(shí)現(xiàn)“相對(duì)優(yōu)雅”停機(jī)的主要手段因?yàn)槟憧梢钥刂朴|發(fā)時(shí)機(jī)不讓它依賴操作系統(tǒng)信號(hào)。第三種才是真正的“優(yōu)雅停機(jī)Graceful Shutdown”也就是從 2.3 開始官方內(nèi)置的能力。它做的事情很明確先停止接收新請(qǐng)求然后等待所有在途請(qǐng)求處理完成或超時(shí)最后再關(guān)閉 WebServer 和 Spring 容器。后面我會(huì)從配置開始完整拆解。2. 先別急著加配置版本、容器與兩行核心參數(shù)的前置判斷2.1 Spring Boot 版本是分水嶺低于 2.3 就沒有原生方案Spring Boot 2.3.0.RELEASE 的 Release Notes 明確寫了為內(nèi)嵌 Web 服務(wù)器增加優(yōu)雅停機(jī)支持。所以如果你項(xiàng)目還在 2.1、2.2對(duì)不起server.shutdowngraceful這個(gè)配置是無效的日志里連個(gè)警告都不會(huì)有。我見過有人把server.shutdowngraceful加到 2.2 項(xiàng)目上發(fā)版之后以為萬事大吉結(jié)果壓測(cè)一打就露餡。所以第一步永遠(yuǎn)是看pom.xml里的父版本parent groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-parent/artifactId version2.7.18/version relativePath/ /parent如果你日常用的是 Spring Boot 3.x那當(dāng)然更沒問題這套機(jī)制一直延續(xù)下來了。如果是老項(xiàng)目暫時(shí)升不動(dòng)版本至少要做到給負(fù)載均衡或注冊(cè)中心留出摘流時(shí)間再手動(dòng)觸發(fā)/actuator/shutdown不要裸著發(fā) SIGTERM。2.2 核心配置只有兩行但第二行含義經(jīng)常被讀錯(cuò)在application.properties或 yaml里加上server.shutdowngraceful spring.lifecycle.timeout-per-shutdown-phase30s第一行很簡單把默認(rèn)的immediate改成graceful告訴 Spring Boot 走優(yōu)雅停機(jī)流程。第二行spring.lifecycle.timeout-per-shutdown-phase寫的默認(rèn)值是 30s。注意關(guān)鍵詞是per-shutdown-phase也就是“每個(gè)關(guān)閉階段”的超時(shí)時(shí)間不是“整個(gè)停機(jī)過程”的總超時(shí)。Spring 容器里不同 Lifecycle 組件按 phase 分批關(guān)閉理論上有幾個(gè) phase就可能累加幾個(gè) 30s。這一點(diǎn)后面講事件鏈的時(shí)候還會(huì)展開先記住不要把它理解成“最多等 30 秒就強(qiáng)制退出”。2.3 官方支持矩陣四個(gè)內(nèi)嵌容器全都支持但成熟度有差異Spring Boot 官方文檔對(duì)優(yōu)雅停機(jī)的描述是支持所有四個(gè)內(nèi)嵌 Web 服務(wù)器Tomcat、Jetty、Reactor Netty、UndertowServlet 和響應(yīng)式應(yīng)用都可以。但做底層適配的人都知道一個(gè)能力“支持”和“支持得好”是兩回事。Tomcat 的實(shí)現(xiàn)最完整從 9.0.33 開始提供了相對(duì)成熟的 Connector pause 線程池等待機(jī)制Jetty 和 Reactor Netty 也能做到“停止接收新請(qǐng)求等待在途請(qǐng)求完成”Undertow 也能用但我在網(wǎng)上見過一些版本差異導(dǎo)致的邊界問題如果你不是必須用 Undertow建議在生產(chǎn)環(huán)境優(yōu)先用 Tomcat省心。容器是否支持實(shí)際表現(xiàn)Tomcat 9.0.33完整支持pause Connector等待線程池任務(wù)完成日志清晰Jetty 9.4支持等待在途請(qǐng)求但部分版本需要額外注意連接超時(shí)Reactor Netty支持WebFlux 場(chǎng)景可用2.3 起支持等待事件循環(huán)中請(qǐng)求Undertow支持能用但社區(qū)反饋的邊界問題相對(duì)多2.4 開啟前檢查下自己的環(huán)境這里給一個(gè)快速自查清單照著過一遍再上線項(xiàng)目spring-boot-starter-web或spring-boot-starter-webflux版本是否 ≥ 2.3。是否使用內(nèi)嵌容器如果打成 war 丟外置 Tomcat這套配置不直接生效。確認(rèn)停機(jī)時(shí)是kill -15或docker stop、systemctl stop觸發(fā)而不是kill -9。有沒有在代碼里自定義 ShutdownHook如果自定義 Hook 里做了“等待 xx 秒”之類的邏輯要測(cè)試它與 Spring 優(yōu)雅停機(jī)的先后順序別讓兩段等待互相打架。3. 停機(jī)時(shí)到底在等什么SIGTERM 到容器關(guān)閉的完整事件鏈3.1 事件鏈路拆解SIGTERM → JVM Hook → Spring 容器關(guān)閉優(yōu)雅停機(jī)不是魔法它只是在正確的位置插入了等待邏輯。進(jìn)程收到kill -15后JVM 開始執(zhí)行已注冊(cè)的 ShutdownHook。Spring Boot 的SpringApplicationShutdownHook在這個(gè)時(shí)機(jī)被觸發(fā)它會(huì)調(diào)用ApplicationContext.close()。close()內(nèi)部會(huì)先觸發(fā)ContextClosedEvent然后通過DefaultLifecycleProcessor去 stop 所有 Lifecycle 組件。關(guān)鍵就在這里Spring Boot 把內(nèi)嵌 WebServer 的優(yōu)雅停機(jī)封裝成了一個(gè)SmartLifecycle它會(huì)在 Spring 容器關(guān)閉時(shí)先執(zhí)行。這個(gè) Lifecycle 做的事是設(shè)置 Server 不再接收新請(qǐng)求Tomcat 表現(xiàn)為停止 accept 新連接。等待活躍請(qǐng)求執(zhí)行完成。超過timeout-per-shutdown-phase的請(qǐng)求不再等待直接強(qiáng)制關(guān)閉。等它結(jié)束后WebServer 才真正銷毀Spring Bean 才開始挨個(gè)銷毀。這條鏈路保證了“先等業(yè)務(wù)收完尾再拆房子”。3.2 三層等待容器層、線程池層、業(yè)務(wù)資源層實(shí)際等的東西可以分成三層看。第一層是 Web 容器層。Tomcat 的 Connector 進(jìn)入 paused 狀態(tài)后不再 accept 新連接但已經(jīng)建立連接上正在執(zhí)行請(qǐng)求的線程不會(huì)被打斷。第二層是線程池層。Tomcat 內(nèi)部維護(hù)了一個(gè)執(zhí)行 Servlet 的工作線程池優(yōu)雅停機(jī)時(shí)它會(huì)等線程池里所有任務(wù)執(zhí)行完。如果你的某個(gè)接口里定義了 10 秒Thread.sleep它就是這里被等的重點(diǎn)對(duì)象。第三層是業(yè)務(wù)資源層。Spring 容器真正 close 時(shí)HikariCP 數(shù)據(jù)源、消息連接池這些 Bean 才開始逐個(gè)關(guān)閉。HikariCP 關(guān)閉時(shí)也會(huì)等待租出去的連接歸還。這就是為什么“Web 容器等待”和“數(shù)據(jù)源等待”是兩個(gè)不同的時(shí)間窗口別只用接口耗時(shí)去預(yù)算停機(jī)總時(shí)長。3.3 為什么日志里只見 “Commencing graceful shutdown” 卻遲遲不結(jié)束開啟優(yōu)雅停機(jī)后收到 SIGTERM控制臺(tái)會(huì)輸出類似這樣的日志o.s.b.w.e.tomcat.GracefulShutdown : Commencing graceful shutdown. Waiting for active requests to complete很多第一次接優(yōu)雅停機(jī)的人看到這行日志然后發(fā)現(xiàn)進(jìn)程遲遲不退會(huì)慌。其實(shí)這是正?，F(xiàn)象。它正在等待在途請(qǐng)求。等所有請(qǐng)求處理完會(huì)看到o.s.b.w.e.tomcat.GracefulShutdown : Graceful shutdown complete之后 Spring 容器繼續(xù)關(guān)閉剩下的 Bean。整個(gè)停機(jī)的標(biāo)準(zhǔn)日志順序應(yīng)該是Commencing graceful shutdown. Waiting for active requests to complete 這里停頓時(shí)間取決于在途請(qǐng)求 Graceful shutdown complete Closing org.springframework.context.annotation.AnnotationConfigApplicationContext ...如果你始終看不到第二行日志大概率是某個(gè)請(qǐng)求永遠(yuǎn)不返回比如 WebSocket 連接、SSE 長連接、卡死的任務(wù)最后只能等超時(shí)被強(qiáng)制切斷。這也是生產(chǎn)環(huán)境最容易出問題的點(diǎn)看似在“優(yōu)雅等待”實(shí)際在“無限等待”。3.4 timeout-per-shutdown-phase 的真實(shí)累計(jì)邏輯前面說了這個(gè)參數(shù)是“每階段超時(shí)”。Spring 的DefaultLifecycleProcessor會(huì)把所有 Lifecycle 分組每個(gè) phase 單獨(dú)計(jì)時(shí)。如果你既用了 WebServer 的優(yōu)雅停機(jī)又自定義了幾個(gè) SmartLifecycle還接了消息監(jiān)聽容器等等那總停機(jī)時(shí)間可能超過 30s。舉個(gè)實(shí)際例子phase 大的 Lifecycle 先關(guān)閉如果它在 30s 內(nèi)沒結(jié)束后面哪怕還有很多 Bean 沒關(guān)也會(huì)被強(qiáng)制打斷繼續(xù)往下走。所以設(shè)置這個(gè)參數(shù)時(shí)最好把你業(yè)務(wù)里“最長的一個(gè)慢請(qǐng)求耗時(shí) 數(shù)據(jù)源連接歸還時(shí)間 自定義清理時(shí)間”都估算進(jìn)去。寧愿給 60s也不要卡在 30s 邊緣。4. 用壓測(cè)說話優(yōu)雅停機(jī)前后的請(qǐng)求行為對(duì)比4.1 測(cè)試環(huán)境與壓測(cè)準(zhǔn)備配置說再多不如自己跑一輪壓測(cè)直觀。下面是我在本地搭的一組最小驗(yàn)證環(huán)境Spring Boot 2.7 項(xiàng)目 Tomcat一個(gè)慢接口模擬“在處理中的業(yè)務(wù)”。RestController public class GracefulController { GetMapping(/slow) public String slow() throws InterruptedException { System.out.println(請(qǐng)求進(jìn)入 Thread.currentThread().getName() 時(shí)間 System.currentTimeMillis()); TimeUnit.SECONDS.sleep(10); System.out.println(請(qǐng)求完成 Thread.currentThread().getName() 時(shí)間 System.currentTimeMillis()); return ok; } }壓測(cè)用 ab 就夠了不用上 JMeterab -n 500 -c 50 http://127.0.0.1:8080/slow這個(gè)命令的意思是總共 500 個(gè)請(qǐng)求50 并發(fā)每個(gè)請(qǐng)求都要花 10 秒。按下命令后間隔幾秒再開一個(gè)終端執(zhí)行kill -15 $(jps | grep -i app | awk {print $1})然后觀察 ab 的統(tǒng)計(jì)結(jié)果和控制臺(tái)日志。4.2 未開啟優(yōu)雅停機(jī)kill 之后響應(yīng)直接被掐斷先把server.shutdowngraceful注釋掉用默認(rèn)的immediate跑一輪。kill 之后控制臺(tái)立刻開始關(guān)閉容器正在執(zhí)行的接口線程直接被中斷。ab 端的表現(xiàn)非常明顯大量Failed requests。客戶端側(cè)報(bào)Connection reset by peer。不管接口邏輯后面還有沒有收尾工作一律不執(zhí)行。最終輸出的Complete requests遠(yuǎn)小于 500。我在實(shí)際壓測(cè)中看到過更夸張的情況有些請(qǐng)求已經(jīng)進(jìn)入 Tomcat 工作線程但還沒來得及打印“請(qǐng)求進(jìn)入”進(jìn)程就關(guān)了。這類請(qǐng)求就是“連業(yè)務(wù)代碼都沒跑完就被掐斷”的典型。4.3 開啟優(yōu)雅停機(jī)新請(qǐng)求被拒絕在途請(qǐng)求正常收尾然后把兩行配置加上重新啟動(dòng)并壓測(cè)。中途 kill -15重點(diǎn)關(guān)注幾個(gè)表現(xiàn)第一控制臺(tái)輸出Commencing graceful shutdown之后原本已經(jīng)在跑的接口線程繼續(xù)打印“請(qǐng)求完成”沒有中斷異常。第二ab 的Complete requests和Failed requests不再難看。已經(jīng)進(jìn)入 Tomcat 的請(qǐng)求基本都能正常拿到響應(yīng)。第三停機(jī)期間新進(jìn)來的請(qǐng)求會(huì)失敗因?yàn)槿萜饕呀?jīng)不再 accept。你會(huì)在 Tomcat 日志里看到連接被拒絕的痕跡這是預(yù)期行為。所以優(yōu)雅停機(jī)的核心價(jià)值不是“所有請(qǐng)求都不失敗”而是“已經(jīng)進(jìn)入的請(qǐng)求別被半路打死”。至于新請(qǐng)求本來就應(yīng)該靠前面的負(fù)載均衡摘流解決這屬于第 5 章要討論的問題。4.4 超時(shí)場(chǎng)景超過等待上限的請(qǐng)求最終怎么收?qǐng)鲈衮?yàn)證一個(gè)邊界如果請(qǐng)求耗時(shí)超過timeout-per-shutdown-phase會(huì)怎樣把spring.lifecycle.timeout-per-shutdown-phase改成3s然后接口 sleep 10 秒壓測(cè)中途 kill。你會(huì)發(fā)現(xiàn)3 秒之后日志里出現(xiàn)容器強(qiáng)制關(guān)閉的動(dòng)作。那個(gè)還在 sleep 的請(qǐng)求被中斷客戶端同樣會(huì)收到連接重置。所以優(yōu)雅停機(jī)不是“無限等”它是有上限的。上限到了該斷還是斷。這個(gè)測(cè)試特別適合用來跟業(yè)務(wù)方對(duì)齊預(yù)期停機(jī)窗口內(nèi)新請(qǐng)求會(huì)失敗超長請(qǐng)求會(huì)失敗只有“正常長度”的在途請(qǐng)求能被保護(hù)。4.5 生產(chǎn)視角看待壓測(cè)結(jié)果跑完這些對(duì)比我建議把結(jié)論寫進(jìn)發(fā)布手冊(cè)發(fā)布前先確認(rèn) Kafka 消費(fèi)位移、消息推送、文件上傳這類長任務(wù)耗時(shí)不超預(yù)算。壓測(cè)結(jié)論要讓運(yùn)維、QA、后端三方都看到別只停留在“我這邊加了配置”。把壓測(cè)中的Graceful shutdown complete日志出現(xiàn)時(shí)間點(diǎn)記錄下來作為每次發(fā)布前的參考基線。5. 單機(jī)優(yōu)雅不解決流量分配注冊(cè)中心、Nginx、Docker 和 K8s 的配合5.1 最容易被忽視的坑負(fù)載均衡還在往停機(jī)節(jié)點(diǎn)甩流量單機(jī)優(yōu)雅停機(jī)只解決“請(qǐng)求已經(jīng)進(jìn)來了”的情況。但發(fā)布的時(shí)候前面掛的 Nginx、Gateway、注冊(cè)中心客戶端并不知道這個(gè)節(jié)點(diǎn)正在停機(jī)它們?nèi)詴?huì)把新請(qǐng)求轉(zhuǎn)發(fā)過來。這個(gè)瞬間連接被拒、超時(shí)、報(bào)錯(cuò)還是會(huì)重演。我見過一個(gè)團(tuán)隊(duì)做出來的停機(jī)順序是反的先 kill 進(jìn)程等容器優(yōu)雅停完了再去 Nginx 摘節(jié)點(diǎn)。摘流事件發(fā)生在進(jìn)程死亡之后前面的用戶流量已經(jīng)遭殃了。正確的順序應(yīng)該是先摘流再停機(jī)。摘流手段根據(jù)你的流量入口不同有幾種做法下面分開說。5.2 手動(dòng)摘流Nginx、Eureka、Nacos、Consul 分別怎么處理如果你們上游是 Nginx最直接的健康檢查方案是Spring Boot 暴露一個(gè)健康檢查接口停機(jī)前先把該接口狀態(tài)改成 DOWNNginx 通過max_fails或主動(dòng)健康檢查摘掉這個(gè) upstream 節(jié)點(diǎn)。比較粗暴但有效的做法是在停機(jī)前用腳本調(diào) Nginx 接口直接標(biāo)記 down。如果用的是注冊(cè)中心更標(biāo)準(zhǔn)化的做法是調(diào)用服務(wù)治理 API 提前反注冊(cè)注冊(cè)中心摘流方式說明Nacosnacos-client的deregisterInstance主動(dòng)摘除后客戶端拉取新列表需要時(shí)間Eureka發(fā)心跳把狀態(tài)置為 OUT_OF_SERVICE配合 eureka 客戶端緩存刷新Consul服務(wù)實(shí)例標(biāo)記為 maintenance 或反注冊(cè)同樣存在傳播延遲無論哪種方式都要記住一個(gè)現(xiàn)實(shí)注冊(cè)中心的摘流是異步傳播的客戶端可能存在緩存延遲。所以不要“反注冊(cè)完立刻殺進(jìn)程”要留一個(gè)緩沖窗口比如再等 5~10 秒等流量真的淡出再停。5.3 Docker stop 的 10 秒絞刑默認(rèn) STOP_TIMEOUT 與 30 秒優(yōu)雅超時(shí)的沖突這塊是網(wǎng)上抱怨最多、也最隱蔽的坑。用 Docker 跑 SpringBoot 時(shí)docker stop默認(rèn)只等 10 秒超過 10 秒直接SIGKILL?？墒莝pring.lifecycle.timeout-per-shutdown-phase默認(rèn)是 30s。如果你的停機(jī)時(shí)間超過 10sDocker 會(huì)毫不客氣地把進(jìn)程干掉優(yōu)雅停機(jī)形同虛設(shè)。解決辦法有三個(gè)# 運(yùn)行時(shí)指定 docker run --stop-timeout 60 your-image # compose 文件 services: app: stop_grace_period: 60s# 更推薦的還是在 Dockerfile 里明確信號(hào) STOPSIGNAL SIGTERM注意這行STOPSIGNAL SIGTERM有些基礎(chǔ)鏡像或啟動(dòng)腳本會(huì)對(duì)信號(hào)做二次轉(zhuǎn)發(fā)如果默認(rèn)不是SIGTERM優(yōu)雅停機(jī)可能根本沒被觸發(fā)。Dockerfile 里寫清楚就沒有這個(gè)歧義。5.4 Kubernetes 滾動(dòng)發(fā)布readiness 探針與 preStop 的最佳姿勢(shì)K8s 場(chǎng)景跟 Docker 又不一樣因?yàn)?K8s 控制的是 Pod 生命周期它默認(rèn)給了terminationGracePeriodSeconds: 30s這個(gè)窗口要大于你預(yù)估的優(yōu)雅停機(jī)時(shí)間。推薦的做法是用 readiness 探針配合 preStop hookspec: terminationGracePeriodSeconds: 60 containers: - name: app readinessProbe: httpGet: path: /actuator/health/readiness port: 8080 initialDelaySeconds: 10 periodSeconds: 5 lifecycle: preStop: exec: command: [/bin/sh, -c, sleep 5]這里面的邏輯是K8s 在停止 Pod 前會(huì)先把該 Pod 從 Service Endpoint 中摘掉但摘掉動(dòng)作的生效也要時(shí)間preStop里 sleep 幾秒等于給了 K8s 一個(gè)緩沖。sleep 結(jié)束K8s 才發(fā) SIGTERM此時(shí)流量已經(jīng)基本不來了Spring Boot 才開始優(yōu)雅停機(jī)。這樣組合起來才能真正做到“先摘流再等請(qǐng)求最后殺進(jìn)程”。5.5 多實(shí)例同時(shí)停機(jī)的雪崩問題分批發(fā)布最后一個(gè)集群層面的坑如果你有多個(gè)實(shí)例發(fā)布系統(tǒng)把實(shí)例 A、B、C 同時(shí) kill那它們同時(shí)在優(yōu)雅停機(jī)同時(shí)在等各自的重請(qǐng)求完成。等它們?nèi)恐貑⑼曛虚g出現(xiàn)的空閑窗口可能直接把整個(gè)服務(wù)的容量打穿。穩(wěn)妥做法是分批發(fā)布先把流量摘掉一部分停一個(gè)、起一個(gè)。滾動(dòng)發(fā)布有天然的順序但如果你是自己寫腳本發(fā)布一定要手動(dòng)控制并發(fā)數(shù)。這個(gè)經(jīng)驗(yàn)我在線上吃過虧優(yōu)雅停機(jī)修好了“單機(jī)請(qǐng)求被掐斷”卻差點(diǎn)因?yàn)椤叭繉?shí)例同時(shí)停機(jī)”導(dǎo)致服務(wù)不可用。6. 給業(yè)務(wù)留足收尾時(shí)間事件監(jiān)聽、Lifecycle 順序與上線檢查清單6.1 ContextClosedEvent別在 Web 容器停止后再做異步收尾優(yōu)雅停機(jī)等于給了你一個(gè)“業(yè)務(wù)收尾”的時(shí)間窗口。但很多團(tuán)隊(duì)把收尾邏輯寫在PreDestroy或自定義 ShutdownHook 里順序非常不可控。更可控的方式是監(jiān)聽ContextClosedEvent。這個(gè)事件在 Spring 容器開始關(guān)閉時(shí)發(fā)出此時(shí) Bean 還都活著你可以在這時(shí)候通知消息隊(duì)列暫停消費(fèi)、把服務(wù)狀態(tài)標(biāo)記為“停止接收流量”、保存內(nèi)存中的批次數(shù)據(jù)等。Component public class ShutdownListener { EventListener(ContextClosedEvent.class) public void onShutdown(ContextClosedEvent event) { // 1. 暫停消息消費(fèi) // 2. 觸發(fā)緩存刷新或持久化 // 3. 標(biāo)記健康檢查為 DOWN System.out.println(容器開始關(guān)閉執(zhí)行業(yè)務(wù)收尾); } }但要注意這個(gè)回調(diào)里不要做耗時(shí)太長的操作它會(huì)被計(jì)入整個(gè)關(guān)閉流程超時(shí)一樣會(huì)被強(qiáng)殺。6.2 SmartLifecycle 與 phase 控制注冊(cè)中心為什么必須放在高 phase如果你需要在 Web 容器停止之前就把注冊(cè)中心摘掉更規(guī)范的做法是實(shí)現(xiàn)SmartLifecycle并給一個(gè)較大的 phase。Spring 的規(guī)則是停止時(shí)數(shù)字越大越先關(guān)閉。所以摘流邏輯應(yīng)該用 Integer.MAX_VALUE 附近的 phase確保它排在 WebServer 優(yōu)雅停機(jī)之前。Component public class DeregisterLifecycle implements SmartLifecycle { private volatile boolean running; Override public void start() { this.running true; } Override public void stop() { // 在這里調(diào)用 Nacos / Eureka / Consul 摘流 System.out.println(先從注冊(cè)中心摘除實(shí)例); this.running false; } Override public boolean isRunning() { return this.running; } Override public int getPhase() { return Integer.MAX_VALUE; } }這個(gè)模式比在ContextClosedEvent里寫更嚴(yán)謹(jǐn)因?yàn)樗?Spring 的關(guān)閉順序是同一套機(jī)制不用擔(dān)心某個(gè) Bean 提前銷毀導(dǎo)致調(diào)用失敗。不過也要注意摘流后必須在注冊(cè)中心傳播延遲里再拖幾秒所以我一般會(huì)在stop()里加一個(gè)輕量 sleep別一摘完就立刻進(jìn)入下一步。6.3 定時(shí)任務(wù)、線程池、數(shù)據(jù)庫連接池在停機(jī)期的真實(shí)表現(xiàn)如果你項(xiàng)目里有Scheduled定時(shí)任務(wù)默認(rèn)情況下它們跑在單線程調(diào)度器里。優(yōu)雅停機(jī)過程中這些任務(wù)不會(huì)自動(dòng)取消如果某個(gè)任務(wù)正在刷新緩存或跑批量任務(wù)它也會(huì)被容器關(guān)閉打斷。我的建議是給這些異步任務(wù)顯式指定一個(gè)線程池并在關(guān)閉時(shí)主動(dòng) shutdown。這樣能保證優(yōu)雅停機(jī)時(shí)任務(wù)執(zhí)行到安全邊界才退出。數(shù)據(jù)庫連接池這塊HikariCP 在容器關(guān)閉時(shí)會(huì)等待租借出去的連接歸還但默認(rèn)的等待時(shí)間并不長。如果某個(gè)慢 SQL 在停機(jī)瞬間還沒跑完Hikari 的連接會(huì)被強(qiáng)制釋放事務(wù)可能回滾。所以你真正要評(píng)估的是“業(yè)務(wù)慢請(qǐng)求的最差耗時(shí)”而不是平均值。6.4 上線前照著抄的停機(jī)檢查清單最后給一份可以直接抄進(jìn)發(fā)布手冊(cè)的檢查清單確認(rèn) Spring Boot ≥ 2.3配置了server.shutdowngraceful且把timeout-per-shutdown-phase按最壞情況調(diào)大。用kill -15壓測(cè)一次確認(rèn)出現(xiàn)Commencing graceful shutdown和Graceful shutdown complete兩行日志。Docker 場(chǎng)景檢查stop-timeout或stop_grace_periodK8s 場(chǎng)景檢查terminationGracePeriodSeconds與 preStop。確認(rèn)注冊(cè)中心摘流在進(jìn)程退出前完成并留了緩沖時(shí)間。明確新請(qǐng)求在停機(jī)窗口內(nèi)注定會(huì)失敗由負(fù)載均衡/網(wǎng)關(guān)做兜底。針對(duì)長連接和長期占用線程的請(qǐng)求WebSocket、SSE、文件上傳單獨(dú)確認(rèn)超時(shí)策略。我個(gè)人的體會(huì)是優(yōu)雅停機(jī)不是一個(gè)讓“所有請(qǐng)求零失敗”的方案它是一個(gè)讓“該成功的請(qǐng)求能成功”的方案。真正要啃的硬骨頭在停機(jī)前的那幾步流量調(diào)度上。把代碼里的等待時(shí)間、容器參數(shù)里的超時(shí)時(shí)間、K8s 里的優(yōu)雅終止時(shí)間這三件事對(duì)齊線上發(fā)布才算真的穩(wěn)健。 SpringBoot優(yōu)雅停機(jī)實(shí)戰(zhàn)：從SIGTERM到K8s滾動(dòng)發(fā)布全解析
凌晨十二點(diǎn)盯著發(fā)布流水線一條kill -15發(fā)下去業(yè)務(wù)群里瞬間冒出好幾條“接口報(bào)錯(cuò)了”“剛才提交的訂單沒返回”。這個(gè)場(chǎng)景是我對(duì) SpringBoot 停機(jī)機(jī)制最初的記憶。默認(rèn)情況下SpringBoot 收到 SIGTERM 并不代表它會(huì)等手頭的事干完而是“幾乎立刻”把 Web 容器和 Spring 容器拆掉所有在途請(qǐng)求直接被 Reset。SpringBoot 優(yōu)雅停機(jī)機(jī)制是解決這類問題的標(biāo)準(zhǔn)方案它從 Spring Boot 2.3 開始由官方原生支持。這篇文章我會(huì)帶你搞清楚優(yōu)雅停機(jī)到底在哪一層生效、兩行配置背后發(fā)生了什么事、實(shí)測(cè)中請(qǐng)求表現(xiàn)差多少、以及真正上線時(shí)最容易忽略的注冊(cè)中心和容器編排坑。適合正在做服務(wù)發(fā)布、彈性伸縮、壓測(cè)驗(yàn)證的 Java 開發(fā)者收藏。1. 從最慘的一次發(fā)布事故說起默認(rèn)停機(jī)到底停掉了什么1.1 kill -15 并不溫柔JVM 鉤子與 Web 容器的同步關(guān)閉很多人有個(gè)誤解以為給 Java 進(jìn)程發(fā)kill -15SIGTERM之后JVM 會(huì)“把當(dāng)前請(qǐng)求處理完再退出”。這個(gè)說法只說對(duì)了一半。JVM 確實(shí)會(huì)執(zhí)行 ShutdownHookSpring Boot 也注冊(cè)了自己的SpringApplicationShutdownHook但問題在于默認(rèn)停機(jī)模式下Spring 容器關(guān)閉 WebServer 時(shí)并不會(huì)等待活躍請(qǐng)求。你可以把那次事故的現(xiàn)場(chǎng)還原一下。Tomcat 收到 stop 指令后Connector 直接進(jìn)入關(guān)閉流程還在執(zhí)行中的 Servlet 線程會(huì)被打斷正在讀取響應(yīng)體的 Nginx 突然收到一個(gè)空的 FIN 包客戶端表現(xiàn)就是 Connection reset by peer。如果你在寫訂單接口可能已經(jīng)完成了數(shù)據(jù)庫事務(wù)提交但響應(yīng)沒送到客戶端調(diào)用方就會(huì)選擇重試于是重復(fù)下單、重復(fù)扣庫存、對(duì)賬不平全都來了。1.2 粗暴關(guān)停的典型故障清單這類問題在線上有非常固定的模式我整理了一張表基本覆蓋了絕大部分事故場(chǎng)景故障現(xiàn)象真實(shí)原因涉及模塊客戶端提示 Connection resetTomcat 在請(qǐng)求進(jìn)行中直接關(guān)閉連接Web 容器下游收到 502/504Nginx 在 Upstream 節(jié)點(diǎn)關(guān)閉瞬間轉(zhuǎn)發(fā)請(qǐng)求失敗負(fù)載均衡消息重復(fù)消費(fèi)消費(fèi)到一半進(jìn)程退出offset 未提交Kafka/RocketMQ事務(wù)已提交但響應(yīng)丟失業(yè)務(wù)邏輯完成響應(yīng)未寫回客戶端Servlet 線程定時(shí)任務(wù)重復(fù)執(zhí)行集群多實(shí)例同時(shí)停機(jī)任務(wù)調(diào)度沒做搶占任務(wù)調(diào)度注冊(cè)中心出現(xiàn)異常實(shí)例服務(wù)端進(jìn)程已死但心跳還沒過期Eureka/Nacos這些故障有個(gè)共同點(diǎn)都不是代碼邏輯錯(cuò)誤而是進(jìn)程退出順序問題。業(yè)務(wù)代碼跑得好好的純粹因?yàn)橥C(jī)姿勢(shì)不對(duì)把“正常完成的請(qǐng)求”變成“客戶端感知到的失敗請(qǐng)求”這才是最虧的。1.3 先分清三個(gè)概念JVM ShutdownHook、Actuator Shutdown 與優(yōu)雅停機(jī)網(wǎng)上搜“SpringBoot 優(yōu)雅停機(jī)”經(jīng)?？吹絻煞N做法混在一起容易踩坑。第一種是 JVM 層面的 ShutdownHook代碼里Runtime.getRuntime().addShutdownHook(new Thread(...))它只保證“JVM 退出時(shí)我能執(zhí)行一段代碼”但改變不了 Web 容器已經(jīng)在關(guān)閉的事實(shí)。你用這個(gè)方式做“通知注冊(cè)中心摘流”因?yàn)轫樞虿粚?duì)往往還沒來得及發(fā)請(qǐng)求容器已經(jīng)斷了。第二種是 Actuator 的/actuator/shutdown端點(diǎn)需要手動(dòng)打開并 POST 觸發(fā)。它本質(zhì)上也是觸發(fā)ApplicationContext.close()在 Spring Boot 2.3 之前它是實(shí)現(xiàn)“相對(duì)優(yōu)雅”停機(jī)的主要手段因?yàn)槟憧梢钥刂朴|發(fā)時(shí)機(jī)不讓它依賴操作系統(tǒng)信號(hào)。第三種才是真正的“優(yōu)雅停機(jī)Graceful Shutdown”也就是從 2.3 開始官方內(nèi)置的能力。它做的事情很明確先停止接收新請(qǐng)求然后等待所有在途請(qǐng)求處理完成或超時(shí)最后再關(guān)閉 WebServer 和 Spring 容器。后面我會(huì)從配置開始完整拆解。2. 先別急著加配置版本、容器與兩行核心參數(shù)的前置判斷2.1 Spring Boot 版本是分水嶺低于 2.3 就沒有原生方案Spring Boot 2.3.0.RELEASE 的 Release Notes 明確寫了為內(nèi)嵌 Web 服務(wù)器增加優(yōu)雅停機(jī)支持。所以如果你項(xiàng)目還在 2.1、2.2對(duì)不起server.shutdowngraceful這個(gè)配置是無效的日志里連個(gè)警告都不會(huì)有。我見過有人把server.shutdowngraceful加到 2.2 項(xiàng)目上發(fā)版之后以為萬事大吉結(jié)果壓測(cè)一打就露餡。所以第一步永遠(yuǎn)是看pom.xml里的父版本parent groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-parent/artifactId version2.7.18/version relativePath/ /parent如果你日常用的是 Spring Boot 3.x那當(dāng)然更沒問題這套機(jī)制一直延續(xù)下來了。如果是老項(xiàng)目暫時(shí)升不動(dòng)版本至少要做到給負(fù)載均衡或注冊(cè)中心留出摘流時(shí)間再手動(dòng)觸發(fā)/actuator/shutdown不要裸著發(fā) SIGTERM。2.2 核心配置只有兩行但第二行含義經(jīng)常被讀錯(cuò)在application.properties或 yaml里加上server.shutdowngraceful spring.lifecycle.timeout-per-shutdown-phase30s第一行很簡單把默認(rèn)的immediate改成graceful告訴 Spring Boot 走優(yōu)雅停機(jī)流程。第二行spring.lifecycle.timeout-per-shutdown-phase寫的默認(rèn)值是 30s。注意關(guān)鍵詞是per-shutdown-phase也就是“每個(gè)關(guān)閉階段”的超時(shí)時(shí)間不是“整個(gè)停機(jī)過程”的總超時(shí)。Spring 容器里不同 Lifecycle 組件按 phase 分批關(guān)閉理論上有幾個(gè) phase就可能累加幾個(gè) 30s。這一點(diǎn)后面講事件鏈的時(shí)候還會(huì)展開先記住不要把它理解成“最多等 30 秒就強(qiáng)制退出”。2.3 官方支持矩陣四個(gè)內(nèi)嵌容器全都支持但成熟度有差異Spring Boot 官方文檔對(duì)優(yōu)雅停機(jī)的描述是支持所有四個(gè)內(nèi)嵌 Web 服務(wù)器Tomcat、Jetty、Reactor Netty、UndertowServlet 和響應(yīng)式應(yīng)用都可以。但做底層適配的人都知道一個(gè)能力“支持”和“支持得好”是兩回事。Tomcat 的實(shí)現(xiàn)最完整從 9.0.33 開始提供了相對(duì)成熟的 Connector pause 線程池等待機(jī)制Jetty 和 Reactor Netty 也能做到“停止接收新請(qǐng)求等待在途請(qǐng)求完成”Undertow 也能用但我在網(wǎng)上見過一些版本差異導(dǎo)致的邊界問題如果你不是必須用 Undertow建議在生產(chǎn)環(huán)境優(yōu)先用 Tomcat省心。容器是否支持實(shí)際表現(xiàn)Tomcat 9.0.33完整支持pause Connector等待線程池任務(wù)完成日志清晰Jetty 9.4支持等待在途請(qǐng)求但部分版本需要額外注意連接超時(shí)Reactor Netty支持WebFlux 場(chǎng)景可用2.3 起支持等待事件循環(huán)中請(qǐng)求Undertow支持能用但社區(qū)反饋的邊界問題相對(duì)多2.4 開啟前檢查下自己的環(huán)境這里給一個(gè)快速自查清單照著過一遍再上線項(xiàng)目spring-boot-starter-web或spring-boot-starter-webflux版本是否 ≥ 2.3。是否使用內(nèi)嵌容器如果打成 war 丟外置 Tomcat這套配置不直接生效。確認(rèn)停機(jī)時(shí)是kill -15或docker stop、systemctl stop觸發(fā)而不是kill -9。有沒有在代碼里自定義 ShutdownHook如果自定義 Hook 里做了“等待 xx 秒”之類的邏輯要測(cè)試它與 Spring 優(yōu)雅停機(jī)的先后順序別讓兩段等待互相打架。3. 停機(jī)時(shí)到底在等什么SIGTERM 到容器關(guān)閉的完整事件鏈3.1 事件鏈路拆解SIGTERM → JVM Hook → Spring 容器關(guān)閉優(yōu)雅停機(jī)不是魔法它只是在正確的位置插入了等待邏輯。進(jìn)程收到kill -15后JVM 開始執(zhí)行已注冊(cè)的 ShutdownHook。Spring Boot 的SpringApplicationShutdownHook在這個(gè)時(shí)機(jī)被觸發(fā)它會(huì)調(diào)用ApplicationContext.close()。close()內(nèi)部會(huì)先觸發(fā)ContextClosedEvent然后通過DefaultLifecycleProcessor去 stop 所有 Lifecycle 組件。關(guān)鍵就在這里Spring Boot 把內(nèi)嵌 WebServer 的優(yōu)雅停機(jī)封裝成了一個(gè)SmartLifecycle它會(huì)在 Spring 容器關(guān)閉時(shí)先執(zhí)行。這個(gè) Lifecycle 做的事是設(shè)置 Server 不再接收新請(qǐng)求Tomcat 表現(xiàn)為停止 accept 新連接。等待活躍請(qǐng)求執(zhí)行完成。超過timeout-per-shutdown-phase的請(qǐng)求不再等待直接強(qiáng)制關(guān)閉。等它結(jié)束后WebServer 才真正銷毀Spring Bean 才開始挨個(gè)銷毀。這條鏈路保證了“先等業(yè)務(wù)收完尾再拆房子”。3.2 三層等待容器層、線程池層、業(yè)務(wù)資源層實(shí)際等的東西可以分成三層看。第一層是 Web 容器層。Tomcat 的 Connector 進(jìn)入 paused 狀態(tài)后不再 accept 新連接但已經(jīng)建立連接上正在執(zhí)行請(qǐng)求的線程不會(huì)被打斷。第二層是線程池層。Tomcat 內(nèi)部維護(hù)了一個(gè)執(zhí)行 Servlet 的工作線程池優(yōu)雅停機(jī)時(shí)它會(huì)等線程池里所有任務(wù)執(zhí)行完。如果你的某個(gè)接口里定義了 10 秒Thread.sleep它就是這里被等的重點(diǎn)對(duì)象。第三層是業(yè)務(wù)資源層。Spring 容器真正 close 時(shí)HikariCP 數(shù)據(jù)源、消息連接池這些 Bean 才開始逐個(gè)關(guān)閉。HikariCP 關(guān)閉時(shí)也會(huì)等待租出去的連接歸還。這就是為什么“Web 容器等待”和“數(shù)據(jù)源等待”是兩個(gè)不同的時(shí)間窗口別只用接口耗時(shí)去預(yù)算停機(jī)總時(shí)長。3.3 為什么日志里只見 “Commencing graceful shutdown” 卻遲遲不結(jié)束開啟優(yōu)雅停機(jī)后收到 SIGTERM控制臺(tái)會(huì)輸出類似這樣的日志o.s.b.w.e.tomcat.GracefulShutdown : Commencing graceful shutdown. Waiting for active requests to complete很多第一次接優(yōu)雅停機(jī)的人看到這行日志然后發(fā)現(xiàn)進(jìn)程遲遲不退會(huì)慌。其實(shí)這是正?，F(xiàn)象。它正在等待在途請(qǐng)求。等所有請(qǐng)求處理完會(huì)看到o.s.b.w.e.tomcat.GracefulShutdown : Graceful shutdown complete之后 Spring 容器繼續(xù)關(guān)閉剩下的 Bean。整個(gè)停機(jī)的標(biāo)準(zhǔn)日志順序應(yīng)該是Commencing graceful shutdown. Waiting for active requests to complete 這里停頓時(shí)間取決于在途請(qǐng)求 Graceful shutdown complete Closing org.springframework.context.annotation.AnnotationConfigApplicationContext ...如果你始終看不到第二行日志大概率是某個(gè)請(qǐng)求永遠(yuǎn)不返回比如 WebSocket 連接、SSE 長連接、卡死的任務(wù)最后只能等超時(shí)被強(qiáng)制切斷。這也是生產(chǎn)環(huán)境最容易出問題的點(diǎn)看似在“優(yōu)雅等待”實(shí)際在“無限等待”。3.4 timeout-per-shutdown-phase 的真實(shí)累計(jì)邏輯前面說了這個(gè)參數(shù)是“每階段超時(shí)”。Spring 的DefaultLifecycleProcessor會(huì)把所有 Lifecycle 分組每個(gè) phase 單獨(dú)計(jì)時(shí)。如果你既用了 WebServer 的優(yōu)雅停機(jī)又自定義了幾個(gè) SmartLifecycle還接了消息監(jiān)聽容器等等那總停機(jī)時(shí)間可能超過 30s。舉個(gè)實(shí)際例子phase 大的 Lifecycle 先關(guān)閉如果它在 30s 內(nèi)沒結(jié)束后面哪怕還有很多 Bean 沒關(guān)也會(huì)被強(qiáng)制打斷繼續(xù)往下走。所以設(shè)置這個(gè)參數(shù)時(shí)最好把你業(yè)務(wù)里“最長的一個(gè)慢請(qǐng)求耗時(shí) 數(shù)據(jù)源連接歸還時(shí)間 自定義清理時(shí)間”都估算進(jìn)去。寧愿給 60s也不要卡在 30s 邊緣。4. 用壓測(cè)說話優(yōu)雅停機(jī)前后的請(qǐng)求行為對(duì)比4.1 測(cè)試環(huán)境與壓測(cè)準(zhǔn)備配置說再多不如自己跑一輪壓測(cè)直觀。下面是我在本地搭的一組最小驗(yàn)證環(huán)境Spring Boot 2.7 項(xiàng)目 Tomcat一個(gè)慢接口模擬“在處理中的業(yè)務(wù)”。RestController public class GracefulController { GetMapping(/slow) public String slow() throws InterruptedException { System.out.println(請(qǐng)求進(jìn)入 Thread.currentThread().getName() 時(shí)間 System.currentTimeMillis()); TimeUnit.SECONDS.sleep(10); System.out.println(請(qǐng)求完成 Thread.currentThread().getName() 時(shí)間 System.currentTimeMillis()); return ok; } }壓測(cè)用 ab 就夠了不用上 JMeterab -n 500 -c 50 http://127.0.0.1:8080/slow這個(gè)命令的意思是總共 500 個(gè)請(qǐng)求50 并發(fā)每個(gè)請(qǐng)求都要花 10 秒。按下命令后間隔幾秒再開一個(gè)終端執(zhí)行kill -15 $(jps | grep -i app | awk {print $1})然后觀察 ab 的統(tǒng)計(jì)結(jié)果和控制臺(tái)日志。4.2 未開啟優(yōu)雅停機(jī)kill 之后響應(yīng)直接被掐斷先把server.shutdowngraceful注釋掉用默認(rèn)的immediate跑一輪。kill 之后控制臺(tái)立刻開始關(guān)閉容器正在執(zhí)行的接口線程直接被中斷。ab 端的表現(xiàn)非常明顯大量Failed requests。客戶端側(cè)報(bào)Connection reset by peer。不管接口邏輯后面還有沒有收尾工作一律不執(zhí)行。最終輸出的Complete requests遠(yuǎn)小于 500。我在實(shí)際壓測(cè)中看到過更夸張的情況有些請(qǐng)求已經(jīng)進(jìn)入 Tomcat 工作線程但還沒來得及打印“請(qǐng)求進(jìn)入”進(jìn)程就關(guān)了。這類請(qǐng)求就是“連業(yè)務(wù)代碼都沒跑完就被掐斷”的典型。4.3 開啟優(yōu)雅停機(jī)新請(qǐng)求被拒絕在途請(qǐng)求正常收尾然后把兩行配置加上重新啟動(dòng)并壓測(cè)。中途 kill -15重點(diǎn)關(guān)注幾個(gè)表現(xiàn)第一控制臺(tái)輸出Commencing graceful shutdown之后原本已經(jīng)在跑的接口線程繼續(xù)打印“請(qǐng)求完成”沒有中斷異常。第二ab 的Complete requests和Failed requests不再難看。已經(jīng)進(jìn)入 Tomcat 的請(qǐng)求基本都能正常拿到響應(yīng)。第三停機(jī)期間新進(jìn)來的請(qǐng)求會(huì)失敗因?yàn)槿萜饕呀?jīng)不再 accept。你會(huì)在 Tomcat 日志里看到連接被拒絕的痕跡這是預(yù)期行為。所以優(yōu)雅停機(jī)的核心價(jià)值不是“所有請(qǐng)求都不失敗”而是“已經(jīng)進(jìn)入的請(qǐng)求別被半路打死”。至于新請(qǐng)求本來就應(yīng)該靠前面的負(fù)載均衡摘流解決這屬于第 5 章要討論的問題。4.4 超時(shí)場(chǎng)景超過等待上限的請(qǐng)求最終怎么收?qǐng)鲈衮?yàn)證一個(gè)邊界如果請(qǐng)求耗時(shí)超過timeout-per-shutdown-phase會(huì)怎樣把spring.lifecycle.timeout-per-shutdown-phase改成3s然后接口 sleep 10 秒壓測(cè)中途 kill。你會(huì)發(fā)現(xiàn)3 秒之后日志里出現(xiàn)容器強(qiáng)制關(guān)閉的動(dòng)作。那個(gè)還在 sleep 的請(qǐng)求被中斷客戶端同樣會(huì)收到連接重置。所以優(yōu)雅停機(jī)不是“無限等”它是有上限的。上限到了該斷還是斷。這個(gè)測(cè)試特別適合用來跟業(yè)務(wù)方對(duì)齊預(yù)期停機(jī)窗口內(nèi)新請(qǐng)求會(huì)失敗超長請(qǐng)求會(huì)失敗只有“正常長度”的在途請(qǐng)求能被保護(hù)。4.5 生產(chǎn)視角看待壓測(cè)結(jié)果跑完這些對(duì)比我建議把結(jié)論寫進(jìn)發(fā)布手冊(cè)發(fā)布前先確認(rèn) Kafka 消費(fèi)位移、消息推送、文件上傳這類長任務(wù)耗時(shí)不超預(yù)算。壓測(cè)結(jié)論要讓運(yùn)維、QA、后端三方都看到別只停留在“我這邊加了配置”。把壓測(cè)中的Graceful shutdown complete日志出現(xiàn)時(shí)間點(diǎn)記錄下來作為每次發(fā)布前的參考基線。5. 單機(jī)優(yōu)雅不解決流量分配注冊(cè)中心、Nginx、Docker 和 K8s 的配合5.1 最容易被忽視的坑負(fù)載均衡還在往停機(jī)節(jié)點(diǎn)甩流量單機(jī)優(yōu)雅停機(jī)只解決“請(qǐng)求已經(jīng)進(jìn)來了”的情況。但發(fā)布的時(shí)候前面掛的 Nginx、Gateway、注冊(cè)中心客戶端并不知道這個(gè)節(jié)點(diǎn)正在停機(jī)它們?nèi)詴?huì)把新請(qǐng)求轉(zhuǎn)發(fā)過來。這個(gè)瞬間連接被拒、超時(shí)、報(bào)錯(cuò)還是會(huì)重演。我見過一個(gè)團(tuán)隊(duì)做出來的停機(jī)順序是反的先 kill 進(jìn)程等容器優(yōu)雅停完了再去 Nginx 摘節(jié)點(diǎn)。摘流事件發(fā)生在進(jìn)程死亡之后前面的用戶流量已經(jīng)遭殃了。正確的順序應(yīng)該是先摘流再停機(jī)。摘流手段根據(jù)你的流量入口不同有幾種做法下面分開說。5.2 手動(dòng)摘流Nginx、Eureka、Nacos、Consul 分別怎么處理如果你們上游是 Nginx最直接的健康檢查方案是Spring Boot 暴露一個(gè)健康檢查接口停機(jī)前先把該接口狀態(tài)改成 DOWNNginx 通過max_fails或主動(dòng)健康檢查摘掉這個(gè) upstream 節(jié)點(diǎn)。比較粗暴但有效的做法是在停機(jī)前用腳本調(diào) Nginx 接口直接標(biāo)記 down。如果用的是注冊(cè)中心更標(biāo)準(zhǔn)化的做法是調(diào)用服務(wù)治理 API 提前反注冊(cè)注冊(cè)中心摘流方式說明Nacosnacos-client的deregisterInstance主動(dòng)摘除后客戶端拉取新列表需要時(shí)間Eureka發(fā)心跳把狀態(tài)置為 OUT_OF_SERVICE配合 eureka 客戶端緩存刷新Consul服務(wù)實(shí)例標(biāo)記為 maintenance 或反注冊(cè)同樣存在傳播延遲無論哪種方式都要記住一個(gè)現(xiàn)實(shí)注冊(cè)中心的摘流是異步傳播的客戶端可能存在緩存延遲。所以不要“反注冊(cè)完立刻殺進(jìn)程”要留一個(gè)緩沖窗口比如再等 5~10 秒等流量真的淡出再停。5.3 Docker stop 的 10 秒絞刑默認(rèn) STOP_TIMEOUT 與 30 秒優(yōu)雅超時(shí)的沖突這塊是網(wǎng)上抱怨最多、也最隱蔽的坑。用 Docker 跑 SpringBoot 時(shí)docker stop默認(rèn)只等 10 秒超過 10 秒直接SIGKILL?？墒莝pring.lifecycle.timeout-per-shutdown-phase默認(rèn)是 30s。如果你的停機(jī)時(shí)間超過 10sDocker 會(huì)毫不客氣地把進(jìn)程干掉優(yōu)雅停機(jī)形同虛設(shè)。解決辦法有三個(gè)# 運(yùn)行時(shí)指定 docker run --stop-timeout 60 your-image # compose 文件 services: app: stop_grace_period: 60s# 更推薦的還是在 Dockerfile 里明確信號(hào) STOPSIGNAL SIGTERM注意這行STOPSIGNAL SIGTERM有些基礎(chǔ)鏡像或啟動(dòng)腳本會(huì)對(duì)信號(hào)做二次轉(zhuǎn)發(fā)如果默認(rèn)不是SIGTERM優(yōu)雅停機(jī)可能根本沒被觸發(fā)。Dockerfile 里寫清楚就沒有這個(gè)歧義。5.4 Kubernetes 滾動(dòng)發(fā)布readiness 探針與 preStop 的最佳姿勢(shì)K8s 場(chǎng)景跟 Docker 又不一樣因?yàn)?K8s 控制的是 Pod 生命周期它默認(rèn)給了terminationGracePeriodSeconds: 30s這個(gè)窗口要大于你預(yù)估的優(yōu)雅停機(jī)時(shí)間。推薦的做法是用 readiness 探針配合 preStop hookspec: terminationGracePeriodSeconds: 60 containers: - name: app readinessProbe: httpGet: path: /actuator/health/readiness port: 8080 initialDelaySeconds: 10 periodSeconds: 5 lifecycle: preStop: exec: command: [/bin/sh, -c, sleep 5]這里面的邏輯是K8s 在停止 Pod 前會(huì)先把該 Pod 從 Service Endpoint 中摘掉但摘掉動(dòng)作的生效也要時(shí)間preStop里 sleep 幾秒等于給了 K8s 一個(gè)緩沖。sleep 結(jié)束K8s 才發(fā) SIGTERM此時(shí)流量已經(jīng)基本不來了Spring Boot 才開始優(yōu)雅停機(jī)。這樣組合起來才能真正做到“先摘流再等請(qǐng)求最后殺進(jìn)程”。5.5 多實(shí)例同時(shí)停機(jī)的雪崩問題分批發(fā)布最后一個(gè)集群層面的坑如果你有多個(gè)實(shí)例發(fā)布系統(tǒng)把實(shí)例 A、B、C 同時(shí) kill那它們同時(shí)在優(yōu)雅停機(jī)同時(shí)在等各自的重請(qǐng)求完成。等它們?nèi)恐貑⑼曛虚g出現(xiàn)的空閑窗口可能直接把整個(gè)服務(wù)的容量打穿。穩(wěn)妥做法是分批發(fā)布先把流量摘掉一部分停一個(gè)、起一個(gè)。滾動(dòng)發(fā)布有天然的順序但如果你是自己寫腳本發(fā)布一定要手動(dòng)控制并發(fā)數(shù)。這個(gè)經(jīng)驗(yàn)我在線上吃過虧優(yōu)雅停機(jī)修好了“單機(jī)請(qǐng)求被掐斷”卻差點(diǎn)因?yàn)椤叭繉?shí)例同時(shí)停機(jī)”導(dǎo)致服務(wù)不可用。6. 給業(yè)務(wù)留足收尾時(shí)間事件監(jiān)聽、Lifecycle 順序與上線檢查清單6.1 ContextClosedEvent別在 Web 容器停止后再做異步收尾優(yōu)雅停機(jī)等于給了你一個(gè)“業(yè)務(wù)收尾”的時(shí)間窗口。但很多團(tuán)隊(duì)把收尾邏輯寫在PreDestroy或自定義 ShutdownHook 里順序非常不可控。更可控的方式是監(jiān)聽ContextClosedEvent。這個(gè)事件在 Spring 容器開始關(guān)閉時(shí)發(fā)出此時(shí) Bean 還都活著你可以在這時(shí)候通知消息隊(duì)列暫停消費(fèi)、把服務(wù)狀態(tài)標(biāo)記為“停止接收流量”、保存內(nèi)存中的批次數(shù)據(jù)等。Component public class ShutdownListener { EventListener(ContextClosedEvent.class) public void onShutdown(ContextClosedEvent event) { // 1. 暫停消息消費(fèi) // 2. 觸發(fā)緩存刷新或持久化 // 3. 標(biāo)記健康檢查為 DOWN System.out.println(容器開始關(guān)閉執(zhí)行業(yè)務(wù)收尾); } }但要注意這個(gè)回調(diào)里不要做耗時(shí)太長的操作它會(huì)被計(jì)入整個(gè)關(guān)閉流程超時(shí)一樣會(huì)被強(qiáng)殺。6.2 SmartLifecycle 與 phase 控制注冊(cè)中心為什么必須放在高 phase如果你需要在 Web 容器停止之前就把注冊(cè)中心摘掉更規(guī)范的做法是實(shí)現(xiàn)SmartLifecycle并給一個(gè)較大的 phase。Spring 的規(guī)則是停止時(shí)數(shù)字越大越先關(guān)閉。所以摘流邏輯應(yīng)該用 Integer.MAX_VALUE 附近的 phase確保它排在 WebServer 優(yōu)雅停機(jī)之前。Component public class DeregisterLifecycle implements SmartLifecycle { private volatile boolean running; Override public void start() { this.running true; } Override public void stop() { // 在這里調(diào)用 Nacos / Eureka / Consul 摘流 System.out.println(先從注冊(cè)中心摘除實(shí)例); this.running false; } Override public boolean isRunning() { return this.running; } Override public int getPhase() { return Integer.MAX_VALUE; } }這個(gè)模式比在ContextClosedEvent里寫更嚴(yán)謹(jǐn)因?yàn)樗?Spring 的關(guān)閉順序是同一套機(jī)制不用擔(dān)心某個(gè) Bean 提前銷毀導(dǎo)致調(diào)用失敗。不過也要注意摘流后必須在注冊(cè)中心傳播延遲里再拖幾秒所以我一般會(huì)在stop()里加一個(gè)輕量 sleep別一摘完就立刻進(jìn)入下一步。6.3 定時(shí)任務(wù)、線程池、數(shù)據(jù)庫連接池在停機(jī)期的真實(shí)表現(xiàn)如果你項(xiàng)目里有Scheduled定時(shí)任務(wù)默認(rèn)情況下它們跑在單線程調(diào)度器里。優(yōu)雅停機(jī)過程中這些任務(wù)不會(huì)自動(dòng)取消如果某個(gè)任務(wù)正在刷新緩存或跑批量任務(wù)它也會(huì)被容器關(guān)閉打斷。我的建議是給這些異步任務(wù)顯式指定一個(gè)線程池并在關(guān)閉時(shí)主動(dòng) shutdown。這樣能保證優(yōu)雅停機(jī)時(shí)任務(wù)執(zhí)行到安全邊界才退出。數(shù)據(jù)庫連接池這塊HikariCP 在容器關(guān)閉時(shí)會(huì)等待租借出去的連接歸還但默認(rèn)的等待時(shí)間并不長。如果某個(gè)慢 SQL 在停機(jī)瞬間還沒跑完Hikari 的連接會(huì)被強(qiáng)制釋放事務(wù)可能回滾。所以你真正要評(píng)估的是“業(yè)務(wù)慢請(qǐng)求的最差耗時(shí)”而不是平均值。6.4 上線前照著抄的停機(jī)檢查清單最后給一份可以直接抄進(jìn)發(fā)布手冊(cè)的檢查清單確認(rèn) Spring Boot ≥ 2.3配置了server.shutdowngraceful且把timeout-per-shutdown-phase按最壞情況調(diào)大。用kill -15壓測(cè)一次確認(rèn)出現(xiàn)Commencing graceful shutdown和Graceful shutdown complete兩行日志。Docker 場(chǎng)景檢查stop-timeout或stop_grace_periodK8s 場(chǎng)景檢查terminationGracePeriodSeconds與 preStop。確認(rèn)注冊(cè)中心摘流在進(jìn)程退出前完成并留了緩沖時(shí)間。明確新請(qǐng)求在停機(jī)窗口內(nèi)注定會(huì)失敗由負(fù)載均衡/網(wǎng)關(guān)做兜底。針對(duì)長連接和長期占用線程的請(qǐng)求WebSocket、SSE、文件上傳單獨(dú)確認(rèn)超時(shí)策略。我個(gè)人的體會(huì)是優(yōu)雅停機(jī)不是一個(gè)讓“所有請(qǐng)求零失敗”的方案它是一個(gè)讓“該成功的請(qǐng)求能成功”的方案。真正要啃的硬骨頭在停機(jī)前的那幾步流量調(diào)度上。把代碼里的等待時(shí)間、容器參數(shù)里的超時(shí)時(shí)間、K8s 里的優(yōu)雅終止時(shí)間這三件事對(duì)齊線上發(fā)布才算真的穩(wěn)健。