Backups

新手入門

留一份你的設定，更新出問題、磁碟壞掉或換新電腦時就能放回去。

開始之前

使用 Settings > Backups（設定 > 備份）需要 Change settings（變更設定）權限。只有擁有者可以還原。
下載、刪除和還原需要你在最近幾分鐘內用密碼登入過。

建立 backup

開啟 Settings > Backups。
選擇 Back up now（立即備份）。你應該會在 Saved backups（已儲存的 backup）下看到新的 backup。
選擇旁邊的 Download（下載），在伺服器之外保留一份。

儲存主金鑰

backup 不會包含主金鑰，而設定裡的密碼和 API 金鑰要靠它才能開啟。沒有對應的金鑰，還原後的 backup 就讀不了這些內容。

在 Master key（主金鑰）下，由擁有者選擇 Download key kit（下載金鑰組）。
把檔案放在伺服器之外，也要和 backup 分開保存。你應該會看到金鑰組的警告從 Settings > Backups 和健康檢查中消失。

之後要使用時，把它改名為 holyarrs.key，放進設定資料夾。不是擁有者？請擁有者下載。

還原 backup

選擇 Restore from a file（從檔案還原），選一個 HolyArrs backup 的 zip。
確認。
HolyArrs 會檢查檔案。你應該會看到 Restore ready. It applies on the next start.（還原已就緒，會在下次啟動時套用。）
HolyArrs 重新啟動，並放入 backup。使用建議的 Docker 重新啟動原則時，這會自動完成。

你目前的資料庫會移到 /config/backups/before-restore-<time>，所以可以復原這次還原。

選項

多久一次

選項	備份時機	保留
Balanced（平衡，預設）	每天	最近 7 天，加上 4 份每週的 backup
Light（輕量）	每週一次	4 週。最省空間
Careful（謹慎）	每天	30 天內的每一份 backup

最新的排程 backup 一定會保留。這些規則只會清理排程 backup。你自己建立的 backup 會一直留著，直到你刪除（按該列的垃圾桶按鈕，無法復原）。HolyArrs 在會變更儲存資料的更新之前也會先做 backup，並保留最新的 3 份，請見更新。

換到新電腦

新安裝第一次啟動時會建立自己的主金鑰。那把金鑰打不開你舊的 backup，所以還原會被拒絕。要先放入舊金鑰。範例把 container 稱為 holyarrs，請換成你自己的名稱。

第一次啟動之前，先建立 container 但不要啟動：docker compose create，或把你的 docker run 指令中的 docker run -d 換成 docker create。
複製舊金鑰進去：docker cp holyarrs.key holyarrs:/config/。改名為 holyarrs.key 的金鑰組也可以。這對 named volume 和主機資料夾都適用；HolyArrs 啟動時會把 /config 裡的檔案交給你的 PUID 和 PGID。如果你使用 HOLYARRS_MASTER_KEY_FILE，就把金鑰放在主機上的那個路徑，並讓你的 PUID 和 PGID 可以讀取。
還原 backup。選一種方式：
- 啟動 HolyArrs，完成首次執行，再到 Settings > Backups 使用 Restore from a file。
- 或在第一次啟動之前還原。把 zip 檔名保持不變，放進名為 backups 的資料夾，再用 docker cp backups holyarrs:/config/ 複製進去。然後用同一個 image 執行一次還原：
  - Compose：docker compose run --rm holyarrs restore <zip name>
  - Docker CLI：docker run --rm --volumes-from holyarrs -e PUID=<puid> -e PGID=<pgid> holyarrs/holyarrs:<tag> restore <zip name>
  如果用的是金鑰檔路徑，加上 -e HOLYARRS_MASTER_KEY_FILE=<its path>，讓還原用你的金鑰檢查。restore --list 會列出它看得到的 backup 名稱。
啟動 HolyArrs。你應該會看到媒體庫和設定都回來了。

在複製金鑰之前就啟動了新安裝？如果上面沒有值得保留的東西，先停止 HolyArrs，用同樣的 docker cp 把舊金鑰覆蓋到新金鑰上，還原，再啟動。

如果沒有成功

症狀： 「Backups are off in this build」。 原因： 這份副本沒有搭配 backup 管理功能執行。 解決方式： App 內無法處理；沒有 backup 的操作項目。

症狀： 下載、刪除或還原時要求輸入密碼。 原因： 這些操作需要最近用密碼登入過。 解決方式： 重新用密碼登入，再試一次。

症狀： 還原因為主金鑰而被拒絕。 原因： 設定資料夾裡的金鑰和 backup 不符。 解決方式： 把對應的 holyarrs.key 放回去，再試一次。

如果 zip 太大或已損壞、含有非預期的檔案、來自較新的資料庫版本，或含有你的金鑰讀不了的資料，還原也會被拒絕。

給進階使用者

backup 裡有什麼

每個 backup 是一個 zip，內含主資料庫、Events 資料庫（如果有的話），以及 backup.json（HolyArrs 版本、資料庫版本、backup 種類、建立時間）。媒體、下載項目、圖片、log 和主金鑰都不在裡面。

在第一次啟動之前還原

docker cp 對 named volume 和主機資料夾都適用；HolyArrs 啟動時會把 /config 裡的檔案交給你的 PUID 和 PGID。如果使用 HOLYARRS_MASTER_KEY_FILE，就把金鑰放在主機上的那個路徑，並讓 PUID 和 PGID 可以讀取。

把 zip 檔名保持不變，放進名為 backups 的資料夾，再複製進去：docker cp backups holyarrs:/config/。
用同一個 image 執行一次還原：
- Compose：docker compose run --rm holyarrs restore <zip name>
- Docker CLI：docker run --rm --volumes-from holyarrs -e PUID=<puid> -e PGID=<pgid> holyarrs/holyarrs:<tag> restore <zip name>
如果用的是金鑰檔路徑，加上 -e HOLYARRS_MASTER_KEY_FILE=<its path>，讓還原用你的金鑰檢查。
啟動 HolyArrs。

restore --list 會列出它看得到的 backup 名稱。