Agent 如何安全管理 Home Assistant 與 RockCoffee 網站

為什麼要記錄這套方法

讓 AI Agent 管理智慧家庭與網站，真正困難的不是「能不能連上」，而是如何在方便、自動化與安全之間取得平衡。

經過不同連線方式、設定來源與部署流程的嘗試後，目前 RockCoffee 採用一個清楚的原則：Agent 在私人 Mac 上工作，Home Assistant 與公開網站彼此隔離，每次操作都必須能驗證、能回復。

整體架構

Rock 提出需求
      │
Mac 上的 AI Agent
      │
先讀 shared-agent 共用事實與授權規則
      │
      ├── Home Assistant：私人 API／SSH／設定驗證
      │
      └── RockCoffee：Astro 建置／備份／SSH 部署

Mac 是整套系統的私人控制面。Codex、OpenClaw 與 Hermes 依任務選擇工具，但都先參考同一份設備別名、操作規則與安全邊界，避免各自使用不同版本的資訊。

Agent 管理 Home Assistant 的方式

Home Assistant 的工作分成三層，不把所有事情都交給同一條連線處理。

1. 狀態查詢

Agent 預設先做只讀檢查，透過 HTTP 可達性、主機與容器狀態、近期紀錄及設定檢查交叉判斷。單一連線失敗或一次負載尖峰，不會直接被當成整套系統故障。

2. 一次性控制

開燈、播放廣播或執行情境等已授權動作，由 Mac 透過 Home Assistant 的驗證 API 呼叫服務。瀏覽器上的公開展示頁不保存憑證，也不直接控制家中設備。

3. 正式設定維護

需要修改自動化或設定時，Agent 透過金鑰驗證的 SSH 連到 Home Assistant 主機，直接以主機端正式設定為準，不使用可能過期的本機副本。

穩定的修改順序是：

備份正式設定。
只做必要的最小修改。
檢查 YAML 或資料格式。
在 Home Assistant 容器內執行正式設定驗證。
通過後才重新載入受影響的功能。
只有確實需要重新啟動 Home Assistant 時，才再次取得 Rock 的同意。

Agent 管理 RockCoffee 網站的方式

網站原始內容保存在 Mac，由 Astro 將 Markdown、JSON、元件與樣式組合成純靜態檔案。

每次更新採用固定部署流程：

在 Mac 修改內容或程式。
執行型別、內容與網站建置檢查。
在網頁主機建立目前版本的壓縮備份。
透過 SSH 金鑰與安全複製，將新版靜態檔案送到獨立的網頁環境。
校正目錄與檔案權限，移除 Mac 產生的額外 metadata。
從外部逐一驗證首頁、主要頁面、圖片與遊戲。
部署中途若失敗，就用剛建立的備份回復舊站。

Home Assistant 與網頁主機雖然運行在同一套 Home Lab 裡，仍是兩個獨立環境。網站只負責公開展示，不能因為網站被瀏覽就取得家庭控制權限。

嘗試後留下的關鍵經驗

不要把公開網頁當成 HA 控制面。 展示與控制分開，能大幅降低憑證外洩與誤操作風險。
不要只相信單一健康訊號。 API、SSH、容器與設定驗證必須交叉確認。
不要用不同步的本機副本修改正式設定。 正式主機上的設定才是權威來源。
不要直接覆蓋網站而沒有備份。 自動備份與失敗回復，讓 Agent 可以安全地持續更新。
部署後一定要校正權限。 檔案存在不代表網頁服務一定讀得到。
Agent 必須先讀共同規則。 連線能力不能取代授權、安全邊界與可回復流程。

為什麼目前這套方式最適合

這個架構沒有追求讓 Agent 擁有最大的權限，而是讓它在正確的地方取得剛好足夠的能力：日常查詢保持只讀、一次性控制需要明確需求、正式修改可以驗證與回復、公開網站則完全不持有家庭控制憑證。

對想讓 AI Agent 管理真實系統的人來說，可靠的關鍵不是更直接的連線，而是把事實來源、授權、操作通道、驗證與回復一起設計好。