第 2 章

安裝 Add-on 22.0.1 與安全設定

依 Add-on 22.0.1 官方文件完成安裝、啟動、日誌檢查與開啟 Web UI，並在動手公開 direct port 前，分清 Ingress、TLS、editor 認證、HTTP endpoint 認證與 static content 認證。

為何需要本章

Add-on 開箱即預先設定 Home Assistant server connection；安裝第一天最安全的做法不是貼上網路文章的長篇 YAML，而是先以預設 Ingress 路徑確認服務正常，再逐項評估是否真的需要 direct access、自訂套件或 shell command。家庭自動化通常握有燈光、門窗狀態與通知能力；錯誤公開 editor 或 flow endpoint 的影響不只是「網頁被看到」。

本章只處理 Add-on 管理層。你不需要自行輸入 Home Assistant token，也不應把 Supervisor token、憑證私鑰、真實 URL 或 entity ID 放入設定範例。修改 Add-on 設定後，固定版本官方文件要求重新啟動 Add-on；在家中重要自動化已依賴 Node-RED 時，先安排維護時段並評估中斷。

底線：不要啟用 leave_front_door_open。固定版本官方文件即使對內網也強烈反對。內網不等於受信任邊界。

核心觀念：入口、傳輸與認證要分開

層用途22.0.1 可驗證行為
Home Assistant Ingress從 Home Assistant UI 開啟 editormanifest 為 ingress: true、動態 ingress_port: 0、ingress_stream: true；NGINX ingress listener 限制 Supervisor ingress 位址
Direct access把容器 Web interface 映射到 hostmanifest 提供容器 80/tcp，建議 host 1880；是否啟用取決於 Network port 設定
Direct TLS加密 direct listener 傳輸ssl、certfile、keyfile只套用 direct access，對 Ingress 無效
Editor direct auth保護 direct 的 editor 路徑wrapper/NGINX 預設透過 Supervisor auth；不可用 leave_front_door_open 繞過
Flow HTTP auth保護 flow 建立的 /endpoint/由 http_node username/password 管理；不是 editor 登入
Static auth保護 Node-RED static content由 http_static 管理，與上述兩者獨立

Add-on runtime 將 Node-RED backend 固定在 loopback 127.0.0.1:46836，使用 /config/ 作 userDir、/config/nodes 作 nodesDir、flows.json 作 flowFile，並把 httpNodeRoot 固定為 /endpoint。Node-RED 自身設定中的 adminAuth 與 https 為 null，是因為認證與 TLS 委派給外層 NGINX/wrapper；這絕不表示公開是安全的。

官方安裝、啟動與驗證順序

  1. 從 Home Assistant 開啟 Add-on 頁。

    依固定 Add-on DOCS 的 My Home Assistant 按鈕前往此 App；確認頁面顯示的是 Community App: Node-RED。若你的平台或管理介面名稱略有不同，以 Add-on 詳細頁為定位，不要使用來路不明的容器映像。

  2. 按下 Install。

    等待安裝完成，不要同時加入 npm_packages、system_packages 或 init_commands。本版只宣告 aarch64 與 amd64；不相符的硬體不要用非官方方式繞過架構檢查。

  3. Start「Node-RED」App。

    首次啟動會建立 /config 所需內容；固定初始化程式也包含舊資料與 theme 遷移處理。若 /config/package.json 已存在，初始化還會嘗試移除衝突的舊套件 node-red-contrib-home-assistant、node-red-contrib-home-assistant-llat 與 node-red-contrib-home-assistant-ws；解除安裝失敗時會記錄 warning。讓初始化完成，不要在啟動中途手動改檔。

  4. 先檢查 Node-RED logs。

    官方順序明確要求先看 logs 是否一切正常。尋找啟動完成或清楚錯誤；分享畫面前遮蔽 token、主機名稱、URL、路徑中的個資與訊息 payload。不要因 editor 暫時未開就反覆按 Start。

  5. 按「OPEN WEB UI」。

    從 Add-on 頁使用按鈕進入預先設定好的 editor。固定文件說不需要新增、變更或更新 server connection；不要為了「完成安裝」自行貼入 token。

  6. 保持預設入口，建立驗收紀錄。

    先不公開 direct port。記錄 Add-on 22.0.1、啟動結果與 Ingress 是否可開啟；接著閱讀第 3 章，再以第 4 章的無副作用 Flow 驗證 runtime。

