WoowTech KNXD

第一部 · 第 3 章

安裝前先完成安全預檢

不抄錄真實環境值，先確認權限、備份、來源版本、immutable build、隔離與停止條件。

已撰寫

本章任務卡

把 KNXD Add-on 想成準備進駐大樓的翻譯櫃檯。正式開門前，你先確認管理權限、備份、來源、建置證明與停止方法。這一章只做檢查，不加入 repository、不安裝、不啟動，也不收集現場值。

目的
完成一張不含環境資料的安裝前檢查表，得到「可以進入第 4 章」或「先停止補資料」的判斷。
準備
可以登入 Home Assistant，並知道誰有 Add-on 管理權限。
時間
約 15 分鐘。
系統變更
不修改 Home Assistant；只做無實值預檢。
預期結果
完成八項分類；本站缺少核准 artifact digest 時，明確得到安裝仍被封鎖的判斷。
停止條件
  • 無法建立或確認可用備份。
  • 需要公開主機、位址、USB 序號、憑證或裝置路徑。

先守住資料與操作界線

檢查表只記分類與占位標記，例如「管理權限：符合」或「網路規劃：未知」。不要把真實值換成看似匿名但仍可回推環境的縮寫。

不得抄錄或分享：主機名稱、IP、KNX 個體位址、群組位址、USB 序號、帳號、密碼、token、憑證與裝置路徑。看到這些內容時，只記「已遮罩」或「未知」，不要貼到文件、截圖、聊天或 issue。

本章不執行像道路短訊息的 KNX telegram，不執行群組寫入，禁止 ETS 群組讀取；也禁止把工程設計寫入裝置的 ETS programming／download與實體控制。若檢查需要接線、開啟裝置或測試設備反應，已經超出本章。

用開門清單理解預檢

大樓櫃檯不會因為招牌掛好了就直接開門。它要先確認誰負責、能否退回原狀，以及送件會走哪一類入口。KNXD Add-on 也一樣。

來源、存檔與送件入口

先這樣想：repository 是指定書庫，commit 是精確存檔編號，artifact digest 是送到現場那只封箱的指紋；三者要有建置證明連起來。介面類別則只說貨會走哪一類入口，不寫門牌與鑰匙編號。

正式名稱：software repository、Git commit、artifact/image digest、source-to-build attestation 與 interface class。

本章會用到：只記核准證明與介面類別各自的符合／不符合／未知狀態；不記裝置路徑、序號、IP 或任何位址。商店版本文字不能代替封箱指紋與來源到建置的證明。

準備一張無實值檢查表

建立八列檢查表：Home Assistant 安裝類型、管理權限、Home Assistant 備份、來源與版本、介面類別、網路規劃、停止條件、還原決策。每列只能選「符合、不符合、未知」，再加一句不含實值的說明。來源與版本列必須同時核對來源鎖、核准的 artifact/image digest，以及把該 digest 綁到固定 commit 的 source-to-build attestation。

  • 安裝類型只記「支援 Add-on 管理」或「待確認」，不記主機資訊。
  • 權限只記角色是否能管理 Add-on，不記帳號或登入資料。
  • 備份只記時間範圍與涵蓋範圍是否已核對，不附檔案、不貼名稱。
  • 介面與網路只記方案類別和是否經負責人確認，不記任何端點或識別值。

