目標與現況
- 目前最難維護的 automation 是哪些？問題是可讀性、重用、除錯，還是跨服務整合？
- 誰會編輯與 Deploy？誰核准有外部副作用的 Flow？
- 有哪些實體、事件、裝置、HTTP 或 MQTT 邊界？哪些資料不能離開家庭網路？
- 可接受的變更窗口、回復時間與備份週期是什麼？
WoowTech · 顧問與決策手冊
先確認問題與責任，再決定是否導入 Node-RED
這是探索、估範與驗收框架，不是保證書。成果取決於家庭情境、整合數量、主機資源、Flow 品質與維運能力；不得把單一案例外推成通用 ROI、容量或延遲承諾。
探索會議的問題
驗收與營運
- 用哪組代表性案例驗收成功、拒絕、逾時與 Home Assistant 重啟？
- 既有 automation 如何並行、停用與回退，才能避免雙重觸發？
- 誰看 Debug／Catch／Status，誰處理 package 與 Add-on 更新？
- 需不需要 Dashboard？若需要，是否接受它是選裝、非綑綁功能？
Node-RED 與原生 HA automation 的 fit／no-fit
| 情境 | 較適合 Node-RED | 較適合原生 automation |
|---|---|---|
| 流程形狀 | 多分支、等待、合流、跨協定且需要可視化追蹤 | 少量 trigger／condition／action，原生 UI 已清楚表達 |
| 團隊能力 | 有人理解 msg、部署範圍、錯誤處理及版本控制 | 維護者只想使用 HA 內建介面與共同 YAML／UI 慣例 |
| 整合需求 | 需要可審查的資料轉換、HTTP／MQTT 與子流程重用 | 只使用 HA 現有 trigger、condition、action |
| no-fit 訊號 | 若無維護者、無備份、無測試環境或拒絕治理，暫不導入 | 若需求簡單，不應為視覺化而額外增加 runtime |
版本與先決條件邊界
固定基準：Add-on 22.0.1、Node-RED 5.0.2、HA WebSocket nodes 0.80.3；FlowFuse Dashboard 2 1.30.2 是 optional nonbundled。先確認相符 tag、相容 Home Assistant、可用備份空間與受控測試環境，再引用本手冊。
- 不得把 Add-on、Node-RED、HA WS 或 Dashboard 的版本互相替代。
- 先盤點 Ingress／direct access、TLS、credential secret、Home Assistant token 與最小權限。
- 第三方 palette node 逐項審核來源、版本、維護狀態與資料流向。
架構選項
A：原生為主
保留簡單 automation；Node-RED 只承接確有多步資料流價值的案例，降低遷移與 runtime 面積。
B：Node-RED 編排層
HA 保存實體與服務權威，Node-RED 處理事件、狀態判斷與流程控制；明定雙方責任及失敗模式。
C：受控外部整合
加入 HTTP／MQTT 時建立 allowlist、逾時、重試上限、秘密注入、審計與停用開關。
D：選裝 Dashboard
只有明確使用者與資訊需求才安裝 FlowFuse Dashboard 2；另列 package 生命週期與權限。
分階段推出
- 盤點：固定版本、資料流、責任人、風險、成功指標與回退點。
- 無副作用試點：只用 Inject、Change、Switch、Debug 驗證 msg 契約與部署流程。
- 影子驗證：讀取 HA 事件／狀態但不呼叫 action，比對既有 automation 的決策。
- 單案例切換：備份後停用一條舊 automation，啟用具限流與錯誤處理的新 Flow。
- 分批擴張：逐案例記錄結果、例外與回退演練，不以試點成功推論全部負載。
- 移交：交付 Flow、版本清單、測試證據、維運 runbook 與已知限制。
範圍與交付物
| 階段 | 包含 | 明確不包含 |
|---|---|---|
| 評估 | 訪談、現況圖、候選案例、風險與估算假設 | 未經核准的正式環境變更 |
| 實作 | 約定 Flow、佔位符設定、錯誤路徑、文件與測試 | 未列入的裝置、客製 node 或公網暴露 |
| 交付 | export JSON、來源版本、驗收矩陣、備份／回復 runbook | 無期限支援、保證效能或未量測 ROI |
威脅與風險控制
| 風險 | 控制 | 停止條件 |
|---|---|---|
| 秘密或識別資料外洩 | 使用 credential store 與佔位符；export、log、截圖三重掃描 | 發現真實 token、URL、entity/device ID 立即停止 |
| 重複或錯誤 action | 預設停用副作用節點、限流、去重、明確 payload 與人工批准 | 無法證明回復或影響範圍時不 Deploy |
| 外部端點失效 | 逾時、有限重試、斷路策略與本地安全狀態 | 無逾時或無失敗路徑不得上線 |
| 更新漂移 | 固定版本、先備份、測試環境重驗與 release note 審查 | 來源版本不明或 manifest 未更新時停止 |
驗收矩陣
| 案例 | 證據 | 通過條件 |
|---|---|---|
| 正常事件 | 固定輸入、Debug 與 HA 狀態前後比對 | 只觸發一次且輸出符合契約 |
| 缺欄位／錯型別 | 測試訊息與 Catch 記錄 | 安全拒絕，不呼叫外部 action |
| HA 斷線／重啟 | Status 時序與恢復紀錄 | 不產生補送風暴，恢復方式符合設計 |
| 回退 | 備份、停新 Flow、還原舊 automation 的演練 | 在約定窗口完成且無雙重觸發 |
| 安全 | sensitive／Flow gate 與人工審查 | 無秘密、真實識別值或未核准端點 |
維護與支援
- 每次更新前匯出 Flow、保存 HA 備份並記錄 Add-on、Node-RED、HA WS 與選裝 package 版本。
- 每季抽查 disabled 節點、credential、HTTP／MQTT 端點、Catch／Status 覆蓋與擁有者。
- 事件支援需有嚴重度、回應窗口、可重現資料與權限邊界；不承諾未量測效能。
- 功能擴充另行估範；維護方案不默認包含新裝置、客製節點或雲端部署。
常見問題
Node-RED 一定比原生 automation 好維護嗎？
不一定。流程形狀、團隊能力、命名、測試與責任分工共同決定；簡單案例通常留在原生較直接。
可以承諾節省多少成本嗎？
不能做通用承諾。先定義基線、期間與可歸因指標，再以實際紀錄評估。
FlowFuse Dashboard 2 已內建嗎？
沒有。1.30.2 在本指南是選裝且 nonbundled，需獨立評估與安裝。
可以直接把範例匯入正式環境嗎？
不可以。先讀 README、替換佔位符、確認 disabled 副作用節點並在隔離環境驗收。
誰有 Deploy 權限？
由專案責任矩陣明定；顧問或 agent 的文件交付不自動取得正式環境部署權。