第 2 章

安裝 Stable 2.0.55

比較 Home Assistant OS Add-on、Docker 與 global npm，選出適合你維運能力的 Stable 2.0.55 部署。這章涵蓋持久化、升級、HA URL/token 的安全處理、pinned Add-on 能力、全部 Stable start options 與低資源主機指引。

先選安裝方式，不要預設人人都該手動部署

上游安裝文件把 Home Assistant OS Add-on 列為偏好的方式。若你已使用 Home Assistant OS，通常先選 Add-on：Supervisor 管理啟停與 Ingress，且 Add-on 透過 Home Assistant API 取得必要連線資訊。Docker 與 global npm 是給能自行維護容器或 Node.js 服務、資料目錄、網路與秘密注入方式的讀者，不是「功能比較完整」的必然升級。

方式適用情境你要自行負責
Stable Add-on 2.0.55Home Assistant OS；希望透過 Supervisor 與 Ingress 管理加入正確 repository、確認 add-on 設定、備份 addon_config、網路與版本升級
Docker image已有容器維運、能使用 host network 並管理持久 volumeHA URL/token 注入、映像版本、重啟策略、/data、IPv6/mDNS、Web UI 存取控制
global npm能管理相容 Node.js、system service、權限與日誌的進階環境套件版本、程序常駐、storage location、更新回復與所有 start options
版本範圍：本章只描述 Stable 2.0.55。Alpha 與 Testing 是不同 release channel；即使可以並存，也不應用本章指令把它們當成 Stable 升級目標。

共同前置條件：HA、IPv6、mDNS 與資料目錄

三種方式都需要可用的 Home Assistant、正確的時間、可持久化儲存，以及 Controller 能抵達的 LAN。Matter 依賴 IPv6、mDNS 與 UDP；若有 VLAN，必須正確處理 multicast 與回程路由。Web UI 能載入不等於 commissioning 所需網路已通。

  • Home Assistant 本身可用，且你有權建立一組專供此服務使用的 long-lived access token；不要把 token 貼進版本庫、聊天或截圖。
  • Controller/Home Hub 與 Matter Hub 所在主機有可用的 IPv6 與 mDNS 路徑；AP/client isolation 關閉。
  • Docker 使用 host network；Add-on pinned config 也啟用 host_network: true。
  • 預先決定持久化位置與備份方式。Docker 固定掛載容器 /data；npm 預設使用使用者家目錄下的應用資料夾，或以 start option 指定。
  • Web UI 不應直接暴露到不受信任網路。需要反向代理、Basic Auth 或 IP allowlist 時，先讀第 20 章；Basic Auth 不是多帳號、RBAC 或 SSO。
秘密處理：以下命令一律只示範 <HA_BASE_URL>、<HA_LONG_LIVED_ACCESS_TOKEN>、<PERSISTENT_DATA_PATH> 等 placeholder。執行時在受控的 secret/environment 機制填值，不把 shell history、compose 檔或診斷輸出公開。

安裝 pinned Stable 2.0.55 Add-on

本指南的 Add-on 事實固定於 WOOWTECH mirror commit a68dc435da8eb206e9efd51388d5d1ce798aefe0。其中 hamh/config.yaml 宣告版本 2.0.55、slug hamh、最低 Home Assistant 2024.1.0，支援 aarch64 與 amd64。它啟用 Home Assistant API、host network 與 Ingress，Ingress port 為動態值，並將 addon_config 以讀寫方式掛載。

pinned config 欄位值／意義
version2.0.55，本章指定 Stable 版本
homeassistant_apitrue，Add-on 可使用 Supervisor 提供的 HA API 能力
host_networktrue，讓 Matter/mDNS 使用主機網路；仍須 LAN 設定正確
ingress / ingress_port啟用 Ingress，port 由平台安排；通常從 Add-on 的「開啟 Web UI」進入
arch只列 aarch64、amd64；不要推論其他架構也受此 mirror 支援
mapaddon_config:rw，資料可持久化且應納入備份
可見 optionsapp_log_level、disable_log_colors、mdns_network_interface、mdns_strip_global_ipv6

  1. 加入 Stable repository

    在 Home Assistant 依序開啟「設定 → 附加元件 → 附加元件商店」，從右上角 repository 管理加入你核准的 Stable Add-on repository。確認顯示的是 Stable hamh，不要誤選 Alpha 或 Testing slug。

  2. 核對版本與架構

    在安裝卡片先確認版本為 2.0.55，主機架構是 pinned config 列出的 aarch64 或 amd64。若不符，停止安裝，不以未知映像替代。

  3. 安裝並檢視設定

    按「安裝」後，到「設定」分頁保留 info log level；只有 Network Diagnostics 指出介面問題時才填 mdns_network_interface。不要任意選 Docker 或 Thread 介面。

  4. 啟動並從 Ingress 開啟

    按「啟動」，先看 Add-on log 是否完成服務初始化，再按「開啟 Web UI」。成功畫面應顯示 Dashboard，且 HA connection 為 Online。

  5. 先備份再建立 Bridge

    確認 Supervisor 備份包含 Add-on 資料，才前往下一章建立 Bridge。不要把「可開 UI」當成備份已完成。

