需求盤點
- 你目前有多少 MQTT 客戶端與訂閱？預估一年內會成長到多少？
- 訊息量是每分鐘幾百則，還是需要高輸送量的裝置骨幹？
- 需不需要規則引擎、資料外送（Connector／Sink）或跨 broker 橋接？
- 是否只有一台 Home Assistant，還是想預留叢集／多節點擴充？
WoowTech · EMQX 5.8.9
先比功能與規模，再談導入
這份手冊協助你做探索會議、需求盤點、與 Home Assistant 內建 Mosquitto 的比較、分階段部署與驗收。EMQX 5.8.9 是開源 MQTT Broker，不是「什麼都做」的平台；本頁不誇大效能承諾，只列可驗證的差距與你的下一步。
探索會議先問什麼
現況與責任
- 現在是否用 Home Assistant 內建 Mosquitto？遷移的停機窗口多大？
- 誰負責維護 EMQX、備份 /data/emqx 與憑證輪替？
- 有沒有 Zigbee2MQTT、ESPhome 或其他 client 已經接在某個 broker？
- 管理 Dashboard 要由本機 HA 開啟，還是需要獨立 URL？
EMQX 與 Mosquitto 的定位
Home Assistant 內建 Mosquitto 是「夠用就好」的入門 broker；EMQX 5.8.9 是「可成長、可管理、可整合」的訊息骨幹。兩者都講 MQTT，差別在管理面與擴充面。
| 面向 | Mosquitto（HA 內建） | EMQX 5.8.9 |
|---|---|---|
| 介面 | HA 整合畫面的選項與寫入 HA 設定檔 | 完整 Dashboard：使用者、ACL、Listeners、規則、監控一頁在手 |
| 驗證與授權 | 以普通使用設定為主 | Password-based Built-in Database、JWT、HTTP／LDAP 認證概念＋ ACL 主題規則 |
| 規則與資料整合 | 需自行外寫程式 | 內建 SQL 規則引擎、Actions（republish／console）、Connector／Sink／Source |
| 監控與維運 | 簡易狀態、仰賴 HA 面 | Overview、Metrics、客戶端清單、Log＆Trace、RBAC（僅 Enterprise）、Health Check |
| 適合 | 入門、定量的標準訂閱 | 多客戶端、需要規則、需要監控與成長照顧 |
銷售用語：說「EMQX 在管理面、規則面與監控面多了這些能力」，不要說「Mosquitto 不好」或「EMQX 一定更快」。效能與規模要看你的實際負載驗收。
規模判斷
規模不是只看裝置總數。請同時記錄客戶端數、訂閱數、每則訊息大小、保留訊息、規則命中次數、連線頻率與 HA 主機資源。EMQX 5.8.9 的實際限制由你建的 Listener 數、QoS──訂閱負荷與硬體決定，先用代表性的資料集壓測，不把單次成功外推成保證上限。
| 指標 | 為什麼重要 |
|---|---|
| 客戶端與訂閱數 | 決定會話、保持連線與 ACL 規則的負載。 |
| 訊息速率 | 決定閘道能跟不上，還是規則引擎忙。 |
| 保留訊息 | 大量 retained 主題佔記憶體與樹。 |
| 規則與 Connector | SQL 規則、HTTP Sink 的吞吐與延遲是另一層。 |
| 持久層 | HA 主機記憶體、磁碟、網路是共同此案的瓶頸。 |
建議部署階段
- 發現與基線：鎖定 EMQX 5.8.9 與 add-on 5.9.0，盤點現有 broker、遷移權責與功能清單。
- 實驗室試點：以少量開發工具或測試用 publish／subscribe 驗證 Dashboard、驗證、ACL 與規則。
- 同網段遷移：把現有 HA 重要訂閱一條條搬到 EMQX，逐一驗證 Zigbee2MQTT、QoS 與 will。
- 分批上線：依區域或風險分批切換，每批保留備份、回復點與變更紀錄。
- 營運移交：交付備份、憑證輪替、監控基線、升級與責任分工與定期複驗。
主要風險與控制
| 風險 | 影響 | 控制方式 |
|---|---|---|
| 連接埠衝突 | 與 HA Mosquitto 或其他 broker 搶 1883 | 先停用或改 HA 的 Mosquitto 連接埠，再安裝 EMQX；在 Listener 設好。 |
| 誤把 add-on 5.9.0 當成 EMQX 版本 | 升級判斷錯誤 | 教學、銷售一律寫 EMQX 5.8.9 + add-on 5.9.0。 |
| 驗證／ACL 未設 | 任何 client 都可讀寫 | 首登改密碼，建 Auth 與最小權限 ACL。 |
| 宿主網暴露 | Broker 經 host_network 或 ngrok 被看到 | 不直接開公網 1883；要外連用 TLS、ngrok 風險說明。 |
| 規則寫錯 | 訊息被覆寫或發送到錯的地方 | 先在 console output 測試，確認再放行。 |
安全與資料界線
- MQTT 密碼、client ID、username、API key、ngrok authtoken、TLS 私鑰與連線字串一律用佔位符，不進 HTML／log／commit。
- Dashboard 管理面不要直接暴露到公網；用 Home Assistant 的「開啟 Web UI」Ingress 或其他最小化代理。
- 對外開放 1883 前，先講明公開 broker 的風險與 TLS 要求；最小化 Rate Limit 與權限。
- 首次設定驗證（Authentication）是最低界線，不把它描述成任意防護。
- 備份範圍 =
/data/emqx（資料、ACL、驗證、規則設定）；還原前先告知影響面。
驗收清單
功能驗收
- Dashboard 顯示 EMQX 5.8.9 版本；add-on 顯示 5.9.0。
- MQTT 使用者在 Dashboard 建立後可用認證連線。
- ACL 主題規則照最小權限生效，顯示拒絕的 logs。
- 一條規則能在 console 輸出觸發成功，再轉到 Sink。
- HA 內建 Mosquitto 遷移後原有訂閱仍在。
營運驗收
- 備份可從
/data/emqx復原。 - 對外 Listener 已設定 TLS 或明確不開放。
- 監控基線（Clients、訊息、節點資源）已留存。
- 連接埠衝突、閘道不穩、驗證失效有可執行 runbook。
- 與 Mosquitto 的差距、未驗收項目列為例外。