Nextcloud AIO 备份与恢复（Backup and restore）功能实战指南：从界面操作到源码级原理

• 云原生
• 运维
• 后端
• 容器编排

导读

Nextcloud All-in-One（AIO）把备份与恢复作为官方内置的一等公民功能：你只需在管理界面点几下按钮，就能完成整机备份、完整性校验、时间点恢复，以及设定每日自动备份；底层则由 BorgBackup 容器驱动，配合主容器的状态机在备份前后自动停止/启动全部服务容器。本文以 QA 测试文档 tests/QA/020-backup-and-restore.md 的验收条目为主线，结合仓库中 DockerController.php、ConfigurationManager.php 等源码实现，讲清备份/恢复的每个界面区块、配置规则与底层执行链路，读完你既能独立完成全流程验证，也能理解其设计原理。

Backup and restore 区块整体结构

在 AIO 管理界面中，展开Backup and restore（备份与恢复）区块后，会依次呈现以下六个子区块：

1. Backup information（备份信息）——展示当前备份状态、上次备份时间等概要信息；
2. Backup creation（创建备份）——提供 "Create backup" 按钮，手动触发一次完整备份；
3. Backup check（备份校验）——提供 "Check backup integrity" 按钮，对已有归档执行完整性检查；
4. Backup restore（恢复备份）——列出全部可用归档，并支持选择某一归档执行恢复；
5. Daily backup（每日备份）——配置每日自动备份的触发时间（24 小时制），以及是否开启自动更新与成功通知；
6. Additional backup location / directories（附加备份位置/目录）——把宿主机目录或 AIO 卷追加进备份范围。

对应的前端模板位于 php/templates/includes/backup-dirs.twig，而真正驱动这些按钮动作的是 DockerController.php 中的一组入口方法，其核心机制是给 BorgBackup 容器注入不同的backupMode（详见下文"底层原理"）。

手动创建备份：停服 → 备份 → 重启

点击Create backup按钮后，后端实际执行的是 DockerController::startBackup()：

1. 将backupMode置为'backup'；
2. 调用PerformRecursiveContainerStop()以依赖顺序停止全部容器（含 Nextcloud 主容器），保证备份期间没有进程写入数据，得到一致性的快照；
3. 启动nextcloud-aio-borgbackup容器，由它完成归档；
4. 备份结束后，BorgBackup 容器退出，面板随后会重新把各容器按依赖顺序拉起（这正对应 QA 文档中"过一会儿能看到容器正在启动、备份显示成功"的预期）。

手动备份的定时任务入口在 php/src/Cron/CreateBackup.php，它把 PHP 内存上限提到 2GB（ini_set('memory_limit', '2048M')）后直接调用startBackup()。也就是说，无论你在界面上点按钮，还是通过 cron 触发，最终都汇入同一条"停容器 → 跑 Borg → 恢复容器"的执行路径。

校验备份完整性：borg check

点击Check backup integrity按钮对应 DockerController::checkBackup()：将backupMode置为'check'，随后直接启动nextcloud-aio-borgbackup容器执行borg check之类的完整性校验，无需先停止其他容器。

同样地，cron 任务 php/src/Cron/CheckBackup.php 与界面按钮殊途同归：同样将内存上限提到 2GB，然后调用checkBackup()。校验完成后，界面上的 "Last check" 会刷新为成功或失败的结果。

恢复备份：按时间点选择并强制回滚

归档列表：从新到旧

恢复区块应列出所有可用备份归档，并按从最新到最旧的顺序排列。这一排序逻辑可以在 ConfigurationManager.php 中看到：读取备份归档列表文件后，逐行解析出每个归档对应的时间戳，最后通过array_reverse()反转数组，保证界面上最新的归档排在最前。

恢复动作的执行链路

点击Restore selected backup后，StartBackupContainerRestore() 会：

1. 开启配置事务，读取请求体中的selected_restore_time（要恢复的归档时间点）与restore-exclude-previews（恢复时是否排除预览图，默认不排除）；
2. 将backupMode置为'restore'，并把上述两个值分别持久化到配置项selected-restore-time与restore-exclude-previews（见 ConfigurationManager.php）；
3. 以forceStopNextcloud = true强制停止所有容器（恢复场景下不允许 Nextcloud 处于运行态）；
4. 启动nextcloud-aio-borgbackup容器执行恢复；
5. 恢复完成后容器重新启动，界面上的 "Last restore" 显示恢复是否成功。

这些配置随后会作为环境变量注入 BorgBackup 容器：BORGBACKUP_MODE（backup/check/list/restore 等）、SELECTED_RESTORE_TIME、RESTORE_EXCLUDE_PREVIEWS（置 1 表示排除预览图），映射关系定义在 ConfigurationManager.php。

Daily backup：每日自动备份的完整验收

24 小时制时间格式校验

Daily backup 区块允许输入 24 小时制时间，例如04:00合法，而24:00、dfjlk等非法输入会被拒绝。提交后，时间被写入每日备份时间文件，并在同一位置出现 "删除该设置" 的选项——对应 ConfigurationController.php 中对daily_backup_time与delete_daily_backup_time两个表单字段的处理，以及 ConfigurationManager::deleteDailyBackupTime() 的删除逻辑。

触发后的自动登出与运行状态

QA 文档特意提示了一个可自测的验证方式：把每日备份时间设成只比当前时间早 1 分钟，随后：

1. 时间一到，界面会自动将你登出（刷新页面即可确认）；
2. 重新登录后，可以看到自动备份"正在运行"的状态；
3. 稍候片刻，能看到各容器依次启动，Backup and restore 区块显示备份成功。

