版本邊界與 Node-RED 在 Home Assistant 中的角色
先把 Add-on、Node-RED runtime、Home Assistant 節點套件與選裝儀表板分清楚，你才能知道畫面、功能與相容性究竟由哪一層決定。本指南固定在可重現的四組版本，不以滾動中的主分支推測行為。
為何需要本章
你在 Home Assistant 裡按下「開啟網頁介面」時，看到的是 Node-RED 編輯器，但負責安裝、啟動、Ingress、資料掛載與權限授予的是 Home Assistant Community App: Node-RED。編輯器內又同時存在 Node-RED 核心節點與 Home Assistant WebSocket 節點。若把這些都叫成「Node-RED 22」，遇到問題時便很容易查錯版本、套用錯誤設定，甚至誤以為某個網路入口已受另一層的登入保護。
本指南的家庭情境是假設你想逐步完成走廊感應燈、離家提醒、溫度觀察等自動化。第一條 Flow 不控制任何設備；稍後才會在明確驗證 entity、觸發條件與回復方式後使用 Home Assistant 的 Action 節點。舊文件或既有 flow 可能稱它為 Call Service；那是舊版介面脈絡，本文後續一律使用目前 UI 名稱 Action。
核心觀念
四層不是四種叫法，而是四份責任
| 層級 | 本指南固定版本 | 負責內容 | 不應外推 |
|---|---|---|---|
| Home Assistant Community App: Node-RED | 22.0.1 | 容器映像、Supervisor manifest、Ingress、direct listener、掛載、啟動設定與預裝套件 | 不是 Node-RED runtime 的版本號 |
| Node-RED | 5.0.2 | 瀏覽器編輯器、runtime、訊息模型、Deploy 與核心節點 | 不要引用其他修補版畫面或行為 |
| node-red-contrib-home-assistant-websocket | 0.80.3 | 連線 Home Assistant 的設定節點、事件、狀態查詢、Action 與 companion entity 節點 | 不是 Home Assistant Core 本身 |
| FlowFuse Dashboard 2 | 1.30.2，選裝 | 另行安裝後提供 dashboard config 與 widget 節點 | 未列於 Add-on direct dependencies，不能說是內建 |
Add-on 的固定 node-red/package.json 明列 node-red 5.0.2 與 node-red-contrib-home-assistant-websocket 0.80.3；也明列 theme collection 5.0.1，卻沒有 @flowfuse/node-red-dashboard。因此 dashboard 只能視為選修擴充。套件名稱中的「Dashboard 2」是產品世代，不代表本指南鎖定的 npm major 必須是 2。
開始前的五步版本盤點
- 確認安裝品項。
在 Home Assistant 的 Add-on 詳細頁確認你使用的是 Node-RED Add-on，而不是另一台主機上自行安裝的 Node-RED。記下 Add-on 顯示版本；本指南只驗證 22.0.1。
- 從啟動紀錄核對 runtime。
先閱讀 Add-on 日誌，確認服務能正常啟動；不要把包含 token、URL、entity ID 或完整訊息內容的日誌貼到公開處。本指南的 runtime 基線是 Node-RED 5.0.2。
- 核對 Home Assistant 節點套件邊界。
Add-on 已預裝 HA WebSocket 0.80.3，不需要為了第一個練習再安裝同名套件，也不要自行改動預設 server connection。等到第 8 章才檢查連線節點。
- 先選擇無副作用練習。
依序閱讀本章、安裝、編輯器，再建立 Inject → Change → Debug。此流程只產生記憶體中的訊息與 Debug 顯示，不呼叫 Action、不寫檔、不操作照明。
- 為未來操作建立變更紀錄。
記下版本、變更目的、Deploy scope 與觀察結果，但清除私人位置、真實 ID、憑證和內部位址。版本不符時先查 release note，不要假定本章每個 UI 細節仍相同。
版本對照與兩種 Home Assistant 門檻
Add-on 22.0.1 的 manifest 宣告 homeassistant: 2023.3.0。這是 Supervisor 判斷 Add-on 是否可安裝的門檻，不是 HA WebSocket 0.80.3 對使用者承諾的完整相容需求。後者的固定 README 明列 Home Assistant 2024.3+、Node-RED 3.1.1+、Node.js 18.2.0+。在本指南組合中，內嵌 Node-RED 5.0.2 高於該 Node-RED floor；你仍應以 Home Assistant 2024.3+ 作為使用 HA WebSocket 0.80.3 的前提。
| 數字 | 來源與用途 | 正確判讀 |
|---|---|---|
| 2023.3.0 | Add-on manifest 的 homeassistant | Supervisor 安裝門檻 |
| 2024.3+ | HA WebSocket 0.80.3 README | 該整合套件的 Home Assistant prerequisite |
| 3.1.1+ | HA WebSocket README | 套件最低 Node-RED；不是本站實際基線 |
| 18.2.0+ | HA WebSocket README | 套件最低 Node.js；Add-on 內由映像管理 |
| aarch64、amd64 | Add-on manifest 的 arch | 22.0.1 宣告的兩種架構；另有 init: false |
init: false 是 container manifest 層的旗標，與設定 safe_mode 讓 Node-RED 以 --safe 啟動不同。也不要把套件內部常數、Add-on 安裝門檻與 README 對使用者列出的 prerequisite 混成單一「最低 HA 版本」。
從家庭情境看系統角色
以「玄關有人經過時，夜間才亮燈」為例：Home Assistant 整合負責把動作感測器與燈具表達成 entity，並維持其狀態；HA WebSocket 節點可訂閱狀態事件、查詢其他 entity，最後透過 Action 請 Home Assistant 執行開燈；Node-RED runtime 負責讓訊息沿著節點與 wires 流動、判斷條件與管理流程生命週期；Add-on 則讓這個 runtime 在 Home Assistant 管理環境內啟動、持久化與透過 Ingress 開啟。
- Home Assistant：設備與服務語意的權威端。Node-RED 不會因為畫布上寫了某個名稱，就自動建立真實設備。
- HA WebSocket 0.80.3：溝通橋梁。它包含 server config、state/event、Action 與 companion entity 等節點；不同節點有不同輸入覆寫及輸出規則。
- Node-RED 5.0.2：執行圖形化程式。每個
msg是 JavaScript object，可有payload、topic、_msgid與其他欄位，不只是單一文字。 - Add-on 22.0.1：部署包裝。它提供資料路徑、proxy、權限與套件集合，但不替你判斷自動化是否安全。
所以「開燈失敗」至少可能落在 entity 不可用、HA connection、Action 設定、訊息條件、runtime Deploy 或 Add-on 啟動等不同層級。先定位層級，再讀對應日誌，遠比反覆重啟有效。
資料、控制與安全責任分層
編輯、部署與重新啟動
你在工作區移動節點是編輯器狀態；按下 Deploy 才把選定範圍交給 runtime；修改 Add-on 設定後，官方 Add-on 文件要求重新啟動 Add-on。Deploy 可能重啟受影響節點，Add-on restart 則重建更外層的服務。對計時器、事件訂閱與有外部副作用的節點而言，範圍不同就可能有不同結果。
認證也不能混為一談
Home Assistant Ingress、direct listener、editor route、flow 建立的 HTTP endpoint、static content 與選裝 dashboard 是不同邊界。能從 Home Assistant 側欄安全開啟 editor，不代表所有 direct endpoint 都自動套用同一層保護；細節在第 2 章拆解。
高權限能力不是每條 flow 都需要
Add-on manifest 授予 Home Assistant API、Supervisor manager、host network、UART 與多個掛載。這描述容器可用能力，不代表你應在 flow 中任意讀寫 Home Assistant 設定、掃描區網或操作序列設備。第三方節點也在 Node-RED process 權限下執行，安裝前必須審查來源與必要性。
由無副作用到家庭自動化的學習路徑
- 第 2 章：透過 Add-on 文件的 Install → Start → Logs → OPEN WEB UI 路徑建立環境，先使用 Ingress，理解 direct port、TLS 與各種認證層。
- 第 3 章：只巡覽 workspace、Palette、sidebar、Help 與三種 Deploy scope。截圖或辨識畫面時不要按 Deploy。
- 第 4 至 7 章：用手動 Inject 練習
msg、Change、Switch、時間與 context；輸出只到 Debug，避免實體副作用。 - 第 8 至 12 章：確認 HA server connection 後，先讀事件與狀態，再學 Action。範例 ID 一律換成你環境中經驗證的 entity，且先設停止與回復條件。
- 後續實戰：加入去彈跳、可用性處理、錯誤路徑、通知與維運。走廊燈等範例先在不影響安全設備的測試對象驗證。
FlowFuse Dashboard 2 只在需要人機介面時選裝。它不是完成 Home Assistant 自動化的先決條件；先把訊息、狀態與錯誤路徑學好，能降低把漂亮畫面誤當可靠控制的風險。
故障排除：先找對層
- 看到 22.0.1，卻在 editor 找不到「Node-RED 22」功能：22.0.1 是 Add-on 版本；應查內嵌 Node-RED 5.0.2 的固定 editor/core 來源。
- Add-on 可安裝，但 HA 節點行為異常：不要只拿 manifest 的 2023.3.0 判斷。核對 HA WebSocket 0.80.3 README 所列 Home Assistant 2024.3+ prerequisite，再看已清除敏感資訊的 Add-on 日誌。
- 教學提到 Dashboard，Palette 卻沒有：FlowFuse Dashboard 2 1.30.2 是選裝且未內建；不是 Add-on 安裝失敗。不要為了前四章先安裝。
- 搜尋到的 Deploy 或 Action 畫面不同：先確認文章是否針對 Node-RED 5.0.2 與 HA WebSocket 0.80.3。新版 UI 名稱是 Action，舊稱 Call Service 只應用於辨識既有資料。
- 不確定問題屬哪層：依序記錄「Add-on 能否啟動、editor 能否開啟、Node-RED 核心 Inject/Debug 能否通、HA server 是否連線、特定 HA 節點是否報錯」。公開回報前移除 token、URL、位置與真實 ID。
固定來源與查證界線
- Add-on 22.0.1 固定提交：manifest、
node-red/package.json、包裝與啟動行為；另見 該提交官方 Add-on 文件。 - Node-RED 5.0.2 固定提交與 Node-RED 官方文件。
- HA WebSocket 0.80.3 固定提交與 整合套件官方文件。
- FlowFuse Dashboard 2 1.30.2 固定提交與 Dashboard 官方文件；僅用來界定選裝項目。
官方文件可用來理解概念；若畫面、預設值或相容性說明不同，先與以上固定版本來源核對，再於無副作用的測試流程確認。
常見問題
Add-on 與 Node-RED runtime 會共用版本號嗎？
看到較新的 Node-RED 修補版說明時，應直接套用嗎？
為什麼安裝後沒有 FlowFuse Dashboard 2？
@flowfuse/node-red-dashboard 1.30.2 是選裝套件，未列在 Add-on 22.0.1 direct dependencies。前四章也不需要它。看到舊 flow 的 api-call-service 要改成 action 嗎？
api-call-service；日後應透過 editor 檢查與遷移。