通过内置更新器升级-未完纪

内置更新器可以自动完成 Nextcloud 安装升级过程中的许多步骤。它适用于没有 root 权限的安装环境（例如共享主机），也适用于用户和数据量较少的安装，并可自动更新手动安装的实例。 [1]

警告

不支持降级，降级可能损坏数据！如果要回退到较早的 Nextcloud 版本，应重新安装该版本，然后从备份恢复数据。在此之前，如果你购买了付费支持，请提交支持工单；否则可到 Nextcloud 论坛求助，确认是否能够在不降级的情况下解决问题。

危险

应保持定期备份（参阅“备份”），并在每次更新前创建备份。内置更新器不会备份数据库或数据目录。 [2]

更新器会做什么？

说明

内置更新器本身只负责将现有文件替换为目标版本的文件。随后还必须执行迁移阶段，以升级数据库和应用。在命令行模式下，代码成功替换后，更新器会询问是否立即替你运行 occ upgrade。在网页模式下，更新器完成后会提供返回实例主 URL 的选项，以打开迁移阶段的网页界面。

内置更新器执行以下操作：

检查预期文件：确认 Nextcloud 安装目录中只有预期的文件，因为曾经发现遗留在 Nextcloud 目录中的某些文件产生了副作用，从而给更新过程带来风险。
检查写入权限：确认更新过程中所有需要写入的文件确实可写。
启用维护模式：在代码更新过程中启用维护模式，以免同时执行其他操作。
创建备份：在数据目录内的 /updater-INSTANCEID/backups/nextcloud-CURRENTVERSION/ 中创建现有代码库的备份，该备份不包含 /data 目录或数据库。
下载：下载目标版本的代码。开始更新之前，网页界面也会显示目标版本。压缩包下载到 /updater-INSTANCEID/downloads/。
解压：将压缩包解压到同一个文件夹。
替换入口文件：把所有 Nextcloud 入口替换为占位文件，使替换文件时所有客户端仍然收到正确的维护模式响应。这些入口包括 index.php、remote.php 和 ocs/v1.php。
删除旧文件：删除除上述入口文件、data 和 config 目录、非随附应用和主题之外的所有文件，当然也保留更新器自身。
将新文件移到位：把解压后的文件移到相应位置。
是否保持维护模式？询问是否继续启用维护模式。这样管理员可以使用网页更新器替换代码，再通过命令行执行实际迁移步骤（occ upgrade）。如果保持维护模式，必须具有命令行访问权限。要使用网页升级页面，请关闭维护模式并点击链接进入升级页面。这一步仅在网页更新器中提供。
完成：代码更新已经结束。你还需要打开提供的链接或使用命令行执行迁移步骤，才能完成升级。

使用命令行更新器

有新更新可用时，你应能在任意 Nextcloud 页面的顶部看到通知。进入管理员设置页面，滚动到“Version”（版本）部分，其中有打开更新器的按钮。只有在应用管理中启用了更新通知应用，这一部分和更新通知才会出现。

你可以不点击该按钮，而是进入 Nextcloud 目录中的 updater/ 目录，以网页服务器用户身份执行 updater.phar，调用命令行更新器。例如：sudo -E -u www-data php /var/www/nextcloud/updater/updater.phar。

核对显示的信息，然后输入“Y”开始更新。

如果发生错误或检查失败，更新器会停止并给出反馈。解决问题后可以重新运行更新器命令。这会继续更新并重新执行失败的步骤，不会重复之前已经成功的步骤。

所有步骤执行完后，更新器会最后询问：“Should the ‘occ upgrade’ command be executed?”（是否执行 occ upgrade 命令？）。这使你可以直接执行命令行升级过程（occ upgrade）。如果选择“No”，更新器会以“Please now execute ‘./occ upgrade’ to finish the upgrade.”（现在请执行 ./occ upgrade 完成升级）结束。

occ upgrade 完成后，会询问是否继续保持维护模式。

命令行更新器的批处理模式

命令行更新器可以在非交互模式下运行。此时不会提出任何交互问题，而是假定只要有更新就应安装，并执行 occ upgrade。完成后会关闭维护模式，除非在 occ upgrade 或代码替换期间发生错误。

使用 –no-interaction 选项执行命令即可，例如：sudo -E -u www-data php /var/www/nextcloud/updater/updater.phar –no-interaction。

使用自定义下载 URL

–url 选项允许覆盖更新器下载的压缩包。常见用途包括：

固定特定版本：安装指定的补丁版本，而不是更新检查所选出的版本。
内部镜像：从公司镜像或代理提供压缩包。
离线或隔离网络环境：先在本地准备压缩包，再通过 file:// URL 提供。

警告

使用 –url 时仍然适用通常的更新规则：

不支持降级。
不支持跳过主版本。必须逐个主版本升级，例如 28 → 29 → 30，而不能从 28 直接升级到 30。

传入 –url 不会绕过这些限制。

可以让更新器指向任意 HTTP/HTTPS URL：