安裝前提、架構與權限能力

Add-on manifest 的 Home Assistant 安裝門檻是 2023.3.0，但 HA WebSocket 0.80.3 對使用者列出的 prerequisite 是 Home Assistant 2024.3+；要使用本指南整合功能，應滿足後者。Add-on 22.0.1 只宣告 aarch64、amd64，並設 init: false。這個 init manifest flag 不是 Node-RED Safe Mode。

Manifest 授予的能力

宣告精確值你應如何判讀
Supervisor APIhassio_api: true、hassio_role: manager容器取得高權限 Supervisor manager 能力；不得輸出 token
Home Assistant APIhomeassistant_api: true可連 Home Assistant Core API；不代表 flow 應硬編碼 token
Authentication APIauth_api: truewrapper 可使用 Supervisor auth API；不能外推到所有 endpoint
Networkhost_network: true擴大本機網路可達面；每個 HTTP、MQTT、TCP/UDP 與 discovery 用途仍須最小化
Serialuart: true有 UART 能力；只有明確需求與裝置控制計畫時才使用相關節點

這些是容器層 grants，不代表每條 flow 都會使用。安裝第三方節點後，該程式碼在 Node-RED process 權限下執行；因此「Add-on 已核准」也不等於任意 npm package 都可信。

固定 node-red/package.json 也直接鎖定 bcryptjs 3.0.3 與 js-yaml 5.2.2。前者供 wrapper 的 HTTP Basic Auth hash，後者是 wrapper/runtime 支援依賴；它們不是你需要拖到 Palette 的節點，也不能據此推論所有 routes 共用同一認證。不要自行替換這些映像內依賴。

資料 maps 與備份界線

Map模式安全意義
addon_configrw/config 可持久化 flows、settings、nodes 與 credentials；限制檔案存取
homeassistant_configrw可讀寫 Home Assistant configuration；不要讓一般 flow 任意操作
mediarw驗證檔名、路徑與不可信內容，避免覆寫或 path traversal
sharerw可能被其他 Add-ons 存取，不要存明文 secrets
sslmanifest 未標 rw供 direct TLS 讀取憑證與私鑰；絕不把私鑰內容放進 flow 或 log

manifest 的 backup_exclude 排除 node_modules。因此備份不是逐 byte 的完整容器副本；還原後自訂 dependency tree 必須能重建。這也是固定第三方 package 版本、保留設定清單與在還原後重新驗證的理由。

每一個 Add-on 選項

下表以 22.0.1 的 config.yaml 為準。問號代表 schema 可省略；「預設」只在 manifest 的 options 明列時填入。不要直接複製官方 DOCS 的示範帳密或命令；該段原文也明確提醒只是範例。

