Commissioning 與 Multi-Fabric
把「掃碼」理解成建立信任關係，而不是一次性的加入動作。你會學會安全處理配對資料、逐一加入多個 Controller，並在移除、重設或清理孤兒資料前判斷真正影響。
配對成功不等於長期可用
Matter Hub 是 Matter Bridge：它把 Home Assistant 實體轉成一個 Bridge 及其下的 Endpoint，讓 Apple Home、Google Home 或 Alexa 這類 Matter Controller 納入各自的家庭。它不是取代 Controller 的另一個 Controller。Commissioning（納管配對）會讓 Controller 與 Bridge 建立可持續驗證的信任；配對畫面關閉後，Fabric、操作階段的安全工作階段與訂閱仍繼續存在。
家庭常見問題不是「完全掃不到」，而是第一個生態系統可用、第二個加入失敗，或重啟後某個生態系統顯示離線。若把所有問題都用重設處理，你可能同時切斷原本正常的 Fabric、遺失房間與自動化關聯，還留下 Controller 端的孤兒裝置。本章的目標是讓你先辨識層級，再做最小變更。
從 Bridge 到狀態回報的心智模型
| 層級 | 代表意義 | 故障時常見表現 | 安全檢查 |
|---|---|---|---|
| Bridge／Endpoint | Bridge 是被納管的 Matter 節點，Home Assistant 實體映射為其下 Endpoint。 | 全部裝置消失或型別不符。 | 先看 Bridge 執行狀態、Devices 映射與篩選預覽。 |
| Commissioning window | 允許新的 Controller 在有限期間建立信任；第一個由 Matter Hub 提供，後續由已在 Fabric 內的 Controller 開啟配對模式。 | App 找不到配件、配對資料被拒。 | 先分清初次納管或新增 Fabric；不要先 reset。 |
| Fabric | 一個管理網域及其憑證關係。同一 Bridge 可屬於多個 Fabric。 | 只有某個生態系統離線，其他仍正常。 | 在 Bridge 詳細資料或 Health 對照每個 Controller 的狀態。 |
| Session | Controller 與 Bridge 之間可恢復的安全通訊工作階段。 | 控制暫時逾時，稍後可能恢復。 | 先觀察 session 是否重建與網路是否可達。 |
| Subscription | Controller 訂閱屬性或事件變動，讓狀態主動更新。 | 控制可成功，但 App 狀態延遲或停在舊值。 | 比較 HA 狀態與 Controller 顯示，檢查訂閱而非重新配對。 |
Fabric 不是「同一家庭裡的使用者帳號」，session 也不是 Fabric。多個家人共用 Apple 家庭通常仍是同一個 Apple Fabric；再加入 Google Home 才是另一個 Fabric。Controller App 中的房間、名稱、家庭成員及自動化屬於該 Controller，不會因 Multi-Fabric 自動複製到另一個生態系統。
QR 與手動配對資料的安全界線
QR 與手動配對資料是讓新 Controller 進入 commissioning 流程的敏感入口。只在 Matter Hub 本機管理畫面與你正在操作的官方 Controller App 之間使用；不要貼到聊天室、工單、公開截圖、日誌附件或版本庫。教學截圖也應完整遮蔽，而不是只遮住其中幾位字元。
- 初次 QR：優先直接以第一個 Controller 的官方 App 掃描 Matter Hub 畫面，不下載、不轉傳、不拍照保存；同一份 QR 不能拿來加入第二個 Fabric。
- 後續手動輸入：在第一個 Controller 找到已納管的 Bridge，開啟「配對模式」取得當次資料，再於第二個 Controller 的數字碼入口輸入；本文件不提供任何範例值。
- 操作環境：避免螢幕分享、錄影或旁觀者；配對模式只維持完成新增所需時間，用畢不保存資料。
- 排錯紀錄：只記時間、Bridge 名稱、Controller 類型、階段與已遮蔽錯誤，不記配對資料或內部識別值。
Release channel、成熟度、Controller 支援分開看
| 事實 | Stable 2.0.55 結論 | 不要推論成 |
|---|---|---|
| Release channel | 本章以 tag v2.0.55、固定 commit 的 Stable 程式與 pinned Add-on 為基準。 | Alpha、Testing 或後續版本也有相同行為。 |
| 產品成熟度 | Bridge commissioning、Fabric 健康資訊與 orphan cleanup 工作流程存在於 Stable；一般 Bridge 流程按穩定功能說明。 | Stable 內每個裝置型別都同樣成熟。 |
| 實驗性功能 | Server Mode 多實體雖在 Stable 出現，仍是「Stable 內的實驗性功能」。 | 可用來承諾正式生產支援或與 Bridge 完全相同。 |
| Controller 支援 | 是否接受 Bridge、某個 device type／cluster，仍由 Controller 與其版本決定。 | 成功納管就保證每個 Endpoint、屬性與事件都呈現。 |
因此，看到 Fabric 已建立只能證明信任關係已加入；看到 session 只能證明目前存在通訊工作階段；看到 subscription 才更接近持續回報。最終仍要對每個代表性型別實測「顯示、控制、狀態回報」三件事。
安全的 Multi-Fabric 加入程序
先固定 Bridge 身分與內容
在 Matter Hub 開啟 Bridges，確認目標 Bridge 正在執行、名稱可辨識，並用 Devices 或篩選預覽核對預計暴露的 Endpoint。配對期間不要同時改名稱、埠、篩選或映射。
備份並記錄目前正常基線
依部署方式備份持久化資料；只記錄 Bridge 名稱、既有 Controller 種類、裝置數量級與測試結果。不要把任何配對資料或內部識別值寫入紀錄。
先加入主要 Controller
在 Bridge 的配對區開啟 commissioning window，於主要 Controller App 選擇新增 Matter 配件並掃描本機 QR；無法掃描時才使用手動入口。完成後確認 Bridge 與數個代表性 Endpoint 可見。
驗證雙向狀態
在 Controller 切換一個低風險燈或開關，確認 Home Assistant 狀態更新；再由 Home Assistant 操作，確認 Controller 不只可控制，也能收到狀態變化。
由主要 Controller 開啟配對模式
在第一個 Controller 的家庭設定或 Bridge 詳細資料找到已納管的 Bridge，選擇開啟配對模式。它會產生供下一個 Controller 使用的當次手動資料；不要重掃 Matter Hub 第一次的 QR，也不要保存或轉傳資料。
在下一個 Controller 輸入當次資料
每次只加入一個新 Fabric，在第二個 App 的新增 Matter 裝置流程選擇數字碼／手動入口，直接輸入第一個 Controller 當下顯示的資料。完成後立即做顯示、控制與狀態回報測試。
整理各自房間與名稱
在每個生態系統內獨立整理房間及顯示名稱。不要期待第一個 Controller 的房間、自動化或家庭成員同步到第二個。
關閉變更窗口並觀察
完成所有新增後，不再變更 Bridge 結構，經過重啟與一段日常使用觀察每個 Fabric 的 session／subscription。保留成功基線供日後比較。
移除、reset 與 orphan cleanup 不是同一件事
| 動作 | 適用時機 | 主要影響 | 何時不要做 |
|---|---|---|---|
| 從 Controller 移除配件 | 你確定只退出該生態系統，其他 Fabric 要保留。 | 該 Controller 的房間、名稱、自動化關聯可能失效。 | 只是短暫 No Response、session 可恢復時。 |
| 移除 Fabric | 已確認某個管理關係不再使用，且能辨識正確對象。 | 該 Fabric 無法再控制 Bridge；其他 Fabric 理論上獨立，但仍須驗證。 | 無法辨識哪個 Fabric、沒有備份或仍有家庭成員依賴時。 |
| Reset Bridge | 持久化信任資料不可恢復、計畫完整重建且接受所有 Controller 重配。 | 可能切斷全部 Fabric，Controller 端留下需另行移除的舊配件。 | 單一 Endpoint 異常、單一 Controller 離線、名稱或房間錯誤時。 |
| Orphan cleanup | Dry-run 顯示已從 HA 刪除、且 tombstone 至少經過七天保護期的 entity identity／mapping 殘留。 | 只清實體身分與映射殘留，不是清 Fabric；誤刪仍可能讓重新出現的實體失去原映射身分。 | HA registry 尚未完整載入、部署磁碟未掛載、還原尚未完成或你看不懂候選項目時。 |
Orphan cleanup 是清理由 HA registry 永久刪除之實體留下的 identity／mapping 資料，不是清除 Matter Fabric，也不是一般連線修復。v2.0.55 先以 dry-run 預覽，並用七天 tombstone 降低短暫消失造成的誤判。若 HA 尚未完整載入或持久化磁碟未正確掛載，先恢復正常部署與資料路徑，再評估候選項目。
把故障範圍限制在一個 Fabric
小型家庭可用一座內容精簡的 Bridge 加入兩個 Controller；裝置數量較多、型別混雜或不同 Controller 能力差異明顯時，分拆 Bridge 通常比頻繁 reset 容易維護。分拆依據應是故障範圍、Controller 支援與區域，而不是隨意把同一實體重複暴露。
- 先建立「核心 Bridge」：只放各 Controller 都能穩定呈現的燈、開關等代表型別。
- 特殊型別另成 Bridge：窗簾、吸塵器、進階感測或實驗性類型先小量驗證。
- 每座 Bridge 使用可辨識且穩定的名稱；不要在納管後頻繁變更結構。
- 每次變更只測一座 Bridge、一個 Fabric、一種型別，讓排錯證據可歸因。
不要因第二個 Controller 不支援某種型別，就重設第一個 Controller 已正常使用的 Bridge。先從篩選或分拆降低第二個 Controller 看見的複雜度，並保留原本正常 Fabric。
依症狀找安全返回點
App 完全找不到 Bridge
確認 Bridge 正在執行且 commissioning window 尚有效；讓手機與 Matter Hub 所在網路可進行本機 IPv6 與 mDNS 發現。先修正介面、VLAN 或 multicast 路徑，不要 reset。
顯示已配對，但 Endpoint 不完整
先核對 Filter、Devices 映射與 Controller 支援的 device type。Fabric 成功不代表 Controller 接受所有型別；用一個基本燈或開關作對照。
只有一個 Controller 顯示離線
其他 Fabric 正常表示 Bridge 與 HA 不一定故障。查看該 Fabric 的 session／subscription、該 Controller 的家庭中樞及網路路徑，避免移除全部 Fabric。
可控制但狀態不更新
比較 Home Assistant 實際狀態與 Controller App，檢查 subscription 是否持續；先重新開啟 App 並觀察 session 恢復，不要用重新配對取代訂閱排錯。
移除後仍看到灰色舊配件
這通常是 Controller 端的房間或快取項目。先在原 Controller 端移除舊配件；不要因此直接清除 Matter Hub 全部儲存。
Orphan cleanup 列出不確定項目
取消操作，確認 HA registry 已完整載入、持久化資料掛載及還原已完成。只有能證明該 entity 已從 HA 刪除，且候選 identity／mapping 通過保護期時才重新評估。
常見問題
Multi-Fabric 會同步房間、名稱與自動化嗎？
第二個 Controller 可以直接掃第一次的 QR 嗎？
某個 Fabric 離線，需要 reset 整座 Bridge 嗎？
何時可以用 orphan cleanup？
Stable 2.0.55 的 Server Mode 可以照相同步驟處理嗎？
固定版本與規格來源
- v2.0.55 前端工作流程（含 orphan cleanup 與 Bridge 介面）
- v2.0.55 orphan cleanup 實作
- v2.0.55 Bridge 資料與 Feature Flags
- Pinned Stable Add-on 設定
- v2.0.55：Connect multiple assistants to one bridge
- Matter Handbook：Fabric
- Matter Handbook：Commissioning
來源固定於 v2.0.55 commit；Controller 的實際呈現仍要以各生態系統當下官方支援與你所用版本驗證。