對話與金鑰的備份：跟 HA snapshot 一起走

為什麼一個月要做一次 snapshot

你的 HA 主機在做的事情越來越多——照明自動化、門鎖、能源監控，現在還加上 Pi Agent 這個 AI 工作站。這代表它壞掉時你失去的東西比以前多得多：不只是燈不會自己開，還會失去所有 AI 對話紀錄、你辛苦一家家申請貼上去的金鑰、你裝過的每一個 Skill、rclone 上傳 Google Drive 的授權。這些東西加起來是好幾週的心血。

• SD 卡壞掉：Raspberry Pi 上跑 HA 的人多半遇過。突然開不了機，卡插到讀卡機也讀不出來。
• 升級失敗：某次 HA 大改版或 Pi Agent add-on 更新後開不起來，想 rollback 卻沒退路（第 21 章會講升級踩雷）。
• 手滑刪東西：在 File editor 或 SSH 裡打錯指令，把設定砍掉。
• 搬家到新主機：從 Pi 4 換到 Pi 5、從 Pi 換到 NUC、從家裡搬到公司。

HA 內建的 Backup（備份）就是為這些場景設計的。你按一下就把整台 HA 的狀態（設定、資料庫、每個 add-on 的 /data/ 目錄）打包成一個 .tar 檔，可以下載、可以自動傳雲端、可以還原到另一台 HA。

Pi Agent 貼在 HA 裡當 add-on 就是為了搭上這班順風車。你不用另外設一套備份機制、不用學新的雲端服務、不用另裝 cron。只要你有做 HA snapshot 的習慣，Pi Agent 的資料就自動有備份。這章就是把「哪些會走、哪些不會走、怎麼驗證」講清楚。

Pi Agent 的 /data/pi-agent/ 目錄地圖

你不需要真的 SSH 進去看這個資料夾，但要知道它長什麼樣，備份的討論才有座標。整棵樹如下，右邊那欄「snapshot 收不收」是這章的重點：

簡單記憶法：「你的成果會走，工具鏈跟半成品不會走」。對話、金鑰、Skill、rclone 授權、成品 mp4 都是你的成果；venv、Chromium、影片中繼檔是可以重下重跑的工具與素材。

為什麼故意排除那 4 個資料夾

看到 venv/、playwright-cache/、clips/、segments/ 沒被備份，你可能第一反應是「不是全備才安全嗎，為什麼要排除？」原因有三個，值得記住：

1. 會讓 snapshot 檔膨脹到嚇死人

   venv/ 加上 playwright-cache/ 兩個資料夾合起來大概 720 MB——這就是第 2 章你首次安裝時等 3-8 分鐘、第 18 章會展開的那一坨。如果它們也進 snapshot，你每一份備份都會多背將近 1 GB。做十次備份就 10 GB，上傳 Nabu Casa 或 Google Drive 都痛苦，硬碟很快滿。

2. 影片管線的 clips / segments 是可重跑的中繼檔

   projects/<某支影片>/clips/ 裡是 Playwright 錄下來的每一段畫面，segments/ 是 ffmpeg 剪出來的過渡片段。這些都是可以照著腳本再產一次的東西——只要 projects/<某支影片>/ 底下的腳本、旁白稿、成品 final.mp4 有備份，你就有能力重新生一次中間檔。備份中繼檔沒有意義，只會讓 snapshot 肥大。

3. 還原後 video-tools-init 會自動幫你重下

   Pi Agent 開機時 pi-web-start.sh 會 fork 一個背景腳本 video-tools-init.sh（第 18 章展開講過）。它的判斷是「sentinel 檔在 且 venv/bin/python3 存在」，任一缺就重下。snapshot 不收 venv/ 跟 playwright-cache/——那 python3 就不在，即使 sentinel 被 restore 進來也會觸發重下。restore 完 Pi Agent 一開機，前面 3-8 分鐘會偷偷把它們重新裝一次。你只要耐心等，什麼都不用做。

所以整個設計哲學是：snapshot 只包「無法從別處重建的東西」。對話、金鑰、Skill、rclone token、成品 mp4——這些丟了就真的丟了；venv、Chromium、影片中間檔——這些永遠可以重下重跑。備份策略設計成這樣，你才能在合理檔案大小內存到很多份歷史快照。

動手：做一次完整備份

步驟很簡單，第一次做的話跟著點就好。之後你會把它變成每個月一次的家常動作。

1. 打開 HA 的備份頁

   在 Home Assistant 側邊欄按 設定 → 系統 → 備份（Settings → System → Backups）。第一次打開會看到一個空清單，或前一次 HA 自動排程做的 backup。舊版本（2023 以前）的路徑是 設定 → 系統 → Server Controls，那條路徑在新版已經沒了，就是這裡。

