網路與安全部署

Matter 可達性與管理介面安全是兩條線

Matter Controller 需要透過 mDNS 發現 Bridge，並以 IPv6 等路徑建立 operational session；管理瀏覽器則透過 HAMH HTTP、REST 與 WebSocket 操作。把 HTTP 放進反向代理不會自動轉送 Matter multicast，把 mDNS reflector 打通也不會替管理介面加上驗證。設計時必須把「Controller 到 Bridge」和「管理者到 Web UI／API」分開畫。

Home Assistant Add-on mirror 在 pinned Stable 2.0.55 設定 host_network: true、啟用 Ingress、掛載 addon_config 持久化，並公開 app log level、disable log colors、mDNS interface 與 strip global IPv6 選項。這些是 add-on 的固定事實；Plain Docker 或 npm 則由 start options 控制，不能假設兩種介面有完全相同欄位。

IPv6、mDNS、VLAN 與 OTBR

IPv6 link-local 只在同一 Layer 2 區段有效，不能當作跨 VLAN 路由方案；跨網段需要可路由的 Unique Local Address（ULA）與正確 firewall／route。mDNS 使用 multicast 來發布與查詢服務；多數路由器不會自然跨 VLAN 轉送，因此需要明確 mDNS reflector／gateway policy，而且 Controller 到 Bridge 的 operational traffic 仍要雙向允許。

多網卡主機若讓 mDNS 在所有介面宣告，Controller 可能選到 Docker bridge、虛擬介面、Thread 介面或不可回程的 global IPv6。mdns-network-interface 用來限制 mDNS 到真實 LAN 介面；mdns-strip-global-ipv6 從 mDNS address set 移除 global IPv6，保留本地可達地址；mdns-disable-ipv4 則完全不宣告 IPv4，只能在確認 Controller 與整條路徑都有 IPv6 時使用。

OpenThread Border Router（OTBR）與 HAMH 可以同主機，但 Thread 介面不是一般 LAN。除了不要把 mDNS 綁到 Thread 介面，還要檢查 OTBR 所加 IPv6 route 是否把跨 VLAN 的 ULA 回程導入 Thread mesh。若 request 能到、reply 回不去，配對可能呈現 peer unresponsive；解法是由網路管理者加更精確的 LAN ULA route，而不是停用 IPv6。

Stable 2.0.55 的啟動選項與限制

以下選項在 v2.0.55 start-options-builder.ts 可驗證。Release channel 為 Stable、命令列／環境組態成熟度為 Stable；它們不代表任何特定 Controller 對 IPv4、IPv6 或跨 VLAN 的支援。Server Mode、Camera 與 Security 即使在 Stable 出現，產品成熟度仍是實驗性（experimental-in-Stable），不可與網路選項的穩定性混為一談。

Add-on pinned mirror 只露出其 schema 所列選項；不要把 plain start option 都寫成 Add-on UI 欄位。相反地，Ingress URL 由 Supervisor 管理，不能硬編 ingress token 或 base path。文件與工單只使用 <INGRESS_PATH>、<LAN_INTERFACE>、<TRUSTED_PROXY> 等明確 placeholder。

安全部署與變更流程

1. 畫出兩條資料路徑

   列出 HAMH 到 HA、Controller hub 到 HAMH、管理瀏覽器到 HAMH 的區段與邊界。標記 <LAN_INTERFACE>、VLAN、proxy 與 OTBR，但不要把真實位址、hostname 或識別資料放進共用文件。

2. 先驗證 IPv6 與 mDNS

   在 Health → Network Diagnostics 只讀確認可用 LAN 介面、IPv6 類型與目前 bound interface。跨 VLAN 必須有可路由 ULA、mDNS forwarding 與雙向 firewall；只有 link-local 時先不要跨 VLAN。

