RocketMQ中文文件（譯）
阿新 • • 發佈：2019-01-10
前言：近日需要研究一下RocketMQ，為了方便日後查詢，因此對官方英文文件進行翻譯記載，也希望能幫助到要學習的朋友。閱讀後發現，文件還是比較粗略的，大概也只能瞭解些概念和簡單實用。快速入門部分比較簡單，因此暫時沒翻譯只翻譯其中重要的幾個部分，快速入門日後會補上。
目前rocket的版本是4.2.0 官方參考文件的地址是：http://rocketmq.apache.org/docs/rmq-arc/ 可以對比來讀，因為可能我翻譯的也不是特別準確，並且為了方便中文閱讀，部分翻譯更接近於中文敘述方式，跟原文略微有不同。哪裡有本質的錯誤歡迎指出。
部署操作--DEPLOYMENT & OPERATIONS
RocketMq結構--RocketMQ Architecture
概述
Apache RocketMQ是一個具有低延遲、高效能和可靠性、萬億級容量同時具備靈活的可伸縮性的分散式消和流處理平臺，它由四個部分組成:name servers, brokers, producers 和 consumers。它們所有都可以水平擴充套件避免單點故障。就像上圖所示名稱服叢集務 NameServer cluster
NameServer服務提供了輕量級的服務發現和路由。每個NameServer服務記錄完整的路由資訊，提供一致的讀寫服務，支援快速儲存擴充套件
代理服務叢集 Broker Cluster
Broker通過提供輕量級主題和佇列機制來處理訊息儲存。它們支援Push和Pull模型，包含容錯機制(2個副本或3個副本)，提供了極強的峰值處理裡能力和按照時間順序儲存數以百萬記的訊息儲存能力，此外，代理提供了災難恢復、豐富的度量統計和警報機制，這些都是在傳統的訊息傳遞系統中缺乏的
生產者叢集 Producer Cluster
produce支援分散式部署，分散式的produce通過broker叢集提供的各種負載均衡策略將訊息傳送到broker叢集中。傳送過程支援快速失敗是低延遲的。
消費者叢集 Consumer Cluster
消費者也支援在推送和者拉取模式下分散式部署，它還支援叢集消費和訊息廣播。提供實時的訊息訂閱機制，能夠滿足大多數消費者的需求。RocketMQ的網站為感興趣的使用者提供了一個簡單的快速入門指南。
名稱服務NameServer
NameServer是一個功能齊全的伺服器，主要包括兩個功能：⊙broker 管理，nameserver 接受來自broker叢集的註冊資訊並提供心跳來檢測他們是否可用。
⊙路由管理 每一個nameserver都持有關於broker叢集和佇列的全部路由資訊，用來向客戶端提供查詢。
我們知道 ，rocketMQ客戶端（生產者/消費者）會從nameserver查詢佇列的路由資訊，客戶端是如何知道nameserver的地址的呢？
有四種方式能夠讓客戶端湖區到nameserver的地址：
⊙通過程式，像這樣producer.setNamesrvAddr("ip:port")
⊙java 配置項，這麼用rocketmq.namesrv.addr
⊙環境變數 NAMESRV_ADDR
⊙HTTP 端點
更多關於nameserver地址發現的詳細資訊請參考
代理服務 broker server
broker server負責訊息的儲存傳遞，訊息查詢，保證高可用等等。像下圖所示，broker server有一些非常重要的子模組：
⊙remoting（遠端） 模組，broker的入口，處理從客戶端發起的請求。
⊙client manager（客戶端管理） 管理各個客戶端（生產者/消費者）還有維護消費者主題訂閱。
⊙store（儲存服務），提供簡單的api來在磁碟保持或者查詢訊息。
⊙HA 高可用服務 提供主從broker的資料同步。
⊙index(索引服務)為訊息建立索引提供訊息快速查詢。
部署Deployment
這一部分介紹生產環境部署方案。概括來說，我們要部署一個沒有單點故障的叢集。必要條件Prerequisite
在開始之前，確定你已經閱讀過快速上手部分，並熟知RocketMq的核心概念和元件。準備部署Production-ready Deployment
Name Server
為了確保在一個例項崩潰時叢集仍然可以執行，建議使用兩個或多個名稱伺服器例項，只要叢集中有一個例項是可用的，整個叢集就可以提供服務。Name Server遵從share-nothing設計方式。Brokers傳送心跳資料到所有name server.當要傳送或者消費時生產者和消費者可以從任何一臺可用的Name server服務查詢到資訊
broker
Brokers可以按照類別分成兩類：master 和slave.master同時提供讀寫服務，slave只提供讀服務。要部署一個沒有單點故障的高可用叢集，需要部署多個broker。一個broker叢集需要有一個brokerId為0的master和多個brokerId不為0的slave。這個broker叢集的主從需要配置相同的brokerName，極端情況下，我們需要保證一個broker叢集中至少部署兩臺brokers服務，每個topic都存在於兩個或多個broker中。
配置Configuration
當你部署一個rocketMQ叢集時，我們推薦一下配置：Broker configuration
| Property Name 屬性名稱 | Default value 預設值 | Details詳細描述 |
|---|---|---|
| listenPort | 10911 | listen port for client 客戶端連線的埠 |
| namesrvAddr | null | name server address 名稱伺服器地址 |
| brokerIP1 | InetAddress for network interface 網址 | Should be configured if having multiple addresses 如果有多個地址需要配置多個 |
| brokerName | null | broker name 代理名稱 |
| brokerClusterName | DefaultCluster | this broker belongs to which cluster 代理屬於哪個叢集 |
| brokerId | 0 | broker id, 0 means master, positive integers mean slave 代理id，0代表主，正數代表從 |
| storePathCommitLog | $HOME/store/commitlog/ | file path for commit log 提交日誌的存放路徑 |
| storePathConsumerQueue | $HOME/store/consumequeue/ | file path for consume queue 消費佇列的存放路徑 |
| mapedFileSizeCommitLog | 1024 * 1024 * 1024(1G) | mapped file size for commit log 提交日誌對映檔案大小 |
| deleteWhen | 04 | When to delete the commitlog which is out of the reserve time 何時刪除已超出預定時間的commitlog檔案 |
| fileReserverdTime | 72 | The number of hours to keep a commitlog before deleting it 刪除之前儲存多少小時 |
| brokerRole | ASYNC_MASTER | SYNC_MASTER/ASYNC_MASTER/SLVAE 同步主/非同步主/從 |
| flushDiskType | ASYNC_FLUSH | {SYNC_FLUSH/ASYNC_FLUSH}. Broker of SYNC_FLUSH mode flushes each message onto disk before acknowledging producer. Broker of ASYNC_FLUSH mode, on the other hand, takes advantage of group-committing, achieving better performance.SYNC_FLUSHASYNC_FLUSH 同步模式會在響應每次生產者前寫入磁碟，非同步模式會提高處理生產者組的提交處理能力 |
命令列管理工具CLI Admin Tool
RocketMQ提供了一個管理工具，用於查詢管理診斷各種問題。如何獲得
這個工具和RocketMQ放到了一起，無論你是下載的是編譯好的版本還是自己編譯的，你的環境中都已經有了。這個案例你需要原始碼，rocketmq-tools的模組包含它自己的原始碼。
如何使用
使用管理工具非常簡單。為了演示，我們假設你已經在*nix環境中切換到${PACKAGE}/bin目錄，輸入 bash mqadmin，你會看到如下幫助選單
The most commonly used mqadmin commands are:
updateTopic Update or create topic
deleteTopic Delete topic from broker and NameServer
updateSubGroup Update or create subscription group
deleteSubGroup Delete subscription group from broker
updateBrokerConfig Update broker's config
updateTopicPerm Update topic perm
topicRoute Examine topic route info
topicStatus Examine topic Status info
topicClusterList get cluster info for topic
brokerStatus Fetch broker runtime status data
queryMsgById Query Message by Id
queryMsgByKey Query Message by Key
queryMsgByUniqueKey Query Message by Unique key
queryMsgByOffset Query Message by offset
queryMsgByUniqueKey Query Message by Unique key
printMsg Print Message Detail
sendMsgStatus Send msg to broker
brokerConsumeStats Fetch broker consume stats data
producerConnection Query producer's socket connection and client version
consumerConnection Query consumer's socket connection, client version and subscription
consumerProgress Query consumers's progress, speed
consumerStatus Query consumer's internal data structure
cloneGroupOffset Clone offset from other group
clusterList List all of clusters
topicList Fetch all topic list from name server
updateKvConfig Create or update KV config
deleteKvConfig Delete KV config
wipeWritePerm Wipe write perm of broker in all name server
resetOffsetByTime Reset consumer offset by timestamp(without client restart)
updateOrderConf Create or update or delete order conf
cleanExpiredCQ Clean expired ConsumeQueue on broker.
cleanUnusedTopic Clean unused topic on broker
startMonitoring Start Monitoring
statsAll Topic and Consumer tps stats
syncDocs Synchronize wiki and issue to github.com
allocateMQ Allocate MQ
checkMsgSendRT Check message send response time
clusterRT List All clusters Message Send RT有關特定命令的資訊請使用mqadmin help，如果你想知道更多的關於某個命令的資訊，比如說clusterList，你只需要輸入bash mqadmin help clusterList，你會看到
usage: mqadmin clusterList [-h] [-i <arg>] [-m] [-n <arg>]
-h,--help Print help
-i,--interval <arg> specify intervals numbers, it is in seconds
-m,--moreStats Print more stats
-n,--namesrvAddr <arg> Name server address list, eg: 192.168.0.1:9876;192.168.0.2:9876複製模式
為了確保不會丟失釋出成功的訊息，RocketMQ提供同步和非同步兩種複製方式來增強訊息的可靠性與高可用性。複製：同步/非同步 Broker
像許多複製系統一樣，同步複製會等待slave響應提交日誌已經被複制，相應的非同步複製會在mater節點處理成功後快速返回。如何配置
在conf檔案加下預設為rocketMQ提供了三種配置作為參考2m-2s-sync
2m-2s-async
2m-noslave注意:所有配置都使用ASYNC_FLUSH
部署
拿2m-2s-sync作為例子部署。首先啟動兩個name server按照在快速開始部分介紹的。假設他們的ip分別為192.168.0.2 和 192.168.0.3。然後啟動brokers假設編譯好的RocketMQ在目錄 /home/rocketmq/dist下
>cd /home/rocketmq/dist/bin
>bash mqbroker -c ../conf/2m-2s-sync/broker-a.properties -n 192.168.0.2:9876,192.168.0.3:9876
>bash mqbroker -c ../conf/2m-2s-sync/broker-a-s.properties -n 192.168.0.2:9876,192.168.0.3:9876
>bash mqbroker -c ../conf/2m-2s-sync/broker-b.properties -n 192.168.0.2:9876,192.168.0.3:9876
>bash mqbroker -c ../conf/2m-2s-sync/broker-b-s.properties -n 192.168.0.2:9876,192.168.0.3:9876
How to verify
Execute the following command to verify according to the CLI section:
> bash mqadmin clusterlist命令列管理工具CLI Admin Tool
RocketMQ提供了一個CLI管理工具帶，用於查詢、管理和診斷各種問題必要條件：
確保你已經閱讀操作過快速入門和核心概念部分怎樣獲取：
這個工具和RocketMQ放到了一起，無論你是下載的是編譯好的版本還是自己編譯的，你的環境中都已經有了。如果您想檢視原始碼，請參考rocketmq-tools模組
如何使用
這個管理工具非常友好，為了演示，在這裡假設你已經在Linux或UNIX安裝好了。目錄切換到${PACKAGE}/bin ，輸入命令bash mqadmin，你會看到下邊的幫助選單
The most commonly used mqadmin commands are:
updateTopic Update or create topic
deleteTopic Delete topic from broker and NameServer.
updateSubGroup Update or create subscription group
deleteSubGroup Delete subscription group from broker.
updateBrokerConfig Update broker's config
updateTopicPerm Update topic perm
topicRoute Examine topic route info
topicStatus Examine topic Status info
topicClusterList Get cluster info for topic
brokerStatus Fetch broker runtime status data
queryMsgById Query Message by Id
queryMsgByKey Query Message by Key
queryMsgByUniqueKey Query Message by Unique key
queryMsgByOffset Query Message by offset
queryMsgByUniqueKey Query Message by Unique key
printMsg Print Message Detail
sendMsgStatus Send msg to broker.
brokerConsumeStats Fetch broker consume stats data
producerConnection Query producer's socket connection and client version
consumerConnection Query consumer's socket connection, client version and subscription
consumerProgress Query consumers's progress, speed
consumerStatus Query consumer's internal data structure
cloneGroupOffset Clone offset from other group.
clusterList List all of clusters
topicList Fetch all topic list from name server
updateKvConfig Create or update KV config.
deleteKvConfig Delete KV config.
wipeWritePerm Wipe write perm of broker in all name server
resetOffsetByTime Reset consumer offset by timestamp(without client restart).
updateOrderConf Create or update or delete order conf
cleanExpiredCQ Clean expired ConsumeQueue on broker.
cleanUnusedTopic Clean unused topic on broker.
startMonitoring Start Monitoring
statsAll Topic and Consumer tps stats
syncDocs Synchronize wiki and issue to github.com
allocateMQ Allocate MQ
checkMsgSendRT Check message send response time
clusterRT List All clusters Message Send RT
See 'mqadmin help <command>' for more information on a specific command.如你所見，大部分常用選單這裡都用簡明的描述給您列出來了，要獲取每個命令的詳細資訊，輸入bash mqadmin help <command>。例如輸入bash mqadmin help clusterList會展示出如下內容。
usage: mqadmin clusterList [-h] [-i <arg>] [-m] [-n <arg>]
-h,--help Print help
-i,--interval <arg> specify intervals numbers, it is in seconds
-m,--moreStats Print more stats
-n,--namesrvAddr <arg> Name server address list, eg: 192.168.0.1:9876;192.168.0.2:9876這個幫助部分列出了可選選項和每個選項的釋義。
最佳實踐 BEST PRACTICE
核心概念Core Concept
根據上面的模型，我們可以深入研究一些關於訊息傳遞系統設計的話題：⊙消費併發
⊙消費熱點
⊙消費均衡
⊙訊息路由
⊙多種連結方式
⊙金絲雀部署
生產者Producer
生產者傳送業務中產生的訊息到broker，rocketMQ提供了多種傳送方式：同步，非同步，單程。生產者組Producer Group
把相同角色的生產者組織到一起。在事務提交後，生產組中的不同例項都可以連線broker執行提交或回滾事務，以防原生產者在提交後就掛掉。警告：考慮到生產者有很強的訊息傳送能力，每個生產者組只允許有一個例項用來避免不必要的初始化
消費者Consumer
消費者從broker拉取訊息給應用使用。在使用者應用方面，提供了兩種型別的消費者。拉取型PullConsumer
拉取型主動從broker拉取資訊，一次拉取一批，用於消費應用進行消費推送型PushConsumer
推送型是另一種思路，它封裝了訊息的拉取和消費程序和其他的內部工作細節，只提供一個在訊息到達時的回撥介面。消費者組Consumer Group
與先前提到的生產者組類似，相同的消費者角色組織到一起起名為消費者組。消費者組是一個棒的概念，它實現了負載平衡和容錯的目標，在資訊消費方面，非常簡單
注意：消費者是消費者組中的一個例項，必須訂閱相同的主題topic
主題 topic
主題是生產者傳遞訊息和消費者拉動訊息的類別。topic與生產者與消費者之間是鬆耦合的。特別強調，一個主題可以有零個一個或者多個生產者向它傳送訊息。相反，一個生產者可以向多個不同的主題傳送訊息。從消費者角度講，一個主題可以被零個或者一個或者多個消費者組訂閱，同樣的一個消費者組可以訂閱一個或多個主題，只要這個消費者組保持一致的訂閱即可。訊息message
訊息是傳遞的資訊。訊息必須有一個主題，可以理解為你寫信事郵寄的地址。訊息也可能有一個標籤選項是額外的鍵值對。例如，你可能傳送一條訊息時設定一個key標記，並通過這個key在broker中篩選這條訊息，用來處理特定的業務。（覺得這麼翻譯更好理解）訊息佇列 message queue
主題被劃分為一個或多個子主題這就是訊息佇列。標籤tag
標籤可以理解為更細一級的主題，為使用者提供更靈活的查詢。有了標籤同一業務產生的訊息可以有相同的主題不同的標籤，不同標籤標記的可以有不同的用途。標籤可以讓你的程式碼變得清晰連貫，還可以給RocketMQ提供更好的查詢支援。代理broker
broker是RockerMQ系統的重要組成部分。它接受並存儲來自生產者傳送的訊息，出來來自消費者的拉取請求。它也儲存和訊息有關的資訊，包括消費者組，消費位置還有主題佇列的資訊。名稱服務 nameserver
名稱服務提供路由資訊。為生產者和消費者客戶端提供一致的主題查詢列表。訊息模式 message model
⊙叢集clustering⊙廣播broadcasting
訊息順序message order
當DefaultMQPushConsumer 被設定好，你可能需要決定消費是順序的還是併發的⊙順序
有序的訊息意味著訊息的使用順序與生產者為每個訊息佇列傳送的順序相同。如果你的使用場景要求必是須順序的，你要確保只用一個佇列存放訊息。
警告：如果消費順序被指定，最大的消費併發數就是這個消費者組的訊息佇列的訂閱數
⊙併發：
當消費訊息是併發的，最大的訊息消費數只受限於每個消費客戶端執行緒池規定的數。
警告：這個模式下順序不在被保證。
代理 Broker
broker最佳實踐
非常有用的小竅門broker 角色
broker角色有ASYNC_MASTER（非同步主）, SYNC_MASTER（同步主） or SLAVE（從）。如果不能容忍訊息丟失，我建議你使用SYNC_MASTER（同步主）並且再加上一個SLAVE(從)服務的方式部署。如果你可以忍受異常情況下的訊息丟失，但是你想broker是高可用的，你可以使用ASYNC_MASTER（非同步主）加SLAVE（從方式部署。如果你想更簡單的部署，你可以只部署一個ASYNC_MASTER（非同步主），不部署任何SLAVE（從）。寫入磁碟型別FlushDiskType
推薦使用ASYNC_FLUSH（非同步寫入），SYNC_FLUSH（同步寫入）代價昂貴，會造成很大的效能浪費。如果你要求可靠性，我們推薦你使用SYNC_MASTER 同步主並配有一個SLAVE從。生產者Producer
生產者最佳實踐
非常有用的小竅門傳送狀態SendStatus
當傳送給訊息時，你需要獲取一個包含傳送狀態的結果。首先，假設訊息的isWaitStoreMsgOK=true（預設配置），我們會在傳送沒用異常的情況下始終得到傳送成功，下邊是幾個狀態的描述FLUSH_DISK_TIMEOUT
如果broker訊息儲存設定的引數是FlushDiskType=SYNC_FLUSH(預設是 ASYNC_FLUSH)，如果broker沒用在配置的5秒時間內完成訊息的儲存，會返回這個狀態值。FLUSH_SLAVE_TIMEOUT
如果broker的角色是SYNC_MASTER(預設 ASYNC_MASTER)，如果5秒內從broker沒用完成同步，會返回這個狀態。SLAVE_NOT_AVAILABLE
如果broker的角色是SYNC_MASTER(預設 ASYNC_MASTER)，但是沒有從被配置，會返回這個狀態。SEND_OK
SEND_OK並不意味著它是可靠的，要確保訊息不丟失，你需要開啟SYNC_MASTER同步主或者SYNC_FLUSH同步寫。重發或丟失Duplication or Missing
如果你傳送後返回的結果是FLUSH_DISK_TIMEOUT, FLUSH_SLAVE_TIMEOUT，並且這時broker掛掉了，你會發現剛剛傳送的訊息丟失了。這種情況下你有兩個選擇，一、丟就丟吧，可能會導致這個訊息的丟失。第二，再發一次，可能會引發訊息重複。通常我們建議是重發一次，並找到一個方法去處理髮送重複引發的重複消費問題。除非你覺得訊息丟失也沒什麼關係。但是記住當你得到的狀態是SLAVE_NOT_AVAILABLE，重複傳送的意義也不大。如果發生這個響應，應該記錄下來，並向叢集管理者報警。超時Timeout
客戶端傳送請求到broker，等待響應，如果經過最大等待時間仍然沒等到響應，客戶端會丟擲一個遠端超時異常。預設等待時間是3秒。你可以通過超時時間設定引數來使用send（msg, timeout）方法代替send(msg)方法。記住我們不建議你設定太小的超時時間，broker需要一些時間去寫磁碟還有做主從同步。這個值設定的超過syncFlushTimeout 也沒什麼大的影響，因為broker可能在超時之前已經返回FLUSH_SLAVE_TIMEOUT或FLUSH_SLAVE_TIMEOUT訊息大小 message size
我們建議大小不要超過512k非同步傳送Async sending
預設的傳送會阻塞直到響應資訊返回。所以如果你關心效能，我們建議你使用，seng(msg,callback)方法，它會非同步返回應答資訊。生產者組 produce group
通常來講，傳送者組沒什麼影響。但是如果你是複雜的事務，你需要關注它。預設在一個jvm中，相同的傳送者組中你只能建立一個生產者，一般這種情況就滿足需求了。執行緒安全 Thread Safety
生產者是執行緒安全的，你放心的使用就是了。效能Performance
如果你要使用超過一個生產者在jvm中用於處理大資料，我們建議你：⊙用少的生產者非同步傳送（3-5個足夠）。
⊙為每個生產者設定例項名稱。
消費者Consumer
消費者最佳實踐
非常有用的小竅門消費者組和訂閱 Consumer Group and Subscriptions
首先你要知道不同的消費者組可以獨立的消費相同的topic，每個消費者組都有它們自己的消費記錄。請確認相同的消費者組中的消費者要訂閱相同的主題。訊息監聽MessageListener
順序Orderly
消費者會鎖定每個訊息佇列，確保順序消費每個訊息。這回導致效能的損耗，但是如果你是關心訊息消費順序的這事非常有用的。不推薦丟擲異常，推薦使用狀態ConsumeOrderlyStatus.SUSPEND_CURRENT_QUEUE_A_MOMENT代替。併發Concurrently
同樣要說，這種模式是併發消費訊息。推薦用於高效能的處理方面。同樣不推薦丟擲異常，應該用返回ConsumeConcurrentlyStatus.RECONSUME_LATER代替。消費狀態Consume Status
在併發訊息監聽中，你可以返回RECONSUME_LATER 來通知消費者現在還不能消費，需要過會重試。你可以繼續消費其他訊息。在順序訊息監聽中，因為更關心的是順序，你不能跳過這條訊息，但是你可以返回SUSPEND_CURRENT_QUEUE_A_MOMENT 讓消費者等一會。阻塞Blocking
不推薦阻塞監聽者，因為會導致執行緒池阻塞，甚至可以導致消費過程停止。執行緒數Thread Number
消費者內部使用執行緒池來處理消費，你可以通過setConsumeThreadMin 或 setConsumeThreadMax來設定執行緒數從哪裡開始消費ConsumeFromWhere
當新的消費者組建立完成，它需要決定是否消費broker中的歷史訊息。CONSUME_FROM_LAST_OFFSET 會忽略歷史訊息，消費這之後的訊息。CONSUME_FROM_FIRST_OFFSET 會消費所有在broker中的訊息。你也可以使用CONSUME_FROM_TIMESTAMP 來指定消費特定時間點之後的訊息。重複Duplication
有很多情況導致重複，例如：生產者重複傳送（比如返回FLUSH_SLAVE_TIMEOUT情況）
消費者還沒來得及更新消費位置就掛掉
如果你的系統不能容忍重複，那你需要做一些處理。例如，你要檢查資料庫的key。（這裡要解決的是冪等性的問題）
名稱服務NameServer
名稱服務的最佳實踐
RockerMQ中，名稱服務設計的目的是協調分散式系統中各個部分元件，而協調主要通過管理主題路由資訊來實現。管理主要有一下兩部分構成：
⊙代理定期更新儲存在每個名稱伺服器中的元資料。
⊙名稱伺服器為客戶端服務，包括生產者、消費者和命令列客戶端提供最新的路由資訊。
因此，在啟動代理和客戶端之前，我們需要告訴他們如何通過給它們提供一個名稱伺服器地址列表來訪問名稱伺服器。在Apache RocketMQ中，可以通過四種方式實現：
編碼方式
在broker中，可以在配置檔案中指定namesrvAddr=name-server-ip1:port;name-server-ip2:port在生產者和消費者中，我們可以通過以下方式獲得名稱服務的地址
DefaultMQProducer producer = new DefaultMQProducer("please_rename_unique_group_name");