Nextcloud aktualisieren: Updater, occ und Rollback-Plan

Ein Nextcloud Update scheitert selten am Code selbst. Es scheitert daran, dass eine App die neue Major-Version nicht unterstützt, dass PHP zu alt ist oder dass der Updater mitten im Schritt abbricht und die Instanz im Wartungsmodus stehen bleibt. Diese Anleitung zeigt dir den vollständigen Ablauf: Backup, Update über Web-Updater oder updater.phar, Abschluss mit occ upgrade und ein Rollback, das du vorher einmal durchgespielt hast.

Was macht ein Nextcloud Update genau?

Ein Nextcloud Update läuft in zwei Phasen: Der Updater ersetzt die Programmdateien unter /var/www/nextcloud, anschließend führt occ upgrade die Datenbank-Migrationen und die App-Updates aus. Erst nach der zweiten Phase ist die Instanz konsistent.

Daraus folgt die wichtigste Regel: Ein abgeschlossener Dateitausch ohne occ upgrade ist kein fertiges Update. Bricht der Vorgang zwischen beiden Phasen ab, findest du neuen Code auf einem alten Datenbankschema. Nextcloud fängt das über den Wartungsmodus ab und verweigert den Login, bis das Upgrade nachgeholt oder zurückgerollt wird.

Nextcloud erlaubt pro Upgrade nur einen Major-Sprung. Von Version 29 kommst du also nach 30, nicht direkt nach 31. Der Updater bietet die übernächste Version schlicht nicht an, ein manuell entpacktes Archiv würde dagegen mit einem Migrationsfehler abbrechen.

Voraussetzungen

• SSH-Zugriff mit sudo auf den Host, etwa eine skalierbare Cloud-VM mit Debian oder Ubuntu
• Eine laufende Nextcloud-Instanz ab Version 28 unter /var/www/nextcloud
• Die zur Zielversion passende PHP-Version (Nextcloud 30 und 31 setzen PHP 8.1 bis 8.3 voraus)
• Zugangsdaten zur Datenbank (MariaDB, MySQL oder PostgreSQL)
• Freier Speicherplatz in Höhe des Programmverzeichnisses plus Datenbank-Dump

Prüfe den Ausgangszustand, bevor du irgendetwas veränderst:

$ sudo -u www-data php /var/www/nextcloud/occ status
$ php -v
$ df -h /var/www /var/backups

Der Web-User heißt auf Debian und Ubuntu www-data, auf RHEL-Systemen apache. Alle occ-Aufrufe laufen unter diesem Konto, sonst gehören neu geschriebene Dateien anschließend root und der Webserver kann sie nicht mehr lesen.

Ablauf im Überblick

graph TD
    A["Backup: Code, Datenbank, config.php"] --> B{"Shell-Zugriff vorhanden?"}
    B -->|"Ja"| C["updater.phar auf der Kommandozeile"]
    B -->|"Nein"| D["Web-Updater in der Admin-Oberfläche"]
    C --> E["occ upgrade ausführen"]
    D --> E
    E --> F{"occ status sauber?"}
    F -->|"Ja"| G["Wartungsmodus aus, Apps prüfen"]
    F -->|"Nein"| H["Rollback: Code und Datenbank zurückspielen"]

Backup und Rollback-Punkt anlegen

Ein Rollback ist nur so gut wie das Backup, das dazugehört. Code-Verzeichnis und Datenbank müssen denselben Zeitpunkt abbilden, deshalb wird zuerst der Wartungsmodus aktiviert und erst danach gesichert.

$ cd /var/www/nextcloud
$ sudo -u www-data php occ maintenance:mode --on
$ sudo mkdir -p /var/backups/nc-$(date +%F)
$ sudo rsync -a --delete /var/www/nextcloud/ /var/backups/nc-$(date +%F)/code/
$ sudo mysqldump --single-transaction --default-character-set=utf8mb4 -u nextcloud -p nextcloud > /tmp/nextcloud-db.sql
$ sudo mv /tmp/nextcloud-db.sql /var/backups/nc-$(date +%F)/nextcloud-db.sql

Bei PostgreSQL nimmst du statt mysqldump den Befehl sudo -u postgres pg_dump nextcloud > /tmp/nextcloud-db.sql.

