本頁內容
RabbitMQ 升級為什麼會出錯?
「很多時候,企業最難做到、或最容易忘記的,就是頻繁升級。有時候一次升級要拖上好幾年。如果他們想從現在的版本直接跳到最新版,就會碰上一堆意想不到的問題——因為他們本來應該一步一步地升級。」
— Jeff Sogolov,AceMQ 工程師,Lucidya 專案會議,2025 年 5 月
從 3.x 到 4.x 必須遵循什麼升級路徑?
rabbitmqctl enable_feature_flag allErlang 相容性呢?
- 3.12最低支援 Erlang 25.x
- 3.13最低需要 Erlang 26(建議 26.2)
- 4.x同樣最低需要 Erlang 26.2
「您可以直接把 Erlang 從 25 升到 26.2。一旦升到 26.2,再把 RabbitMQ 升到 3.13——您已經有正確的 Erlang 了。接著從 3.13 升到 4.1,同樣的 Erlang 版本依然適用。」
— Jeff Sogolov,AceMQ 工程師,Lucidya 會議,2025 年 5 月
策略 1:滾動升級(原地升級)
- 停止節點 1(只停止服務——不是作業系統)
- 將節點 1 上的 Erlang 升級到所需版本
- 將節點 1 上的 RabbitMQ 升級到目標版本
- 啟動節點 1 上的 RabbitMQ 服務
- 確認節點 1 已重新加入叢集且運作正常
- 對節點 2 與節點 3 重複上述步驟
策略 2:藍綠部署
- 以目標 RabbitMQ 與 Erlang 版本建置新叢集(綠)
- 在綠叢集上設定指向藍叢集的 federated queue 上游
- 隨著消費者移到綠叢集,Federation 會自動將訊息從藍叢集拉到綠叢集
- 所有消費者都移到綠叢集後,再將生產者移過去
- 生產者移轉完成後,使用 Shovel 外掛程式排空藍叢集中剩餘的訊息
- 讓藍叢集除役
「藍綠部署是零停機的。您可以隨時進行——不需要維護模式。代價是您會同時運行兩個叢集,有些公司負擔不起,尤其是地端環境。但對於可以輕鬆啟動新叢集的 AWS 部署來說,這非常合理。」
— Jeff Sogolov,AceMQ 工程師,Lucidya 會議,2025 年 5 月
升級前檢查清單
- 確認目前的 RabbitMQ 版本,並找出所需的升級路徑
- 查閱目標版本與中間版本的 Erlang 相容性矩陣
- 在目前版本上啟用所有 feature flag(rabbitmqctl enable_feature_flag all)
- 透過 Management API 備份叢集定義(拓撲、使用者、權限)
- 在動到正式環境之前,先在測試環境中完整驗證升級流程
- 確認節點離線時負載平衡器的健康檢查行為
- 在測試環境中模擬節點重新啟動,測試用戶端的重新連線行為
- 若採用滾動升級,請排在流量最低的時段
- 開始之前先將回復計畫寫成文件
在您確定窗口之前,若想從更全面的角度檢視準備情況,請參閱RabbitMQ 遷移準備檢查清單。
RabbitMQ 4.x 中可能讓 3.x 環境出問題的變更
大多數出錯的 3.x 到 4.x 升級,都栽在少數幾項變更上。只要讀過 4.0 的發行說明,這些都不算意外,但在一個沿用 3.8 與 3.9 慣例發展起來的大型環境中,每一項都很容易被忽略。
- 傳統佇列鏡像已經移除。鏡像傳統佇列(
ha-mode與ha-params原則鍵)在 3.9 被列為淘汰,並在 4.0 中移除。4.x 節點不會鏡像傳統佇列,因此任何依賴 HA 原則進行複寫的佇列,在原則不再生效的那一刻,就會變成單一節點佇列。這是唯一必須在升級之前、而不是之後處理的變更:將每個鏡像佇列遷移到仲裁佇列,然後刪除 HA 原則。rabbitmq-diagnostics check_if_cluster_has_classic_queue_mirroring_policy可以告訴您是否還有殘留。相關取捨請參閱我們的傳統佇列與仲裁佇列比較一文。 - 暫時性非獨占佇列已被列為淘汰。不專屬於單一連線的非持久佇列,已被標記為淘汰功能,並可透過設定加以禁止。它們在 4.x 中仍可運作,但請規劃全面改為宣告持久佇列,並只在真正屬於單一連線的狀態上使用獨占佇列。
- 預設佇列類型。宣告佇列時若未指定
x-queue-type,除非虛擬主機設定了default_queue_type,否則得到的仍是傳統佇列。請針對新的工作負載,在每個 vhost 將其設為quorum,並確保宣告佇列的用戶端程式碼明確傳入x-queue-type,以免有人被 vhost 層級的預設值嚇一跳。 - AMQP 1.0 已成為核心協定。在 4.0 中,不再需要另外安裝 AMQP 1.0 外掛程式;1.0 已在同一個 listener 上,與 0-9-1 一起原生實作。既有的 0-9-1 用戶端不受影響。原本使用舊外掛程式的團隊,應將其從已啟用外掛程式清單中移除;想使用 1.0 的團隊,則應改用持續維護中的 1.0 用戶端函式庫,而不是舊有的函式庫。
- 以 Khepri 作為中繼資料儲存庫。 Khepri 是以 Raft 為基礎、用來取代 Mnesia 的方案,在 3.13 中以實驗性功能推出,並在 4.x 中正式受支援,但需要自行選擇啟用。升級後,節點會繼續使用 Mnesia,直到您刻意啟用
khepri_dbfeature flag 為止。請把它當成一項獨立的變更,安排專屬的測試窗口,而不是版本升級的附帶效果。 - 必須先啟用所有 feature flag。只要 3.13 叢集中還有任何穩定的 feature flag 未啟用,就無法加入 4.x 節點,而 4.x 節點也會拒絕在該叢集上啟動。請在第一個節點升級之前,啟用所有 flag。
- 外掛程式與管理介面。為 3.x 編譯的外掛程式需要改用 4.x 的建置。管理外掛程式本身會延續下去,但會移除鏡像相關的檢視,而 AMQP 1.0 外掛程式則不再有任何作用。在假設任何社群外掛程式能正常運作之前,請先加以檢查。
- MQTT 5。 MQTT 5 支援在 3.13 推出,並延續到 4.x。如果您是從 3.12 或更舊的版本升級,您的 MQTT 用戶端會在升級路徑中一併獲得這項支援。
- Erlang。 4.x 需要 Erlang/OTP 26 或更新版本。如果您的節點仍在 OTP 25,Erlang 升級會作為滾動升級的一部分,一次一個節點進行。在選定目標版本之前,請參閱我們關於Erlang 26 生命週期結束與 RabbitMQ的說明。
應該留在 3.13,還是升級到 4.x?
3.13 是最後一個 3.x 系列。它的社群支援期很短,一旦結束,任何 3.x 版本都不再有上游的安全性修補程式。這就是驅動這項決策的真實限制。
只有在一種情況下,留在 3.13 是合理的:您擁有會將安全性修正向下移植到您所運行版本的商業或延伸支援方案。若沒有這項方案,3.13 叢集就是一座 CVE 定時炸彈。我們的延伸 LTS 支援涵蓋 3.8.x 至 3.13.x,並提供向下移植的修補程式,讓客戶能依自己掌控的時程運行較舊的系列,而不是被上游時程牽著走。它能爭取時間,但無法免除規劃升級的必要。
當以下四項條件全部成立時再升級:
- 鏡像傳統佇列已全數移除,且不再有任何 HA 原則。
- 每個節點上的所有穩定 feature flag 都已啟用。
- Erlang 已在 OTP 26 或更新版本,或您已準備好在滾動升級期間一併升級。
- 用戶端應用程式使用的是持續維護中的函式庫版本,且在仲裁佇列上的行為正確(能正確處理
x-delivery-limit、死信處理與重新連線)。
如果您需要不靠外掛程式的 AMQP 1.0、在較舊 3.x 上使用 MQTT 5,或是 4.x 的仲裁佇列改進(包括訊息優先順序,以及能阻止毒訊息無限循環的預設投遞上限),就應該比維護時程所建議的更早升級。
如果您使用的是 3.8 到 3.12,答案相同,但路徑更長:先升到 3.13 並穩定下來,再升到 4.x。我們會為客戶執行這兩個階段,而RabbitMQ 升級與修補服務也是依此規劃範圍的。
繼續使用是否安全,與是否可行,是兩個不同的問題。RabbitMQ 3.x 是否仍可安全運行一文逐一系列說明了生命週期結束日期與 CVE 風險。如果您決定繼續使用,RabbitMQ 3.x 延伸 LTS 支援能在升級等待窗口期間,讓版本持續獲得修補。
我們使用的滾動升級操作手冊
這是我們在客戶叢集上遵循的步驟順序。它假設叢集有三或五個節點、所有重要的資料都使用仲裁佇列,且用戶端具備斷線重連機制。
- 盤點。記錄各版本、Erlang 版本、已啟用的外掛程式與所有原則。在任一節點上執行
rabbitmq-diagnostics check_if_any_deprecated_features_are_used與rabbitmq-diagnostics check_if_cluster_has_classic_queue_mirroring_policy。兩者都必須回報沒有問題,才能繼續。 - 啟用所有穩定的 feature flag。
rabbitmqctl enable_feature_flag all在單一節點上執行即可套用到整個叢集。請以rabbitmqctl list_feature_flags確認;任何仍為disabled的 flag 都會阻擋升級。 - 逐一流程將鏡像傳統佇列轉換為仲裁佇列。仲裁佇列無法原地轉換。針對每條流程,宣告仲裁佇列、將消費者重新指向、將生產者重新指向、排空舊佇列,然後刪除它。請逐一應用程式進行,讓錯誤只影響一條流程,而不是整個環境。
- 確認 Erlang 目標版本。確認每個節點上都有 OTP 26 或更新版本的套件,且該版本正是您的 4.x 建置經過測試的版本。
- 匯出定義並進行備份。
rabbitmqctl export_definitions再加上每個節點資料目錄的檔案系統備份。一旦越過回復邊界,您就要從匯出的定義重建。 - 一次升級一個節點。停止節點之前,先執行
rabbitmq-upgrade await_online_quorum_plus_one,確保此節點離線期間沒有任何仲裁佇列失去多數。接著執行rabbitmq-upgrade drain將節點置於維護模式、正常關閉用戶端連線,並將仲裁佇列的 leader 角色轉移出去。停止服務,視需要升級 Erlang,升級 RabbitMQ,啟動服務,並確認節點已重新加入。 - 等待仲裁佇列成員追上進度。
rabbitmq-queues quorum_status <queue>針對最繁忙的佇列執行,或在下一個準備停止的節點上執行rabbitmq-diagnostics check_if_node_is_quorum_critical。在這項檢查通過之前,不要開始處理下一個節點。 - 確認用戶端已重新連線。管理介面中已升級節點的連線數應恢復到基準值。如果某個用戶端函式庫沒有重新連線,請在處理下一個節點之前就先修正。
- 對其餘每個節點重複上述步驟。在此期間,叢集會以 3.13 與 4.x 混合運行。在最後一個節點完成之前,不要變更原則、新增佇列或啟用任何新功能。
- 啟用新的 4.x feature flag。最後一個節點升級完成後,再執行一次
rabbitmqctl enable_feature_flag all。這就是回復邊界:一旦啟用了 4.x 專屬的 feature flag,就沒有降級的路徑。在這一步之前的所有操作,都可以透過將節點還原為 3.13 來復原。
rabbitmqctl enable_feature_flag all
rabbitmq-upgrade await_online_quorum_plus_one
rabbitmq-upgrade drain當叢集規模小到可以重建、匯出的定義值得信賴,而且您能透過 DNS 或負載平衡器移轉用戶端時,藍綠部署就是另一種選擇。它能給您一個乾淨的 4.x 叢集,以及一個完好的 3.13 叢集作為退路。對於累積了多年未記錄原則的叢集,我們偏好採用這種方式。
無論採用哪種方式,技術支援都會以 15 分鐘的 P1 回應涵蓋整個升級窗口,這在第 6 步到第 10 步之間最為重要。
常見問題
可以直接從 RabbitMQ 3.13 升級到 4.x 嗎?
可以。從 3.13.x 滾動升級到 4.0.x 是受支援的,前提是所有穩定的 feature flag 都已啟用、不再有任何傳統佇列鏡像原則,且 Erlang 已是 OTP 26 或更新版本。如果您使用的是 3.12 或更舊的版本,就無法直接跳到 4.x;請先升級到 3.13、啟用其 feature flag,再繼續升級。原因在於 4.x 節點只能加入已完整啟用 3.13 feature flag 組合的叢集,而較舊的系列無法滿足這項條件。
可以繼續使用 RabbitMQ 3.x 嗎?
可以,但唯有搭配會向下移植安全性修正的技術支援方案才算安全,因為 3.x 的上游修補程式會隨著 3.13 社群支援期結束而停止。我們的延伸 LTS 支援涵蓋 3.8.x 至 3.13.x,並提供向下移植的 CVE 修補程式,正是為這種情況而設。當用戶端遷移、法規遵循凍結期或佇列轉換所需的時間,超出上游時程所允許的範圍時,繼續使用是合理的。但它不適合作為永久狀態;請依您自己的時程規劃升級到 4.x。
如何在不停機的情況下升級 RabbitMQ?
採用滾動升級,一次一個節點。啟用所有 feature flag、移除鏡像傳統佇列、匯出定義,接著針對每個節點執行rabbitmq-upgrade await_online_quorum_plus_one、將節點排空,升級 Erlang 與 RabbitMQ、重新啟動,並等待仲裁佇列成員追上進度後,再處理下一個節點。具備斷線重連機制的用戶端只會經歷短暫的重新連線,而不是服務中斷。如果現有叢集太過錯綜複雜、無法原地升級,則可選擇藍綠部署:建立新的 4.x 叢集,再切換用戶端。
RabbitMQ 4 需要 Erlang 26 嗎?
需要。RabbitMQ 4.x 需要 Erlang/OTP 26 或更新版本。如果您的 3.13 節點已在 OTP 26 上,Erlang 這一步就不需要做任何事;如果仍在 OTP 25,請在同一個滾動升級窗口中,於每個節點上連同 RabbitMQ 套件一起升級 Erlang。請查閱相容性對照表,確認您要安裝的確切 4.x 修補版本,因為較新的 4.x 版本會提高最低版本要求。我們關於Erlang 26 生命週期結束的文章,說明了這對支援時程的影響。