2. 按右下角「立即備份」，選「手動備份」

   2024 之後的 HA UI 是右下角 Backup now（立即備份）→ Manual backup（手動備份）——舊教學裡的「建立備份 / 完整備份」按鈕已經改名。點下去會跳出一個「選要備份什麼」的畫面：預設所有東西都勾（Home Assistant 設定、每個已安裝 add-on、共享資料夾、媒體）。第一次建議保持全勾——它會把 HA 核心設定＋每個 add-on（含 Pi Agent 的 /data/pi-agent/）一起包。想省空間可以取消 media 跟 share 這兩個大戶，其他別動。

3. 幫這次備份取個能一眼看懂的名字

   預設名字通常是「Core <版本>」加時間戳，字很長但沒鑑別度。改一個像 2026-08-14-full、升級前備份、裝完 GLM 金鑰 這種你未來會看得懂的名字。取個好名字之後找備份會快很多。

4. 加密與 Backup Emergency Kit

   2025 版 HA 預設會自動幫你產一把加密金鑰並要求你下載 Backup Emergency Kit（一個 .txt 檔，裡面就是那把金鑰）。這個檔案務必存到密碼管理器或印出來收好——金鑰掉了，那份 backup 就真的還原不回來，沒有任何官方後門。要不要另外自訂密碼隨意，重點是那把 emergency kit 一定要留一份跟 HA 本體分開的地方（別跟 backup 檔一起放同一朵雲）。

5. 選存放位置、按下去等幾分鐘

   下一步選 backup 要存哪：本機、Nabu Casa、掛好的 Network Storage、或第三方 add-on（例如 Google Drive Backup、Samba Backup）提供的位置。可以多勾幾個做多重備援。備份時間跟資料量與 add-on 數量有關，家用規模大概 1-10 分鐘。做完那份 backup 會出現在清單裡，可以按三個點選下載 .tar存到本機。

重要：測試還原一次才算數

備份做完不代表你有備份。真正的驗證是「拿它去 restore 看能不能起來」——沒測過的備份等於沒有備份，這是老話但沒錯。做法：

1. 準備一台「不是你原本 HA」的 HA

   可以是家裡另一台舊 Pi、公司閒置的 NUC、桌機上跑一個 Home Assistant OS 的 VirtualBox 虛擬機，或雲端一個小 VPS 裝 HA supervised。不要直接在原機還原——原機還原會把你現有資料蓋掉，還原失敗就雙輸。

2. 裝好 HA、上傳 backup、按還原

   在測試機的設定 → 系統 → 備份頁按右上三個點的「上傳備份」把你剛剛下載的 .tar 傳上去，然後點該備份卡片、按「還原備份」。加密備份會要求你貼上 Backup Emergency Kit 裡的那把金鑰（或你當時自訂的密碼），沒那把就 restore 不動。HA 會提示要重開機，讓它自己重來。

3. 等 Pi Agent 自動起來、video-tools 重下

   還原後 Pi Agent 會出現在側邊欄。前面 3-8 分鐘它在背景重下 720 MB 的 venv 與 Chromium（第 18 章講過的 video-tools-init）。這時候你點進去 pi-web 可以用，但影片管線還沒好，不用急。

4. 打開 pi-web，逐項檢查

   這是驗證的關鍵——要真的看到才算數：

   • 左邊 Session 列表：你之前的對話應該全部都在
   • Models 面板：所有 provider 都在，按 Test 應該綠燈
   • Skills 面板：你裝過的 Skill 都在清單裡
   • 試著開一個新對話，隨便問一個問題，AI 有回應
   都通過才代表這份 snapshot 真的救得回你。有一項掛掉就要回頭查（見 troubleshoot）。

不建議：手動 rsync /data/pi-agent/ 到別台

你可能會想：「反正我知道 /data/pi-agent/ 就是全部東西了，那我直接 SSH 進 HA、rsync 這個資料夾到別台不就好？何必用 HA 內建 backup？」技術上可以，實務上有三個坑：