Docker：鎖定映像、host network 與 /data

Docker 適合已有容器維運能力的讀者。Stable 2.0.55 需要 host network 以避開 Matter/mDNS 受一般 bridge network 限制；資料寫入容器 /data，必須掛載持久 volume。為可重現性，本章使用明確版本 tag，而不是會移動的 latest。

docker run -d   --name home-assistant-matter-hub   --restart unless-stopped   --network host   -v <PERSISTENT_DATA_PATH>:/data   -e HAMH_HOME_ASSISTANT_URL="<HA_BASE_URL>"   -e HAMH_HOME_ASSISTANT_ACCESS_TOKEN="<HA_LONG_LIVED_ACCESS_TOKEN>"   -e HAMH_LOG_LEVEL="info"   ghcr.io/riddix/home-assistant-matter-hub:2.0.55

不要把實際 token 寫進可提交的 Compose 檔；改用受權限保護的 env file、container secret 或部署平台的 secret store。<HA_BASE_URL> 應是容器可抵達的 Home Assistant HTTP(S) base URL，不要照抄別人的主機名稱或私有位址。

  1. 建立受限資料目錄

    在主機建立 <PERSISTENT_DATA_PATH>，設定只有執行服務所需帳號可讀寫，並將它加入備份。不要把該目錄同步到公開空間。

  2. 準備秘密注入

    在 secret store 建立 HA URL 與 long-lived token 變數。若只能用 env file，將檔案設為最小權限並排除版本控制。

  3. 啟動固定版本容器

    執行上方命令；確認使用 --network host、版本 2.0.55 與 /data 掛載。不要為了「容器啟得來」移除持久 volume。

  4. 驗證 health 與日誌

    先看容器狀態與啟動日誌，再從受控網路開啟 Web UI。只分享已遮蔽的錯誤摘要，不分享環境變數列表或完整設定。

  5. 測試重建持久性

    在建立正式 Bridge 前，記錄版本與備份位置；更新演練應能以同一 /data 重建容器。不要用刪除 volume 測試。

Global npm：只給能管理常駐服務的環境

global npm 安裝不提供 Supervisor 或容器層的常駐、網路隔離與資料掛載。你要自行維護相容 Node.js、服務帳號、systemd 或其他 process manager、重啟策略、日誌輪替及 storage location。若這些責任不熟悉，回到 Add-on 或 Docker。

npm install -g @riddix/[email protected]

home-assistant-matter-hub start   --home-assistant-url="<HA_BASE_URL>"   --home-assistant-access-token="<HA_LONG_LIVED_ACCESS_TOKEN>"   --storage-location="<PERSISTENT_DATA_PATH>"   --log-level=info

v2.0.55 同版安裝文件仍使用舊 package 名稱，但 release workflow 在發布時改寫為 @riddix/hamh；以上游 release workflow 與已發布 package 為準。安裝後的 executable 仍是 home-assistant-matter-hub。命令列參數可能出現在 shell history 或 process listing，因此實際長期服務建議以 HAMH_HOME_ASSISTANT_ACCESS_TOKEN 從受保護的 service environment／secret file 注入，而不是把 token 直接留在命令列。環境變數規則為把 option 轉成大寫底線並加 HAMH_ 前綴，例如 --storage-location 對應 HAMH_STORAGE_LOCATION。

權限原則：服務帳號只需讀取設定、寫入 storage、連線 HA 與開啟所需網路服務。不要因權限錯誤就改用 root 常駐；先修正目錄擁有者與 service unit。

Stable 2.0.55 全部 yargs CLI／environment start options

以下逐項來自 exact commit 的 start-options-builder.ts，是完整的 yargs CLI／environment 清單。這些環境變數由 yargs .env("HAMH") 產生：長 option 轉大寫、連字號轉底線並加前綴。Boolean、number 與 array 仍要符合型別；其中 IP allowlist 在環境變數形式只能提供一個值。

