設定與組態

為什麼要學這個

EMQX 的參數散在幾個地方：可以直接在 Dashboard 動態調整的、藏在設定檔的、以及以環境變數覆蓋的。家用場景常會不小心把兩個設定寫到不同層，結果改不動卻又不確定誰贏。

這章把 EMQX 的設定體系講清楚：Dashboard 的 Management 模組先說明，再講設定檔（emqx.conf、HOCON）與 EMQX_ 環境變數的優先權，最後帶到 Secret（敏感值）與 add-on 的 env_vars 用法。讀完，你改任何設定都不會再東猜西猜。

核心概念

EMQX 的設定分「靜態」與「動態」兩類目錄。

• 靜態設定 etc：通常是唯讀，放在主設定檔（例如 emqx.conf）；主要在部署或升級時改。
• 動態設定 data/configs：可寫，把你從 Dashboard、REST API、CLI 做的變更儲存到 cluster.hocon。

優先權從低到高是：base.hocon（5.8.4 起才有）＜ cluster.hocon ＜ emqx.conf ＜ 環境變數。也就是說，越後面越高。

Dashboard 的 Management 模組就是「動態調整」的入口：Cluster Settings、MQTT Settings、Logging、Monitoring 等都可以在執行中不重啟就套用。

名詞對照

動手做

1. 進 Cluster Settings 看動態設定

   左側 Management → Cluster Settings，這裡可調整 MQTT、Listener、Logging 等設定，儲存後立即生效。

2. 用 add-on 的 env_vars 追加環境變數

   Home Assistant → 左側 EMQX add-on → 組態（Configuration）。在 env_vars 填 name 與 value；add-on 只接受以 EMQX_ 開頭的變數名，改完後記得重啟。

3. 用環境變數覆蓋一個預設值

   例如要改節點名，填 EMQX_NODE__NAME（雙底線代表設定層級）。存檔後重啟 add-on，再看 Dashboard 數值。

4. 若需要「靜態」設定檔

   進 add-on 的「資料」目錄可以看到 /data/emqx/etc/emqx.conf。除非必要，不手動改，因為 Dashboard 寫的都落在 cluster.hocon。

設定檔：HOCON 與優先權

從 EMQX 5.0 起用 HOCON 格式（是 JSON 的 superset，可用巢狀物件或扁平路徑寫）。

node {
  name = "[email protected]"
  cookie = "<你的cookie>"
}

也可以寫成扁平：node.name = "[email protected]"。

實際的優先權如果沒特別記，很容易混亂。重點是「後出現優先」與「高層優先」：base.hocon 最弱、環境變數最強。若你在動態調整寫的是 cluster.hocon，但同一項目在 emqx.conf 或環境變數裡另有設定，重啟後可能被改回去。

建議：不要在 emqx.conf 與 cluster.hocon 同時寫同一項目，以免重開後數值回到其中一端。

EMQX_ 環境變數與 add-on env_vars

環境變數與設定檔的轉換規則：

• 設定檔用點（.）分隔層級，環境變數用雙底線（__）。
• 變數名稱一律以 EMQX_ 開頭。
• 值會以 HOCON 解析，因此可傳入複雜型態。

Woow EMQX add-on 在 config.yaml 定義了 env_vars 組態。範例：

env_vars:
  - name: EMQX_NODE__NAME
    value: "[email protected]"
  - name: EMQX_LISTENERS__TCP__DEFAULT__MAX_CONNECTIONS
    value: "1000000"

存檔後重啟 add-on 才會生效。

Secret 管理：別踩 HOCON 的註解坑

EMQX 的設定有「Secret」型別，用來存密碼與 token 這類敏感值。在 add-on 或 Dashboard 的欄位輸入時，一律以佔位符（例如 <你的密碼>）代替實值，不寫實際秘密。

一個常見的坑：HOCON 裡 `#` 是註解開頭。若密碼含 #，例如 MQtt#123，沒有加引號，解析器會把它當成 MQtt，`#123` 會被當成註解丟掉。要用「HOCON 層級雙引號」把它包起來，才能保留整個字面值：

export EMQX_DASHBOARD__DEFAULT_PASSWORD='"MQtt#123"'

含 : 或 = 的值也要比照。URL 編碼（如 %23）不適用——EMQX 不會解開環境變數的 URL encoding。

故障排除

• 改了設定，重開後又被打回原形：多半是 emqx.conf 或環境變數的優先權較高。把要用的值改到高一層（例如環境變數），把它固定住。
• env_vars 不生效：先確認變數名以 EMQX_ 開頭且用了雙底線（__）；存檔後要重啟 add-on。名字拼錯會在啟動 log 裡看到 warning。
• 密碼含 # 卻被截斷：因為 HOCON 把 # 當註解。把它加上一層雙引號整體存進去（連引號），不要只貼原值。
• 找不到要改的設定：先判斷它是 Dashboard 可動態調、還是在設定檔裡的靜態項目。前者用 Management；後者去 emqx.conf 或用環境變數。

常見問題

官方來源

• EMQX 5.8 設定檔與環境變數（pinned docs 分支）
• EMQX 5.8 Management 動態設定（pinned docs 分支）
• Woow EMQX add-on README（pinned commit）
• Woow EMQX add-on config.yaml（env_vars）