企业官网建设流程全解析

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

导读

本文以 Nextcloud All-in-One（AIO）的初始备份为切入点，系统讲解备份位置（本地目录与远程 SSH/Borg 仓库）的合法输入规则、Create backup的完整执行流程、备份容器的底层运作机制，以及备份成功后界面状态的变化。文章以 004-initial-backup.md 的 QA 验收流程为骨架，结合 ConfigurationManager.php 的参数校验、DockerController.php 的容器编排与 backupscript.sh 的实际执行逻辑，帮助你理解并正确完成 AIO 的首次备份配置，并为后续的备份/恢复操作打好基础。

一、备份位置输入：两种合法模式与校验规则

完成初始安装并启动所有容器后，AIO 界面中的Backup and restore（备份与恢复）区域会出现两个输入框：一个是填写本地备份路径，另一个是填写远程 SSH 备份仓库 URL，二者下方均有对应的格式说明文字。

1.1 本地备份路径的合法性判定

按照 QA 流程 004-initial-backup.md 的验证用例，本地路径需遵循以下规则：

这一规则在后端源码中有明确实现。ConfigurationManager.php 的validateBorgLocationVars()方法中，本地路径必须满足以下条件之一：

• 以/开头且不以/结尾（如/mnt/backup）；
• 或者是特殊的 Docker 卷名nextcloud_aio_backupdir（该卷需要你提前手动创建，例如在 Windows 上创建备份卷时使用）。

此外，源码还包含一条 QA 流程未直接列出的附加校验：备份路径不能位于 Nextcloud 数据目录（NEXTCLOUD_DATADIR）之下或与其相等，否则会抛出异常。这是因为备份若包含数据目录本身，恢复时会导致备份归档被一并删除（源码注释中引用了 nextcloud/all-in-one 的 issue #6607）。

1.2 远程 Borg 仓库 URL 的合法性判定

除了本地路径，AIO 还支持通过 SSH 使用 BorgBackup 进行远程备份。远程仓库 URL 必须同时包含@和:。QA 流程给出了典型用例：

对应实现位于 ConfigurationManager.php 的validateBorgRemoteRepo()方法：仓库字符串必须包含@，且必须包含:，缺一不可。

1.3 本地路径与远程仓库互斥

两个输入框不能同时填写：要么填本地路径，要么填远程仓库 URL。源码中validateBorgLocationVars()对此有明确处理（ConfigurationManager.php）：

• 两者都为空：抛出Please enter a path or a remote repo url!
• 两者都不为空：抛出Location and remote repo url are mutually exclusive!

填写合法的备份位置并提交后，页面会重新加载，随后 Backup and restore 区域会展示：

• Backup information（备份信息）区域：包含加密密码（borg 加密口令）、备份位置等重要信息；
• Backup creation（创建备份）区域：包含Create backup（创建备份）按钮。

二、首次备份执行流程：从点击按钮到备份完成

2.1 备份按钮的交互逻辑

点击Create backup按钮后，会弹出一个**窗口提示（window prompt）**用于确认操作，你可以选择取消或确认：

• 取消：直接返回网站页面，不做任何操作；
• 确认：页面出现大号 spinner（加载指示器）并阻塞页面，防止误操作；等待一段时间后，界面会提示Backup container is currently running（备份容器正在运行）。

2.2 底层执行链路：DockerController 的容器编排

点击确认后，前端请求会进入 PHP 后端。在 DockerController.php 中，StartBackupContainerBackup()通过流式响应（startStreamingResponse）调用startBackup()，其核心逻辑为：

public function startBackup(bool $forceStopNextcloud = false, ?\Closure $addToStreamingResponseBody = null) : void { $this->configurationManager->backupMode = 'backup'; $id = self::TOP_CONTAINER; $this->PerformRecursiveContainerStop($id, $forceStopNextcloud, $addToStreamingResponseBody); $id = 'nextcloud-aio-borgbackup'; $this->PerformRecursiveContainerStart($id, true, $addToStreamingResponseBody); }

即：

1. 将配置中的backupMode置为backup；
2. 递归停止所有顶层容器（即先停止 Nextcloud 及全部依赖容器，保证数据一致性）；
3. 启动nextcloud-aio-borgbackup备份容器执行实际备份。

注意StartBackupContainerBackup()中传入了$forceStopNextcloud = true，表明创建备份会强制停止 Nextcloud，这也是备份期间页面被阻塞、实例不可用的原因。

2.3 备份容器的定义与挂载

nextcloud-aio-borgbackup容器的完整定义见 containers.json。关键信息：