選項預設／schema用途與安全操作
log_level未顯式預設；trace|debug|info|notice|warning|error|fatal，可省略控制 Add-on log 詳細度；官方 DOCS 說預設為 info。排障才短暫提高，完成後調回必要程度，因 log 可能含訊息內容
credential_secret未顯式預設；password，可省略加密 Node-RED 儲存 credentials。設定後安全備存且不要任意更改，否則既有 credentials 無法解密；Projects 手動啟用時行為另有邊界
themedefault；固定清單，可省略只改 editor 外觀，不是資安控制；變更後重啟 Add-on
http_node.username / password空字串；str/password保護 flow 建立的 /endpoint/；需 direct port 才能按 DOCS 所述方式存取。與 editor auth 分開，使用自訂強密碼
http_static.username / password空字串；str/password只保護 static content，不保護 editor 或其他 routes
ssltrue；booldirect listener TLS 開關，對 Ingress 無效；不要只看這個值就判定整體安全
certfilefullchain.pem；str/ssl/ 下 certificate filename；不會自動簽發或續期，需驗證來源、有效期與配對
keyfileprivkey.pem；str/ssl/ 下 private-key filename；限制讀取，禁止匯出內容
system_packages[]；字串陣列啟動時安裝額外 Alpine packages；增加供應鏈、原生程式與啟動時間風險
npm_packages[]；字串陣列啟動時安裝額外 npm/Node-RED packages；固定版本、審查維護者與程式能力，最初保持空陣列
init_commands[]；字串陣列每次啟動逐行以 shell eval 執行；具有任意命令能力，不放秘密，最初保持空陣列
leave_front_door_open未顯式預設；bool，可省略繞過 direct editor 的 Supervisor auth。不要啟用；保持省略或 false，即使只有內網也一樣
safe_mode未顯式預設；bool，可省略true 會傳入 --safe，runtime 啟動但 flows 不啟動，僅供修復；不是認證或永久停用
max_old_space_size未顯式預設；int，可省略V8 old-space MB；不是 container 總 RAM 限制。不要在無量測下任意設高或設低

每次啟動的自訂初始化順序固定為 system_packages → npm_packages → init_commands。這是 fail-fast 流程：任何 package 安裝或 command 失敗，都會立即中止該初始化服務，後續階段不會繼續執行。

Theme 固定清單

查看 22.0.1 支援的 theme 名稱

schema 允許以下名稱：

  • default
  • aurora
  • cobalt2
  • dark
  • dark-modern
  • dracula
  • espresso-libre
  • github-dark
  • github-dark-default
  • github-dark-dimmed
  • midnight-red
  • monoindustrial
  • monokai
  • monokai-dimmed
  • night-owl
  • noctis
  • noctis-azureus
  • noctis-bordo
  • noctis-minimus
  • noctis-obscuro
  • noctis-sereno
  • noctis-uva
  • noctis-viola
  • oceanic-next
  • oled
  • one-dark-pro
  • one-dark-pro-darker
  • railscasts-extended
  • selenized-dark
  • selenized-light
  • solarized-dark
  • solarized-light
  • tokyo-night
  • tokyo-night-light
  • tokyo-night-storm
  • totallyinformation
  • zenburn
  • zendesk-garden

初始化程式會處理舊 dark 向 dark-modern 的遷移；新設定可直接選清單中的現行項目。

Ingress、direct port、TLS 與 HTTP routes

首選 Ingress

從 Home Assistant 的 OPEN WEB UI 進入，不需要先映射 host port。manifest 的動態 ingress port 不是你應手動打開的固定對外 port；ingress_stream: true 也不等於每個自建 endpoint 都自動受 Home Assistant 登入保護。

Direct access 是額外暴露面

manifest 宣告容器 80/tcp 可映射 host 1880，description 為 Web interface。只有明確需要直接存取 HTTP nodes 或 dashboard 等 route，且已完成網路分區、TLS、認證與來源限制評估時，才在 Add-on 的 Network 區設定 port。不要公開到網際網路，也不要假設路由器 NAT 或「只有家人知道位址」就是控制措施。

/endpoint/ 特別重要

固定 direct NGINX template 對 /endpoint/ 不套 editor 的 Supervisor auth；應由 http_node credentials 保護。Add-on DOCS 也指出 HTTP nodes 或 dashboard 要使用 direct access，URL 應以 /endpoint/ 開頭，否則 Home Assistant authentication 會介入。這不表示只要加 prefix 就安全：仍須 Basic Auth、TLS、輸入驗證與 rate/size 控制。

TLS 不是身份驗證

ssl: true 只讓 direct listener 使用 HTTPS；certfile 與 keyfile 從 /ssl/ 取得。憑證驗證伺服器及加密傳輸，不能取代 editor auth 或 endpoint credentials。Ingress TLS 由其外層路徑處理，不受此選項控制。

