Health、Network Map 與診斷

同一個「離線」可能有六種原因

Controller 顯示 No Response，只代表它目前不能可靠使用某個 Matter endpoint；原因可能是 Home Assistant WebSocket 中斷、Bridge stopped／failed、Fabric 尚未 commissioned、Controller session 不活躍、subscription 消失、mDNS 宣告到錯誤介面，或 endpoint 自身映射失敗。Health 的價值是把這些層次同時呈現，讓你先定位再動作，而不是反覆重配對。

Stable 2.0.55 有可到達的 /health 與 /network-map 路由。HealthPage 組合 Health Dashboard、Live Event Log、Network Diagnostics、System Information 與 Translation Editor；Network Map 則把依 rootVendorId 合併的 Controller vendor group、Hub、Bridge、Device 與 Failed 節點視覺化；它不是一個節點對一個 Fabric。這些頁面屬 Stable 維運功能，但它們描述 HAMH 所知的狀態，不是對 Controller UI 行為的保證。

Health 狀態與連線訊號怎麼讀

後端基本 Health 將 HA connected 與 Bridge 統計彙整成 healthy、degraded、unhealthy。HA 已連線且沒有 stopped／failed Bridge 才是 healthy；HA 已連線但有 stopped 或 failed 是 degraded；HA 未連線則是 unhealthy。這是服務層摘要，不代表每個 entity 都正常，也不代表每個 Controller 都完整支援。

Detailed Health 為每座 Bridge 提供 status／reason、port、priority、device count、fabric count、failed entity count、Controller warnings、entity diagnostics，以及 session／subscription 摘要。Session 活動欄位可區分傳輸層仍有往來與 Interaction Model 指令是否停滯；subscription 又分 whole-node wildcard、endpoint-specific 或 unknown scope。單看「有 session」仍不足以證明控制正常。

Fabric 是信任關係；session 是某段時間內的安全連線；subscription 是 Controller 要 Bridge 主動回報哪些資料的訂閱。Fabric 存在但 session 為零，可能是 Controller hub 暫時離線或網路不可達；session 存在但 subscription 為零，可能只能讀寫卻沒有持續狀態回報；session 與 subscription 都在但單一 endpoint failed，則優先查映射與來源 entity。

DiagnosticsPage 存在，但 v2.0.55 沒有路由

重要版本事實：DiagnosticsPage.tsx 在 v2.0.55 程式碼中存在，HealthPage 也重用其中的 LiveEventLog；然而 routes.tsx 沒有註冊獨立 DiagnosticsPage 路由。因此你不能在 Stable 2.0.55 教學中聲稱側欄有一個獨立 Diagnostics 頁或提供杜撰網址。可操作入口是 Health & Diagnostics 頁內嵌的即時事件區與 Export Diagnostic。

Network Map 是從 Bridge 與 device API 建圖，不是封包擷取，也不是路由器的實體拓撲。圖上的 Controller vendor group 由 commissioned Fabric records 的 rootVendorId 建立並去重；同 vendor 的多個 Fabric 會合併成一個節點，因此節點數與邊線不能當精確 Fabric 數或一對一拓撲。精確 Fabric records 請看 Detailed Health；線條也不代表即時封包方向或訊號強度。Failed 節點則是 HAMH 建置 endpoint 時的失敗項目，不等同 Controller 宣告的故障。

從摘要走到可驗證根因

1. 開啟 Health & Diagnostics，先讀全域摘要

   確認版本、uptime、Home Assistant connected，以及 running／total Bridge 比例。不要先按 Restart。若 HA disconnected，先處理共同上游；若只有一座 Bridge failed，縮小到該 Bridge。

2. 逐座展開 Bridge 與 Fabric health

   比對 device count、fabric count、failed entity count、Controller warning。再查看每個 Fabric 的 session 與 subscription 彙整。只記錄「有／無、近期／停滯、數量趨勢」，公開紀錄不要抄出 Fabric 或 Node 識別值。

3. 用 Live Event Log 建立時間線

   保留 state update、command received、entity error／warning、session opened／closed、subscription changed、bridge started／stopped 所需類型；用 filter chip 隔離症狀，先重現一個低風險操作。Clear Events 只清前端觀察清單，不是修復。

4. 執行 Network Diagnostics

   閱讀 pass／warn／fail 與建議，再展開 interface 表。確認 bound interface 是可達 LAN 介面、IPv4 開關符合部署、IPv6 存在且不是只靠不可跨網段的 link-local。不要把畫面中的真實位址貼到工單。

5. 切換 Network Map 交叉比對

   確認 Hub 到各 Bridge、依 rootVendorId 建立並去重的 Controller vendor group，以及 Device 節點是否符合預期；個別 Fabric records 請回 Detailed Health 核對。點 Refresh Data 重新載入資料。拖曳位置只改瀏覽器 local storage 的版面；Undo 可撤回移動，Reset Layout 清除保存位置，Fullscreen 只改檢視。

6. 最後才匯出診斷或調整設定

   若仍無法定位，按 Export Diagnostic，先離線檢查內容並遮蔽所有識別、網路、entity name 與錯誤中的秘密片段。需改 mDNS、Firewall 或 VLAN 時轉第 20 章；需重啟或重設時回第 18 章／第 22 章的備份與回復流程。