Das Datenverzeichnis (Standard: /var/www/nextcloud/data) sicherst du getrennt, weil es je nach Instanz mehrere hundert Gigabyte umfasst. Für den Rollback eines Updates ist es nicht zwingend erforderlich, denn ein Update verändert Nutzdateien nicht. Wichtig sind Programmverzeichnis, config/config.php und die Datenbank. Wenn dein Host Snapshots unterstützt, ziehe zusätzlich einen Snapshot der VM: Das ist der schnellste Rückweg, sofern die Instanz während des Fensters keine neuen Uploads annimmt.

Update mit dem Updater einspielen

Der integrierte Updater lädt das Zielarchiv, prüft die Signatur, legt eine eigene Sicherung unter data/updater-<instanceid>/backups/ ab und tauscht die Dateien aus. Er aktualisiert keine Datenbank.

Updater auf der Kommandozeile starten

Der CLI-Weg ist der stabilere. Er kennt kein max_execution_time des Webservers und zeigt jeden der elf Schritte einzeln an:

$ cd /var/www/nextcloud
$ sudo -u www-data php updater/updater.phar

Der Updater fragt zunächst Continue update? [y/N] und am Ende Should the "occ upgrade" command be executed? [Y/n]. Bestätige den zweiten Punkt mit Y, wenn du keinen eigenen Wartungsplan fährst. Anschließend fragt er, ob der Wartungsmodus aktiv bleiben soll. Lasse ihn aktiv, solange du die Verifikation noch nicht abgeschlossen hast.

Mit --no-backup überspringt der Updater seine interne Sicherung. Setze das Flag nur, wenn dein eigenes Backup steht und der Platz auf der Datenpartition knapp ist.

Alternative: Web-Updater

Ohne Shell-Zugriff startest du das Update unter Verwaltungseinstellungen → Übersicht über die Schaltfläche Update starten. Halte das Browser-Tab offen, bis alle Schritte durchgelaufen sind. Bei Instanzen mit vielen Apps läuft der Web-Updater häufiger in ein PHP-Timeout als die CLI-Variante. Ein Abbruch in Schritt 5 bis 8 ist reparabel, siehe Troubleshooting.

Welche Zielversion angeboten wird, steuert der Release-Kanal. stable ist die Vorgabe:

$ sudo -u www-data php occ config:system:get updater.release.channel
$ sudo -u www-data php occ config:system:set updater.release.channel --value stable

Update per occ abschließen

Hast du occ upgrade im Updater übersprungen oder das Archiv manuell entpackt, holst du die zweite Phase jetzt nach:

$ cd /var/www/nextcloud
$ sudo -u www-data php occ upgrade
$ sudo -u www-data php occ app:update --all

occ upgrade gibt jede Migration einzeln aus und endet mit Update successful. Läuft der Befehl über eine SSH-Sitzung, starte ihn in tmux oder screen: Große Instanzen brauchen für Migrationen an oc_filecache durchaus 20 Minuten und mehr, ein Verbindungsabbruch würde den Prozess mittendrin beenden.

Datenbank nachziehen

Neue Major-Versionen bringen regelmäßig zusätzliche Indizes mit, die aus Laufzeitgründen nicht automatisch angelegt werden. Die Admin-Oberfläche meldet sie später als Sicherheits- und Einrichtungswarnung:

$ sudo -u www-data php occ db:add-missing-indices
$ sudo -u www-data php occ db:add-missing-columns
$ sudo -u www-data php occ db:add-missing-primary-keys
$ sudo -u www-data php occ maintenance:repair --include-expensive

Diese Befehle schreiben direkt auf große Tabellen. Führe sie im Wartungsmodus aus, nicht im Live-Betrieb.

Anschließend beendest du den Wartungsmodus:

$ sudo -u www-data php occ maintenance:mode --off

Verifikation

Prüfe zuerst den Status. maintenance muss auf false stehen, needsDbUpgrade ebenfalls, und versionstring muss der Zielversion entsprechen:

$ sudo -u www-data php occ status
  - installed: true
  - version: 31.0.5.2
  - versionstring: 31.0.5
  - edition:
  - maintenance: false
  - needsDbUpgrade: false

Danach die Integrität der Programmdateien. Der Befehl gibt bei einer sauberen Installation nichts aus und liefert Exit-Code 0:

$ sudo -u www-data php occ integrity:check-core
$ echo $?
0

Zuletzt die Apps: Nextcloud deaktiviert bei einem Major-Upgrade jede App, die die neue Version nicht als kompatibel deklariert. Vergleiche die Liste mit dem Stand vor dem Update:

$ sudo -u www-data php occ app:list --shipped false
$ sudo -u www-data php occ app:enable <app-id>