安全初始設定與變更清單

  • 先保留 theme: default、ssl: true、預設憑證檔名，並讓 system_packages、npm_packages、init_commands 都是空陣列；不要加入未用功能。
  • 保持 direct host port 未公開。若業務需求必須啟用，逐一驗證 direct TLS、editor auth、http_node 與 http_static，並限制網路來源。
  • 絕不啟用 leave_front_door_open。safe_mode 只在排障時暫用，修復後先審視有副作用節點，再按計畫恢復。
  • 為 credential_secret 建立受控備存，不把值放在 flow、公開截圖或版本庫。設定後不要任意更改。
  • 每次設定變更前記錄目的與回復值；變更後依官方文件 restart Add-on，先讀 logs，再 OPEN WEB UI。重要家庭自動化要安排可接受的中斷時段。
  • 備份策略要考慮 node_modules 被排除；保留固定版本的自訂套件清單，並實際演練還原後重建與 flow 驗證。
  • 日誌提高至 trace/debug 前先縮小重現範圍；完成後降低層級，分享時清除秘密、環境 ID、內部 endpoint 與私人事件內容。

故障排除

  • 安裝按鈕不可用：先核對 Home Assistant 與硬體。22.0.1 manifest floor 為 2023.3.0，architecture 只有 aarch64/amd64；不要用手動改 manifest 的方式繞過。
  • Start 後 OPEN WEB UI 無法使用：按照官方順序先看 Add-on logs。等待首次初始化完成，確認沒有自訂 package 或 command 失敗；不要先新增 direct port。
  • Ingress 可開 editor，但 HTTP In endpoint 不通：這是預期需要另行設計的邊界。DOCS 指出 HTTP nodes 需要 Network direct access，並使用 /endpoint/；啟用前先配置 TLS 與 http_node 強認證。
  • Direct access 出現憑證錯誤：確認 ssl、/ssl/ 下的 certfile/keyfile 名稱、憑證有效期與配對；不要關閉認證或公開 HTTP 當作修復。
  • 修改 credential_secret 後 credentials 失效：停止反覆修改。固定 DOCS 明確說變更會使既有 credentials 無法解密；依受控備存與備份復原，不要把值貼到 issue。
  • 加套件後啟動很慢或失敗：移除最近新增項目，一次只恢復一項。每次啟動依 system_packages → npm_packages → init_commands 執行；任一 package 安裝或 command 失敗都會立即中止該初始化服務。
  • Flow 啟動後立即造成問題：設定 safe_mode: true 並 restart 以不啟動 flows 的方式修復；完成後先檢查 Action、HTTP、檔案與裝置節點，再移除 Safe Mode。

固定來源

常見問題

安裝後要自己新增 Home Assistant server 或 token 嗎？
不需要。Add-on 22.0.1 DOCS 說已預先設定，開箱可用；不要為了初始化而硬編碼 token。
ssl: true 是否代表 Ingress 與所有 endpoint 都安全？
不是。該開關只控制 direct listener TLS，對 Ingress 無效；TLS、editor auth、flow endpoint auth 與 static auth 是不同控制層。
可以只在家中內網啟用 leave_front_door_open 嗎？
不可以。本指南不提供任何啟用方式；固定官方文件也強烈建議不要使用，即使只暴露在內網。
為何 /endpoint/ 需要另外設定帳密？
direct NGINX 路徑不套 editor 的 Supervisor auth，這類 flow HTTP routes 由 http_node 保護。仍需 TLS、輸入驗證與網路限制。
加入 npm package 後 App 反覆啟動失敗，先做什麼？
先查看 Add-on log 中失敗的初始化階段，移除最近加入的 package 並重新啟動；不要連續加入更多 package 或用提高記憶體上限掩蓋供應鏈、版本或編譯錯誤。
備份是否包含已安裝的全部 npm 檔案？
不能這樣假定。manifest 的 backup exclusion 包含 node_modules；還原後 dependency tree 必須可由受控清單重建並重新驗證。