• 版本不對就會出事：models.json、sessions/*.jsonl 的欄位格式有可能在 Pi Agent 版本升級時微調。你把舊版格式的檔案塞進新版 add-on 可能會讓 pi-web 讀取失敗；反過來也可能。HA 官方 backup 會把 add-on 版本一起記錄，還原時是「同版對同版」，這個對齊你自己 rsync 沒辦法保證。
• 會漏掉 add-on 中繼狀態：add-on 除了 /data/ 還有它的 options.json（設定分頁的內容）、config 分頁的環境變數、log_level 之類。HA backup 一起包，rsync 你要自己想辦法收齊，很容易漏。
• 還原時 Pi Agent 不會知道要重下 video-tools：sentinel 檔案 /data/pi-agent/.video-tools-installed 你也一起 rsync 過去了，video-tools-init.sh 一開機看到這個檔（且 venv/bin/python3 存在檢查）就跳過重下——但如果你只搬 sentinel 沒搬 venv，或 venv 被排除，pi-web 開得起來但影片管線一用就崩。這時要進 Configuration 開 reset_video_tools 才能重來（見 第 18 章）。

結論：正解永遠是 HA snapshot。它就是為這種場景設計的，你別自作聰明繞過去。

進階：金鑰是否要另外存進密碼管理器

Pi Agent 的金鑰放在 /data/pi-agent/models.json，HA snapshot 一定會帶走。理論上你有 snapshot 就等於有金鑰備份。但實務上還是建議你把 每支 API 金鑰另外貼一份到密碼管理器（1Password、Bitwarden、iCloud Keychain 都行），理由兩個：

• 多一份保險：萬一你的 HA snapshot 檔沒有做（一個月忘記做那次剛好機器掛）、或雲端上傳失敗自己沒發現、或 backup 本身壞掉解不開——你至少還有密碼管理器裡的一份。金鑰跟 snapshot 綁在一起有風險共存的問題。
• snapshot 檔外流時金鑰不會跟著外流：snapshot 是 .tar 檔，沒加密的話用任何 archive 工具就能解開，裡面 data/pi-agent/models.json 是明文 JSON 一看就有金鑰。如果你把 snapshot 隨手放桌面、上傳到不受信任的雲端、或分享給朋友幫忙看問題——金鑰就外流了。密碼管理器裡的那份不會被連動，你至少可以主動去 provider 後台把外流的舊 key 廢掉，換一個新的貼回 Pi Agent 就好，不會整個帳號被 hack。

操作也不麻煩：申請每支金鑰的時候（第 5 章那類流程），拿到 key 的當下順手貼一份到密碼管理器一筆「新項目」，欄位寫 Pi Agent GLM key / 申請日期 / 對應 provider 網址。以後每次去 Models 面板貼進 Pi Agent 也貼進密碼管理器，兩處保持一致。

升級 Pi Agent 前強烈建議先備

每次 Pi Agent add-on 有更新提示，動手升級之前強烈建議做一次 snapshot。這不是慣例級的建議，是硬性建議，尤其對於重大版本（例如 v0.13.0 這種有 breaking change 的）。

原因：Pi Agent 的 add-on 頁面沒有「downgrade」按鈕。HA 的 add-on 商店只提供最新版下載，你升上去發現行為變了、不喜歡、想退回去——沒得退，除非你有 snapshot 可以還原到升級前的狀態。

已知的高風險升級點（未來會擴充，請以第 21 章當時的紀錄為準）：

SOP 建議：設定 → 系統 → 備份 → 建立備份（完整）→ 命名「升級前 <日期>」→ 等 backup 完成 → 回 add-on 頁面按更新。多花 5 分鐘，換一條退路。

搬家到新 HA 主機的完整流程

你把 HA 主機換掉（從 Pi 換到 NUC、從舊 Pi 升到 Pi 5、家裡搬到公司）也一樣用 snapshot 走。整個流程幾乎跟「測試還原」一樣，但這次是玩真的：

1. 舊機做一次乾淨的 snapshot

   臨走前的最後一次備份要特別小心。做完之後不要再對舊機做任何操作——不要開新對話、不要換設定，因為那些改動不會在你剛做的 snapshot 裡。要嘛開加密、要嘛下載到 USB 隨身碟、要嘛上傳到 Nabu Casa。三管齊下最保險。

2. 新機裝好 HA（不安裝任何 add-on）

   先把 Home Assistant OS 或 supervised 裝到新硬體上、能開機、能連到你的 Wi-Fi 就可以了。此時不要急著裝 Pi Agent——因為等一下 restore 會把 Pi Agent 連同資料一起裝回來，你先手動裝反而多此一舉。

3. 在新機 restore 舊 snapshot

   設定 → 系統 → 備份 → 上傳備份 → 選還原。加密就填密碼。HA 會提示要重開機，restore 完 Pi Agent 會自己出現在側邊欄。

4. 等 3-8 分鐘讓 video-tools 重下

   新機的 venv/ 跟 playwright-cache/ 是空的（snapshot 沒帶）。s6-overlay 開機時會自動去下，這段時間 pi-web 可以打開、可以聊天、可以看歷史 session，但影片管線還不能用。等日誌顯示 video-tools-init done 就好了。

5. 打開 pi-web 測一次對話確認 provider 還通

   開一個新 session，切到你常用的 provider（例如 GLM），隨便問一個問題。有回應就代表金鑰、網路、everything 都對得起來。如果 provider 那邊回 401 / 403，可能是網路 IP 變了觸發風控，或那家 provider 有 IP 白名單設定要更新——這種是 provider 帳號問題不是 Pi Agent 問題。

常見卡關

1. snapshot 檔動輒 1 GB 以上，正常嗎

   正常。完整備份含所有 add-on 的 /data/——除了 Pi Agent 之外你可能還有 InfluxDB、Node-RED、MQTT broker、File editor 各自的資料。如果你只在乎 Pi Agent 那份：選「部分備份」，只勾 Home Assistant Core 跟 pi_agent 這個 add-on 的資料。這樣 snapshot 大概會小到幾百 MB 甚至幾十 MB，看你對話歷史多寡。但注意：部分備份不含其他 add-on，還原時只還原你勾的那些。

2. 還原之後 Pi Agent 空空的，對話跟金鑰都不見

   八成是做 backup 時漏勾了這個 add-on。做完的 backup 可以在清單卡片點進去看「包含哪些內容」——如果 Woow HA Pi Agent 沒出現在 Add-ons 區塊，這份 backup 本來就沒帶它的資料。回頭重做一次：Backup now → Manual backup 的資料選擇畫面裡，Add-ons 分區找到 Woow HA Pi Agent，確認它有勾。現代 HA 一個 add-on 的資料是隨 add-on 條目一起打包（沒有分開的「add-on 本體 / add-on 資料」兩個 checkbox），所以只要勾了就會帶 /data/pi-agent/。（如果你看到的介面還有分開的兩個勾選項，代表你 HA 版本很舊，強烈建議升級——升級前記得先做一次完整備份，見第 21 章。）

3. 金鑰還原完好像還在，但按 Test 綠燈變紅

   先分兩種可能：（a）金鑰本身還有效——很可能對應的 API 服務改了 endpoint（例如 GLM 改網址、Anthropic 改路徑），這時候要去 Models 面板編輯那個 provider，把 baseUrl 更新到最新，再按 Test。第11 章的六家 provider 對照有講各家 baseUrl 現況。（b）金鑰過期或被廢——時間隔太久那家 provider 主動撤銷了那把 key，或你自己在後台重生過。這時候要重申請一支 key 貼回來，snapshot 救不了這個。

4. 影片管線壞、按產影片沒反應

   還原後 3-8 分鐘內 video-tools-init 還沒跑完，這時候試影片管線一定失敗。做法：（a）等——去 HA 的 add-on 記錄檔看有沒有 video-tools-init done，出現才算好；（b）如果十幾分鐘還沒好，或看到錯誤日誌，去 add-on 設定分頁把 reset_video_tools 開起來、重啟 add-on、等它重下一次（第 18 章詳講）。

5. 還原後 Skills 面板是空的但 /data/pi-agent/skills/ 有檔

   這是「檔案還原了但 pi-web 沒重掃」的少見狀況。做法：按新對話（不是重整頁面），pi-web 開新 session 時會強制掃一次 skills 目錄，Skill 就會出現。如果還是不行，重啟 Pi Agent add-on（HA 的 add-on 頁面按重啟）。

6. rclone 上傳 Google Drive 還原後不動

   rclone.conf 的 OAuth token 有時效（refresh_token 通常長效但長期閒置或帳號側撤銷都會失效），還原一份很舊的 snapshot 常會遇到。第 19 章教過的作法：SSH 進 add-on 容器跑 rclone config reconnect gdrive:（記得帶你當初設的 remote 名稱＋冒號，通常就是 gdrive:），會跳同一個 OAuth 授權流程 refresh token，不用整個 rclone config 重來。詳細錯誤訊息（oauth2: token expired）對照見第 19 章末段。

7. Backup Emergency Kit 檔案掉了、還原時要密碼

   2025 版 HA 的自動排程備份會用系統自動產的加密金鑰，就記在那個 .txt 檔（Backup Emergency Kit）裡。掉了：先去設定 → 系統 → 備份 → 右上三個點 → 顯示加密金鑰，能再顯示一次讓你複製起來——只要你還能登入原本的 HA，就有救。如果原機也掛了、Kit 也沒存，那份 backup 就真的解不開，沒有官方後門。教訓：Kit 一存到就馬上抄一份到密碼管理器，這是新版 HA 最容易踩的坑。其他 restore 卡關的通用排錯思路對照第 22 章。

常見問題