3. 限制 mDNS 到正確介面

   Add-on 在 Configuration 設定 mdns_network_interface 為唯讀畫面確認的 LAN 介面；plain 部署使用對應 start option。只有 global IPv6 回程不可靠時才啟用 strip global IPv6；只有 IPv4 宣告確定不可達且所有 Controller 支援 IPv6 時才 disable IPv4。

4. 建立最小 firewall 規則

   允許必要網段間的 mDNS、HAMH Bridge 實際配置之 operational port 與回程，管理 HTTP 只允許管理 VLAN／proxy。不要從文件預設固定 Bridge port 清單；以 Bridges 頁實際設定為準。Camera Plugin 專用 Bridge 若啟用，另評估同一 operational port 的 TCP。

5. 保護 Web UI、API 與 WebSocket

   優先使用 Add-on Ingress 或可信反向代理。v2.0.55 WebSocket 路徑會套用 base path，但 upgrade 直接掛在 raw HTTP server，繞過 HAMH Express Basic Auth 與 application IP allowlist；proxy 必須自行驗證並限制 upgrade，後端不可直接暴露到不可信網路。plain 部署仍要讓 path rewrite、前端資產、REST 與 WebSocket 使用相同前綴。

6. 再加 Basic Auth 與 allowlist

   透過 secret manager／受限環境設定提供帳密，不把值寫進 compose 範例或 command history；allowlist 只列必要管理來源。保留 health live／ready 的監控需求，了解程式碼讓這兩個 probe 略過 Basic Auth，因此更應限制網路可達範圍。

7. 單變更驗證與回復

   每次只改一項，重啟後檢查 Network Diagnostics、Health ready、WebSocket live status、Bridge session 與一個低風險 endpoint。若失敗，回復上一個已知設定；不要把 mDNS、VLAN、proxy 與驗證同時改動。

Ingress、Basic Auth、Lock Credentials 與秘密

Ingress 與 base path

WebApi 在設定非根 base path 時把根路徑 redirect 到該前綴，並把 API 與 Web UI 掛在同一 app router。另支援 Home Assistant Ingress 與 proxy location header。因前綴 header 會影響 URL 重建，應由可信 proxy 移除外部同名 header 後寫入固定值；HAMH 後端最好不對不可信網段直接 listen。

反向代理必須同時代理一般 HTTP 與 WebSocket upgrade。安全例外：v2.0.55 的 upgrade 不會繼承 HAMH Express Basic Auth 或 application IP allowlist；必須由可信 proxy／網路邊界驗證並限制 WebSocket，且阻止直接連到 backend。若頁面能載入但狀態不更新、Live Event 顯示 Offline，常見原因是 WebSocket 沒有轉送或 base path 不一致，而不是 Matter session 壞掉。

Basic Auth 與 IP allowlist

Basic Auth 可由環境選項或 Settings 儲存設定提供；若環境設定存在，程式以環境來源為準。它只有一組 username／password 語意，不是多使用者權限分級。未搭配 TLS 時，Basic Auth 不提供足夠的傳輸保密；在 proxy 後還需處理來源 IP，否則 allowlist 可能只看到 proxy 或受 spoofed header 影響。

http-ip-whitelist 接受 IPv4、IPv6 或 CIDR，可重複指定；ENV 模式只能指定一個值，且未設定時預設允許所有來源。它是網路篩選，不替代驗證、TLS、CSRF／瀏覽器風險管理或 application-level authorization。

Lock Credentials

Lock Credentials 是 Stable 2.0.55 可到達頁面，用於把特定 Home Assistant lock entity 與 Matter PIN credential 關聯；當 requirePinForRemoteOperation 啟用時，遠端 unlock／unbolt 需要驗證 PIN，但 lock 仍允許不帶 PIN。列表回應採遮蔽形式，UI 不回顯秘密；持久化資料是 PBKDF2 hash 與 salt，不是可取回明文，但短 PIN 熵低，仍須防範離線猜測。可新增、更新、啟用／停用或刪除。這不是 Matter commissioning credential，也不是一般網站登入密碼。