从源码结构看，主容器通过 Containers/mastercontainer/dinit.d/backup-time-file-watcher 这类看护进程监听每日备份时间文件的变化并触发备份，配合 StartAndUpdateContainers.php 等 cron 任务完成"备份后把容器拉起来"的收尾工作。

备份结果通知

每日备份结束后的成败通知由 php/src/Cron/BackupNotification.php 负责：读取 BorgBackup 容器的退出码，0视为成功、大于 0视为失败，并通过sendNotification()向 Nextcloud 推送 "Daily backup successful!/failed!" 消息。如果你不希望收到成功通知，可以设置环境变量SEND_SUCCESS_NOTIFICATIONS=0，此时只把成功结果记录到日志。

另外值得一提的是，UPDATE_NEXTCLOUD_APPS环境变量在"每日备份运行中且启用了自动更新"时才会置为yes（见 ConfigurationManager.php），即 Nextcloud 应用自动更新被设计为随每日备份流程执行，避免单独更新带来的停机窗口。

Additional backup directories：附加备份目录的合法性规则

在附加备份目录输入框中，QA 文档给出了三个典型用例：/etc（宿主机绝对路径）与nextcloud_aio_mastercontainer（AIO 卷名）应被接受，而nextcloud/test应被拒绝。其校验逻辑位于 ConfigurationManager::setAdditionalBackupDirectories()：

if (!preg_match("#^/[.0-9a-zA-Z/_-]+$#", $entry) && !preg_match("#^[.0-9a-zA-Z_-]+$#", $entry)) { throw new InvalidSettingConfigurationException("You entered unallowed characters! Problematic is " . $entry); }

两条正则分别对应两种合法形态：

• ^/[.0-9a-zA-Z/_-]+$：以/开头的宿主机绝对路径，如/etc、/data/backup；
• ^[.0-9a-zA-Z_-]+$：不带斜杠的纯卷名/相对名，如nextcloud_aio_mastercontainer。

而nextcloud/test既不以/开头、又包含/，两个正则都无法匹配，因此被拒绝。非法输入会抛出 InvalidSettingConfigurationException，界面会提示 "You entered unallowed characters! Problematic is ..."。

校验通过后，条目按换行拆分、去重后持久化（getAdditionalBackupDirectoriesArray()使用array_unique去重，见 ConfigurationManager.php）；当存在附加目录时，注入 BorgBackup 容器的ADDITIONAL_DIRECTORIES_BACKUP环境变量会被置为yes（ConfigurationManager.php），Borg 备份脚本据此把宿主机目录或卷一并纳入归档范围。具体执行逻辑可以参考 BorgBackup 容器内的 backupscript.sh 与 start.sh，排除规则则维护在 borg_excludes 中。

底层原理：backupMode 状态机与配置持久化

backupMode 驱动 Borg 容器行为

整个备份/恢复功能的核心是一个"模式"字段：backupMode支持backup、check、list、restore、check-repair、test等多种取值，分别在 DockerController.php 的对应入口中被写入：

• startBackup()→'backup'（创建备份）
• checkBackup()→'check'（校验完整性）
• listBackup()→'list'（列出归档）
• StartBackupContainerRestore()→'restore'（恢复）
• check-repair与test对应校验修复与连通性测试场景

该模式最终通过BORGBACKUP_MODE环境变量传递给nextcloud-aio-borgbackup容器（ConfigurationManager.php），Borg 容器据此决定本次启动要执行备份、校验还是恢复脚本。

配置的持久化与事务

backupMode、selectedRestoreTime、restoreExcludePreviews等字段都通过ConfigurationManager的get()/set()读写，其中恢复类操作还使用了startTransaction()/commitTransaction()保证多字段更新的一致性（见 StartBackupContainerRestore()）。每日备份时间与附加目录则直接以文件形式存放在主容器数据卷中（GetDailyBackupTimeFile()、GetAdditionalBackupDirectoriesFile()等路径由 DataConst.php 定义），getDailyBackupFileContent()还带 mtime 缓存，避免频繁读盘。

备份保留策略

归档的保留策略由BORG_RETENTION_POLICY环境变量控制（ConfigurationManager.php），由 BorgBackup 的备份脚本在每次备份后按策略清理旧归档，实现自动化的"增量备份 + 定期精简"。

用 QA 测试计划验证你的实例

如果你正在维护自己的 AIO 实例并想复现上述全部行为，可以直接照搬 tests/QA/020-backup-and-restore.md 的验收步骤：

1. 展开 Backup and restore，确认六个子区块齐全；
2. 检查恢复归档列表按从新到旧排列；
3. 依次点击 Create backup、Check backup integrity，稍候确认 "Last backup / Last check" 显示成功；
4. 输入04:00应通过、24:00与dfjlk应被拒绝；提交后确认出现删除选项；
5. 把时间设为 1 分钟后触发自动备份：验证自动登出、重新登录后显示备份运行中、容器自动重启、备份成功；
6. 在附加备份目录中验证/etc、nextcloud_aio_mastercontainer合法而nextcloud/test非法，并执行一次包含附加目录的备份确认成功。

按照 QA 流程，完成本项验证后即可继续进入密码修改的验收环节 tests/QA/030-aio-password-change.md；关于如何在干净实例上跑通整套 QA 计划，可参考 tests/QA/readme.md 与 develop.md。

• 云原生
• 运维
• 后端
• 容器编排