Nextcloud AIO 每日备份脚本（daily-backup.sh）外部调用全指南：环境变量、执行流程与 cron 自动化-平芜编程栈

云原生
运维
后端
容器编排

【免费下载链接】all-in-one

📦 The official Nextcloud installation method. Provides easy deployment and maintenance with most features included in this one Nextcloud instance.

项目地址：https://gitcode.com/GitHub_Trending/al/all-in-one

点击查看免费下载

Nextcloud AIO（All-in-One）把每日备份、容器启停与镜像更新统一封装在 mastercontainer 内的/daily-backup.sh脚本中。本指南以 tests/QA/080-daily-backup-script.md 定义的 QA 场景为主线，结合 readme.md 中的官方文档与 Containers/mastercontainer/daily-backup.sh 的完整源码，逐条讲解五个环境变量的语义、典型调用命令、脚本内部执行流水线，并给出基于 cron 的「先停机备份、再自动更新」的完整自动化方案。读完本文你将能够在不打开 AIO 界面的前提下，从宿主机用一行docker exec触发备份、备份完整性校验、容器启停与全量更新，并把这些操作安全地编排进定时任务。

脚本从哪来：mastercontainer 内的内置工具

daily-backup.sh是随 mastercontainer 镜像一起交付的 Bash 脚本。在 Containers/mastercontainer/Dockerfile 中可以看到：