• 镜像：ghcr.io/nextcloud-releases/aio-borgbackup（标签跟随%AIO_CHANNEL%）；
• 环境变量：BORG_REMOTE_REPO、BORG_PASSWORD、BORG_MODE、SELECTED_RESTORE_TIME、RESTORE_EXCLUDE_PREVIEWS、BACKUP_RESTORE_PASSWORD、ADDITIONAL_DIRECTORIES_BACKUP、BORGBACKUP_HOST_LOCATION、BORG_RETENTION_POLICY等；
• 卷挂载：将主机上的备份目录（%BORGBACKUP_HOST_LOCATION%）挂载到容器内/mnt/borgbackup，同时挂载nextcloud_aio_mastercontainer、nextcloud_aio_nextcloud_data、nextcloud_aio_elasticsearch、nextcloud_aio_redis等卷；
• 权限与设备：cap_add: SYS_ADMIN、devices: /dev/fuse、read_only: true（只读根文件系统），并启用apparmor_unconfined——这是为了支持 borg 的 FUSE 挂载与恢复操作。

三、远程备份的 SSH 密钥授权流程

当选择远程仓库作为备份位置时，AIO 的远程备份遵循一套固定的授权流程（QA 文档 004-initial-backup.md 中明确列出）：

1. 输入远程 borg 仓库 URL，例如ssh://user@host:port/path/to/repo或user@host:/path/to/repo；
2. 首次连接时自动生成 SSH 密钥对，并显示公钥内容；
3. 你需要把公钥添加到远程服务器的~/.ssh/authorized_keys文件中，使 AIO 能够免密连接；
4. 授权完成后，AIO 即可在远程服务器上创建和恢复备份。

具体到 QA 验证流程：

• 填写合法远程仓库 → 页面重新加载 → 点击Create backup；
• 首次备份尝试会失败（因为远程尚未授权），此时界面会展示 borg 使用的 SSH 公钥，供你复制并配置到远程服务器；
• 在远程完成授权后，再次滚动到页面下方并点击Create backup，这次备份应当成功。

这一流程在备份容器的启动脚本中有完整实现。start.sh 中，当设置了BORG_REMOTE_REPO时：

export BORG_REPO="$BORG_REMOTE_REPO" # 私钥/公钥存放位置 export BORGBACKUP_KEY="/nextcloud_aio_volumes/nextcloud_aio_mastercontainer/data/id_borg" # 首次连接接受新主机密钥 export BORG_RSH="ssh -o StrictHostKeyChecking=accept-new -i $BORGBACKUP_KEY"

而 backupscript.sh 中负责密钥生成与展示：

if [ -n "$BORG_REMOTE_REPO" ] && ! [ -f "$BORGBACKUP_KEY" ]; then echo "First run, creating borg ssh key" ssh-keygen -f "$BORGBACKUP_KEY" -N "" echo "You should configure the remote to accept this public key" fi if [ -n "$BORG_REMOTE_REPO" ] && [ -f "$BORGBACKUP_KEY.pub" ]; then echo "Your public ssh key for borgbackup is: $(cat "$BORGBACKUP_KEY.pub")" fi

即首次运行时自动ssh-keygen生成无口令密钥对（存放于 mastercontainer 卷的data/id_borg），随后打印公钥内容供你在远程服务器授权。远程 borg 仓库的初始化与本地不同：由于borg config不支持远程仓库，AIO 会在nextcloud_aio_mastercontainer/data/borg.config中创建一个占位文件来记录“已初始化”，加密密钥由远程侧自行保管（backupscript.sh）。

四、备份执行细节：从预检到归档

备份容器启动后，backupscript.sh 会执行一系列预检（pre-flight checks），全部通过后才真正创建 borg 归档：

1. 卷挂载检查：/nextcloud_aio_volumes下的每个目录都必须是挂载点（backupscript.sh）；
2. 默认卷检查：nextcloud_aio_apache、nextcloud_aio_nextcloud、nextcloud_aio_database、nextcloud_aio_database_dump、nextcloud_aio_elasticsearch、nextcloud_aio_nextcloud_data、nextcloud_aio_mastercontainer必须全部存在（backupscript.sh）；
3. 目标位置检查：本地备份时目标目录必须是挂载点，否则拒绝执行（backupscript.sh）；
4. 关键文件检查：configuration.json、config.php、database-dump.sql、数据目录的.ncdata/.ocdata标记文件必须存在且内容有效（backupscript.sh）；
5. 上次导出失败标记检查：若存在export.failed文件，则拒绝创建新备份，并提示先手动重启数据库容器重试导出（backupscript.sh）。