HA token 與 secret handling

HA access token、Basic Auth password、Plugin secret、Lock Credential 與完整 Matter identity 備份都需使用 secret manager、受限環境或 root-only config，最小化 HA 權限與備份讀取者。Protocol debug、HTTP access log 與診斷匯出要有短保留期，分享前人工檢查。完整備份加密離線保存，復原後若懷疑外洩就執行對應輪替，而不是只刪檔。

單網段、VLAN 與 OTBR 情境

單一家庭 LAN：Add-on host networking、手機、Controller hub 與 HA 同一受控區段。你仍需確認 multicast 未被 AP isolation／IGMP 設定抑制，並把管理入口限制在 Ingress。簡單拓撲不等於可以關閉 IPv6或公開 Web UI。

小型辦公室 VLAN：Controller hub 在 IoT VLAN，HAMH 在 Server VLAN，管理者從 Management VLAN 經 proxy。網路管理者配置 ULA routing、mDNS gateway、只允許 Bridge operational traffic 雙向；管理 HTTP 只進 proxy。Basic Auth 是額外保護，不是跨 VLAN firewall 的替代。

同主機 OTBR：mDNS 固定綁 LAN 介面，Network Diagnostics 不應把 Thread interface 當廣告出口。跨 ULA VLAN 若只有單向可達，檢查 route selection；以更精確 LAN route 修正回程，避免粗暴刪除 Thread 路由或停用 IPv6。

症狀、檢查與安全修復

1. 配對找不到 Bridge

   檢查：手機／hub 區段、mDNS forwarding、bound interface、IPv6 與 AP isolation。安全修復：先回同一受控 Layer 2 驗證，再逐項恢復 VLAN policy；不要先 Factory Reset 多次。

2. 配對成功後 No Response

   檢查：mDNS 是否發布不可達介面／GUA、operational port 雙向 firewall、session health。安全修復：綁 LAN 介面，必要時 strip global IPv6，修正 firewall 後單座 restart。

3. OTBR 啟動後跨 VLAN 失聯

   檢查：回程 IPv6 route 是否被 Thread 的廣泛 ULA route 接管。安全修復：由管理者增加遠端 Controller VLAN 的更精確 LAN route，再驗證 route；不要停用整個 Thread。

4. 反向代理頁面可開但資料不更新

   檢查：WebSocket upgrade、base path、ingress／forwarded prefix header。安全修復：統一 rewrite 與前綴，讓 proxy 覆寫 header，重新載入頁面。

5. 啟用 allowlist 後管理者也被擋

   檢查：後端看到的是 client 還是 proxy、CIDR 與 IPv6 表示。安全修復：從主控台回復上一份 config，以實際可信來源重新加入；不要暫時改成對外全開。

6. Basic Auth 忘記或來源衝突

   檢查：Settings 顯示來源是否 environment；環境來源優先。安全修復：在主機受控 console 更新／移除對應 secret 後重啟，立即輪替；不要把值貼入 issue。

常見問題

固定版本來源

• v2.0.55 Stable start options 原始碼
• v2.0.55 Web API、Express Basic Auth／allowlist、base path 與 raw-server WebSocket 掛載原始碼
• v2.0.55 WebSocket raw upgrade 與未套用 application auth 的依據
• v2.0.55 remote unlock PIN 驗證與不帶 PIN lock 行為
• v2.0.55 Lock PIN PBKDF2 hash／salt 儲存
• v2.0.55 網路介面與 mDNS diagnostics 原始碼
• v2.0.55 Lock Credentials UI 與遮蔽顯示原始碼
• v2.0.55 反向代理與 WebSocket 官方文件
• v2.0.55 IPv6、VLAN、mDNS 與 OTBR 官方排錯文件
• Pinned Stable Add-on host network、Ingress 與 schema