COPY --chmod=775 Containers/mastercontainer/*.sh /

它把Containers/mastercontainer/目录下所有.sh脚本（含daily-backup.sh）以可执行权限复制到容器的根目录/，因此宿主机上可以直接通过docker exec在容器内执行/daily-backup.sh。

该脚本同时是 AIO 内部定时任务的底层执行器：Containers/mastercontainer/cron.sh 中的主循环在到达每日备份时间（默认04:00，由daily_backup_time配置文件控制）时，会设置好DAILY_BACKUP、AUTOMATIC_UPDATES、START_CONTAINERS等环境变量并调用bash /daily-backup.sh。换言之，你在界面上开启「每日备份」后看到的执行效果，与你手动执行该脚本得到的行为完全一致——理解了脚本，就理解了 AIO 的整个备份/更新调度机制。

⚠️ 前置条件：脚本只有在 AIO 完成首次初始化后才能正常工作。你必须先访问一次 AIO 界面、填入域名并启动容器（或从 borg 备份恢复旧实例），脚本内的守卫逻辑才会放行。这一点在 tests/QA/080-daily-backup-script.md 指向的官方文档中有明确警告。

五个环境变量：一次调用能做什么

/daily-backup.sh不接收位置参数，一切行为都由注入的环境变量驱动。下表汇总了 readme.md 中定义的五个开关：

环境变量	取值	作用	隐含行为
`AUTOMATIC_UPDATES`	`1`	自动停止容器 → 更新镜像 → 重新启动全部容器（含 mastercontainer 自身）	隐含`START_CONTAINERS=1`
`DAILY_BACKUP`	`1`	自动停止容器并创建一份 borg 备份	隐含`STOP_CONTAINERS=1`
`STOP_CONTAINERS`	`1`	在脚本开始时停止所有容器	被`DAILY_BACKUP=1`隐含
`START_CONTAINERS`	`1`	在脚本结束时启动所有容器（不更新）	被`AUTOMATIC_UPDATES=1`隐含
`CHECK_BACKUP`	`1`	对所有既有 borg 备份执行完整性校验	非阻塞，容器可保持运行

两条关键约束：

DAILY_BACKUP与CHECK_BACKUP不能同时为1。脚本源码 Containers/mastercontainer/daily-backup.sh 中有一道显式守卫：if [ "$DAILY_BACKUP" = 1 ] && [ "$CHECK_BACKUP" = 1 ]; then ... exit 1。原因是备份要求容器停机以获得一致快照，而备份校验被设计为非阻塞、可与在线运行共存，两者语义互斥。
所有选项都不返回错误码。官方文档明确提示「None of the option returns error codes」，因此你需要自行判断执行结果（例如检查 borg 容器是否如预期停止、检查日志），而不能依赖脚本的退出状态。

常用调用示例

以下命令均在宿主机执行，核心形态是：

sudo docker exec [--env 变量=值 ...] nextcloud-aio-mastercontainer /daily-backup.sh

触发一次每日备份（备份完成后容器保持停止）：

sudo docker exec -it --env DAILY_BACKUP=1 nextcloud-aio-mastercontainer /daily-backup.sh

这条命令适合放进 cron 定时执行，也是官方文档给出的标准示例。

执行备份完整性校验（不停止容器）：

sudo docker exec --env DAILY_BACKUP=0 --env CHECK_BACKUP=1 --env STOP_CONTAINERS=0 nextcloud-aio-mastercontainer /daily-backup.sh

注意这里显式把DAILY_BACKUP和STOP_CONTAINERS置为0，避免默认值或隐含行为干扰校验流程。校验的输出可以在nextcloud-aio-borgbackup容器的日志中查看。

只停止所有容器（适合维护窗口或配合外部备份方案）：

sudo docker exec --env STOP_CONTAINERS=1 nextcloud-aio-mastercontainer /daily-backup.sh

只启动所有容器（不更新镜像）：

sudo docker exec --env START_CONTAINERS=1 nextcloud-aio-mastercontainer /daily-backup.sh

全量自动更新：

sudo docker exec --env AUTOMATIC_UPDATES=1 nextcloud-aio-mastercontainer /daily-backup.sh

脚本内部执行流水线（源码级拆解）

深入 Containers/mastercontainer/daily-backup.sh 的源码，可以发现脚本由若干守卫、等待循环和 PHP Cron 任务串联而成。理解这条流水线，能帮你判断各场景下脚本会停留多久、做什么事。

1. 初始化守卫

脚本启动后依次检查：

配置是否完成：读取/mnt/docker-aio-config/data/configuration.json，只有其中出现wasStartButtonClicked为1或true才继续，否则直接退出（L9-L14）；
是否处于恢复模式：如果 borgbackup 容器正在运行且配置处于backup-mode: restore，则退出以免打断恢复流程（L16-L23）；
备份与校验互斥：如前所述（L26-L29）。

2. 会话清理与锁文件

脚本会删除 AIO 界面的全部活动会话并创建锁文件/mnt/docker-aio-config/data/daily_backup_running（L31-L36）。锁文件的作用是防止备份期间界面操作与脚本冲突；除非 mastercontainer 刚完成更新，否则执行脚本会把用户「踢出」界面。

3. 等待依赖容器就绪/停止

脚本通过docker ps与nc（netcat）轮询等待：

等待 apache 容器可访问（必要时先把 mastercontainer 接入nextcloud-aio网络，见 L39-L52）；
等待 watchtower 容器停止（L53-L56）；
等待 borgbackup 容器停止（L57-L60）。

每个等待循环都以 30 秒为步长，因此脚本整体耗时取决于容器的实际状态。

4. 按环境变量分阶段执行 PHP Cron 任务

流水线中段的每一步都是调用su-exec www-data php运行 php/src/Cron/ 目录下的真实任务：

阶段	触发条件	调用的任务	作用
更新 mastercontainer	`AUTOMATIC_UPDATES=1`	UpdateMastercontainer.php	更新主控容器自身，脚本可能在此中断
拉取镜像	`AUTOMATIC_UPDATES=1`	PullContainerImages.php	预先拉取新镜像，缩短后续停机窗口
停止容器	`CHECK_BACKUP!=1`且（`DAILY_BACKUP!=1`或`STOP_CONTAINERS=1`）	StopContainers.php	按需停止全部业务容器
创建备份	`DAILY_BACKUP=1`	CreateBackup.php	启动 borgbackup 容器执行备份，随后等待其停止
校验备份	`CHECK_BACKUP=1`	CheckBackup.php	启动 borg 完整性校验
启动并更新	`AUTOMATIC_UPDATES=1`	StartAndUpdateContainers.php	全量更新后拉起所有容器
仅启动	`START_CONTAINERS=1`且未自动更新	StartContainers.php	只启动容器、不更新

其中 CreateBackup.php 与 CheckBackup.php 的实现非常简短：二者都把内存上限提升到 2048M，然后分别调用DockerController::startBackup()与DockerController::checkBackup()，真正的容器编排逻辑集中在 php/src/Controller/DockerController.php。

5. 收尾：锁清理与成功通知

脚本结束前删除锁文件（L124）；当DAILY_BACKUP=1且（AUTOMATIC_UPDATES=1或START_CONTAINERS=1）时，会等待 Nextcloud 容器在 9000 端口就绪，再调用 BackupNotification.php 发送备份成功/失败通知（L126-L144）。

关于 mastercontainer 自更新的特殊说明

当AUTOMATIC_UPDATES=1时，脚本在更新 mastercontainer 自身的阶段就可能因容器停止而中断。官方文档明确说明：此时应当等待 mastercontainer 重新启动，然后用相同的参数再执行一次脚本，才能把其余容器的更新正确完成。这也正是下面自动化方案中「连续两次调用」的由来。

实战编排：cron 驱动的「停机备份 + 自动更新」

如果已有外部备份方案、不希望 AIO 内置备份介入，官方文档（readme.md）给出了完整的 cron 编排思路。需要提醒的是，官方明确标注这种做法「不被推荐」——你将失去从 AIO 界面一键创建/恢复备份的能力，且外部备份前必须确保所有容器已正确停机。

第一步：停机脚本

创建/root/shutdown-script.sh：

#!/bin/bash # 停止所有容器 docker exec --env STOP_CONTAINERS=1 nextcloud-aio-mastercontainer /daily-backup.sh # 可选：若 AIO 运行在虚拟机中，可在停机后关闭虚拟机 # poweroff

设置权限并写入 cron：

sudo chown root:root /root/shutdown-script.sh sudo chmod 700 /root/shutdown-script.sh sudo crontab -u root -e

在 crontab 中加入（每天 04:00 执行）：

0 4 * * * /root/shutdown-script.sh

随后在 AIO 停机后，由你的外部备份方案接管备份（若备份运行在同一宿主机，至少应备份全部 docker 卷，以及未存放在 docker 卷中的 Nextcloud 数据目录）。

第二步：自动更新脚本

创建/root/automatic-updates.sh：

#!/bin/bash # 先尝试执行一次更新 if ! docker exec --env AUTOMATIC_UPDATES=1 nextcloud-aio-mastercontainer /daily-backup.sh; then # 等待 watchtower 停止 while docker ps --format "{{.Names}}" | grep -q "^nextcloud-aio-watchtower$"; do echo "Waiting for watchtower to stop" sleep 30 done # 等待 mastercontainer 重新启动 while ! docker ps --format "{{.Names}}" | grep -q "^nextcloud-aio-mastercontainer$"; do echo "Waiting for Mastercontainer to start" sleep 30 done # 再执行一次，确保所有容器都被正确更新 docker exec --env AUTOMATIC_UPDATES=1 nextcloud-aio-mastercontainer /daily-backup.sh fi

同样设置权限并写入 cron（每天 05:00 执行，紧跟在备份之后）：

sudo chown root:root /root/automatic-updates.sh sudo chmod 700 /root/automatic-updates.sh sudo crontab -u root -e

0 5 * * * /root/automatic-updates.sh

该脚本利用「选项不返回错误码」的特性：第一次执行若因 mastercontainer 自更新而中断，则等待 watchtower 与 mastercontainer 状态稳定后重试一次，从而把「更新自身」与「更新其余容器」两个阶段完整跑完。

常见问题与排查要点

脚本执行后什么都没发生：检查是否已完成首次初始化（configuration.json中的wasStartButtonClicked）、是否处于恢复模式、是否同时传了DAILY_BACKUP=1与CHECK_BACKUP=1。脚本源码中这几处守卫都会打印明确的退出原因。
界面会话被清空：这是预期行为，锁文件存在期间 AIO 界面被屏蔽；待脚本完成后锁文件会被删除。
想知道备份校验结果：查看nextcloud-aio-borgbackup容器的日志，而非 mastercontainer 日志。
想确认内部调度行为：AIO 界面开启每日备份后，cron.sh 会依据daily_backup_time文件的内容设置环境变量并调用同一个脚本——外部手动调用与内部定时调度完全等价，可作为故障复现与验证的手段。
该脚本对应的 QA 场景：tests/QA/080-daily-backup-script.md 将其列为需要「按文档行为逐条验证」的验收项，配合 tests/QA/readme.md 中描述的干净实例搭建流程，可以完整复现本文的所有命令。

小结

/daily-backup.sh是 Nextcloud AIO 暴露给运维人员的唯一外部操作入口：五个环境变量覆盖了「备份、校验、停机、启动、更新」五种原子操作，脚本内部则通过锁文件、等待循环与一系列 PHP Cron 任务保证各阶段有序执行。无论你是想在宿主机上手工运维，还是通过 cron/外部脚本实现「先停机备份、后自动更新」的完整自动化链路，理解本文的变量语义与执行流水线，就掌握了在不触碰 AIO 界面的前提下安全操作整套实例的能力。