一張壞掉的 SD 卡，代價比以前更高了

你的 Home Assistant 主機已經在管燈光、門鎖跟能源儀表板。以前弄丟它，頂多是花一個晚上重新配對裝置。Pi Agent 加上了一層重建起來難得多的東西：你每一次的對話、你設定過的每一把供應商金鑰、你裝過或寫過的每一個 Skill，還有上傳到 Google Drive 的 rclone 授權。加起來可能是好幾週的心血。

有四種狀況常見到值得先做好準備：

• 儲存裝置故障。 SD 卡或硬碟可能毫無預警地變得讀不出來。
• 升級失敗。 一次 Home Assistant 版本更新或 add-on 更新，可能讓服務起不來，沒有最近的備份，要 rollback 會很困難。
• 手滑誤刪。 在 File editor 或 SSH 裡打錯一個指令，就把你需要的設定砍掉了。
• 換主機搬家。 從 Pi 4 換到 Pi 5、從 Pi 換到 NUC，或搬到另一棟建築物，這種操作之所以行得通，就是因為有備份存在。

Home Assistant Backup 會把你選的系統設定、資料庫、共用資料，加上每個你選的 add-on 的 /data/ 目錄，打包成一個 .tar 存檔。Pi Agent 就是為了搭上這班順風車才以 add-on 的形式運作，這樣它的資料才能跟著同一個存檔走。不需要另外設第二套備份系統，也不需要再多寫一個排程工作。

成果會進存檔；工具鏈不會

你完全不用透過 SSH 打開這個資料夾，但看過它的結構，這條界線就一目瞭然了。

這四項排除是刻意的，理由是大小。 venv/ 跟 playwright-cache/ 加起來大約用掉 720 MB。把它們包進去，每份存檔都會多將近 1 GB，保留十份備份就多花大約 10 GB，去存那些會自己重新下載的檔案。clips 跟 segments 可以從你留下來的腳本跟旁白重新生成。

有一個後果會讓人意外。那個空的標記檔 .video-tools-installed 是 會進存檔——但光還原它，並不會跳過那次下載，因為啟動檢查同時也要找那個 Python 執行檔。

flowchart TD
  A["還原之後 add-on 啟動"] --> B{"Is .video-tools-installed there?"}
  B -->|"是，它是從存檔裡帶回來的"| C{"Is venv/bin/python3 there?"}
  B -->|"任何"| D["重新下載，3-8 分鐘"]
  C -->|"否，venv 被排除在外了"| D
  C -->|"是"| E["跳過，立刻就緒"]
  D --> F["Log 顯示 video-tools-init done"]

五個步驟，大約五分鐘

1. 步驟 1

   打開備份頁面

   前往 Settings → System → Backups。第一次可能是空的，也可能已經顯示某個既有排程做出來的東西。2023 年之前的版本，這個功能放在 Settings → System → Server Controls；那條路徑現在已經不存在了。

2. 步驟 2

   點 Backup now，再點 Manual backup

   在資料選擇畫面，第一次全部保持勾選：設定、每個 add-on、共享資料夾跟媒體。這樣才能把 Woow HA Pi Agent 跟它的 /data/pi-agent/ 包進存檔裡。之後你可以拿掉大型媒體來縮小檔案——但要讓 Pi Agent 保持勾選。

3. 步驟 3

   取一個你認得出來的名字

   把預設那個版本加時間戳記的通用名稱，換成有意義的： 2026-08-14-full、 before-pi-agent-upgrade、 provider-keys-configured。半年後，這是唯一能告訴你該挑哪一份存檔的東西。

4. 步驟 4

   下載 Backup Emergency Kit

   2025 年後的 Home Assistant 版本會自動產生一把加密金鑰，並提供給你 Backup Emergency Kit，一個裝著那把金鑰的 .txt 檔。把它放進密碼管理器，或印出來。讓它遠離主機跟存檔本身——不要放在跟它能解鎖的檔案同一個雲端資料夾裡。

5. 步驟 5

   選擇目的地，再把一份副本帶離這台裝置

   本地儲存、Nabu Casa、掛載的網路儲存空間，或像 Google Drive Backup 或 Samba Backup。家用備份通常花 1-10 分鐘。出現在清單裡之後，用它的選單下載那個 .tar ，把這份副本存到別的地方。