逐項完成安全預檢

  1. 確認 Home Assistant 安裝類型。只判斷目前環境是否提供 Add-on 管理介面。若不確定或畫面不同，記「未知」並停止，不用其他主機方式繞過。
  2. 確認管理權限。由實際管理者人工確認你是否能安裝、啟動與停止 Add-on。權限不清楚就停止，不借用或分享憑證。
  3. 確認備份或回復點。人工核對 Home Assistant 備份的時間、涵蓋範圍與還原責任人。沒有能說明範圍的備份，就不要進入安裝。
  4. 核對來源與版本。預期repository（指定軟體書庫）身分是 da-anda/hass-io-addons，本站來源鎖固定在commit（精確來源存檔） 60d4a702e2011e75c90a0f1012dfbd916eb24ce0，來源版本邊界是 Add-on 0.6.1。還必須取得核准的 artifact/image digest 與 source-to-build attestation，證明待安裝 image 由該固定來源建置。商店顯示 0.6.1 不能完成這項證明。本站目前沒有核准 digest，所以這一列應記「未知」，安裝仍被封鎖。
  5. 確認介面類別。只由負責人選定「USB 類、序列類、網路類或尚未決定」等分類。本章不選driver（入口轉接說明），不填裝置、端點或 KNX 位址。
  6. 確認隔離規劃。只記是否已有非正式使用中的測試 Home Assistant、無 KNX／USB／裝置映射、實體 bus 斷開、網路暴露受限、備份／回復負責角色與在場管理者的核准安排。任一項未知，就在加入 repository 與安裝前停止；不得為填表而掃描網路、測試端點或記錄 IP。
  7. 寫下停止條件。至少包括版本不符、備份不清楚、出現識別值、介面意外連接、非預期程序行為，以及任何實體設備反應。
  8. 寫下還原決策。分清「停止 Add-on」與「還原 Home Assistant 備份」。指定由誰判斷、依哪個變更範圍處理；不要先假設停止等於還原。

完成檢查

八列都為「符合」才進入第 4 章的條件式操作區。任一列為「未知」或「不符合」，結果就是先停止，不用加入 repository 或嘗試安裝來找答案。由於本站目前沒有核准 artifact/image digest，現階段「來源與版本」必須保持未知；你可以閱讀第 4 章，但不能執行生命週期動作。

  • 安裝類型與管理權限已有明確分類，但沒有記錄主機或帳號資料。
  • 我已核對備份的時間與涵蓋範圍，並知道停止不等於還原。
  • 我已把 Add-on 0.6.1 的來源版本邊界、artifact/image digest 與 source-to-build attestation 分開；沒有核准 digest 時保持「未知」。
  • 我只記介面和網路方案分類，沒有抄錄任何真實值。
  • 我已寫下停止條件、操作人與還原決策人。

下一步：全部符合時，前往第 4 章。若有缺項，先看開始前是否準備好與停止及還原。

預檢卡住時怎麼辦

  • 不知道安裝類型：請 Home Assistant 管理者只回覆是否有 Add-on 管理能力；不要索取系統畫面或主機資料。
  • 找不到備份：停止後續動作。先依目前 Home Assistant 版本的官方介面建立並核對備份；本章不猜按鈕位置。
  • 來源或版本不同：保留「不符」分類並停止。不要把 0.6.1 的設定宣告套到其他版本。
  • 有人要求提供連線資料：拒絕抄錄，改用「網路類，待核准」等分類；若仍必須提供實值才能繼續，就結束本章。
  • 停止方法說不清楚：先閱讀停止與還原條目，由管理者確認責任後再重新預檢。

進階補充與常見問題

進階補充：固定 config.yaml 能支持哪些判斷

第 3 章保留的來源是 KNXD Add-on 0.6.1 固定 commit 內的 knxd/config.yaml。它支持宣告版本、九項選項、介面列舉與欄位形狀。它不支持目前 Home Assistant 畫面位置，也不能證明某個本機介面、網路端點或 KNX bus 狀態。

因此白話檢查表會分開核對來源版本、待安裝 artifact 與分類。固定 config.yaml 不能證明商店 image 的建置來源；詳細選項、INI 與 driver 留到後續章節，不在預檢時填入。

為什麼連備份名稱也不抄？

備份名稱可能含主機或家庭線索。只記「時間與涵蓋範圍已核對」就足以完成本章。

知道 IP 才能做網路規劃嗎？

本章不需要。你只確認是否已有經核准的隔離規劃；實值不進入教學紀錄。

預設介面是否可以直接採用？

不可以從來源預設推論現場適用。介面類別要由負責人依硬體與安全規劃另行確認。

全部符合是否代表 KNX 已經準備完成？

不代表。它只表示可以進入不連接 bus 的 Add-on 生命週期練習，沒有證明 ETS、整合、群組操作或實體設備狀態。

證據與來源

證據類別：source-bounded

功能對照：addon-options-schema

固定來源只支持文件所述範圍；本頁不代表任何本機、硬體、網路或 KNX 匯流排驗證結果。