確認 KNXD Add-on 生命週期安全閘門

本章任務卡

這一章把 KNXD Add-on 的生命週期想成「進駐、值班、換班、下班」。但櫃檯不能先搬進正式大樓：完整隔離、書面核准與 immutable build 證明都要在加入 repository 或安裝前完成。本站目前沒有核准的 artifact/image digest，所以你只能閱讀條件式介面導覽，不能實際安裝或啟停。

目的

分清 installed、running、stopped 與匿名日誌證據，並知道生命週期操作何時仍被封鎖。

準備

第 3 章八項預檢全部符合；六項隔離條件、核准紀錄與 artifact provenance 已由管理者證明。

時間

約 20 分鐘。

系統變更

本站目前缺少核准 artifact digest，因此不加入 repository、不安裝、不啟停；日後仍須先通過完整 isolated-test 閘門。

預期結果

能分辨來源、artifact 與程序證據，並在證明不完整時停在第一個變更前。

停止條件

• 不得傳送 telegram、執行群組讀寫或實體控制。
• 無法說明變更影響或還原方法。

先確認本章不會碰什麼

本章的證據只限程序／狀態／日誌。日後最多只能觀察「Add-on 已安裝」「程序顯示 running」「程序已停止」或「日誌出現某類匿名訊息」。Add-on running 不等於 KNX bus 已接通，也不能提升成 ETS、Home Assistant KNX 整合、群組操作或設備控制成果。

不要連接 KNX 介面或 bus，不得傳送像道路短訊息的 KNX telegram；禁止群組讀寫與ETS programming／download，也禁止實體控制。不得抄錄、收集、分享或發布真實主機、IP、位址、USB 序號、憑證、token 或裝置路徑。

加入 repository、安裝、啟動、重新啟動、停止、移除與還原都屬環境變更。完整 isolated-test gate、書面核准與 immutable artifact provenance 必須先完成。所有動作只由在場管理者逐步手動確認，不使用 shell、API、腳本或自動化。

用櫃檯值班理解狀態

所有動作前的完整閘門

介面導覽提示：Home Assistant 的 Add-on 商店、repository 管理及備份介面會隨版本改變。請依Home Assistant 官方 Add-on 文件辨認目前版本的地標與流程。名稱或位置不同時，先回官方文件核對；不要猜按鈕。

在加入 repository 或安裝前，由在場管理者逐項證明下列六項；不是正式使用中的 Home Assistant 才有資格繼續：

• 這是非正式使用中的測試 Home Assistant，不是家中、辦公室或客戶現場正在提供服務的系統。
• 系統沒有映射 KNX、USB 或其他裝置路徑。
• 實體介面與 bus 都保持斷開，也沒有可讓測試程序碰到現場設備的替代連線。
• 可能開啟的服務只在管理者核准的 bounded network 測試範圍，不會意外被一般區域網路或公開網路連到。
• 已核對安裝前 Home Assistant 備份、最小回復方法，以及負責停止、移除或還原的角色。
• 具 Add-on 管理權限的管理者全程在場，能在異常時立即停止。

任一項無法證明，就在加入 repository 與安裝前停止。正式使用中的 Home Assistant 不得安裝未通過上述閘門的 Add-on。

書面核准紀錄

操作前要建立 privacy-safe change record。公開或教學紀錄只放不含環境線索的 ID；私人核准者證明、精確操作範圍與六項隔離證據留在有存取控制的紀錄中。下列欄位缺一，就不繼續。

變更／核准紀錄 ID

使用組織核發、無姓名、主機、地址或時間線索的 privacy-safe ID；本站不提供可誤用成真實紀錄的範例值。

受控紀錄參照

只記可由授權人員查回的受控參照；它必須綁定私人核准者證明、精確操作範圍與六項隔離證據，但公開頁面不放姓名、系統路徑或連結。

核准者角色

只記角色，不記姓名，例如「Home Assistant 管理者」；私人核准者證明保留在受控紀錄。

核准動作與範圍

逐項列出此次是否包含加入 repository、安裝、啟動一次、重新啟動一次、停止、移除或備份還原；精確操作範圍不含 KNX 介面、bus、telegram、ETS 或實體設備。

隔離證據參照

綁定上方六項隔離證據的受控紀錄，只公開符合／不符合／未知分類，不公開環境值。

核准日期與時間

時間保留在受控紀錄；公開教材只顯示「已記錄」狀態，避免串聯現場活動。

停止條件

綁定本次適用的停止條件；隔離失效、狀態不明、證明不符或非預期行為都要立即停止。

隱私界線

不記主機名稱、主機 ID、IP、KNX 位址、USB 序號、裝置路徑、帳號、密碼、token、憑證或其他秘密。

Immutable build／artifact provenance 閘門

來源鎖固定 da-anda/hass-io-addons 的 commit 60d4a702e2011e75c90a0f1012dfbd916eb24ce0，其中宣告 Add-on 0.6.1。這只能證明來源內容。商店顯示的 0.6.1 不能證明待安裝 image 就等於鎖定 commit。