sudo -u www-data php /var/www/nextcloud/updater/updater.phar \
    --url https://download.nextcloud.com/server/releases/nextcloud-33.0.0.zip

在版本 34 中加入。

对于本地准备的压缩包，使用 file:// URL：

sudo -u www-data php /var/www/nextcloud/updater/updater.phar \
    --url file:///tmp/nextcloud-33.0.0.zip

签名验证

使用 –url 时，更新器无法自动查找官方签名。有两种选择：

提供签名：通过 –signature 传入 Base64 编码的签名。可以从 https://nextcloud.com/changelog/ 或托管压缩包的同一个镜像获取签名： [3]
```
sudo -u www-data php /var/www/nextcloud/updater/updater.phar \
    --url file:///tmp/nextcloud-33.0.0.zip \
    --signature "BASE64_SIGNATURE_HERE"
```
跳过验证：使用 –no-verify 完全关闭完整性检查。仅在你完全信任来源和传输通道，或已经自行验证压缩包（例如核对 SHA-512 校验和）时这样做：
```
sha512sum -c nextcloud-33.0.0.zip.sha512
```
然后运行更新器，不检查签名：
```
sudo -u www-data php /var/www/nextcloud/updater/updater.phar \
    --url file:///tmp/nextcloud-33.0.0.zip \
    --no-verify
```
警告

–no-verify 会移除防止压缩包损坏或被篡改的完整性检查。使用这一选项之前，务必通过独立通道验证压缩包。

这些选项可以与 –no-interaction 组合，实现全自动运行：

sudo -u www-data php /var/www/nextcloud/updater/updater.phar \
    --url file:///tmp/nextcloud-33.0.0.zip \
    --signature "BASE64_SIGNATURE_HERE" \
    --no-interaction

使用网页更新器

网页更新器执行与命令行更新器相同的步骤和检查。

使用内置更新器更新 Nextcloud 安装，只需几个步骤：

有新更新可用时，你应能在任意 Nextcloud 页面的顶部看到通知。进入管理员设置页面，滚动到“Version”（版本）部分，其中有打开更新器的按钮。只有在应用管理中启用了更新通知应用，这一部分和更新通知才会出现。

点击“Open updater”（打开更新器）按钮。

核对显示的信息，点击“Start update”（开始更新）按钮启动更新。

如果发生错误或检查失败，更新器会停止并给出反馈。解决问题后，点击“Retry update”（重试更新）按钮。这会继续更新并重新执行失败的步骤，不会重复之前已经成功的步骤。

如果在更新完成之前关闭了更新器，可以重新打开更新器页面，从上一个成功的步骤继续。关闭网页不会中止正在执行的步骤，但也不会继续下一步，因为下一步需要由打开的更新器页面触发。

所有步骤执行完后，更新器会最后询问：“Keep maintenance mode active?”（是否保持维护模式？）。你可以选择通过网页升级页面或命令行升级过程（occ upgrade）继续。如果保持维护模式，必须具有命令行访问权限。

完成。现在可以继续进入网页升级页面，或运行 occ upgrade。下面“网页升级”和“命令行升级”两个示例展示后续屏幕的样子。

网页升级

网页升级会按下面的方式继续：

命令行升级

命令行升级会按下面的方式继续：

$ sudo -u www-data php ./occ upgrade
Nextcloud or one of the apps require upgrade - only a limited number of commands are available
You may use your browser or the occ upgrade command to do the upgrade
Set log level to debug
Updating database schema
Updated database
Updating <files_pdfviewer> ...
Updated <files_pdfviewer> to 1.1.1
Updating <gallery> ...
Updated <gallery> to 17.0.0
Updating <activity> ...
Updated <activity> to 2.5.2
Updating <comments> ...
Updated <comments> to 1.2.0
Updating <theming> ...
Updated <theming> to 1.3.0
Starting code integrity check...
Finished code integrity check
Update successful
Maintenance mode is kept active
Reset log level

故障排查

内置更新器会把所有操作记录到专用日志 updater.log 中，该文件位于你配置的 datadirectory 中，例如 /var/www/html/data/updater.log。它有助于定位失败的环节。如果到社区帮助论坛 https://help.nextcloud.com 求助，也需要提供这一日志。 [4]
如果使用网页模式的更新器遇到问题，且环境允许使用命令行，请尝试命令行模式。命令行可以避免网页服务器超时问题，因为更新器执行某些步骤时可能需要很长时间。
如果问题似乎出在备份步骤，可以尝试关闭更新器自动创建的安装文件备份。请记住，这些备份不包含你的数据，而你应当已经另行备份数据。只有命令行模式可以禁用备份步骤；在 updater.phar 命令后附加 –no-backup 选项即可。
如果命令行更新器询问是否运行 occ upgrade 时你误选了否，可以安全地手动执行 occ upgrade，或者访问实例的 URL，完成数据库迁移和应用升级阶段。
如需帮助，请访问社区帮助论坛：https://help.nextcloud.com。 [5]