MQTT

MQTT 將您的 Meshtastic mesh 網路橋接至網際網路，實現超越無線電範圍的長距離通訊。

概觀

MQTT 模組可將您的節點連接至 MQTT 代理伺服器，實現以下功能：

透過網際網路傳送訊息至不同實體 mesh 網路上的節點
與智慧家庭自動化及監控系統整合
將節點位置發布至公開的 Meshtastic 地圖
自訂資料管線，用於記錄與警示通知

運作方式

〔您的節點〕→ 無線電 → 〔具備 Wi-Fi 的閘道節點〕→ MQTT 代理伺服器 → 〔遠端閘道〕→ 無線電 → 〔遠端節點〕

具備網際網路連線（Wi-Fi 或乙太網路）的閘道節點，將 mesh 訊息發布至 MQTT 主題。訂閱相同主題的遠端閘道，將這些訊息注入其本地 mesh 網路。

設定

啟用 MQTT

前往「設定 → 模組設定 → MQTT」。
啟用 MQTT 模組。
設定代理伺服器連線：

MQTT toggle switch

設定	描述說明	默認
伺服器位址	MQTT 代理伺服器主機名稱	mqtt.meshtastic.org
使用者名稱	代理伺服器驗證	meshdev
密碼	代理伺服器驗證	large4cats
根主題	訊息的基礎主題	msh
加密	加密 MQTT 承載內容	已啟用
~~JSON 輸出~~	⚠️ 已棄用——韌體已移除 JSON 封包支援；此欄位將被忽略	已停用
TLS	與代理伺服器的安全連線	已停用
地圖回報	將位置回報至公開地圖	已停用

預設 Meshtastic 代理伺服器

社群在 mqtt.meshtastic.org 維護一個公開的代理伺服器。此伺服器供一般使用與測試之用。

🔒 隱私：公開代理伺服器上的訊息，任何訂閱者均可讀取。私人通訊請務必啟用頻道加密。

私有代理伺服器

為了獲得更好的隱私保護與控制權，您可以自行架設 MQTT 代理伺服器：

Mosquitto（輕量、開放原始碼）
HiveMQ
EMQX

請將您的節點設定為指向私有代理伺服器，並輸入相應的登入憑證。

地圖回報

啟用地圖回報後，您的節點將把位置發布至 Meshtastic 社群地圖：

可在〔meshmap.net〕(https://meshmap.net) 及類似的社群地圖服務上查看
僅分享位置與節點資訊
若不希望位置公開顯示，請停用此功能

上行 vs 下行

方向	描述說明
上行	訊息從 mesh 網路 → MQTT 代理伺服器
下行	訊息從 MQTT 代理伺服器 → mesh 網路

可依頻道設定哪些方向為啟用狀態，以控制訊息流向與無線電佔用時間。

訊息格式

MQTT 使用 protobuf 訊息格式：

格式	描述說明	使用情境
Protobuf	二進位 Meshtastic protobuf 編碼	節點間 mesh 橋接

⚠️ 注意：韌體已移除 JSON 輸出支援。 Json_enabled 設定在應用程式中仍會顯示，以維持舊版相容性，但對目前的韌體版本不會產生任何效果。

加密與隱私

了解分層加密模型：

頻道加密在 mesh 網路上進行，發生於 MQTT 傳輸之前。若您的頻道已設定 PSK，MQTT 承載內容將已加密——代理伺服器及任何訂閱者只能看到密文。
MQTT 加密（模組設定）在傳輸至代理伺服器的過程中新增額外的加密層。此設定可保護中繼資料與路由資訊。
TLS 對連接至代理伺服器的 TCP 連線進行加密，防止網路層級的竊聽。

🔒 重要：預設公開頻道使用眾所周知的金鑰。透過 MQTT 傳送的預設頻道訊息實際上等同於未加密 — 任何人均可解碼。私人通訊請務必使用自訂 PSK。

最佳實踐

在橋接至 MQTT 的頻道上使用頻道層級加密（PSK）
請勿在無法連接網際網路的節點上啟用 MQTT（這將導致緩衝堆積並浪費記憶體）
敏感部署環境請使用私有代理伺服器
從繁忙的 MQTT 主題下行訊息時，請留意無線電佔用時間——每則下行訊息都會消耗本地 mesh 網路的無線電佔用時間
若僅需遠端監控 mesh 網路而不需注入訊息，建議僅啟用上行模式

故障排除

MQTT 無法連線

檢查 Wi-Fi——閘道節點必須具備有效的網際網路連線（Wi-Fi 或乙太網路）。 MQTT 無法直接透過 LoRa 無線電連結運作。
確認登入憑證 — 帳號或密碼錯誤在大多數代理伺服器上會靜默失敗，不顯示錯誤訊息。請仔細確認是否有多餘的尾端空白字元。
防火牆 — 連接埠 1883（MQTT）或 8883（MQTT+TLS）必須開放。部分網路會封鎖非標準連接埠。
DNS 解析 — 若使用自訂代理伺服器主機名稱，請確認節點能夠正確解析該名稱。請嘗試直接使用代理伺服器的 IP 位址進行連線。

訊息未正常橋接

檢查上行／下行設定 — 若僅啟用上行，訊息只會從 mesh 網路流向 MQTT，不會反向傳送。請在接收端閘道上啟用下行功能。
頻道不符 — 兩個閘道必須使用相同頻道且具備相同的 PSK。不符時，訊息將以不同金鑰加密，導致對方收到的內容為亂碼。
主題不符 — 請確認兩個閘道使用相同的根主題。預設的 msh 適用於公開代理伺服器。