• 受控紀錄中有管理者核准的 artifact/image digest，且演算法與完整 digest 都已核對。
• 有可驗證的 source-to-build attestation，把該 digest 綁到上方固定 commit 與建置流程。
• 操作人能核對 Home Assistant 將取得的 artifact 就是已核准 digest；不能只看名稱或版本文字。

條件式介面導覽

以下只是版本容錯的地標、預期可觀察狀態與停止點。只有日後受控紀錄補齊所有閘門時，管理者才可依當時的 Home Assistant 官方文件人工執行。

1. 加入 repository。核准紀錄與 artifact/image digest 證明都有效時，從 Home Assistant 的設定區找到 Add-on 管理地標，再依官方文件進入 repository 管理。加入後只接受清單顯示核准 repository 身分；若項目不同、來源無法辨認或介面要求猜測，停止。本站目前缺少 digest，所以不要執行。
2. 人工安裝。核准紀錄與 artifact/image digest 證明都有效時，從 Add-on 商店找到已核准來源的 KNXD 詳細頁。安裝完成後，預期頁面能分辨「已安裝」狀態與生命週期控制區；不要用商店版本推論 commit。若自動啟動或要求真實 KNX 值，立即停止。本站目前缺少 digest，所以不要執行。
3. 人工啟動。核准紀錄與 artifact/image digest 證明都仍有效時，由在場管理者使用詳細頁的啟動控制一次。預期只觀察到 Add-on 程序狀態由停止類狀態轉為 running 類狀態；文字依版本而異。這不證明 bus。本站目前缺少 digest，所以不要執行。
4. 人工重新啟動一次。核准紀錄與 artifact/image digest 證明都仍有效，且前一步狀態可解釋時，才使用詳細頁的重新啟動生命週期控制一次。預期只看到短暫轉換後回到 running 類狀態；反覆重試或狀態不明就停止。本站目前缺少 digest，所以不要執行。
5. 人工停止。受控核准範圍包含停止且前述證明仍有效時，使用詳細頁的停止控制。預期狀態不再是 running，而是 stopped 類狀態。畫面未改變時不反覆操作，保持隔離並前往停止與還原。本站目前沒有操作可停止。
6. 人工移除。只有受控核准範圍包含移除，且 Add-on 已停止時，才從詳細頁辨認移除／解除安裝的生命週期動作。預期已安裝狀態與該實例的生命週期控制消失，或頁面回到可安裝狀態；這不代表 Home Assistant 整體已還原。本站目前沒有安裝可移除。
7. 人工還原。只有備份涵蓋範圍與受控核准完全相符，才由管理者從 Home Assistant 備份管理地標選取事前核對的回復點，先檢視影響範圍再確認。預期只回到該備份涵蓋的狀態；還原後要重新核對 Add-on 與其他受影響項目。本站目前沒有生命週期變更需要還原。

完成檢查與證據判讀

目前正確完成結果是「因缺少核准 artifact provenance，在第一個變更前停止」。日後若證明補齊，日誌也只在 Home Assistant 畫面內短暫查看。依安全日誌條目完成去識別，只記時間範圍、元件與錯誤類別；移除主機、IP、位址、帳號、token、session、憑證、裝置名稱、路徑與序號，不發布完整日誌。

• 我知道固定 commit 只證明來源，商店版本不能代替 artifact/image digest 與 source-to-build attestation。
• 我已在加入 repository 與安裝前檢查六項隔離條件及完整核准紀錄；目前缺少 digest，所以沒有執行變更。
• 我能說明 installed、running、stopped、removed 與 restored 各自可觀察的範圍，不跨層推論。
• 我不連接介面或 bus；不傳送 telegram；不執行群組操作；不執行 ETS programming／download；也不執行實體控制。

下一步：保持所有 KNX 介面、裝置映射與 bus 斷開。需要判讀程序狀態時看Add-on 狀態；缺少 artifact provenance 時只保留「blocked」紀錄。

停止、移除與還原決策

1. 先縮小變更範圍。若日後問題只涉及這個 Add-on，先停止 Add-on，再移除 Add-on。完成後只確認程序未執行且 Add-on 實例已移除；不要把移除說成整個 Home Assistant 已還原。
2. 只有範圍相符才考慮整體還原。若已發生 Add-on 以外的變更，而且事前核准的備份確實涵蓋該範圍，管理者先核對備份時間、內容與其他可能被覆蓋的變更，再人工確認使用 Home Assistant 官方備份還原流程。介面與用詞依版本而定，本章不虛構按鈕。
3. 還原後再驗證。由管理者確認 Home Assistant 回到預期範圍、KNXD Add-on 為預期的停止或已移除狀態，且沒有非預期影響。任一結果不明就保持隔離並停止後續操作。

• 缺少 digest 或 attestation：保持 blocked，不加入其他 repository，也不安裝相似版本。
• 程序狀態不明：只記匿名錯誤類別後停止；不要填 bus 值、換 driver 或接上介面嘗試。
• 日誌含環境資料：停止分享並刪除副本；若秘密已揭露，交由管理者撤銷或輪替。

進階補充與常見問題