備份、還原與更新
EMQX 備份、還原與更新：/data/emqx 資料範圍、驗證／ACL／資料整合設定備份、還原流程、add-on 更新，以及 Mosquitto 遷移。
為什麼要學這個
EMQX 日積月累會累積兩種你不想丟掉的東西：設定與資料。設定是 Authentication、Authorization（ACL）、規則與 Connector／Sink 這些架構；資料則是 built-in database 裡的帳號、API key、黑名單與 retained 訊息。哪天你誤改一個 ACL 斷了全家的燈，或 Home Assistant 主機要換機，沒有備份就等於從零重建。
讀完這章，你會知道 add-on 的資料集中在哪、哪些檔要跟著備份、還原時回到那一步，也能安全地走完 add-on 更新，以及把 Mosquitto 換成 EMQX 時該搬哪些東西。
核心概念
EMQX 把運行資料集中在 資料目錄（data dir），add-on 把它放在 /data/emqx 底下。拆開來看有三塊：/data/emqx/data（EMQX 資料、內建資料庫的持久化）、/data/emqx/etc（設定檔）、與 /data/emqx/plugins（外掛）。記錄檔則寫在 /config/log，不在上述備份範圍內。
Home Assistant 的備份（Backup）涵蓋 add-on 的 /data，是最省事的整包還原。想用檔案層級的方式帶走設定，也可用 EMQX 的 CLI：emqx ctl data export 把設定與內建 DB 打包成 emqx-export-YYYY-MM-DD-HH-mm-ss.sss.tar.gz，寫在資料目錄的 backup 子資料夾；emqx ctl data import 把它灌回。
另外要注意版本語意：add-on 5.9.0 只新增 ngrok TCP 通道，核心仍是 EMQX 5.8.9。看到 add-on 商店有新版，未必代表 broker 版本躍遷——以 CHANGELOG 為準。
名詞對照
| 英文 | 中文 | 一句話 |
|---|---|---|
| Data Directory | 資料目錄 | EMQX 存放資料與設定的目錄 |
| Backup | 備份 | 把資料複製保存，以便之後還原 |
| Restore | 還原 | 把備份內容灌回 EMQX |
| Export | 匯出 | CLI／介面把設定打包成檔案 |
| Mnesia | 內建資料庫 | EMQX 內建的 Erlang 資料庫，存帳戶與 ACL |
| Migration | 遷移 | 把舊 broker（如 Mosquitto）配置轉成 EMQX |
備份涉及密碼與 token 的人會更要注意安全：任何含帳密或 API key 的備份檔，都應存放在只有你能讀的地方，不要放進 repo 或公開位置。
動手做
用 Home Assistant 建立備份
到 Home Assistant 的設定 → 系統 → 備份，按「立即備份」。完整備份會納入 add-on 的
/data，也就涵蓋/data/emqx。把備份檔同步到安全位置。（可選）用 EMQX CLI 匯出設定包
在 add-on 終端或容器內執行
emqx ctl data export，會產生emqx-export-*.tar.gz，提供檔案層級的攜帶方式，適合想單獨存設定或搬到相同版本的 EMQX。還原的順序
要還原整台主機就直接回復那個備份。若你只換 EMQX（重裝後），先停掉 add-on、把
/data/emqx的內容放回對應位置，再啟動 EMQX；最後確認 Dashboard 裡的帳號與 ACL 都在。更新 add-on
在附加元件頁按下方的「檢查更新」，出現新版（例如 5.9.0）才按更新，更新完依提示重新啟動。更新前先做一份備份；若只是新增 ngrok 而不動 EMQX 核心，回歸風險相對低。
備份涵蓋哪些資料
add-on README 把「備份包含 /data/emqx 下的所有資料」列為原則。具體範圍如下表。
| 路徑 | 保存內容 |
|---|---|
| /data/emqx/data | EMQX 資料、內建資料庫（Mnesia）的持久化 |
| /data/emqx/etc | EMQX 設定檔（含 listener、認證、整合等 rewrite） |
| /data/emqx/plugins | 外掛檔案 |
| /config/log | 記錄檔（不在備份範圍內） |
對照 EMQX 文件，export tar 的內容通常涵蓋：認證與授權設定、資料整合（Rules／Connectors／Sinks／Sources）、Listeners 與 Gateway 設定、內建資料庫（Dashboard 使用者與 REST API key、用戶端 password-based 認證與 enhanced authentication、PSK、Authorization 規則、Blacklist）、以及 retained 訊息。放在資料目錄內的 TLS 憑證與 ACL 檔也會一起搬。
若你的憑證檔或 ACL 檔案放在資料目錄「外頭」，那兩者就不在包內，還原前要手動搬回。這正是很多人在還原後「明明打了備份卻少了 ACL」的常見原因。
還原與 CLI 匯入
若採用 CLI 匯入，帶回的檔可寫絕對路徑、相對路徑，或放在資料目錄的 backup 子資料夾後只給檔名。EMQX 5.8 的文件列了幾個硬性條件：
- 匯入時 EMQX 節點必須在運行中。
- 若為 core＋replica 叢集，只在 core 節點做匯入。
- Enterprise 版匯出的資料不能匯入 Open Source。
- 匯入的檔案不能改名。
匯入的語意是「補進去、會更新」，不會刪除既有的其他資料。少數情況可能與既有資料不相容，例如認證方式（salt position、密碼儲存模式）不同，匯入後舊使用者憑證可能失效。所以先備份、再小心還原是正路。
如果你用的是 EMQX Enterprise，Dashboard 的 System → Backup & Restore 也能建立與還原備份檔；但 Woow 這個 add-on 內建的是 5.8.9 Open Source，較大機會以 CLI 或主機層級的備份為主。
Mosquitto 的遷移重點
把 Home Assistant 從 Mosquitto 換到 EMQX 時，最重要的是「連接埠 1883 只有一個贏家」：Mosquitto 與 Woow EMQX 無法同時運行，都綁 1883。
停掉 Mosquitto
把 Mosquitto add-on 停止（或移除），空出 1883。
把設定搬到 EMQX
在 EMQX 重新建立相同的使用者（在此可以沿用之前設定的帳密），並把 ACL 規則重新實作——EMQX 用 Access Control 管理。
指到 EMQX
把 HA 的 MQTT 整合、Zigbee2MQTT 與各外部裝置的 broker 位址改成 EMQX（homeassistant、1883），帳號用 EMQX 的使用者。
驗證與最後收尾
確認 HA、Z2M 與所有裝置都連上，Clients 頁可見。若舊 Mosquitto 有長期累積的 ACL，逐一審查、轉成 EMQX 的 Authorization 更能避免誤放。
備份這層原則在這裡同樣適用：遷移前先為舊 Mosquitto 的設定留一份現況，遷移失敗時還能退回。
故障排除
- 備份裡找不到 /data/emqx：請確認 Home Assistant 備份包含 add-on 資料（有的情況你會只備份系統或某些 add-on 資料）。若只換 EMQX、要用檔案層級還原既有設定，改用 CLI export 比較可控。
- 還原後 Dashboard 進不去：檢查 1883／18083 是否被其他服務占用，先停衝突者；再看 Log，確認資料目錄放回的位置正確。
- CLI 匯入報「找不到檔案」：匯入檔不能改名；若放在 backup 子目錄，用 basename 即可。路徑若為相對路徑，需以 EMQX 根目錄為基準。
- 更新後版本好像沒變：先看 CHANGELOG。add-on 5.9.0 只是多 ngrok TCP，EMQX 核心仍是 5.8.9。若你期待的是核心新功能,可能要再看版本。
常見問題
備份一定要用 Home Assistant 快照嗎
不用太費心。先把「完整 Home Assistant 備份」養成習慣最實在；想帶著設定到另一台同版本 EMQX 時，再用 emqx ctl data export/import 這組 CLI。
還原後我的 MQTT 帳號還在嗎
只要備份含內建資料庫（emqx_authn_mnesia），password-based 的使用者就會還原。若之前用 file／HTTP 等外部認證,請確認設定與資料是否也在備份裡。
add-on 更新會不會清空我的設定
不會，前提是 /data 沒被替換。升級 add-on 不會刪除資料目錄；但每次升級前仍建議先做備份,以便萬一新版行為不如預期時可回退。
從 Mosquitto 搬過來最常漏掉什麼
通常是 ACL 與「把整合指向 EMQX」。Mosquitto 沒圖形介面,ACL 存在設定檔；搬到 EMQX 要在 Access Control → Authorization 重新建立。記得同時把 HA MQTT、Z2M 與外部裝置的 broker 位址都改掉。