备份

给你的配置留一份副本，更新出问题、磁盘坏了或者换新机器时可以放回去。

开始之前

• Settings > Backups（设置 > 备份）需要 Change settings（更改设置）权限。只有所有者能恢复。
• 下载、删除和恢复都要求最近几分钟内用密码登录过。

做一次备份

1. 打开 Settings > Backups。
2. 点击 Back up now（立即备份）。你应该会看到新备份出现在 Saved backups（已保存的备份）下面。
3. 点击它旁边的 Download（下载），在服务器之外留一份。

保存主密钥

备份里从不包含主密钥，而设置里的密码和 API 密钥要靠它才能打开。没有对应的密钥，恢复出来的备份就读不了这些内容。

1. 在 Master key（主密钥）下面，由所有者点击 Download key kit（下载密钥包）。
2. 把这个文件放在服务器之外，并且和备份分开存放。你应该会看到密钥包的警告从 Settings > Backups 和健康检查里消失。

以后要用时，把它改名为 holyarrs.key，放进配置文件夹。你不是所有者？请所有者来下载。

恢复备份

危险

备份之后做的改动都会丢失。先把对应的主密钥准备好。

1. 点击 Restore from a file（从文件恢复），选一个 HolyArrs 备份 zip。
2. 确认。
3. HolyArrs 会检查这个文件。你应该会看到 Restore ready. It applies on the next start.（恢复已就绪，下次启动时生效。）
4. HolyArrs 重启并把备份放到位。用推荐的 Docker 重启策略时，这一步会自动完成。

你当前的数据库会移到 /config/backups/before-restore-<time>，所以恢复可以撤销。

选项

多久备份一次

选项	备份频率	保留
Balanced（均衡，默认）	每天	最近 7 天，外加 4 份每周副本
Light（轻量）	每周一次	4 周。最省空间
Careful（谨慎）	每天	30 天内的每一份

最新的计划备份始终保留。这些规则只清理计划备份。你自己做的备份会一直留着，直到你删除（点那一行的垃圾桶按钮；无法撤销）。HolyArrs 在会改动已存数据的更新之前也会先备份，并保留最新的 3 份；见更新。

搬到新机器

新安装在首次启动时会生成自己的主密钥。这把密钥打不开你的旧备份，所以恢复会被拒绝。先把旧密钥放到位。示例里的容器叫 holyarrs；请换成你自己的名字。

1. 首次启动之前，先创建容器但不启动：docker compose create，或者把你的 docker run 命令里的 docker run -d 换成 docker create。
2. 把旧密钥复制进去：docker cp holyarrs.key holyarrs:/config/。改名为 holyarrs.key 的密钥包也可以。命名卷和主机文件夹都能这样做；HolyArrs 启动时会把 /config 里的文件交给你的 PUID 和 PGID。如果你用了 HOLYARRS_MASTER_KEY_FILE，就把密钥放到主机上的那个路径，并让你的 PUID 和 PGID 可读。
3. 恢复备份。选一种方式：

   • 启动 HolyArrs，完成首次运行，然后在 Settings > Backups 里用 Restore from a file。

   • 或者在首次启动之前恢复。把 zip 原名不动放进一个叫 backups 的文件夹，用 docker cp backups holyarrs:/config/ 复制进去。然后用同一个镜像运行一次恢复：

     • 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 会列出它能看到的备份名。

4. 启动 HolyArrs。你应该会看到媒体库和设置都回来了。

还没复制密钥就启动了新安装？如果上面没有值得保留的东西，停止 HolyArrs，用同样的 docker cp 把旧密钥覆盖到新密钥上，恢复，然后启动。

如果不成功

现象： “Backups are off in this build”（这个构建里备份已关闭）。 原因： 这份程序运行时没有带备份管理器。 解决办法： 应用里没有办法；也没有备份相关的控件。

现象： 下载、删除或恢复时要求输入密码。 原因： 这些操作要求最近用密码登录过。 解决办法： 用密码重新登录，再试一次。

现象： 恢复因为主密钥被拒绝。 原因： 配置文件夹里的密钥和备份不匹配。 解决办法： 把对应的 holyarrs.key 放回去，再试一次。

以下 zip 也会被拒绝恢复：太大或已损坏、里面有不该有的文件、来自更新的数据库版本，或者里面的数据你的密钥读不了。

进阶

备份里有什么

每个备份是一个 zip，里面有主数据库、事件数据库（如果有），以及 backup.json（HolyArrs 版本、数据库版本、备份类型、创建时间）。媒体、下载内容、图片、日志和主密钥都不在里面。

在首次启动之前恢复

docker cp 对命名卷和主机文件夹都适用；HolyArrs 启动时会把 /config 里的文件交给你的 PUID 和 PGID。如果用了 HOLYARRS_MASTER_KEY_FILE，就把密钥放到主机上的那个路径，并让 PUID 和 PGID 可读。

1. 把 zip 原名不动放进一个叫 backups 的文件夹，再复制进去：docker cp backups holyarrs:/config/。
2. 用同一个镜像运行一次恢复：
   • 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>
3. 如果用了密钥文件路径，加上 -e HOLYARRS_MASTER_KEY_FILE=<its path>，让恢复用你的密钥来核对。
4. 启动 HolyArrs。

restore --list 会列出它能看到的备份名。

相关页面

• 更新
• 安装
• 健康检查