建立第一個 Matter Bridge
用 Stable 2.0.55 的 Wizard、Area Setup 或完整 Manual Setup 建立 Bridge。你會看懂十個範本、自動 port、network preflight、Alexa 5540 警告、filter guards、Controller profiles、進階身分／session 欄位，以及匯入前預覽與衝突處理。
先決定 Bridge 邊界，不急著按 Create
一座標準 Matter Bridge 是一個 Matter Node，內含 Aggregator 與多個裝置 Endpoint。你要先決定它服務哪一組 HA 實體與哪些外部 Controller。Stable 2.0.55 支援多座 Bridge，也支援同一 Bridge 的 Multi-Fabric；但 Controller Device Type 支援、產品成熟度與 Stable release channel 是三個不同事實。
第一座建議選少量、非安全關鍵、容易觀察的裝置。大型 Bridge 在某些 Controller 可能不穩定，介面也會提示必要時拆分。拆分方式可按 Area、domain 或 Controller 專用 workaround；沒有一種方式適用所有家庭。
| 決策 | 保守起點 | 後續可調整 |
|---|---|---|
| 裝置範圍 | 一個 Area 或單一常用 domain 的少量裝置 | 確認 Controller 呈現後再擴大 Filter |
| Controller | 先選主要 Controller profile 或保持未選 | 有相容性衝突時拆 Controller 專用 Bridge |
| Port | 接受 next free port；Alexa 目標保留 5540 | 每座 Bridge 唯一，衝突時選其他可用 port |
| Server Mode | 一般裝置保持關閉 | 只有 standalone 需求才啟用；Stable 中多實體仍屬實驗性 |
| Filter | 明確 include、必要 exclude | 先看 preview，避免空 include 意外包含全部 |
Stable 2.0.55 全部十個範本
範本是預填 filter、icon 與部分 feature flags 的起點，不是 Controller 支援保證。Wizard 選中範本後仍可走後續 Controller profile 與 review；完整 Create Bridge 頁也可選範本，再用表單或 JSON 編輯。十個範本如下：
| 範本 | Include | 預設 flag／邊界 |
|---|---|---|
| All Lights | domain light | autoBatteryMapping |
| All Switches & Plugs | domain switch | 無額外 flag；實際 power/energy 仍依映射 |
| All Sensors | sensor、binary_sensor | auto battery/humidity/pressure mapping |
| Climate & Covers | climate、fan、cover、humidifier | autoBatteryMapping |
| Security & Locks | lock、alarm_control_panel 或 motion/door/window device class | includeMode: any、auto battery；不等同實驗性 Security Plugin |
| Robot Vacuum (Server Mode) | domain vacuum | serverMode；應改成精確單一實體。多實體 Server Mode 是 experimental-in-Stable |
| Media Players & Speakers | domain media_player | 無額外 flag；呈現依 Controller |
| Google Home Optimized | pattern * | auto force sync、battery/humidity/pressure；範圍很廣，先縮小 |
| Alexa-Optimized Covers | domain cover | HA percentage 與 auto battery；Alexa 首次配對還要 port 5540 |
| Automations & Scripts | automation、script、scene | 無額外 flag；外部呈現與 momentary 行為需另驗證 |
Security & Locks 只是標準實體 Filter 範本，與 Stable 中仍標示實驗性的 Security Plugin 不同。名稱相似不代表同一功能。Google Home Optimized 預設 wildcard 是「全部裝置」範圍，可能比你預期大；選範本後應在完整 editor 縮小，或改用 Area/Label。
用 Bridge Wizard 建立小型標準 Bridge
Wizard 有六個階段：Template、Controller、Bridge Info、Entity Filter、Feature Flags、Review。Template 與 Controller 可 Skip；Bridge name 必填；Filter 不能留成空 include；Review 會顯示設定摘要與 Network preflight，最後可 Create Bridge 或 Add Another。
開啟 Wizard 並選範本
在 Dashboard 按「Bridge Wizard」。選擇與目標最接近的十個範本之一，或按 Skip Template 從空白設定開始。不要只因名稱含 Controller 就推論所有裝置都受支援。
選 Controller profile
從 Apple Home、Google Home、Amazon Alexa、Multi-Controller 擇一，或 Skip。Profile 只合併推薦 feature flags，不會自動完成配對或驗證 Device Type。
填 Bridge Info
輸入可辨識且不含敏感位置資訊的名稱。保留自動取得的 next free port；若目標是 Alexa，第一座務必規劃 5540。一般 Bridge 不勾 Server Mode。
設定明確 Filter
只有選 Skip Template 時，Wizard 才能編輯 Pattern、Domain、Area、Label 與 exclude；選非 Server Mode 範本時，範本 filter 在 Wizard 內是唯讀，需建立後到完整 editor 修改。空白設定可用 Pattern、Domain、Area 或 Label。首次測試選單一 Area／Domain 或明確 pattern；加入 exclude 排除不需暴露的實體。Label 必須至少選一個，其他類型也至少填一個值。
檢視四個 Wizard flags
依需求調整 Auto Compose Devices、Auto Force Sync、Invert Cover Direction、Include Hidden Entities。Controller profile 已推薦的 flags 會合併顯示；不要為了「功能最多」全部開啟。
Review 與 preflight
核對名稱、port、include、exclude、Server Mode 與 flags。展開 network remediation，先處理 fail/warn；Alexa port 警告存在時返回 Bridge Info 修正。
Create 或 Add Another
只有摘要與 preflight 符合計畫才按 Create Bridge。v2.0.55 的 Add Another 即使建立失敗也會重設表單，因此每次都要回 Bridges 確認 Bridge 確實存在；下一個建議 port 依最初取得的 nextPort 加上佇列數推算，不一定是你手動輸入的目前 port 加一。
四個 Controller profile 是推薦設定，不是支援矩陣
| Profile | 合併的 feature flags | 解讀邊界 |
|---|---|---|
| Apple Home | auto composed、battery、humidity、pressure mapping | cover 使用標準 Matter percentage；特定裝置類型仍需 Apple 支援 |
| Google Home | auto force sync、auto composed、battery、humidity、pressure | Force Sync 是失去 subscription 時的 workaround，會增加流量 |
| Amazon Alexa | auto force sync、battery、humidity、pressure、HA cover percentage | 首次 commissioning 仍需 5540；某些類型／flag 只適合 Alexa-only Bridge |
| Multi-Controller | auto force sync、auto composed、battery、humidity、pressure | 取平衡設定，不會消除各 Controller 對 Device Type 的差異 |
Profile 的 flag 會覆蓋／合併進範本目前值。若你取消選取 profile，Wizard 不會自動回復先前所有 flag；Review 時要看最終結果。對互斥 workaround，例如 Alexa 專用亮度行為，應用 Controller 專用 Bridge 隔離，而不是假設 Multi-Controller 能同時滿足。
空 Filter、Label guard 與 remediation
後端語意中，空 include 可能代表 include everything，因此 Wizard 明確阻止意外空清單。Pattern/Domain/Area 沒有值時顯示「至少輸入一個值」；Label 沒選任何標籤時顯示選擇至少一個 label 或換類型。切換 filter type 也會清除不相容的 pattern 字串，避免殘值漏到 Domain/Area matcher。
Server Mode 強制用 entity ID pattern，畫面警告要精確單一實體，第一個實體是 primary。上游 bridge schema 允許一個 Server Mode Node 最多十個裝置 Endpoint，但多於一個是 experimental-in-Stable；Wizard 的「exactly one」指引是較安全的產品路徑。
| Filter type | 輸入 | 常見風險 |
|---|---|---|
| Pattern | wildcard 或明確 entity pattern | * 太廣；include all switch 開啟時要特別確認 |
| Domain | 逗號分隔 domain | 包含某 domain 所有實體，可能超出 Controller 或資源規模 |
| Area | HA area IDs | 使用 ID 而非顯示名稱；實體未分 Area 時不會命中 |
| Label | 從 API 載入並選擇 HA labels | 至少一個；載入失敗時不要用空 selection 繼續 |
| Exclude | Wizard 以 pattern 列表建立 | 先 include 再 exclude；過廣規則可能排除所有預期裝置 |
完整 Manual Editor 會顯示 Filter Preview，並提醒 labels 的正確用法。Preview 是建立前重要 guard：確認預期實體數、vacuum／大量命中／unsupported-domain 警告與敏感裝置是否誤入。若結果為零，不要把 include 改成空白試運氣；回到 Area/Label/Pattern 識別逐項修正。
自動 port、Network preflight 與 Alexa 5540
Wizard 開啟時呼叫 api/matter/next-port；失敗時 fallback 5540。Manual Create Page 從 5540 起掃描 used ports，選第一個 free port。Area Setup 取得 next port 後，每建立一個 Area 就遞增。每座 Bridge 的 port 必須唯一；完整 editor 會在 port 已被另一 Bridge 使用時阻止 Save。
PreflightPanel 呼叫 api/network，將 diagnostic 結果整理為 passed、warnings、failed。每個異常可展開 How to fix：若有 Add-on option，會顯示 option 與對應 container flag，並提醒變更 start option 後重啟 Add-on；其餘問題要在 host/network 修復。Preflight 是 advisory，不會自動阻擋 Create，所以你必須自行把 fail 當成先修條件。
先分配 5540
若任何 Bridge 要給 Alexa，先建立它並使用 5540。其他 Bridge 接受自動 free port。
查看 pass/warn/fail 摘要
在 Wizard Review 等待 Network preflight 完成。無資料或 server 無法抵達時，不應視為全部通過。
展開每個 How to fix
依建議辨識 Add-on option、container flag 或 host/network 問題；不要盲目套用範例介面名稱。
修正後重跑 Review
需要 start option 時完整重啟服務，再回 Wizard 重新取得 diagnostics。確認錯誤消失才建立。
Area Setup：按 HA Area 批次建立多座 Bridge
Area Setup 從 api/matter/areas/summary 載入至少含一個「已啟用、目前不是 unavailable，且屬 API 支援 domain」實體的 Area；卡片 entity count 也採同一 eligibility 規則，並顯示最多四個主要 domains。你可 Select All／Clear、逐 Area 勾選，並可選四個 Controller profile 之一。不符合 eligibility 的 Area 會被排除。
建立時每個 Area 形成一個 Area matcher、無 exclude，預設啟用 auto battery/humidity/pressure mapping，再合併 Controller profile flags。程式依序建立，port 從 next free port 起逐一增加；即使某一個失敗，後續 Area 仍會繼續，最後分別顯示 success/error 與 partial summary。
先整理 Home Assistant Areas
在 HA 確認需要暴露的實體已放入正確 Area，且 Area 不包含不應外露的敏感裝置。Area Setup 本身沒有逐實體 exclude。
選 Controller profile
選主要 Controller 或保持未選；記住這只合併 flags。若 Alexa 需要 5540，避免一次批次建立多個都期待 Alexa 首配。
選少量 Areas
先勾一至兩個，查看 entity/domain 摘要。Select All 可能一次建立很多 Bridge，低資源主機尤其要避免。
按 Create Bridges 並看進度
進度條按 Area 數更新。不要離頁或重複點擊；每個結果會列出成功或錯誤。
處理 partial results
記錄失敗 Area 與已遮蔽錯誤摘要；回 Bridges 核對已成功項目，避免重新建立造成重複。修正 port/filter 後只補失敗項目。
完整表單／JSON：icon、country、priority、suffix 與 session
Manual Create Page 同樣可先選十個範本，接著由 BridgeConfigEditor 編輯。預設是 Fields Editor，可切到 JSON Editor；兩者都依同一 schema 驗證。頁面還會顯示 Filter Preview 與 Bridge Icon Upload。icon 可選內建類型或由管理介面處理自訂圖示；不要把含住址或識別資訊的圖片當圖示。
| 欄位 | 用途 | 風險與建議 |
|---|---|---|
name | Bridge 顯示名稱 | 使用穩定、非敏感名稱；必填 |
port | Matter 服務 port | 每座唯一；Alexa 首配 5540；衝突會 validation error |
filter | include/exclude 與模式 | 看 Preview，不使用意外空 include |
featureFlags | 映射、Controller workaround、Server Mode 等 | 逐項啟用；Server Mode 多實體為 experimental-in-Stable |
countryCode | Bridge country code 設定 | 使用部署實際的標準國別值；不是 UI 語言 |
icon | Dashboard／Bridge 識別 | 不影響 Controller 支援；自訂檔需納入 assets/backup |
priority | 啟動優先序，較小先啟動；預設 100 | 多 Bridge 才需規劃，並非效能權重 |
serialNumberSuffix | 附加到各 entity serial，協助避開某些 Controller stale cache | 會改身分觀察，可能造成裝置視為新項目；不應常態亂改 |
uniqueIdSuffix | 混入標準 Bridge 的 device uniqueId | 可 mint fresh identities，影響 Controller cache；只在明確復原計畫下用 |
sessionMaxAgeHours | 標準／Server Mode session age rotation；0 停用，範圍 0–168 | Config 優先於 HAMH_MATTER_SESSION_MAX_AGE_HOURS；兩者都沒有時，標準 Bridge 預設停用，只有 Server Mode 預設 4 小時 |
Editor 會對 Server Mode、多實體、Vacuum OnOff 與 Auto Force Sync 加 Auto Composed Devices 顯示警告。這些不是無條件禁止，但必須讀完再保存。切換 Fields/JSON 時 icon 由獨立元件保留；JSON 編輯仍應避免貼入任何秘密，BridgeConfig 本身也不應包含 HA token 或 pairing data。
既有 Bridge 匯入：先 Preview，再決定 overwrite
除了三種新建工作流，Bridges 頁的 Import dialog 可讀取 Bridge export JSON。選檔後前端解析 JSON，先呼叫 preview API；解析或預覽失敗只顯示錯誤，不會直接匯入。Preview 列出 export 時間、格式版本、每座 Bridge 名稱、port、filter rule count，以及 Already exists。
預設所有預覽項目被勾選，你可以 Select All、Select None 或逐一取消。overwriteExisting 預設 false；關閉時，已存在項目會 skipped，而不是悄悄覆寫。開啟 overwrite 前必須有目前完整備份，並先比較 port、filter、identity suffix 與 feature flags。舊格式會顯示 migrated 與來源版本，表示匯入時轉成目前格式，不代表所有語意差異已人工確認。
驗證檔案來源
只使用你控制且已掃描的 export JSON。不要匯入聊天或論壇提供的設定，也不要把 export 當作公開附件。
讀完整 Preview
核對 exported time、source format、Bridge 名稱、port 與 filter rules。看到 older version migration 時先另存備份並逐項比較。
取消不需要的項目
對已存在或 port 規劃不符的 Bridge 取消勾選。Select None 可安全回到零選擇，此時 Import 按鈕會停用。
審慎選擇 overwrite
預設保持關閉，讓 existing 被 skipped。只有明確要取代且已備份、理解身分與 Filter 影響時才開啟。
匯入後核對結果
Dialog 會摘要 imported、skipped 與 failed 數量。逐座進 Bridge details 檢查 status 與 device count，不因部分成功就重按整批 Import。
建立 Bridge 的常見卡關
Wizard 不讓你離開 Filter
檢查是否空 include：Label 至少選一個，Pattern/Domain/Area 至少填一個值。不要利用 JSON 空陣列繞過 guard；先決定明確範圍。
Alexa preflight 顯示 port 警告
回 Bridge Info 改成 5540；若已被其他 Bridge 使用，先決定是否重新分配未配對 Bridge。不要在非 5540 繼續並期待稍後自動修正。
Port already used
查看 used ports 與占用 Bridge，使用 next free port。若占用的是已配對 Bridge，不要直接改它的 port；先評估 Controller 中斷與重新配對影響。
Area Setup 部分成功
依 results 區分 succeeded/failed，只補建失敗 Area。回 Bridges 檢查成功項目，避免 Select All 重跑造成重複。
Preview 顯示零實體或數量過大
核對 Area ID、Label、Domain 與 include/exclude 順序。零結果不要清空 include；過大先縮小到單 Area 或明確 pattern。
Network preflight 無法載入
把它視為 diagnostics 未完成，而非 all passed。確認 backend
api/network可達、WebSocket/HTTP 無全域警告，再從 Health 執行 Network Diagnostics。匯入後出現 skipped 或 failed
先讀摘要與 Already exists，不立刻開 overwrite 重跑。比較 ID、port 與現有設定，備份後再針對單一衝突處理。
常見問題
十個範本哪一個最適合第一座 Bridge？
每座 Bridge 都可以用 5540 嗎？
選 Controller profile 就保證相容嗎？
Server Mode 已在 Stable，為何還說 experimental？
Area Setup 會自動排除不支援裝置嗎？
Import 的 overwrite 可以當合併嗎？
固定版本官方與原始碼來源
- v2.0.55 Bridge Wizard 六階段、guards 與多 Bridge
- v2.0.55 全部十個 Bridge templates
- v2.0.55 四個 Controller profiles
- v2.0.55 Network preflight 與 Alexa 5540 警告
- v2.0.55 Area Setup 批次流程
- v2.0.55 Manual editor、port validation、preview 與 warnings
- v2.0.55 BridgeConfig schema、priority、suffix 與 session
- v2.0.55 Import preview、selection 與 overwrite