Bridge、Device 與啟動管理

維運的目標不是「一直重開」

Matter Bridge 是 Home Assistant 實體與外部 Matter Controller 之間的長期邊界。Home Assistant 連線、Bridge 程序、Matter Fabric、Controller session 與裝置 endpoint 各自有生命週期；其中一層異常，不代表其他層都壞了。若每次看到「No Response」就重設，反而會破壞仍然有效的配對身份，增加重新整理房間、名稱與自動化的成本。

Stable 2.0.55 的 Bridges 頁面可對所有 Bridge 執行 Start All、Stop All、Restart All，也能匯入或匯出 Bridge 設定；個別 Bridge 詳細頁則顯示狀態、配對摘要、失敗實體、Entity Mapping、endpoint 與 cluster。Startup Order 頁面把啟動優先序獨立出來。你應先選最小影響範圍：單一裝置顯示異常，先查映射與失敗原因；單一 Bridge 卡住，才重啟該 Bridge；只有共同維護窗口才考慮批次動作。

Bridge 與 Device 生命週期

Bridge 設定定義名稱、連接埠、Filter、Feature Flags、基本識別與優先序；Matter identity storage保存已配對 Fabric 所依賴的身份資料；Endpoint tree則是 Bridge 啟動後，依目前 Home Assistant registry、Filter 與 Entity Mapping 建出的 Matter 裝置樹。三者不是同一份資料。只匯出 Bridge JSON 不等於完整備份身份，也不保證復原後免重新配對。

Start 會從持久化設定建立 Bridge 與 endpoint；Stop 會關閉這座 Bridge 的 Matter 運作，但不等於刪除設定；Restart 是依序停止再啟動。v2.0.55 前端沒有 Refresh Devices 控制；裝置集合或映射改變時，正常 UI 路徑是編輯後單座 Restart。後端另有 authenticated POST /api/matter/bridges/:bridgeId/actions/refresh，但這不是頁面按鈕，也不同於畫面定期刷新。Force Sync 只在 Bridge running 且 autoForceSync 已啟用時執行，否則回報同步零個；它只推送相對記憶體 last-sync snapshot 已變更的狀態。

Bridge 詳細頁的裝置樹由根 endpoint 向下呈現 parts。常見根節點是 Aggregator，底下每張 endpoint 卡顯示裝置類型、來源 Home Assistant 實體、Matter clusters 與展開後的 cluster state。Cluster 是能力集合，不是 Controller UI 的保證；同一個 cluster 即使在樹中存在，Controller 仍可能不呈現、只呈現部分屬性，或因產品成熟度而行為不同。

Stable、成熟度與 Controller 支援分開看

本章的 Bridges、Bridge 詳細頁與 Startup Order 都是 Stable 2.0.55 可到達路由，批次啟停、Force Sync、匯入預覽、Startup priority、裝置樹、mapping profile 與 device image 也是同版程式碼中的功能。這只說明發布通道為 Stable，不代表所有經由 Bridge 暴露的裝置類型都已成熟，也不代表每個 Controller 都支援每個 cluster。

Startup priority 只是 HAMH 內部的 Bridge 啟動順序，不是網路 QoS、Matter Fabric 優先權，也不會命令 Controller 先連哪一座 Bridge。程式碼以數值由小到大排序；Startup Order 頁拖曳儲存時依畫面順序寫入間隔化的數值。沒有設定時顯示預設優先值，因此你應以畫面順序為主，不需要手算。

一次完成可回復的維運流程

1. 在 Bridges 先記錄基準

   開啟 Bridges，確認目標 Bridge 的名稱、Running／Stopped／Failed 狀態、裝置數與是否只有一座受影響。若是 Failed，先進入詳細頁抄錄一般化的 status reason；分享紀錄前刪除身份、網路與秘密資料。

2. 縮小到單一 Bridge

   點選目標 Bridge，展開 failed entities，逐項看來源實體與 reason。往下檢查 Entity Mapping 與 endpoint tree：確認裝置是否存在、Matter device type 是否合理、預期 cluster 是否存在。先修正 Home Assistant unavailable、Filter 排除或 mapping 設定，不要用批次重啟掩蓋原因。

3. 選擇最小生命週期動作

   只是停止維護，使用 Stop；排除 Failed 原因後使用 Restart；新增／移除實體或映射後，用單座 Restart 讓 endpoint 集合重新建立；只有 Bridge running、autoForceSync 已開，而且 endpoint 與 session 都正常但 Controller 狀態仍舊時，才從更多選單執行 Force Sync。完成後等 Health 與 log 穩定再做下一步。

4. 需要整批維護時才用批次按鈕

   回到 Bridges，確認維護窗口與所有 Controller 可能短暫離線，再使用 Start All、Stop All 或 Restart All。畫面會顯示處理數量，但成功通知不取代逐座驗證；批次結束後逐一確認狀態與 failed entity count。

5. 安排重啟後的啟動順序

   進入 Startup Order，把依賴較少、規模較小或最關鍵的標準 Bridge 拖到前面，把 endpoint 很多或實驗性工作負載放後面。有未儲存變更提示時按 Save Changes，下方操作按 Save Startup Order；看到未儲存提示消失後才離開。這會保存 priority，不會當場重啟 Bridge。

6. 留下可回復交付物

   在 Bridges 選 Export All 下載設定 JSON；若只搬一部分，也可透過個別匯出 API／介面產物保存。另在 Settings 建立包含身份的完整備份並離線保護。記錄版本、匯出日期、Bridge 數、映射維護與預期 Controller，檔案中不得加上任何配對碼或憑證。

匯入、圖示、映射與裝置樹維護

