WoowTech KNXD
幫助、停止與安全還原
先依症狀找到固定條目。這些條目只協助判讀、去識別與停止，不代表 KNX bus 已成功。
白話內容交付狀態：完整 22 章白話教學已交付；這只代表文件內容完成，不證明 KNX bus、ETS、Home Assistant 整合、群組操作、實體控制或本機環境相容性。
開始前是否準備好
用與第 3 章完全相同的八項清單判斷是否能繼續。
- 判斷條件
- 逐項確認：Home Assistant 安裝類型、管理權限、Home Assistant 備份、來源與版本、介面類別、網路規劃、停止條件、還原決策。來源與版本還必須有核准的 artifact/image digest 與 source-to-build attestation。
- 可觀察結果
- Home Assistant 安裝類型、管理權限、Home Assistant 備份、來源與版本、介面類別、網路規劃、停止條件、還原決策八項各有符合、不符合或未知；八項全為符合才算完成。
- 停止動作
- 任一項不符合或未知時，不加入 repository、不安裝也不啟動 Add-on。本站目前沒有核准 artifact digest，所以來源與版本項目仍是未知。
- 還原注意
- 建立備份不等於已驗證可還原；先核對備份時間、內容範圍、回復負責角色與可用性。
怎麼看 Add-on 狀態
分清楚程序正在執行、listener 正在等待與 KNX bus 實際成功。
- 判斷條件
- 只依 Home Assistant 顯示與已去識別的日誌分類程序、listener 與 bus 三個不同層級。
- 可觀察結果
- 能把 running 寫成程序狀態、listener 寫成等待狀態，並把 KNX bus 保持為未證實。
- 停止動作
- 若狀態層級無法分辨，停止進一步設定或連線，不用重啟來猜測。
- 還原注意
- 狀態判讀不需要還原備份；若先前已有未核准變更，另依變更紀錄評估還原。
怎麼安全分享日誌
只保留錯誤類別，移除位址、主機、路徑、序號、權杖與 session。
- 判斷條件
- 分享前已移除主機名稱、IP、位址、token、session、帳號、裝置名稱、路徑與序號。
- 可觀察結果
- 保留下來的內容只描述時間範圍、元件與錯誤類別，無法回推家庭或主機環境。
- 停止動作
- 發現任何識別值就停止分享，刪除公開副本並重新產出去識別版本。
- 還原注意
- 清理日誌不會回復系統狀態；若日誌揭露秘密，還要撤銷或輪替該秘密。
何時停止與如何還原
遇到未知寫入、實體動作或無法解釋的狀態時先停止，再依變更範圍判斷是否需要還原 Home Assistant 備份。
- 判斷條件
- 先判斷問題只需要停止 Add-on，還是需要把 Home Assistant 狀態回復到既有備份。
- 可觀察結果
- 停止 Add-on 只停止其服務，不會還原設定；還原 Home Assistant 備份則依該備份範圍回復狀態。
- 停止動作
- 出現未知寫入、非預期實體動作或無法解釋的狀態時，先停止 Add-on 並保留去識別證據。
- 還原注意
- 不要把停止 Add-on 稱為還原。還原 Home Assistant 備份前，必須核對時間點、涵蓋範圍及對其他變更的影響。
版本是否適用
先核對 Add-on、KNXD 與 Home Assistant 的文件版本界線。
- 判斷條件
- Add-on、KNXD、Home Assistant 與文件版本都能對到本站固定來源或明確標示的證據缺口。
- 可觀察結果
- 版本摘要分開列出各專案，不把版本並列改寫成相容性或現場成果。
- 停止動作
- 版本或來源對不上就停止套用教學步驟，先保留差異並尋找對應文件。
- 還原注意
- 版本不符通常先停止而不是還原；若已造成設定變更，再依備份範圍另行評估。
回報文件問題
提供章節、版本與可重現的離線證據，不附環境秘密。
- 判斷條件
- 已準備章節、版本、預期文字與可重現的離線證據，且所有環境資料已去識別。
- 可觀察結果
- 回報能讓維護者重現文件問題，但不包含操作授權或現場成果宣稱。
- 停止動作
- 資料仍含環境秘密或需要現場操作才能證明時，先停止提交並縮小證據。
- 還原注意
- 文件回報不會變更或還原環境；不要把備份、設定或憑證附在 issue。
前往 GitHub Issues 回報文件問題。連結只開啟問題清單，不會自動建立 issue。