预检通过后，脚本执行：

• 初始化 borg 仓库（若未初始化）：使用borg init --encryption=repokey-blake2创建加密仓库，并对本地仓库额外设置additional_free_space 2G（保留 2GB 空闲空间）并修复过大的 borg 缓存（backupscript.sh）；
• 创建归档：以$CURRENT_DATE-nextcloud-aio（格式%Y%m%d_%H%M%S）命名归档，使用--compression "auto,zstd"压缩，并通过--exclude-from /borg_excludes排除不需要备份的文件（backupscript.sh）；
• 排除项：排除文件见 borg_excludes，包括 Caddy 配置目录、nextcloud.log、audit.log（GDPR 原因）、证书目录、会话目录、id_borg*密钥文件等；
• 裁剪与压缩：按BORG_RETENTION_POLICY（默认--keep-within=7d --keep-weekly=4 --keep-monthly=6，见 Dockerfile）执行borg prune与borg compact，自动清理旧归档；
• 备份失败处理：若创建归档失败，脚本会立即删除失败的归档；若是在新仓库上的首次失败，还会删除borg.config以便你重新选择备份位置（backupscript.sh）。

此外，AIO 还支持通过.noaiobackup标记文件排除 Nextcloud 数据目录或预览目录（appdata_*/preview/），适用于数据目录过大或无需备份预览图的场景（backupscript.sh）。

五、备份成功后的界面状态确认

备份流程结束后，QA 流程要求确认以下界面变化：

1. 顶部凭据收起：初始安装阶段在页面顶部显示的 Nextcloud 初始凭据（容器运行时可见），备份成功后应被收进一个details标签（可折叠）中；
2. 自动跳转与状态回显：等待一段时间并经历几次自动刷新后（页面需保持焦点），页面会跳转到常规界面，并在 Backup and restore 区域显示最近一次备份成功；
3. 备份选项折叠：页面下方会出现一个details标签，展开后可以查看所有备份选项。

从实现角度看，备份容器退出后，start.sh 会生成backup_archives.list文件（列出所有nextcloud-aio归档及其时间戳），写入 mastercontainer 卷的data/backup_archives.list，前端据此展示备份历史与“最近一次备份成功”的状态。该文件同样在 ConfigurationManager.php 的getLastBackupTime()中被读取，用于在界面上显示最后备份时间。

六、与后续 QA 流程的衔接

初始备份通过验证后，可以继续阅读 020-backup-and-restore.md 完成更完整的备份/恢复验证。该文档进一步要求：

• 展开所有备份选项，确认包含Backup information、Backup creation、Backup check、Backup restore、Daily backup以及additional backup location六个区域；
• 备份恢复区域按时间从新到旧列出所有可用归档；
• 支持创建备份、检查备份完整性（Check backup integrity）与恢复所选备份（Restore selected backup）三种操作；
• 每日自动备份时间支持 24 小时制输入（如04:00合法，24:00、dfjlk非法）；
• 可以追加备份额外目录/卷（如/etc、nextcloud_aio_mastercontainer，但不能是nextcloud/test这类嵌套路径）。

这些能力同样由 DockerController.php 中对应的StartBackupContainerCheck()、StartBackupContainerRestore()、StartBackupContainerCheckRepair()、StartBackupContainerTest()等方法驱动，核心模式与初始备份一致：设置backupMode→ 按需停止顶层容器 → 启动 borgbackup 容器执行对应模式的操作。

七、关键要点速查

• 本地路径：必须以/开头、不以/结尾；合法示例/mnt/backup、/media/backup、/host_mnt/c/backup、/var/backups；也可使用预建卷名nextcloud_aio_backupdir；不得位于NEXTCLOUD_DATADIR之下。
• 远程仓库：必须同时包含@与:；合法示例ssh://user@host:22/path/to/repo、user@host:/path/to/repo。
• 互斥规则：本地路径与远程仓库只能二选一，不能同时填写。
• 远程授权流程：首次备份触发自动生成 SSH 密钥 → 复制公钥到远程~/.ssh/authorized_keys→ 再次点击Create backup完成备份。
• 备份机制：基于 BorgBackup（repokey-blake2加密、auto,zstd压缩），先递归停止 Nextcloud 容器保证数据一致性，再由nextcloud-aio-borgbackup容器执行归档、裁剪与压缩。
• 界面反馈：确认备份后页面被 spinner 阻塞并提示备份容器运行中；成功后初始凭据收起、最近备份状态显示成功、所有备份选项可折叠展开。

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