Listeners 與 TLS

為什麼要學這個

到目前為止，你連線多半用純 TCP 的 1883，但 EMQX 5.8.9 的一個特色，就是同一個 broker 可以同時監聽多個「出口」：標準 MQTT（TCP）、WebSocket、安全 WebSocket、以及走 SSL/TLS 的加密連線。你想讓某些裝置走加密、Home Assistant 走 WebSocket、測試走 1883，就得看懂這些監聽器（Listener）是誰、如何新增與編輯，以及最重要的憑證概念。

這章帶你看看五個埠各自用途、在 Management → Listeners 新增／編輯監聽器、理解 SSL/TLS 與 mTLS 的單向與雙向驗證；還有家用最常絆腳的連接埠衝突（Mosquitto 卡 1883、WebRTC 卡 8083）該怎麼在 Dashboard 安全地遷移。

核心概念

監聽器（Listener）是 EMQX 對外接受 MQTT client 連線的「伺服端監聽點」：每一個都有傳輸協定（TCP／SSL／WebSocket／WSS）＋綁定位址與埠，並可設定這支監聽器能接受多少並發連線（max_connections）。EMQX 一個實例同時可以啟動多支監聽器，因此你能讓不同用途的 client 走不同協定與埠。

官方文件明確列出四種主要傳輸：TCP（1883）、SSL（8883）、WebSocket（8083）、Secure WebSocket（8084）。Dashboard 管理介面本身則由 add-on 開在 18083（HTTP），所以你日常常講的「五個埠」是：1883、8083、8084、8883 與 18083。

要連進加密入口，client 會自動做 SSL/TLS 交握，驗證 server 憑證。它區分單向驗證（client 驗 server）與雙向驗證（mTLS）（server 也驗 client 的憑證）。這章後段把憑證與交握說清楚。

名詞對照

動手做

1. 瀏覽現有監聽器

   登入 Dashboard，左側 Management → Listeners。你可以在這裡看到既有監聽器，例如 TCP（1883）、SSL（8883）、WebSocket（8083）、WSS（8084），各有對應的協定與埠。用 Add（新增）也可以建立新的監聽器。

2. 編輯 SSL 監聽器並換憑證

   在 Listeners 列表點 SSL 監聽器的 Name（例如 default），進編輯頁。該頁可更換 TLS Cert（伺服器憑證）、TLS Key（對應私鑰）與 CA Cert（信任的 CA）；EMQX 預設使用內建的測試憑證（在 etc/certs）。改完按 Update。

3. 啟用／關閉 mTLS 交握

   在同頁的 TLS Verify 開關決定是否要驗證 client 憑證（雙向）；要強制 mTLS，就把 TLS Verify 設為 Enable、並把 Fail If No Peer Cert 設為 true，這樣沒有憑證的 client 在交握階段就會失敗。

4. 處理連接埠衝突

   若某一埠（如 8083 被 WebRTC 用）卡住，先暫停衝突的一方，再到 Listeners 頁把該監聽器的埠改掉並 Update。注意：若監聽器是由 emqx.conf 定義的，Dashboard 的變更只會生效到下次 EMQX 重啟之前。

五個埠與協定

因為 add-on 以 host_network 模式開在 Home Assistant 主機上，這五個埠直接用到 HA 的連接埠。核心對照如下。

照文件說法，WebSocket 監聽器的 MQTT path 預設是 /mqtt。你可能有些裝置只用 1883，另一些走 8883 加密；web 瀏覽器若要塞網頁，就走 8083（或 8084 的安全版）。你並不需要同時把五個都顧著，加裝需求逐一選一個「用得上」的即可。

TLS、憑證與 mTLS

TLS（Transport Layer Security）在傳輸層加密資料，EMQX 把它用在 MQTT 連線、資料整合往外部資源、以及叢集節點之間，都可以單向或雙向。單向（one-way）時 client 驗證 server 的身分憑證；雙向（mTLS）時 server 還要驗證 client 的憑證，可防中間人攻擊。

SSL/TLS 需要三支檔案：certfile（伺服器憑證）、keyfile（對應的私鑰）與 cacertfile（受信任的 CA 清單）。EMQX 出貨自帶一組只用於測試的憑證（在 etc/certs），所以你看的 8883 監聽預設是「單向」可用的測試環境。要上線務必要換成受信 CA 簽發的憑證（例如你家網域＋可被信任的 CA），私鑰只放系統與你自己看。

mTLS（雙向）的實作，就是把 SSL 監聽器的 TLS Verify 打開、並把 Fail If No Peer Cert 設為 true，強迫每個 client 握手都要提供受信任的憑證。另外，EMQX 預設每 120 秒重新載入憑證，所以更換 server 憑證不一定需要重啟 EMQX。

連接埠衝突與遷移

因為 host_network，這五個埠與 Home Assistant 主機上的其他服務共用編號，最常見的衝突，要談兩個例子：官方 README 明說「無法與 Mosquitto 同時運行」（兩個都盯 1883），以及 WebRTC（AlexxIT）與 EMQX 共用 8083。

處置的流程照 add-on README：先暫停衝突的一方（如 Mosquitto），再啟動 EMQX；若想兩者共存，就到 Management → Listeners 把衝突監聽器的埠改掉或新增一支監聽器定在別的埠，再重新啟動該服務。也可以完全只保留你需要的 listener（例如只開 1883 與 8883），把不用的埠關掉，減少被掃描的攻擊面。

要注意官方文件的一條提示：若監聽器在 emqx.conf 中被定義，Dashboard 上的變更只會生效到下次 EMQX 重啟為止。想讓啟動後就固定生效，就得用設定檔或環境變數（add-on 的 EMQX_LISTENERS__* 環境變數在第 17 章談）。

故障排除

• EMQX 啟動失敗、Log 顯示「連接埠被佔用」：找出是哪一埠，暫停衝突的 Mosquitto（1883）或 WebRTC（8083），再啟動 EMQX；之後想長期共存，再到 Listeners 把其中一方的埠改掉。
• 換憑證後 8883 一直連不上：確認 certfile／keyfile 成對、CA 與 server 憑證是 PEM 格式，且 server 憑證的 CN（或 SAN）與 client 連線的位址相符（否則會見 Hostname/IP does not match certificate 的錯誤）。可在 Listeners 用 Reset 換回測試憑證，用來隔離問題。
• 啟用 mTLS 後無憑證 client 全部斷掉：這是 mTLS 的預期——雙向就是堅持 client 提供「受信任憑證」。若你只是想暫時不嚴，把 TLS Verify 關回單向，或先幫該 client 簽發一張受信任的用戶端憑證。
• 在 Dashboard 改了埠，重啟後又變回原本：多半是該監聽器由 emqx.conf 定義，Dashboard 變更只到重啟前。想持久，用 add-on 環境變數（EMQX_LISTENERS__*）在啟動時覆寫，細節在第 17 章。

常見問題

官方來源

• EMQX 5.8 Listener Configuration（四協定與埠）
• EMQX 5.8 Enable SSL/TLS（單向／雙向 mTLS）
• EMQX 5.8 Client TLS 連線範例
• EMQX 5.8 Network and TLS 總覽
• Woow EMQX add-on README（連接埠與衝突）