完整疑難排解
EMQX 完整疑難排解：無法啟動、無法連線、Dashboard 進不去、連接埠衝突、資源不足、驗證失效的症狀、檢查與安全修復。
為什麼要學這個
EMQX 出問題時，最怕的不是「壞掉」，而是不知道從哪裡開始看。很多人一看到 add-on 開不起來就整包移除重裝，結果把設定清光、帳號也消失。正確順序是先看 Log、確認埠、再檢查資源——多數問題其實是這三個根源。
讀完這章，你會有四組「症狀 → 檢查 → 安全修復」清單：無法啟動、無法連線、Dashboard 進不去、資源或連接埠被吃光。你也能分辨哪些是設定失誤、哪些是環境限制，不再靠盲猜。
核心概念
先建立診斷的順位。Woow add-on 的 README 與 EMQX 文件共同的建議是「從 Log 開始」：Log 會告訴你啟動失敗的真正原因，而不是只看到加載旋轉。
看 Log
add-on 的 Log 顯示啟動過程、ngrok 狀態與 EMQX 錯誤。多數「啟動失敗」都能在這裡找到原因。
確認連接埠
1883、18083 若被其他 add-on 占用，EMQX 就無法監聽。先確認 Mosquitto、WebRTC 等是否還在跑。
看資源
EMQX 比 Mosquitto 吃得多。記憶體不足會讓 add-on 反覆重啟或無法啟動。
修復的每一步都應是「安全的最小動作」：不隨意刪資料、不默默把埠搬到全網。真要動資料前，先備份。
名詞對照
| 英文 | 中文 | 一句話 |
|---|---|---|
| Symptom | 症狀 | 你觀察到的異常現象 |
| Diagnosis | 診斷 | 找出根因的過程 |
| Safe Fix | 安全修復 | 不刪資料的小幅調整 |
| Log | 記錄檔 | add-on 啟動與錯誤的日誌 |
| Port Conflict | 連接埠衝突 | 兩個服務搶同一個埠 |
| Resource Limit | 資源上限 | RAM／CPU 不足壓迫 add-on |
建立診斷基線
先確認 add-on 是否真的啟動
到 Home Assistant 的 Woow EMQX 一頁，看狀態是「啟動」或反覆重啟。反覆重啟常在 Log 顯示端口或記憶體原因。
檢查 1883 與 18083
確認沒有 Mosquitto 或 WebRTC 占用 1883／8083，EMQX 才不會在啟動時因監聽被佔而退場。
用 Log 搜關鍵字
在 add-on Log 搜「address already in use」「不能 binding」或「out of memory」等，可以很快縮窄問題。
測試一個已知的 MQTT client
用後端的小工具（WebSocket client、或你的 HA MQTT）連 1883，若連得上表示 broker 有收連線；若連不上，就看驗證是否成立、埠與位址是否正確。
無法啟動與資源不足
症狀：add-on 啟動後很快掉回「已停止」，或一直卡在啟動。
- 檢查：先看 Log；接著確認連接埠是否被其他服務占用（Mosquitto 用 1883、WebRTC 用 8083），也確認主機記憶體還夠。
- 安全修復：先停掉衝突的 add-on 或減載，再一次啟動 EMQX。若記憶體不足，就關閉其他吃資源的 add-on。不要動資料目錄。
EMQX 比 Mosquitto 需要更多 RAM／CPU；Woow README 建議至少 512MB RAM。若你的主機同時跑影片或 AI 服務，先縮減再加。
無法連線與驗證失效
症狀：HA、Z2M 或外部裝置連 1883 掉；或錯誤是「驗證失敗」。
- 檢查：確認 EMQX 已設定 Authentication；確認使用的帳號密碼在 built-in database 裡存在且正確；確認 broker 位址（homeassistant、1883）無誤。
- 安全修復：若驗證未設好，先建立使用者；若帳號被誤改，重新建立並改用正確密碼。勿把真實密碼印進 Log 回答中。
特別注意：EMQX 若「尚未設定認證」，會允許 all client 連線——那不是正常連上的證明。要嘛設驗證，要嘛關閉匿名。
Dashboard 進不去／連接埠衝突
症狀：點「開啟 Web UI」沒有畫面，或打不開 18083。
- 檢查：18083 是否被其他服務占用；add-on 是否在啟動狀態；Ingress 是否真的可達。
- 安全修復：用 Home Assistant 左側的 EMQX 圖示（Ingress）進；停止或調整與 18083 衝突的服務；重啟 add-on 後再試。
Dashboard 是控制整個 broker 的入口。若你想直接連 18083 來用，記得確認它沒有暴露在公網。
快速修復對照表
- 症狀：add-on 無法啟動，Log 出現端口占用→先停掉 Mosquitto 或 WebRTC；確認 1883／8083 空出後再啟動。
- 症狀：無法連線、老是認證失敗→確認 Authentication 已建立、帳密正確、broker 位址與端口無誤；不要把預設 public 繼續使用。
- 症狀：Dashboard 打不開→用 Ingress 進；若直打 18083，確認沒有端口衝突、且不被公網直接暴露。
- 症狀：連線一陣子就斷→檢查資源上限與 Rate Limit；EMQX 比 Mosquitto 吃資源，主機若記憶體吃緊會影響穩定性。
- 症狀：ngrok 已啟用但無公開 URL→見第 19 章：檢查 authtoken、重啟、看 ngrok service log。
常見問題
重裝 add-on 會不會比修好更快
很多時候並不會更快。要注意：升級 add-on 不會清資料，重裝（尤其是移除後重裝）則可能一併清掉。先看 Log 確認不是簡單能修的原因，再考慮重裝；真要動手，先備份 /data/emqx。
1883 被誰占用該怎麼查
通常是 Mosquitto（1883）或 WebRTC 整合（8083）。檢查 Home Assistant 的 add-on／整合清單，把衝突者暫停即可。
記憶體不足時該怎麼判斷
看 add-on Log 裡的「out of memory」或「系統 RAM 不足」之類訊息。建議至少 512MB。多吃資源的 add-on 暫停時，EMQX 較容易穩定。
外部無法連上，是 EMQX 還是我的網路問題
先用同一網路的 client 測試內網連線；內網可連而外網不行，就回到路由器／ngrok 或防火牆。若連內也失敗，多半是驗證或監聽埠的設定。