Network Map、log、metrics 與翻譯工具

Network Map 互動

Network Map 支援縮放、平移、MiniMap、Controls、節點拖曳、單步 Undo、Reset Layout、Refresh Data 與 Fullscreen。拖曳後位置保存於目前瀏覽器 local storage；換瀏覽器、清除網站資料或按 Reset Layout 後不會保留。Refresh Data 重新抓 Bridge，接著載入每座 Bridge devices；它不進行 Matter Factory Reset，也不會修復失敗實體。

System log 與 Live Event

System log 適合看啟動、mDNS、HA 連線、Bridge failure、Plugin 與資源警告；Live Event 偏向執行期間的 state、command、session 與 subscription 時序。把兩者對齊：先標記症狀時間，再看相鄰事件與 log。Protocol debug 可能包含逐封包資訊，只能暫時啟用並嚴格保護，完成後回復正常等級。

Metrics 與 System Information

Metrics JSON 包含 uptime、heap／RSS、Bridge total／running／stopped／failed、device／Fabric totals、HA connected 與 registry 數；Prometheus 格式另有每座 Bridge status 與 device count label。System Information 顯示版本與執行環境資料，適合核對架構、Node 與資源。監控應看趨勢，不要把一次高峰直接判為洩漏。

Translation Editor

Translation Editor 可選語言、搜尋 key、篩選 missing／edited、編輯本機覆寫、逐 key reset、reset all、複製／匯出 JSON、匯入 JSON，也能建立與移除 custom language。覆寫與 custom language 由瀏覽器 local storage 還原，影響的是此瀏覽器上的 HAMH UI，不會改 Home Assistant 翻譯，也不會推送到 Controller。

匯入翻譯前先確認 JSON 只含字串 key／value，不含環境描述或秘密。Reset key 回到內建字串；Reset All 清除此語言的本機編輯。Custom language 若刪除，該瀏覽器不再提供它；要跨瀏覽器搬移，先 Export JSON，再在目標端 Import，並保留可回復副本。

三種診斷路徑

全部 Controller 同時異常：先看 HA connected 與所有 Bridge 是否一起 degraded；若 HA disconnected，先修共同連線。若 Bridge 都 running，再看 Network Diagnostics 的 bound interface 與 mDNS warning。這比逐座重配對更能命中共同根因。

只有一個 Controller 異常：Fabric 仍存在，但對應 session 或 subscription 停滯；其他 Controller session 正常。此時優先檢查該 Controller hub 與 VLAN／mDNS 路徑，不要 Factory Reset 整座 Bridge。Controller 支援差異也可能造成單一 device type 缺失。

只有一個 entity 異常：Bridge 與 session 健康，Network Map 出現 failed device 或 Health entity diagnostic 提供 reason。回到 Bridge 詳細頁修正 HA 狀態、Filter 或 mapping；Network Map 的 Refresh Data 用於確認結果，不是修復按鈕。

常見卡關與安全返回點

1. Health 顯示 unhealthy

   檢查：HA connected 與 ready；unhealthy 首先反映 HA 未連線。安全修復：確認 HA 服務、URL、權限與 WebSocket，不先重設 Fabric；連線恢復後再看 Bridge recovery。

2. Health 是 healthy，但 Controller 仍 No Response

   檢查：對應 Fabric 的 session 活動、subscription、Network Diagnostics 與 Controller hub。安全修復：先修 mDNS／IPv6／multicast 或 Controller hub，必要時單座 restart；healthy 不是 endpoint 支援保證。

3. Network Map 一直載入

   檢查：Bridges API 與每座 devices 是否都能完成、瀏覽器 console／WebSocket、是否有大型 Bridge。安全修復：回 Bridges 找失敗者、按一次 Refresh Data；不要連續按 Reset Layout，因為它只清位置。

4. Live Event 顯示 Offline

   檢查：反向代理是否轉送 WebSocket upgrade、base path 是否一致。安全修復：修正 proxy 後重新載入 Health；不要因前端 socket 斷線推論 Matter Fabric 已遺失。

5. Network Diagnostics 綁到多餘介面

   檢查：介面用途，特別是 container 與 Thread 介面。安全修復：在啟動選項綁定真正 LAN 介面，重啟服務後重跑診斷；名稱必須取自你自己的唯讀畫面。

6. 翻譯覆寫換瀏覽器就消失

   檢查：是否在原瀏覽器 local storage、是否曾 Export。安全修復：由可信 JSON Import；若資料已清除且沒有匯出，就回到內建翻譯，不要把翻譯檔誤當系統備份。

常見問題

固定版本來源

• v2.0.55 路由清單：Health 與 Network Map，以及未註冊 DiagnosticsPage 的依據
• v2.0.55 HealthPage 組成原始碼
• v2.0.55 Network Map 以 rootVendorId 合併 Controller vendor group
• v2.0.55 health、detailed、live、ready 定義
• v2.0.55 DiagnosticsPage 與 LiveEventLog 原始碼
• v2.0.55 Network Map 互動與 local storage 原始碼
• v2.0.55 JSON 與 Prometheus metrics 原始碼
• v2.0.55 Translation Editor 原始碼