沒測試過的備份只是個猜測

在一台 不是 你正式主機的機器上測試：另一台 Pi、一台閒置的 NUC、一台 Home Assistant OS 虛擬機，或一台跑 Home Assistant Supervised 的小型 VPS。還原會覆蓋現有資料，所以在正式機上測試失敗，可能會讓你兩份都沒了。

在那台機器上裝好 Home Assistant，打開 Settings → System → Backups，上傳 .tar 從右上角選單，打開它的卡片，選 Restore backup。被問到的時候輸入 Emergency Kit 裡的金鑰；沒有那把密鑰，還原沒辦法繼續。讓它重啟，接著給 video-tools-init 3-8 分鐘的時間。

現在打開 pi-web，檢查四件事。少檢查一項都不算真正測試過：

• Session 清單 ——之前每一次對話都在。
• Models 面板 ——每個供應商都在，而 Test 在每一個上都測試成功。
• Skills 面板 ——每個已安裝的 Skill 都出現。
• 一次新對話 ——選定的供應商能回答一個簡單的問題。

如果十分鐘後影片管線還是沒反應，或 log 顯示的是錯誤而不是 video-tools-init done，就強制乾淨重建：打開 reset_video_tools 在這個 add-on 的 Configuration 分頁上，同一個頁面也放著 log_level 跟 timezone，接著存檔重啟這個 add-on。這個開關不是新的；0.13.0 只是後來加上了自動清理，讓 add-on 事後自己把選項改回 false 。比較舊的版本會讓它一直開著，得自己手動關掉。

Configuration 分頁填了四把供應商金鑰，留了三個空白——每一個都是備份必須帶走的 add-on 狀態。

• Configuration 是最上方四個分頁之一——Info、Documentation、Configuration、Log。這個 add-on 讓你設定的每一項，都藏在它後面。
• Options 面板是一份簡單的欄位清單，在畫面下方 groq_api_key 這裡被截斷了。這裡的東西不會有人幫你重建。
• 眼睛圖示 在每個已填欄位旁邊，能用明文顯示那把金鑰。這個畫面一鍵就能揭露的東西，一份沒加密的存檔，會揭露給任何拿到它的人。

存檔裡的憑證是明文儲存的

Pi Agent 把供應商金鑰以明文存在 models.json，而 rclone 把它的 Google Drive refresh token 存在 rclone.conf。這個 add-on 備份時兩者都會被包進去。這在還原那天很方便，其他每一天都很危險。

所以每一把金鑰都在密碼管理器裡留一份副本——1Password、Bitwarden、iCloud 鑰匙圈——理由有兩個：

建立每把金鑰時就幫它標籤：用途、日期、供應商網站。每次在 Models 面板換金鑰時就更新它。離開這台裝置的每份存檔都要加密，絕對不要把備份附在支援請求裡。

有兩種時刻，備份就不再是可有可無的了

每次 add-on 更新之前

Pi Agent 的 add-on 頁面沒有 Downgrade 按鈕，add-on 商店通常也只提供目前的版本。如果一次更新改變了行為、或直接起不來，升級前的那份備份就是實際上唯一的回頭路。

更新之前先記下這件事你現在跑的版本號，就是你以後會後悔沒寫下來的那個數字。

• Current version ——這裡是 0.12.0。把它寫進備份名稱裡，讓這份存檔自己說清楚它能還原到哪個版本。
• Autoupdate 應該保持關閉。一次自動到來的更新，背後不會有一份剛做好的備份撐著。
• 有一個 沒有 Downgrade 按鈕 在這個頁面上。這個缺失，就是備份存在的全部理由。

整套流程就一行： Settings → System → Backups → Backup now → Manual backup，取名叫「Before upgrade <日期>」，等它跑完，再回到 add-on 頁面點 Update。

搬到新主機

機制一樣，但風險更高，因為新機器會變成正式環境。在舊主機上做最後一次乾淨的備份，接著 停止使用它 ——在那之後開始的對話不會在存檔裡。在新硬體上安裝 Home Assistant，但先不要裝 任何 add-on；還原時會把 Pi Agent 跟它的資料一起帶回來。輸入金鑰，再給影片工具 3-8 分鐘的時間。這段期間聊天功能跟 Session 紀錄照樣能用。

接下來往哪走