Ein Blick ins Log fängt Fehler ab, die die Oberfläche nicht zeigt. Die Logdatei liegt standardmäßig unter /var/www/nextcloud/data/nextcloud.log, ein Eintrag pro Zeile im JSON-Format. Wer solche Läufe dauerhaft auswerten will, leitet das Log an einen zentralen Collector weiter statt es nur lokal zu rotieren.

Wie rollst du ein fehlgeschlagenes Nextcloud Update zurück?

Ein Rollback besteht aus drei Schritten: das alte Programmverzeichnis zurückspielen, den Datenbank-Dump derselben Sicherung einlesen und danach den Wartungsmodus deaktivieren. Code und Datenbank müssen zwingend aus demselben Backup stammen.

$ sudo -u www-data php occ maintenance:mode --on
$ sudo mv /var/www/nextcloud /var/www/nextcloud.failed
$ sudo rsync -a /var/backups/nc-2026-08-17/code/ /var/www/nextcloud/
$ sudo chown -R www-data:www-data /var/www/nextcloud
$ sudo mysql -u nextcloud -p nextcloud < /var/backups/nc-2026-08-17/nextcloud-db.sql
$ sudo -u www-data php /var/www/nextcloud/occ maintenance:mode --off

Beim Einlesen des Dumps überschreibst du die bestehenden Tabellen. Wenn der Dump kein DROP TABLE enthält, leere die Datenbank vorher mit DROP DATABASE nextcloud; CREATE DATABASE nextcloud; und den ursprünglichen Zeichensatz-Optionen.

Sind zwischen Backup und Rollback bereits Dateien hochgeladen worden, kennt die zurückgespielte Datenbank diese Dateien nicht. Der folgende Befehl liest das Datenverzeichnis neu ein und trägt sie nach:

$ sudo -u www-data php occ files:scan --all

Der Updater legt zusätzlich eine eigene Kopie unter /var/www/nextcloud/data/updater-<instanceid>/backups/nextcloud-<version>/ ab. Sie enthält Code und config.php, aber keine Datenbank. Als alleinige Rollback-Grundlage reicht sie deshalb nicht.

Troubleshooting

Der Updater bricht ab und startet nicht neu. Er merkt sich den letzten Schritt in einer Statusdatei. Lösche sie und starte den Lauf erneut:

$ sudo rm -f /var/www/nextcloud/data/updater-*/.step
$ sudo -u www-data php /var/www/nextcloud/updater/updater.phar

Die Instanz bleibt im Wartungsmodus. Wenn occ selbst nicht mehr startet, setzt du den Wert direkt in /var/www/nextcloud/config/config.php auf 'maintenance' => false, und rufst danach occ status auf. Meldet der Status needsDbUpgrade: true, fehlt noch occ upgrade. Den Wartungsmodus davor wieder zu deaktivieren, öffnet eine Instanz mit halb migrierter Datenbank für Nutzer.

Eine App blockiert das Upgrade. Deaktiviere sie vor dem nächsten Versuch und aktiviere sie nach dem Upgrade wieder:

$ sudo -u www-data php occ app:disable <app-id>

PHP passt nicht zur Zielversion. Prüfe vor dem Update mit php -v und der Kompatibilitätsmatrix der Zielversion. Eine zu neue PHP-Version ist genauso ein Blocker wie eine zu alte, weil Nextcloud die unterstützte Spanne hart abfragt.

Fazit

Der verlässliche Ablauf für ein Nextcloud Update ist immer derselbe: Wartungsmodus an, Code und Datenbank im selben Moment sichern, updater.phar auf der Kommandozeile laufen lassen, mit occ upgrade abschließen und über occ status sowie occ integrity:check-core verifizieren. Plane pro Major-Version einen eigenen Durchlauf und teste den Rollback einmal auf einer Kopie der Instanz, bevor du ihn im Ernstfall brauchst.

Weiterlesen

• Nextcloud All-in-One mit Docker installieren
• Nextcloud auf Ubuntu 24.04 mit nginx installieren
• Nextcloud sichern und wiederherstellen: Daten, Datenbank, Config
• Nextcloud mit Docker Compose betreiben
• Nextcloud Office einrichten: Collabora oder OnlyOffice
• Nextcloud, ownCloud oder Seafile: Welche Lösung wofür?
• Nextcloud per WebDAV einbinden: Linux, Windows, macOS
• Welcher Server für Nextcloud? RAM, CPU und Storage dimensionieren
• Was ist Nextcloud? Funktionsweise, Komponenten und Einsatz