配置 Nextcloud 后台任务：Cron、Webcron 与 systemd 定时器-未完纪

Nextcloud 需要定期执行一些任务，例如数据库清理。这些工作应在没有用户交互的情况下进行，同时尽量避免影响正常使用。管理员可以为此配置后台任务。

这类定时执行的命令或 Shell 脚本通常称为 cron jobs。cron.php 是 Nextcloud 内部按需运行后台任务的入口。应用会自动向它注册日常维护工作，例如回收临时文件，或用 filescan() 检查外部挂载文件系统中新出现的更新。

参数：`maintenance_window_start`

这个设置只在 Cron 模式下生效，可写入 config/config.php。有些后台任务每天只运行一次；指定小时后，自行声明为“非时效性”的任务会避开工作时段，只在该起始时间之后的四小时内运行。小时按 UTC 解释，例子包括活动记录过期、可疑登录训练和更新检查。

例如，值为 1 表示这些任务可在 UTC 01:00 至 05:00 之间运行：

'maintenance_window_start' => 1,

若不在意何时运行，可设为 100。但这会允许耗资源的任务在使用高峰发生，可能使服务变慢。维护窗口不是暂停全部后台任务，也不会约束未声明支持该窗口的紧急工作。

这个参数也可通过 occ 设置，方式与其他系统配置相同：

occ config:system:set maintenance_window_start --type=integer --value=1

这里 occ 表示按当前部署方式调用 Nextcloud 的命令行工具；不要假设它已经在任意终端的 PATH 中。操作时应使用实例的 HTTP 服务用户和匹配的 PHP 环境。

三种调度方式

后台任务可通过 AJAX、Webcron 或操作系统 Cron 调度。默认是 AJAX，官方推荐 Cron。

AJAX

适用情境：单用户实例。

每次用户访问 Nextcloud 页面，只执行一个后台任务。优点是无需系统访问权限，也无需第三方服务；缺点是依赖有人定期打开页面，因此可靠性最低。尤其使用 Activity 应用、外部存储中有文件增删改，或实例有多个用户时，应使用 Cron。

Webcron

适用情境：非常小的实例，文档以约 1–5 名用户为例，实际取决于使用量。

把实例 cron.php 的地址登记到外部 Webcron 服务后，服务会定期请求该地址；原文举例的服务是 easyCron。实例必须能从互联网访问，例如：

URL to call: http[s]://<domain-of-your-server>/nextcloud/cron.php

Webcron 仍通过 Web 服务器执行，往往受到 Web 请求资源限制。为减少任务中断，每次调用只执行一个任务。若每五分钟调用一次，一天最多触发 288 个任务，因此只适合很小的实例；更大的实例应使用 Cron。

Cron

操作系统的 Cron 是优先推荐方式，可以绕开 Web 服务器对请求的固有限制。

在 Unix 类系统中，以 HTTP 服务用户运行 cron.php。常见用户是 www-data 或 wwwrun；先编辑该用户的计划任务：

# crontab -u www-data -e

然后加入每五分钟一次的调用：

*/5  *  *  *  * php -f /var/www/nextcloud/cron.php

检查任务是否已保存：

# crontab -u www-data -l

列表中应出现类似内容：

[snip]
*/5  *  *  *  * php -f /var/www/nextcloud/cron.php

命令开头的 # 是原文的管理员提示符，不属于要输入的命令。/var/www/nextcloud/cron.php 必须替换成实际安装路径。有些系统需要使用 php-cli 而不是 php；准确的计划任务语法还应查看本机 crontab 手册。计划任务存在，只能证明它已配置；实际执行结果还需要核对日志和实例状态。

用 systemd 定时器替代 Cron

如果系统使用 systemd，可以选择定时器方案。它需要两个文件：nextcloudcron.service 和 nextcloudcron.timer，放在 /etc/systemd/system/ 中。该方案用于本机原生安装；容器实例应按后面的部署补充理解。

nextcloudcron.service：

[Unit]
Description=Nextcloud cron.php job

[Service]
User=www-data
ExecCondition=php -f /var/www/nextcloud/occ status -e
ExecStart=/usr/bin/php -f /var/www/nextcloud/cron.php
KillMode=process

把 www-data 替换为 HTTP 服务用户；把 occ、cron.php 的路径替换为实例对应路径。示例的 ExecCondition 使用 php，而 ExecStart 使用 /usr/bin/php，实际部署时应核对两者是否指向相同、合适的 CLI PHP。

ExecCondition 在执行前检查实例是否正常运行；状态不合适时，跳过后台任务。KillMode=process 允许 Cron 启动的外部程序在 Cron 进程结束后继续运行。

.service 文件不需要 [Install] 段。旧版文档曾推荐添加它，升级配置时应检查这一点。

nextcloudcron.timer：

[Unit]
Description=Run Nextcloud cron.php every 5 minutes

[Timer]
OnBootSec=5min
OnUnitActiveSec=5min
Unit=nextcloudcron.service

[Install]
WantedBy=timers.target

OnBootSec 让它在开机五分钟后触发；OnUnitActiveSec 让它在服务上次激活五分钟后再次触发。Unit 指明要执行哪个服务。

启动并启用定时器：

systemctl enable --now nextcloudcron.timer

enable 搭配 --now 会同时启动该单元。若刚创建或修改单元文件，先让 systemd 重新加载配置，再检查定时器与服务日志；不要把“定时器存在”当作后台任务成功执行。

通过命令行或 Cron 服务运行 cron.php 时，Nextcloud 会自动切到 Cron 模式，因此不强制要求先在管理菜单里选择 Cron。

部署补充：容器路径与宿主机路径

容器化部署需要区分 PHP 运行位置与 Nextcloud 文件所在位置。官方 Docker 镜像文档将安装目录放在容器的 /var/www/html，并示范以 www-data 用户通过 docker exec 调用 occ。宿主机上的 /var/www/nextcloud 不能自动代表容器内部路径。官方镜像说明

下面只示范读取容器实例状态。先把 CONTAINER_ID 替换成目标实例容器的真实标识，并核对镜像的 HTTP 用户及内部安装路径：

docker exec --user www-data CONTAINER_ID php /var/www/html/occ status -e

后台调度可以由部署已有的 Cron 机制、适配镜像的独立 Cron 容器或宿主机调度器完成；具体命令必须与部署匹配。不要同时叠加多个调度入口，也不要把原生安装的 systemd 示例直接贴到未知容器环境。本章没有创建容器、修改服务或实际执行后台任务。

来源与许可

正文依据 Nextcloud Background jobs；本次读取页面标识为 Nextcloud 35 Administration Manual。Nextcloud 文档贡献者的材料按 CC BY 3.0 提供，见官方文档仓库许可声明。本版完整翻译页面的参数、AJAX、Webcron、Cron、systemd 正文，保留全部十个原始代码块，并补充提示符、运行条件、部署路径与容器状态检查说明。不代表原作者背书。

代码已与读取到的原始页面逐字核对。未在真实 Nextcloud、PHP、Cron、systemd 或容器环境执行，不能据此声称任务已经成功运行。

文章版权归作者所有，未经允许请勿转载。

THE END