Home Assistant WebSocket 連線與節點全景圖

為何需要本章

Home Assistant 節點不只是一個「呼叫服務」按鈕。固定版套件註冊 32 個 NodeType：有的接收事件、有的查 cache、有的呼叫 API、有的在 HA 建立 companion entity，另有共享連線的 config node 與 deprecated 相容節點。如果把它們全視為相同，容易把讀取誤認成觸發、把 config node 當成 flow 步驟，或讓高風險 API 節點接到不可信輸入。

本章基線是 Community Add-on 22.0.1，其 node-red/package.json 固定內嵌 Node-RED 5.0.2 與 node-red-contrib-home-assistant-websocket 0.80.3。Add-on manifest 的 homeassistant_api: true 是授權 capability，而套件 README 對 Add-on 使用者明確提供「I use the Home Assistant Add-on」連線模式；兩者共同界定預先配置路徑。

核心觀念

• Server config 是共享組態：persisted type 為 server，保存連線模式與共同設定，被多個 HA 節點引用；它不是一個有 input/output 的一般處理步驟。
• Executable node 會在 flow 執行：可因 HA 事件輸出、因傳入 msg 查詢，或產生外部副作用。每種觸發時機、output property 與錯誤契約都不同。
• Entity node 暴露 companion entity：讓 Node-RED 在 HA 端呈現 binary sensor、button、number、select、sensor、switch、text 或 time。這不是查詢既有 entity 的同義詞。
• Config node 提供共享設定：Server、Device Config 與 Entity Config 是 3 個真正的 config nodes。Update Config 則是有一個 input 與一個 output 的 executable utility，會修改 companion metadata，不是 config node。
• Deprecated 只為相容：舊通用 Entity persisted type ha-entity 仍註冊，但新 flow 應選具體 entity node；遷移前保留備份並逐欄比較。

目前 UI 術語是 Action；舊流程或舊文件可能稱它為 Call Service，這個舊稱只用來辨認既有內容。0.80.3 的 NodeType key 是 Action，但 persisted type 仍是 api-call-service；不要把匯出 JSON 的 type 手改成 action，也不要因名稱更新就重建 credential。

確認 Add-on 預先配置連線

1. 確認基線與備份。

   在 Add-on 資訊頁核對版本，並備份 flow/credentials。不要稱「Node-RED 22.0.1」；正確說法是 Add-on 22.0.1 內嵌 Node-RED 5.0.2。

2. 拖入唯讀節點。

   先使用 Current State 等收到手動訊息才查詢的節點；更深入的 Current State 設定與缺值處理見第 10 章。不要以 Action、Fire Event、API、Webhook 或 companion switch 作第一次連線測試。

3. 選擇既有 Server config。

   在節點的 Server 欄位只選擇 Add-on 已預先配置的既有 Server config，不新增、不編輯連線，也不輸入任何 token。若清單中沒有這項預先配置，立即停止並依本章故障排除檢查，不要自行建立替代 config。

4. 用 placeholder 完成設定。

   若教學畫面要求 entity，使用你環境內專為測試核准的唯讀 entity；記錄時改成 sensor.example_temperature。不公開 entity/device/area/tag/zone/webhook ID。

5. 部署並觀察狀態。

   使用最小 Deploy scope，查看節點狀態與 Add-on log 是否連線。Debug 僅輸出必要欄位，不輸出完整 config、headers 或 HA state attributes。

6. 驗證失敗路徑。

   在不改 credential 的前提下測試缺 entity、unknown/unavailable 等資料狀況。加入 Catch/Status，確認失敗不會流向任何有副作用的節點。

Add-on 路徑應直接共用既有預先配置的 Server config，並先查引用。若它不存在，本章流程到此停止；不要建立第二份連線。刪除或修改 shared config 會影響所有引用節點；這是 config/runtime 邊界最常見的維運風險。

Add-on 連線、權限與隱私邊界

Add-on 22.0.1 manifest 宣告 homeassistant_api: true，套件也在 Add-on 的 direct dependencies 固定為 0.80.3。這證明此映像已打包相容套件並獲得 HA Core API capability；不代表任何 imported flow 都安全，也不代表每個第三方節點自動取得最小權限。Node-RED flow 與額外套件都在受信任執行邊界內，匯入前仍須審查。

Server editor 的連線設定包含 Add-on mode、連線延遲、base URL/access token（非 Add-on 路徑用）、certificate 選項與 heartbeat；另有 HA boolean、global context 暴露、autocomplete cache 與 selector/status UI 設定。不要為了排障關閉 certificate 驗證，也不要把 base URL、access token 或完整 config 匯出到公開材料。

Server config 被 Current State、Events: state、Action 等多個 node 引用；它的修改是共享變更，而非只影響目前 dialog。操作前可從 config node 檢查引用，變更後用 Modified Nodes/Flows 的實際範圍審查。connection delay/heartbeat 是連線管理選項，不是業務 retry，也不能保證某次 Action 成功。

HA server 的 cache 讓 Current State/Get Entities 等節點可以查詢狀態，但「cache 中有資料」不等於資料永遠新鮮；斷線、啟動中、unknown、unavailable、entity 新增/刪除都要明確處理。輸出 state attributes 時採 allowlist，只保留決策需要欄位。

節點分類與四步學習路徑