CLI optionEnvironment用途與預設
--configHAMH_CONFIGJSON 設定檔路徑，可用 kebabcase 或 camelcase key；空字串等同無檔案，路徑不存在或 JSON 無效會失敗
--log-levelHAMH_LOG_LEVEL應用程式等級：silly/debug/info/notice/warn/error/fatal；預設 info
--protocol-log-levelHAMH_PROTOCOL_LOG_LEVELmatter.js MessageChannel/Exchange 等級，同一組選項；預設 info，只有協定排錯才降低
--disable-log-colorsHAMH_DISABLE_LOG_COLORS停用 ANSI 顏色；boolean，預設 false
--json-logsHAMH_JSON_LOGS輸出結構化 JSON log；boolean，預設 false
--storage-locationHAMH_STORAGE_LOCATION資料目錄；npm 預設使用者家目錄的應用資料夾，容器應持久化 /data
--http-portHAMH_HTTP_PORTWeb 應用 port，預設 8482；--web-port 是已棄用 alias
--http-ip-whitelistHAMH_HTTP_IP_WHITELIST允許 IPv4、IPv6 或 CIDR；CLI 可重複，ENV 只能一個；未設定時允許所有 IP
--mdns-disable-ipv4HAMH_MDNS_DISABLE_IPV4停用 mDNS IPv4、只用 IPv6；預設 false，不等於停用 IPv6
--mdns-network-interfaceHAMH_MDNS_NETWORK_INTERFACE限制 mDNS 到指定 LAN 介面；不要猜名稱，先看 Network Diagnostics
--mdns-strip-global-ipv6HAMH_MDNS_STRIP_GLOBAL_IPV6從 mDNS 移除 GUA，避免 Controller 選不可回程位址；預設 false
--home-assistant-urlHAMH_HOME_ASSISTANT_URLHA HTTP(S) URL；manual deployment 必填
--home-assistant-access-tokenHAMH_HOME_ASSISTANT_ACCESS_TOKENHA long-lived access token；manual deployment 必填且屬秘密
--home-assistant-refresh-intervalHAMH_HOME_ASSISTANT_REFRESH_INTERVAL偵測新裝置、實體與設定的刷新秒數；預設 60
--ha-message-timeoutHAMH_HA_MESSAGE_TIMEOUT單次 HA WebSocket registry/action request timeout，毫秒；預設 60000
--http-auth-usernameHAMH_HTTP_AUTH_USERNAME可選 HTTP Basic Auth 使用者名稱；不是多帳號系統
--http-auth-passwordHAMH_HTTP_AUTH_PASSWORD可選 HTTP Basic Auth 密碼；用 secret 注入並與 username 一起規劃
--http-base-pathHAMH_HTTP_BASE_PATH反向代理子路徑 base path，預設 /；需與代理 WebSocket/API 路徑一致
無 CLI 對應HAMH_MATTER_SESSION_MAX_AGE_HOURSBridge runtime 直接讀取，不經 yargs；0 停用，非零值夾在 1–168。未設定時標準 Bridge 預設 0（停用），Server Mode 預設 4 小時

HAMH_MATTER_SESSION_MAX_AGE_HOURS 是 runtime-only 例外，不是 yargs option，也沒有 CLI 對應。--http-port 的舊 alias --web-port 仍可到達，但 exact source 明確標示 deprecated，新的部署應使用 http-port。啟動選項不等於 Add-on 設定頁全部可見；pinned Add-on 只暴露其 schema 中列出的 options，其餘由 Add-on entrypoint、Supervisor 或固定封裝管理。

備份、升級與回復順序

Bridge configuration、Matter operational state、映射與其他應用資料必須跟版本一起管理。只備份 compose 或 Add-on 設定頁不夠；真正的 storage／addon_config 才是回復關鍵。任何升級前先保存一致性備份，再記錄目前映像或套件版本，最後才停止服務。

  1. 建立一致性備份

    Add-on 使用 Home Assistant 備份並確認包含該 Add-on；Docker/npm 先停止寫入或停止服務，再備份完整持久資料目錄。備份本身要加密並限制存取。

  2. 記錄可回退版本

    記錄 Stable 2.0.55 與部署方式，不記錄 token。Docker 保留可拉回的明確 tag；npm 記錄 package version；Add-on 記錄 repository 與版本。

  3. 只變更一個層次

    升級映像／套件時先不改 Bridge Filter、port、網路介面或 HA token，以免故障時無法判斷來源。

  4. 啟動後做四層驗證

    依序確認程序、HA connection、Bridge running、既有 Controller 狀態。不要為了版本顯示未更新就重建 Bridge；先處理前端版本 mismatch。

  5. 失敗時回復資料與版本

    先停止失敗版本，再恢復相符資料備份與原版本。不要把新版本已寫入的資料目錄直接交給更舊版本，除非固定版本文件明確支援。

