MQTT、預裝節點矩陣、Palette 管理與 FlowFuse Dashboard 2 選裝且非內建擴充

先區分核心協定、預裝套件與選裝套件

Add-on 22.0.1 內嵌 Node-RED 5.0.2 與 HA WebSocket nodes 0.80.3。MQTT In、MQTT Out、mqtt-broker 是 Node-RED core；package matrix 是 Add-on image 的直接 dependency 清單；Palette Manager 與 npm_packages 會再增加第三方 server code；FlowFuse Dashboard 2 1.30.2 則是選裝且非內建。這四層不能混稱。

Add-on 有 host_network: true 與 uart: true grants，並以 media:rw、share:rw 掛載資料。這些只表示可能可達或可讀寫，不表示 MQTT、serial、File、File In、Watch 已被使用。任何外連或檔案節點仍要逐一固定目的地、topic、裝置與路徑。備份與秘密處理見第 21 章。

MQTT 的每一層都要獨立選擇

Broker 連線設定決定 transport、協定版本與 session；MQTT In 決定 subscription filter、訂閱 QoS 與輸出資料型別；MQTT Out 決定 publish topic、QoS、retain 與 MQTT 5 properties。設定一個 TLS checkbox 不會自動建立 topic ACL，選 QoS 2 也不會讓下游業務「恰好執行一次」。

MQTT 5 增加 properties 與訂閱 flags；選 MQTT 3.1 或 3.1.1 時不能依賴 MQTT 5 的 response topic、correlation data、content type、message expiry、user properties、no local、retain as published、retain handling 或 session expiry。先固定 broker 支援版本，再設定 nodes，不要靠 client 自動猜測。

高頻 MQTT 與大型 payload 的測試方法可沿用第 18 章：只 Debug 白名單欄位，限制案例數。Message shape 與型別基礎見第 5 章。

六步離線檢查，不建立 broker 連線

1. 建立 topic 契約表。

   為每個資料方向寫出 placeholder topic、publisher、subscriber、payload schema、最大 bytes、允許頻率、QoS、retain 與重複處理方式。不要填真實 broker、client ID 或 credentials。

2. 選定協定與 session。

   明確記錄 MQTT 3.1、3.1.1 或 5；再決定 clean session／clean start、client ID、auto unsubscribe 與 MQTT 5 session expiry。協定不支援的欄位保持空白。

3. 離線讀範例 JSON。

   開啟 14-mqtt-in-out.json，確認 MQTT In 與 MQTT Out 都是 d:true；broker config 為 autoConnect:false，host/client ID/topic 全為完整 placeholder，沒有 credentials。

4. 檢查 TLS 與 ACL。

   在文字規格中指定受控 TLS config、server certificate 驗證、獨立 client credentials，以及最小 publish／subscribe topic ACL。不得把 secret 寫入 broker URL、Function、flow export 或 Debug。

5. 條件式：盤點 package 來源。

   只有要稽核預裝節點或評估安裝時，才對照本章 25 項 bundled matrix，並記錄精確 npm package、固定版本、維護狀態、授權、transitive dependencies、權限與移除方式。本章不執行安裝；只讀 MQTT 的讀者可略過。

6. 條件式：記錄套件或 Dashboard 失敗與回復。

   只有涉及套件或 Dashboard 時，才列出套件啟動失敗、route／Socket.IO 問題與回復方式；MQTT 的 broker 不可達、憑證錯誤、ACL 拒絕、duplicate、stale retained message 與 session 恢復則在 topic 契約中記錄。相關節點保持停用，且不執行 I/O。

離線 MQTT 契約（不是連線設定）
broker: PLACEHOLDER_MQTT_BROKER_HOST
client id: PLACEHOLDER_MQTT_CLIENT_ID
subscribe: PLACEHOLDER_MQTT_INPUT_TOPIC
publish: PLACEHOLDER_MQTT_OUTPUT_TOPIC
protocol: PLACEHOLDER_MQTT_VERSION
max payload: PLACEHOLDER_LIMIT
credentials: 只存受控 credentials store
network action: 禁止執行

章末離線驗收

Node-RED 5.0.2 MQTT In、Out 與 broker 欄位

MQTT In：訂閱與輸出資料型別

MQTT In 輸出至少包含 msg.topic、msg.payload、msg.qos、msg.retain。MQTT 5 packet 可能再投影 responseTopic、correlationData、contentType、messageExpiryInterval、payloadFormatIndicator、reasonString 與 userProperties。這些都是不可信 broker/message metadata，不能直接用來選 HA Action、檔案路徑或 HTTP URL。

