備份、復原、遷移與完整疑難排解
先分清 Bridge 設定備份與完整 identity snapshot 的精確範圍，再演練 preview、選擇性 restore、遷移與回退；最後用「症狀 → 檢查 → 安全修復」處理配對、No Response、mDNS、failed entities、低資源與災難重設。
能下載檔案，不等於能復原
Matter Bridge 的可復原狀態至少包含 Bridge config、entity mappings、Matter identity／Fabric credential、每座 Bridge 的 Plugin enabled／disabled state 與部分管理資產。遺漏 identity 時，Bridge 設定雖可重建，Controller 仍需重新 commissioning；同一份 identity 同時在兩台主機啟動，又會造成重複服務與難以預測的 session／mDNS 行為。
Stable 2.0.55 Settings 的 Backup & Restore 同時提供下載式 config／full backup、restore preview、選擇 Bridge、overwrite、include mappings、restore identity、內部 snapshots、auto backup 與 retention。Restore 可能覆寫目前設定並要求應用程式 restart；因此每次復原前還要先下載「目前」備份，保留明確回退點。
| 問題 | 需要的證據 | 安全返回點 |
|---|---|---|
| 只是設定誤改 | Bridge export／config backup、diff | 選擇性 restore，不碰 identity |
| 主機或 volume 故障 | Full backup、版本與校驗 | 停止舊端後完整 restore |
| Controller No Response | Health、session、mDNS、log | 修網路／單座 restart，不先 reset |
| 確定 identity 無法使用 | 備份不可用與 Controller 清理計畫 | 最後手段 Factory／disaster reset |
四種匯出物與精確範圍
Bridge export JSON（第 18 章）主要包含 Bridge definitions，用來搬 Filter 與基本設定。Config backup ZIP包含 backup.json 中的 Bridges 與 entityMappings，也會明確標示不含 identity；其 archive 只帶存在的 per-Bridge Plugin enabled／disabled flags，不含 bridge icon，復原後仍需重新 commissioning。
Full backup ZIP會要求加入 identity，但只在個別 Bridge identity directory 實際存在時才封入，並加入匹配 Bridge icon；Plugin 部分仍只有 per-Bridge enabled／disabled flags。includesIdentity: true 只是整體請求 metadata，不是每座都成功封入的證明。Stored snapshot採同樣條件式 identity／icon 範圍；可分 manual／auto 並依 retention 刪除舊檔。復原後要比較 identitiesRestored 與所選 Bridge 數，才可判斷身份保存是否完整。
程式碼沒有把所有 storage 資產都封入這些 archive：已安裝 Plugin packages、installed-plugins.json、per-plugin config／storage／secrets、Lock Credentials、device-images 都不在備份範圍；獨立的 mapping profile 匯出檔也不是額外自動收集資產。App Settings（例如 Basic Auth、auto recovery、backup preference）也沒有出現在 backup.json restore scope。你要另行記錄非秘密設定，資產保存可信原檔；任何秘密只進專用 secret 管理與加密備份，不寫進維運筆記。
版本、成熟度與支援邊界
| 能力 | Release channel | 產品成熟度 | Controller 支援 |
|---|---|---|---|
| Backup／preview／restore／snapshots | Stable 2.0.55 | Stable 維運能力；破壞性操作需演練 | identity 正確可保留 Fabric，但 Controller reconnect 仍受網路影響 |
| Auto Recovery | Stable 2.0.55 | Stable 設定 | 只重試 failed Bridge，不干預 running Bridge |
| Update Checker | Stable 2.0.55 | 資訊功能 | 依 Add-on／Docker／npm 顯示不同更新指引 |
| Server Mode、Camera／Security 的復原 | Stable 內可備份其相關狀態 | 實驗性（experimental-in-Stable） | 恢復資料不等於 Controller 完整支援 |
Update Checker 從 release 資訊比較 current／latest，顯示 release notes 與偵測到的執行環境；它不會自動安裝更新。更新方法必須依你的 Add-on、Docker 或 npm 部署，不要把「有新版本」寫成「已安全升級」。先讀 release notes、備份、確認回退映像／套件，再在維護窗口更新。
Auto Backup 預設啟用、retention 預設 5，而且自動 snapshot 是在 graceful shutdown 時嘗試，不是週期排程。Auto Recovery 預設啟用、interval 60 秒；UI 範圍是 10–3600 秒。它只週期性重啟 failed Bridge，也會在 HA reconnect 後觸發恢復；running Bridge 不會被碰。若根因是連接埠衝突、設定錯誤或記憶體不足，Recovery 只會產生重試紀錄，不會修好配置。
建立、驗證、復原與回退
建立備份清冊
在 Settings → Backup & Restore 建立 manual snapshot，另下載 config backup 與 full backup；記錄 HAMH 版本、日期、Bridge 數、mapping 數、是否含 identity／icon。不要在清冊抄錄任何身份或秘密值。
移出主機並驗證
把 archive 複製到加密離線位置，計算校驗摘要並測試能否開啟 ZIP、讀取 README 與 backup metadata。不要解壓 identity 到共用資料夾；測試完清除暫存。
在變更前建立回退點
升級、Plugin 安裝、遷移或 restore 前，再建立一份 current full snapshot。記錄現行 image／package 版本、storage mount 與必要非秘密 settings；確保舊版本映像仍可取得。
先做 Restore Preview
上傳可信 archive，檢查版本、建立時間、includes identity、每座 Bridge 是否 exists、mapping count。只選要復原的 Bridge；overwrite 預設保持關閉，include mappings 與 restore identity 依計畫選擇。
停止衝突來源再復原
遷移時先停止舊 HAMH，確保同一 identity 只有一個 active instance。執行 Restore，閱讀 restored／skipped／errors 計數；若 UI 要求 restart，使用 graceful restart，等待 HA 與 Bridge 穩定。
逐層驗證身份穩定
確認版本、HA connected、Bridge running、device／Fabric count、failed entities、session／subscription、mDNS interface；再用低風險 endpoint 做 Controller 到 HA 與 HA 到 Controller 的雙向測試。不要以「頁面能開」當完整成功。
失敗就回退，不連續覆寫
停止新端，保存已遮蔽 log，還原變更前 snapshot 或重新啟動舊端；一次只保留一個 active instance。若 archive 有 errors，不要接著覆寫更多 Bridge，先釐清版本、storage permission 與缺少檔案。
遷移、身份穩定與低資源操作
遷移與 identity stability
安全遷移順序是「完整備份 → 驗證 archive → 停止舊端 → 以相同 storage／完整 identity 復原新端 → 啟動單一新端 → 驗證」。Bridge ID、identity directory 與 endpoint identity 一起保留，才有機會讓 Controller 不需重新 commissioning。只複製 Bridge config，或讓 storage volume 變成空目錄，都無法達成。
Stable identity feature 與持久化 entity identity 可降低重新啟動後 endpoint 改號，但 Filter、mapping、Plugin device set 大幅改變仍可能改變 Controller 所見。遷移同時不要重命名、大改 Filter、切 Server Mode 與升級多個版本；先證明 identity 原樣可用，再逐項變更。
Settings 與 assets 清冊
另存非秘密 settings checklist：Basic Auth 由 environment 或 stored settings 提供、Auto Recovery enabled／interval、backup auto／retention、mDNS start options、base path 與 log level。秘密值只記錄「已由 secret manager 提供」，不記內容。Bridge icon 在 full backup；device image 準備原始素材；translation local override 需由原瀏覽器另外 export。
低資源操作
官方同版 Low-Resource 文件指出 HAMH 啟動會載入 Matter cluster definitions、HA registry 與 V8 overhead，endpoint 數會增加記憶體。資源有限時優先縮小 Filter、減少 endpoint、停用不需要的 auto composed、把非必要大型 Add-on 移開，並看 metrics 的 heap／RSS 趨勢與主機 OOM 訊號。
Force Sync 在 heap pressure 下可跳過；程序無 stack trace 重啟、最後只見 Killed 或 container exit 顯示 OOM 是典型線索。Plain Docker／npm 可依官方指引調整 Node heap；Add-on 由 entrypoint 動態設定，不應自行杜撰 UI 選項。Swap 是緩衝，不是解決無上限 endpoint 的方法。
| 資源壓力訊號 | 先做 | 避免 |
|---|---|---|
| heap 長期接近上限 | 縮小 entity／Bridge、檢查 Plugin | 頻繁 Force Sync |
| exit code／host OOM | 查主機事件、提高可用 RAM 或降低負載 | 只開 debug 增加負荷 |
| 大型 HA request timeout | 查 HA 負載與 message timeout 設定 | 直接 reset Fabric |
| 多 Bridge 同時啟動尖峰 | 調 Startup priority | 一再 Restart All |
更新、主機遷移與災難復原
例行更新：Update Checker 只提示版本。你先讀 release notes、建立 full snapshot、保存目前 image、更新單一環境，逐層驗證。若出現 schema／Controller regression，停止新版本並以舊版本與原 snapshot 回退，不在失敗環境繼續重設。
搬到新主機：新端先準備 host networking、IPv6、mDNS 與持久化 storage，但不要啟動同一 identity。停止舊端後復原 full backup，保持 Bridge config 與 network identity 穩定；成功後才關閉舊端回退窗口。
storage 遺失：若有驗證過的 full backup，以相同 Stable 版本復原；若只有 config backup，接受需要重新 commissioning，先在 Controller 端清理舊關係再配對。若完全沒有可用備份，才進入 disaster reset，並把 Controller、HAMH 與自動化重建列為完整專案。
症狀 → 檢查 → 安全修復
配對失敗或找不到 Bridge
檢查：Bridge running、未 commissioned 狀態、手機／hub 同區段、IPv6、mDNS bound interface、multicast 與 operational firewall。安全修復：先回簡單同網段，修正介面與 firewall，重新開 commissioning window；不要連續 Factory Reset。
配對完成後 No Response
檢查：HA connected、Fabric 是否存在、session／subscription、mDNS 是否宣告錯誤介面、Controller hub。安全修復：修共同網路，必要時先確認
autoForceSync再單座 restart／Force Sync；其他 Controller 正常時優先查該 hub 與支援。mDNS 間歇消失或重複紀錄
檢查：AP multicast／IGMP、mDNS reflector、多介面、是否曾非正常斷電、Fabric 實際數。安全修復：綁 LAN 介面、修 multicast、graceful restart 並等待 cache TTL；只有真實多餘 Fabric 才按配對清理流程。
Bridge 顯示 Failed
檢查：status reason、HA、port、storage permission、memory、Plugin。安全修復：修根因後讓 Auto Recovery 或單座 restart 重試；Recovery history 反覆失敗就停用重試並人工處理。
只有部分 entity failed
檢查：failed reason、HA unavailable、Filter、device class、mapping／composed links。安全修復：修來源或 mapping 後單座 Restart；不要把整座 Bridge reset。
Restore Preview 正常但 Restore 有 errors
檢查：每座 Bridge error、exists／overwrite、版本、archive 完整性、storage 權限。安全修復：停止後續覆寫，回復 current snapshot；在隔離副本重現，確認後只重試失敗項。
遷移後 Controller 找到兩個服務
檢查：舊主機或舊 container 是否仍 active、mDNS cache。安全修復：立刻保留單一 active instance，正常停止另一端，等待／清理 Controller cache；不要同時 reset 兩端。
低資源主機無預警重啟
檢查：metrics、host OOM、container exit、endpoint 數與大型 Plugin。安全修復：降低 entity、錯開 Bridge 啟動、增加 RAM／合適 heap；不要用更密集 Recovery 製造 restart loop。
最後手段：disaster reset
檢查：已證明 full backup 無法復原、identity 不可用，且網路／Controller 問題已排除。先把目標 Bridge 啟動為 Running；v2.0.55 對 Stopped／Failed Bridge 可能不執行 reset 就返回並 start。安全修復：保存現況 archive 與遮蔽 log，逐座在 Controller 移除舊 Bridge，再對 Running HAMH Bridge 執行 Factory Reset，並於動作後核對 Fabric／commissioning 狀態，再重建並逐座重新 commissioning；最後重建房間與自動化。任何配對資料都只在本機 UI 顯示，不抄錄到文件。
常見問題
Config backup 能保留 Controller 配對嗎？
Full backup 包含 Plugin、Lock Credentials、device images 與所有 Settings 嗎？
Auto Recovery 會重啟正常 Bridge 嗎？
Update Checker 會自動升級嗎？
搬家時可以讓新舊主機同時跑來測試嗎？
何時才應 Factory Reset？
固定版本來源
- v2.0.55 config／full backup、preview、selective restore 精確範圍
- v2.0.55 snapshots、auto backup、retention、條件式 identity／icons／Plugin flags
- v2.0.55 per-plugin config／storage 位於備份範圍外的依據
- v2.0.55 Auto Backup／Recovery 預設值
- v2.0.55 graceful shutdown 時嘗試 auto backup
- v2.0.55 Backup & Restore UI、preview 與 restart flow
- v2.0.55 Auto Recovery interval 與 UI 說明
- v2.0.55 Update Checker 原始碼
- v2.0.55 Low-Resource 官方指南
- v2.0.55 配對、No Response、mDNS 與 Recovery 官方排錯
- Pinned Stable Add-on version、storage map 與網路設定