簡介
EMQ X Broker 的配置文件通常以 .conf
作爲後綴名,你可以在 etc
目錄找到這些配置文件,主要配置文件包括:
配置文件 | 說明 |
---|---|
etc/emqx.conf | EMQ X Broker 配置文件 |
etc/acl.conf | EMQ X Broker 默認 ACL 規則配置文件 |
etc/plugins/*.conf | EMQ X Broker 擴展插件配置文件 |
需要注意的是,通過不同方式安裝的 EMQ X Broker,etc
目錄所處的路徑可能不同。
語法規則
- 採用類似 sysctl 的 k = v 通用格式
- 單個配置項的所有信息都在同一行內,換行意味着創建一個新的配置項
- 鍵可以通過
.
進行分層,支持按樹形結構管理配置項 - 值的類型可以是
integer
,fload
,percent
,enum
,ip
,string
,atom
,flag
,duration
andbytesize
- 任何以#開頭的行均被視爲註釋
示例:
mqtt.max_packet_size = 1MB
數據類型
integer
整型數據。
float
浮點型數據。
percent
以 %
結尾的百分比數據,最終會被轉換爲 float
類型。
enum
通常我們會在類型爲 enum
的配置項附近列出它的所有可選值。
ip
當你看到某個配置項的數據類型爲 ip
時,意味着你可以使用 <IP>:<Port>
的形式來設置該配置項,例如 0.0.0.0:1883
。
string
*.conf
文件中除註釋以外的所有內容都會先被解析成字符串再轉換爲其他類型,因此沒有必要對 string
類型的值額外使用雙引號對值進行修飾,並且這種方式也不被支持。
Yes!
dir = tmp
No!!!
dir = "tmp"
atom
atom
類型的值最終會轉換成 Erlang 的 atom
,但它在 *.conf
文件中的使用方式與 string
完全一致。
flag
flag
用於那些具有兩個可能值的變量,flag
默認可用值爲 on
和 off
,它們將映射爲 true
和 false
以供應用程序使用。如果我們爲某個配置項建立了其他的映射關係,我們會在配置文件中註明。
duration
duration
用於指定那些固定的時間間隔,你可以使用以下時間單位:
- f - fortnight
- w - week
- d - day
- h - hour
- m - minute
- s - second
- ms - millisecond
你可以任意組合這些時間單位,例如 1w13ms
,也可以使用浮點數,例如 0.5d
,這些時間間隔最終將會被轉換成我們指定的基準單位。這裏有一點需要注意,如果你以毫秒爲單位設置了某個配置項,而它的基準單位爲秒,那麼它將向上舍入至最接近的描述,例如 1s50ms
= 2s
。因此,我們會列出這一類配置項的基準單位。
bytesize
bytesize
支持以更易讀的方式來設置報文大小、緩衝區大小等配置,單位可以是 KB
,MB
和 GB
,你也可以使用小寫,例如 kb
,但不支持大小寫混合,例如 Kb
,它們最終都將被轉換爲字節數。如果你未指定任何單位,那麼它被直接作爲字節數使用。
默認配置
在 EMQ X Broker 的配置文件中,你會看到很多被註釋掉的配置項,這意味着這些配置項會使用他們的默認值,通常我們會列出這些配置的默認值。
Zone & Listener
EMQ X Broker 提供了非常多的配置項,並支持全局配置和局部配置。例如,EMQ X Broker 提供了匿名訪問的功能,即允許客戶端不需要用戶名與密碼就能連接 Broker,通常在用戶的生產環境中,此功能被默認關閉,但用戶可能又希望在他的內網環境中啓用此功能。從 3.0 版本開始,EMQ X Broker 就通過 Zone 與 Listener 爲用戶提供了這種可能。
Listener
Listener 主要用於配置不同協議的監聽端口和相關參數,EMQ X Broker 支持配置多個 Listener 以同時監聽多個協議或端口,以下是支持的 Listener:
監聽器 | 說明 |
---|---|
TCP Listener | A listener for MQTT which uses TCP |
SSL Listener | A secure listener for MQTT which uses TLS |
Websocket Listener | A listener for MQTT over WebSockets |
Secure Websocket Listener | A secure listener for MQTT over secure WebSockets (TLS) |
EMQ X Broker 默認提供 5 個 Listener,它們將佔用以下端口:
端口 | 說明 |
---|---|
1883 | MQTT/TCP 協議端口 |
11883 | MQTT/TCP 協議內部端口,僅用於本機客戶端連接 |
8883 | MQTT/SSL 協議端口 |
8083 | MQTT/WS 協議端口 |
8084 | MQTT/WSS 協議端口 |
Listener 配置項的命名規則爲 listener.<Protocol>.<Listener Name>.xxx
,<Protocol>
即 Listener 使用的協議,目前支持 tcp
, ssl
, ws
, wss
。<Listener Name>
可以隨意命名,但建議是全小寫的英文單詞,xxx
則是具體的配置項。不同協議的 Listener 的 <Listener Name>
可以重複,listener.tcp.external
與 listener.ssl.external
是兩個不同的 Listener。
由於默認配置的存在,我們能夠非常快速地展示如何添加新的 Listener,以 TCP Listener 爲例,我們只需要在 emqx.conf
中添加以下一條配置即可:
listener.tcp.example = 12345
當然這種情況我們更建議您複製一份默認 Listener 的配置進行修改。
Zone
一個 Zone 定義了一組配置項 (比如最大連接數等),Listener 可以通過配置項 listener.<Protocol>.<Listener Name>.zone
指定使用某個 Zone,以使用該 Zone 下的所有配置。多個 Listener 可以共享同一個 Zone。Zone 的命名規則爲 zone.<Zone Name>.xxx
,Zone Name
可以隨意命名,但同樣建議是全小寫的英文單詞,xxx
是具體的配置項。
此時,我們的每個配置項都存在三個可用值,分別是全局的值,Zone 裏設置的值以及默認值,它們的優先級順序爲:Zone > Global > Default。