MQTT Out：publish 欄位與 message overrides

MQTT Out 有 Broker、Topic、QoS、Retain；Topic 留空時可取 msg.topic，QoS／Retain 留空時可取 message 值。節點中固定的 topic、QoS、retain 會優先套用。這種彈性也意味著不可信 message 可能改變 publish 行為；對外部輸入先移除或驗證 msg.topic、msg.qos、msg.retain。

MQTT 5 時另有 User Properties、Response Topic、Correlation Data、Content Type、Message Expiry。Response Topic 是協定 metadata，不會自動建立安全 RPC；reply topic ACL、correlation 唯一性、timeout、duplicate 與 late reply 都要另外設計。Publish topic 不可含 + 或 #。

mqtt-broker：連線、安全、session 與訊息

匯入舊 broker config 時還要檢查 persisted verifyservercert。5.0.2 編輯器定義的 legacy 預設為 false；若 TLS config 沒有提供 rejectUnauthorized，runtime 就以這個值作 fallback。舊設定必須改用核准的 TLS config，並確認最後得到 rejectUnauthorized=true；只打開 TLS toggle 只能表示使用加密 transport，不能證明已驗證 broker identity。

Protocol value 3 對應 MQTT 3.1 compatibility，4 是 MQTT 3.1.1，5 是 MQTT 5。若停用 auto-connect，5.0.2 允許由受控 action message 連線或斷線；這不是本章操作入口，不要把 MQTT In 或 HTTP In 的外部 payload 直接接去控制 broker。Add-on host_network:true 讓更多本機服務可能可達，因此 broker allowlist 與 ACL 特別重要。

Add-on 22.0.1 的直接 dependencies 角色摘要

固定 node-red/package.json 共 25 項直接依賴：19 項提供 Palette／config nodes，1 項是 Node-RED runtime，1 項是 editor theme，4 項是 wrapper／runtime support libraries。這不是完整 transitive tree；預裝只代表可用，不代表任何 flow 已執行它。只需 MQTT 的讀者可跳過下方參照清冊。

其中 Cast、InfluxDB、Modbus、email、feedparser、ping、serialport 等具有網路、資料庫或實體 I/O；BigTimer、SunEvents、suncalc 相關節點可能依時間自主產生訊息。Counter、moment、smooth 等看似純轉換，也可能把錯誤結果送往後續 action。依第 17 章把運算與副作用分層，不因「bundled」而省略驗證。

Palette、npm_packages 與啟動持久性

Palette Manager 安裝 node module，module 的 server-side JavaScript 以 Node-RED process 權限執行；這不是只有 editor icon 的 UI 變更。Add-on 的 npm_packages 則在每次啟動時切到 /opt，執行 npm install --omit=dev --omit=optional。system_packages 先用 Alpine package manager 安裝，再處理 npm packages，最後才逐行 eval init_commands；任一失敗會中止初始化。

不要只寫 package name 或寬鬆 semver。變更紀錄至少保留 exact version、官方 registry identity、來源 repo、license、維護者、發佈日期、known advisories、Node／Node-RED compatibility、transitive tree 摘要與 rollback（回復）version。鎖定 direct version 不等於所有 transitive dependencies 都永久不變；在隔離環境產生可重建 lock／清冊，再依正式程序更新。

Add-on backup 明確排除 node_modules，所以恢復不是逐 byte 還原安裝樹；自訂 declarations、package metadata 與可用 registry 必須能重新建立相同依賴。啟動時 install 也會增加 availability 依賴。不要同時以 Palette 與 npm_packages 管同一 package，以免 ownership 與版本不清。

File／File In／Watch 與 mounted storage

Node-RED core 另有 File、File In、Watch。Add-on 的 media:rw、share:rw grants 讓容器具備讀寫可能性；不是自動授權 Flow 使用任意 path。File name 若來自 MQTT、Dashboard 或 HTTP input，可能形成 traversal、覆寫與資料外洩。固定 base directory 與 filename allowlist，限制 bytes／頻率，所有 write 保持停用。Serial nodes 同理：uart:true 是 grant，不是任意裝置命令的核准。

FlowFuse Dashboard 2 1.30.2：選裝且非內建

Add-on 22.0.1 的 25 項清單沒有 @flowfuse/node-red-dashboard。固定 package 1.30.2 宣告 Node >=14、Node-RED >=3.0.0；Node-RED 5.0.2 位於宣告範圍，但仍要在目標 Add-on 測試。Package 註冊 5 個 config nodes 與 22 個 ui-* widgets，共 27 registrations，會新增 server code、browser code、HTTP route 與 Socket.IO 通訊。