不要先 Reset：Factory Reset 會影響 commissioning 與 Controller 關係，不是一般升級回復手段。先用版本回退與 storage 備份。

2–4 GB 主機的保守配置

上游 low-resource guide 估計：Node.js 與 Matter cluster definitions 約 200–300 MB；HA registry 約 50–150 MB 且隨實體數增加；每個 Matter Endpoint 約 1–3 MB；中等安裝的典型 steady state 約 400–600 MB。這是估計值，不是保證或硬性最低規格。

可用 RAM 情境上游建議起點觀察重點
2 GB1–2 座 Bridge、總計不超過約 50 個 entity；非必要先停用 autoComposedDevicesswap、OOM/exit 137、啟動低記憶體警告
4 GB2–4 座 Bridge、約 100–200 entities 的指引範圍memory pressure log、與其他大型 Add-on 競爭
8 GB 以上文件稱通常不需特殊配置，但仍應監控實際 Endpoint 與工作負載不要把 RAM 足夠誤解成 Controller 或網路沒有規模限制

自 v2.0.25 起，應用會以可用記憶體 25% 動態設定 Node heap，並限制在 256–1024 MB。Add-on entrypoint 自動處理，不能從 Add-on 設定頁直接覆寫；Docker/npm 可用 NODE_OPTIONS 調整，但必須留足系統與 HA 空間。若最後一行是 Killed、容器 exit 137 或 OOMKilled，先減少實體與停用高負載 Add-on，再評估 RAM／swap，不要靠無限制提高 heap。

安裝與首次啟動排錯

  1. Add-on 商店找不到 Stable

    確認 repository URL、重新整理商店，並辨識 slug hamh；不要以 hamh-alpha 或 hamh-testing 代替。再核對主機是 HA OS 與支援架構。

  2. HA authentication failed

    不要把 token 貼到 log 或工單。檢查 secret 是否完整、URL 是否為服務可抵達的 base URL、token 是否被撤銷；必要時建立新 token 並安全替換，舊 token 隨即撤銷。

  3. Docker 重建後 Bridge 消失

    停止容器，檢查 <PERSISTENT_DATA_PATH>:/data 是否仍指向原資料且權限正確。不要初始化空 volume 後繼續配對；先從備份回復。

  4. UI 可開但配對找不到

    確認 host network、IPv6、mDNS 與 Controller 網路路徑。到 Health 的 Network Diagnostics 看實際綁定介面；不要只改 HTTP port。

  5. 程序反覆被終止

    查容器狀態、exit code 與主機 OOM 記錄。若為低記憶體，減少 Endpoint、停用非必要自動組合或其他高負載服務，並依平台策略處理 swap／RAM。

  6. 變更 start option 沒生效

    核對名稱、型別、HAMH_ 前綴與服務是否完整重啟。Add-on 只能使用 pinned schema 暴露的欄位，不能假設所有 CLI option 都能直接貼入 Add-on 設定。

常見問題

Home Assistant OS 使用者應優先選哪一種？
上游文件把原生 Add-on 列為 preferred。若你沒有特殊容器維運需求，先用 Stable Add-on，比手動部署更符合多數讀者的責任範圍。
Docker 可以不用 host network 嗎？
固定版本文件與範例都把 host network 視為 Matter 限制下的必要／建議做法。一般 bridge network 可能讓 mDNS 公告不可達；不要因 HTTP 能映射 port 就省略。
Add-on 需要手動填 HA URL 與 token 嗎？
pinned Add-on 啟用 homeassistant_api: true，其公開 schema 沒有 URL/token 欄位。手動部署才要求這兩個 start options。
可以把 token 寫在 Compose 檔嗎？
不建議。用受保護的 env file、secret store 或部署平台 secret，並確保不進版本控制、截圖、shell history與診斷匯出。
--web-port 還能用嗎？
Stable 2.0.55 仍把它當 --http-port alias，但 exact source 已標示 deprecated。新設定應使用 --http-port／HAMH_HTTP_PORT。
升級時是否要重新配對？
正常升級應保留 storage 與既有 Matter 狀態，不應先重設或重配。先備份、固定版本、只改軟體層，失敗時回復相符版本與資料。

固定版本官方與原始碼來源