不必先記住全部節點。依序學習：Events: state（第 9 章）掌握事件、Current State／Get Entities（第 10 章）查詢狀態、Action（第 11 章）執行動作、其他事件與時間節點（第 12 章）；再進入第 13 章實戰與第 14 章 companion entity。

0.80.3 共提供 32 種 NodeType：19 個 home_assistant、9 個 home_assistant_entities（8 個 companion entities 加上 executable Update Config）、3 個 config、1 個 deprecated。

這份矩陣供選型與查閱，不需要把全部 32 個都拖進流程；選定類別後，再進入對應章節實作。

Server/config 與 executable 的責任邊界

Executable node 在 runtime 收到 msg 或 HA 事件後工作；config node 則提供共享物件與 metadata。你可能在畫布看不到 Server config，卻有十幾個節點引用它。因此「刪除看不到的設定」可能讓整批節點失去連線，而修改一個 Action 不會自動修改 Server。

Action 節點的 current UI 欄位應以 action、target、data 理解：target 是 entity/device/area 等選擇，data 是該 action 的參數。response 取決於 HA action，不能保證都在 msg.payload。此外，Current State、Get Entities、Action 等可設定 output property；不要假設節點永遠覆寫 payload。

Action 與 Current State 有 Block Input Overrides 邊界，但不能外推到所有節點。Get Entities 可接受 msg.payload.* 覆寫 rules/output，沒有等同的通用切換；若輸入來自 HTTP、MQTT 或 webhook，先以 Change/Switch 移除不允許欄位並建立 allowlist。API、Fire Event、Action、companion switch/button 等具副作用面，絕不直接接受未驗證外部 msg。

Companion entity 是「Node-RED 提供給 HA 的 entity」。Binary Sensor/Sensor 偏輸出狀態，Button 可由 HA 按下後觸發 flow，Number/Select/Text/Time 接受受限值，Switch 有 get/set/listen 語意。每一種都需要 availability、輸入驗證、唯一性與移除/遷移政策；第 14 章再做深入實作，本章不建立真實 companion entity。

三組需求 floor 與版本邊界

0.80.3 README 的使用者 prerequisites 是 Home Assistant 2024.3+、Node-RED 3.1.1+、Node.js 18.2.0+；其中 Node 與 Node-RED floor 也可由 package metadata 驗證。這是套件對使用者宣告的相容需求。

Add-on 22.0.1 config.yaml 另有 homeassistant: 2023.3.0。那是 Supervisor 的 Add-on 安裝門檻，不能取代套件 README 的 HA 2024.3+ prerequisite。套件 src/const.ts 還有內部 HA_MIN_VERSION = '2023.12'；同樣不能拿來降低對使用者宣告的 2024.3+ floor。三個數字屬於不同層，排障時要分開報告。

升級任何一層前先備份，檢查 release notes 與 migration，於副作用節點停用的測試流程驗證。舊 Entity 節點、Action persisted type、output property、unknown/unavailable/null old/new state 都是遷移時容易出錯的項目。不要直接搜尋／取代流程 JSON type，也不要把新版 palette 名稱當 persisted type。

所有 entity/device/area/tag/zone/webhook ID 都是環境資料；Webhook URL/ID 甚至具入口敏感性。文件與問題回報只用 sensor.example_temperature 之類 placeholder，並清除 access token、headers、地點、日曆內容與 state attributes。虛構 ID 也不可複製成正式部署而跳過現場 allowlist。

故障排除

• 找不到 Add-on 預先配置的 Server config：立即停止本章操作，確認從正確的 Add-on 22.0.1 editor 進入、初始化與 Add-on log 均正常，再依固定 Add-on 文件檢查安裝。不要新增 Server config，也不要建立或貼入 token 排障。
• 只有一個節點沒有輸出：檢查該節點 trigger/input 模式、entity selector、output property 與 unknown/unavailable；用手動 Inject 和必要欄位 Debug 隔離，不改 shared credential。
• 匯入後看到舊 Entity 節點：它是 deprecated ha-entity。先備份並閱讀遷移文件，再映射到具體 companion entity；不要直接改 JSON type。
• 找不到 Action type 的 JSON：current palette 名稱是 Action，但 persisted type 仍為 api-call-service，這是預期相容行為。不要改成不存在的 action type。
• 版本看似高於安裝門檻仍不相容：不要把 Add-on HA 2023.3.0 floor 與套件 HA 2024.3+ prerequisite 混用；同時記錄 Add-on、Node-RED、HA WS、HA、Node 五層版本。
• Debug 洩漏 ID 或 attributes：立即停用完整訊息 Debug，清理 sidebar/log/匯出；公開 issue 前以 placeholder 取代。若 credential 可能曝光，依事故流程輪替，不把值再傳送給任何人。

固定來源

• Add-on 22.0.1 固定提交 bcfd5b8：node-red/config.yaml 與 node-red/package.json。
• HA WebSocket 0.80.3 固定提交 2cbbb69：README.md、package.json、src/const.ts、src/index.ts、src/nodes。
• HA WebSocket 官方使用者文件。
• Add-on 22.0.1 固定官方文件。

選擇節點前先確認它屬於讀取、事件、外部副作用、共享設定或 companion entity；再依上方學習路徑進入對應章節，不要用名稱相似取代行為驗證。

常見問題