Bridge 設定匯入／匯出

Export All 產物是版本化 JSON，包含 Bridge 設定陣列與匯出時間。Import 會先 Preview，列出名稱、連接埠、Filter rule 數、是否已存在，允許選擇 Bridge 與是否覆寫。舊格式可在預覽時標示 migration。安全做法是先預覽、只勾需要項目、預設不覆寫；確認目標環境沒有連接埠衝突後才套用。

設定匯出不包含 Matter identity、entity mappings、bridge image 資產與所有應用設定，因此它適合複製 Bridge 定義，不是災難復原檔。完整範圍請依第 22 章使用 Backup。匯入保留 Bridge 識別欄位可能影響既有資料對應；不要把同一份設定同時啟動在兩個主機上，避免同名服務與身份衝突。

Bridge icon 與 device image

Bridge icon 存在專用儲存目錄，支援常見點陣與向量格式，後端有檔案大小上限；Startup Order 卡片若找到自訂 icon 就顯示它，否則依 Bridge 設定選預設 icon。Device image 則按 Home Assistant entity 維護，Devices 與 endpoint 卡可批次解析是否有自訂或自動來源，也可上傳與移除。圖片是管理介面資產，不會神奇改變 Controller 端圖示；Controller 仍依 Matter device type 自行渲染。

Mapping profile

Bridge 詳細頁的 Entity Mapping section 可匯出 mapping profile、匯入預覽並套用。Profile 適合把相同裝置型號的映射規則移到另一座 Bridge，但匯入前仍要檢查目標 entity 是否存在、裝置能力是否相同、舊 mapping 是否會被覆寫。Profile 不包含 Fabric 身份，也不是 Bridge Filter 的替代品。

Endpoint、cluster 與失敗實體

Endpoint 卡把來源 entity、device type、clusters、cluster state 與自動映射線索集中呈現。先看 failed entities 的 reason，再比對 endpoint tree：若來源 entity 根本不在樹中，查 Filter、disabled mapping 與 HA registry；若 endpoint 在但缺能力，查 device class、override 與 composed entities；若 cluster 在但 Controller 不顯示，查 Controller 支援，不要任意改成不相符的 device type。

家庭與小型辦公室的操作節奏

家庭情境：客廳照明 Bridge 正常，只有一個窗簾 endpoint 失敗。你先在 failed entities 看 reason，回 Home Assistant 確認來源 entity，再修正 mapping。其他 Bridge 與 Controller 都維持運作；只有修正後單座 Restart，避免全屋裝置同時離線。

小型辦公室：照明、空調與門鎖分成三座 Bridge。主機重啟時，先讓較小且關鍵的照明 Bridge 啟動，再啟動空調，最後才是 endpoint 多、負載較高的其他 Bridge。Startup priority 幫你固定這個順序，但網路、防火牆與 Controller 可達性仍需獨立管理。

改版維護：先 Export All 供設定差異比對，再建立完整身份備份。升級後逐座啟動：確認 Health、裝置數、Fabric 數與 failed count，再測一個低風險 endpoint 的雙向狀態。設定匯出可協助重建 Bridge；只有完整身份備份才可能保留既有 commissioned Fabric。

症狀、檢查與安全修復

1. Start 後立刻變成 Failed

   檢查：詳細頁 status reason、系統紀錄、HA connected、連接埠與儲存權限。安全修復：先排除明確原因，單座 Restart；若仍失敗，保留 log 與設定，不要 Factory Reset。Auto Recovery 只會重試 failed Bridge，不能修正配置錯誤。

2. Force Sync 顯示零個、很少或被跳過

   檢查：Bridge 是否 running、autoForceSync 是否啟用、endpoint 是否相對記憶體 snapshot 真的有變更、Health 的 session／subscription，以及 metrics 記憶體。安全修復：先恢復 HA 與 Controller 連線、降低資源壓力，再只執行一次；未變更 endpoint 被略過屬正常。

3. 匯入預覽顯示已存在

   檢查：Bridge 名稱、識別、連接埠與目標環境現有設定。安全修復：預設保持 overwrite 關閉，只選真正缺少的 Bridge；需要覆寫時先完整備份並安排停止衝突 Bridge。

4. 裝置在 Home Assistant 存在但裝置樹沒有

   檢查：Filter Preview、hidden／disabled 狀態、mapping disabled、device class 與 failed reason。安全修復：修正 Filter 或 mapping 後單座 Restart；不要為了「出現」而指定不相符 Matter type。

5. 裝置樹有 cluster，Controller 卻沒有控制項

   檢查：Controller 對該 Matter device type／cluster 的支援與本功能成熟度。安全修復：保留正確映射、分拆給相容 Controller 或採 Controller 支援的較保守類型；不要宣稱跨 Controller 等價。

6. 重啟後自訂圖示或圖片消失

   檢查：持久化 storage 是否掛載、資產是否包含在所用備份範圍。安全修復：修正持久化後由可信原檔重新上傳；圖示遺失不應觸發 Fabric Reset。

常見問題

固定版本來源

• v2.0.55 Bridges 頁批次動作與匯入／匯出原始碼
• v2.0.55 Startup priority 排序原始碼
• v2.0.55 Bridge 詳細頁、失敗實體與 endpoint tree 原始碼
• v2.0.55 Force Sync、Factory Reset 與 Delete 選單原始碼
• v2.0.55 Force Sync flag／snapshot 條件與 Running-only Factory Reset 行為
• v2.0.55 Bridge export、preview、migration 與 import 原始碼
• v2.0.55 Mapping profile 匯入／匯出原始碼
• v2.0.55 Bridge icon 儲存與格式限制原始碼