Add-on direct NGINX 的 /endpoint/ 不走 editor 的 Supervisor auth_request；Ingress 只允許 Supervisor ingress source，但不能外推成每個 Dashboard user 都有 widget authorization。http_node Basic Auth 是否符合你的 route 與 Socket.IO session 要以實際 proxy 路徑驗證。使用 custom Dashboard path 時，必須把 custom route 與 hard-coded /dashboard/manifest.webmanifest 分開測試 path 與 auth；切勿因 editor 有登入，就假設 dashboard page、manifest、assets 與即時 channel 自動安全。

Legacy migration，不是 drop-in replacement

舊的 unscoped node-red-dashboard 以 Angular v1 為基礎，屬 legacy；本章不教 fresh install。先前 scoped 名稱 @flowforge/node-red-dashboard 已 deprecated 且不再更新。FlowFuse Dashboard 2 是重寫產品，不可宣稱既有 ui_* nodes、theme、layout、custom template、browser script、URL、authentication 或 client state 能自動、原樣遷移。

既有 legacy flow 應先清冊化 pages/groups/widgets、template code、routes、身分驗證、CSS、browser dependencies 與 message contracts，再在隔離副本逐頁重建和比對。Legacy 與新 Dashboard 並行時還要防止 route、Socket.IO、credentials 與雙重副作用衝突。不要先移除舊套件，也不要把新 widget 接到 production action。

故障排除

• MQTT node 一直 disconnected：保持 In／Out 停用，依序檢查 placeholder、DNS、port、協定版本、TLS chain、server hostname、client ID、credentials 與 broker ACL。不要先關閉 certificate validation，也不要改成匿名連線。
• 收到重複訊息：QoS 1、reconnect 或 subscriber restart 都可能重送。以穩定 message ID／業務 key 做有界 deduplication，記錄期限；不要假設 QoS 2 能讓 HA、email 或資料庫副作用端到端 exactly once。
• 新訂閱立刻收到舊命令：檢查 packet 的 retain flag 與 broker retained state。不要由本章範例發佈清除訊息；先由 broker 管理程序確認 topic、權限與影響範圍。
• 非 clean session 後 subscription 異常：確認 client ID 唯一且固定、session expiry、auto unsubscribe、broker 佇列上限與舊 client 是否仍在線。不要讓多個執行個體共用 client ID。
• JSON output 報解析錯誤：確認 content type、encoding 與 publisher schema；不要把無法解析的 bytes 直接改成 auto-detect 後當可信 object。限制 payload bytes 並把錯誤路徑接有限 Catch。
• Add-on 在自訂 package 後無法啟動：檢查 exact package、architecture、registry availability、system_packages → npm_packages → init_commands 的 fail-fast 順序。使用已記錄的回復版本，不能用未 pin 版本反覆試裝。
• Palette 有 package，但找不到預期 node：先看 package role；bcryptjs、js-yaml、line-by-line、source-map-support、node-red runtime 與 theme collection 都不是一般 runtime Palette node。再檢查 package 的實際 registrations 與啟動 log。
• Dashboard page 可開啟但即時資料不更新：分開檢查外部 route rewrite、Socket.IO path、HTTP 與 io middleware、proxy streaming／upgrade、same-origin 與 session。不要為排錯公開 direct endpoint 或移除 authentication。
• Legacy Dashboard flow 匯入後版面／template 不同：Dashboard 2 不是 drop-in。逐頁重建 config nodes、widgets、layout、CSS、template 與 message contract，不要 fresh install legacy package，也不要把兩套 nodes 名稱直接互換。

固定版本來源與官方文件

本章用 exact commits 確認 MQTT fields、25 項直接依賴、啟動安裝順序與 Dashboard 2 邊界。外部 broker 與組織 ACL 屬環境政策，不由這些原始碼自動提供。

• Home Assistant Community App: Node-RED 22.0.1 固定提交：25 項 direct dependencies、grants、maps、system_packages、npm_packages 與啟動順序。
• Node-RED 5.0.2 固定提交：MQTT In／Out／broker、TLS、WebSocket／TCP／UDP 與 File／File In／Watch。
• FlowFuse Dashboard 2 1.30.2 固定提交：package identity、compatibility、27 registrations、route 與 Socket.IO。
• Node-RED 官方文件：Core nodes。
• Node-RED 官方文件：Adding nodes。
• Node-RED 官方文件：Securing Node-RED。
• FlowFuse Dashboard 2 官方文件。
• 本站停用範例：14-mqtt-in-out.json；匯入前先讀安全範例說明。

常見問題