Nextcloud-Migration: Der Weg aus der Daten-Bruchbude

Die eigene Nextcloud-Instanz ist gewachsen, oft organisch, manchmal ungestüm. Irgendwann stößt die alte Infrastruktur an Grenzen. Dann steht eine Migration an – ein kritischer Akt, der mehr ist als simples Kopieren. Ein Überblick über Strategien, Fallstricke und bewährte Praktiken.

Man stelle sich vor, man müsste eine komplette Bibliothek umziehen, in der nicht nur jedes Buch, sondern auch jede Notiz, jeder Lesezeichen und jeder ausgeliehene Titel penibel dokumentiert ist. Dieses Szenario kommt einer Nextcloud-Migration erstaunlich nahe. Es geht nicht nur um die Nutzerdateien in /data. Die eigentliche Komplexität liegt im Zusammenspiel von Dateisystem, Datenbank, Konfiguration, App-Daten und Cache-Schichten. Eine unbedachte Aktion kann hier zu inkonsistenten Zuständen, kaputten Dateiverknüpfungen oder im schlimmsten Fall zu Datenverlust führen.

Die Gründe für einen Umzug sind vielfältig: Die Performance der alten Festplatten lässt nach, ein Wechsel des Hosters steht an, oder man konsolidiert mehrere Instanzen. Vielleicht soll die Nextcloud auch aus einer virtuellen Maschine in einen Kubernetes-Cluster wandern, um skalierbarer zu werden. Dabei zeigt sich schnell, dass es den einen goldenen Migrationspfad nicht gibt. Der optimale Weg hängt massiv von der Größe der Instanz, der verfügbaren Downtime und der Ziel-Infrastruktur ab.

Die Grundlagen: Was wandert eigentlich alles?

Bevor man den ersten Befehl tippt, muss klar sein, welche Bestandteile überhaupt bewegt werden müssen. Eine Nextcloud-Installation besteht aus mehreren, lose gekoppelten Komponenten. Der erste und offensichtlichste Teil ist das Datenverzeichnis, standardmäßig /var/www/nextcloud/data oder ein anderer Pfad, der in der Konfiguration hinterlegt ist. Hier liegen alle hochgeladenen Dateien der Nutzer, oft in einer durch Hashwerte verschlüsselten Struktur.

Dann gibt es den Quellcode der Nextcloud-App selbst sowie aller zusätzlich installierten Apps. Dieser liegt im Webroot, etwa /var/www/nextcloud/. Wichtig: Diese beiden Teile – Daten und Code – sind strikt getrennt. Eine reine Code-Aktualisierung berührt die Nutzerdaten normalerweise nicht.

Das Herzstück ist die Datenbank. Ob MySQL, MariaDB, PostgreSQL oder SQLite, hier werden alle Metadaten gespeichert: Benutzerkonten, Gruppenzugehörigkeiten, Datei- und Ordnerpfade, Freigabelinks, Aktivitätsprotokolle, Kalender, Kontakte und die Konfiguration der meisten Apps. Die Datenbank ist der zentrale Index für alle Dateien. Sie enthält die Landkarte, die auf die physischen Dateiblöcke im Datenverzeichnis verweist. Ohne sie sind die Dateien nutzlos.

Zuletzt gibt es noch die Konfigurationsdatei config/config.php. Sie enthält kritische Pfade, Datenbank-Zugangsdaten und spezifische Einstellungen. Zudem generiert Nextcloud laufend Cache-Dateien und Sitzungsdaten, die bei einer Migration meist verworfen werden können.

Strategie 1: Der klassische „Stopp-und-Kopier“-Ansatz

Für kleinere bis mittlere Instanzen mit tolerierbarer Downtime ist die direkte Methode oft die robusteste. Das Prinzip ist simpel: Die alte Instanz wird in einen schreibgeschützten Zustand versetzt, alle Komponenten werden gesichert und auf das neue System kopiert, dort werden sie eingerichtet und die Instanz wird neu gestartet.

Der erste Schritt ist das Setzen des Wartungsmodus. Das verhindert, dass während des Kopiervorgangs neue Daten geschrieben oder bestehende verändert werden. Ein einfacher occ maintenance:mode --on über die Kommandozeile genügt. Nun wird die Datenbank exportiert. Mit Tools wie mysqldump oder pg_dump erstellt man ein vollständiges SQL-Dump. Dabei sollte man auf Konsistenz achten – die Option --single-transaction für MySQL/MariaDB ist hier ein guter Freund.

Parallel dazu beginnt der Transfer der Dateien. Das Arbeitstier hierfür ist seit Jahrzehnten rsync. Ein Befehl wie rsync -avz --progress /pfad/zu/alten/data/ nutzer@neuer-server:/pfad/zu/neuen/data/ überträgt die Daten effizient und lässt sich bei Unterbrechungen fortsetzen. Der Webroot mit dem Code wird ebenfalls per rsync übertragen. Auf dem Zielsystem müssen dann die Datenbank importiert und die config.php angepasst werden – vor allem die Pfade und Datenbank-Zugangsdaten. Ein occ maintenance:mode --off beendet den Umzug.

Der Vorteil dieser Methode ist ihre Übersichtlichkeit und hohe Erfolgsquote. Der Nachteil liegt auf der Hand: Die Downtime entspricht der Kopierdauer der Nutzerdaten. Bei Terabyte an Daten kann das Stunden oder sogar Tage dauern. Für viele produktive Umgebungen ist das nicht akzeptabel.

Strategie 2: Live-Migration mit minimaler Ausfallzeit

Wenn der Dienst nur für ein kurzes Fenster, vielleicht nur wenige Minuten, unterbrochen werden darf, muss man trickreicher vorgehen. Das Ziel ist ein inkrementeller Transfer. Man kopiert zunächst einen Großteil der Daten bei laufendem System, stoppt dann kurz für einen finalen Abgleich und schaltet um.

Hierfür kann man rsync mehrfach einsetzen. Beim ersten Lauf überträgt man den kompletten Datenbestand. Da Nextcloud währenddessen aktiv ist, werden auf der Quelle während des Kopierens bereits wieder Dateien geändert oder neu angelegt. Deshalb folgen ein oder mehrere weitere rsync-Läufe, die nur die Differenzen (die *delta*) übertragen. So schrumpft die Datenmenge für den finalen, blockierenden Sync dramatisch.

Für die Datenbank bietet sich ein ähnliches Vorgehen mit Master-Slave-Replikation an. Man richtet die neue Datenbank als Slave der alten ein. Sie repliziert dann kontinuierlich alle Änderungen. Zum Migrationszeitpunkt wird der Slave vom Master getrennt und zur neuen primären Datenbank befördert. Das erfordert natürlich tiefere Kenntnisse in der Datenbankadministration.

Ein interessanter Aspekt ist die Behandlung externen Speichers. Wenn die Nextcloud mit External Storage oder S3 Object Storage verbunden ist, ändert sich der Migrationsaufwand fundamental. Die eigentlichen Dateien liegen dann nicht im lokalen Datenverzeichnis, sondern auf einem separaten Speichersystem wie einem S3-kompatiblen Dienst. In diesem Fall muss oft nur die Datenbank mit den Metadaten migriert werden, sowie die Konfiguration für den externen Speicher angepasst werden. Die Dateien selbst bleiben, wo sie sind. Das vereinfacht den Vorgang erheblich.

Der Sonderfall: Upgrade und Migration in einem Schritt

Häufig ist der Umzug auf neue Hardware mit einem größeren Versionssprung der Nextcloud-Software verbunden. Das ist eine typische Stolperfalle. Die goldene Regel lautet: *Migration und Major-Upgrade niemals kombinieren.*

Man sollte zuerst die Migration auf der *alten* Nextcloud-Version durchführen. Auf dem neuen System läuft also exakt die gleiche Version wie auf dem alten. Erst wenn diese migrierte Instanz stabil läuft, führt man das Upgrade auf dem neuen Server durch. So hat man im Fehlerfall klar isoliert, ob das Problem beim Umzug der Daten oder beim Aktualisieren der Software lag. Das occ upgrade-Kommandos sollte auf dem frisch migrierten System laufen, nachdem alle Dateien und die Datenbank sicher übertragen wurden.

Nicht zuletzt deswegen ist eine vollständige Backup-Strategie vor Start der Arbeiten unabdingbar. Ein Backup der Datenbank, des Datenverzeichnisses und der Konfiguration muss auf einem unabhängigen System liegen. Das gibt die Sicherheit, im Fall der Fälle einen definierten Rücksetzpunkt zu haben.

Die Krux mit den Datei-IDs und Storage-Layern

Nextcloud verwaltet Dateien intern nicht nur über Pfade, sondern über numerische fileids. Diese IDs sind der primäre Schlüssel in der Datenbank. Bei einer Migration müssen die physischen Dateien im Datenverzeichnis genau zu diesen IDs passen. Wird die Struktur manuell verändert oder gehen Dateien verloren, bricht die Referenzierung ab. Die Folge sind Fehler wie „Datei nicht gefunden“ in der Oberfläche, obwohl die Datei physisch existiert.

Das Tool der Wahl, um dies zu reparieren, ist der occ files:scan --all-Befehl. Er durchsucht das gesamte Datenverzeichnis und baut die Indizes in der Datenbank neu auf. Bei großen Instanzen ist dieser Vorgang sehr ressourcenintensiv und kann Stunden dauern. Er sollte aber nach jeder Migration durchgeführt werden, um Konsistenz zu gewährleisten.

Eine weitere Ebene der Komplexität bringen verschlüsselte Installationen. Bei aktivierter Server-side Encryption oder gar End-to-End-Encryption (E2EE) wird der Migrationsvorgang kritischer. Die verschlüsselten Dateien sind ohne die entsprechenden Keys unbrauchbar. Bei Server-side Encryption muss der Master-Key sicher mit migriert werden. Bei E2EE liegen die Schlüssel bei den Clients; hier muss sichergestellt sein, dass die Nutzer nach der Migration ihre Clients neu mit dem Server synchronisieren können, ohne Daten zu verlieren. Ein Backup der config/encryption.config.php und der Keys aus dem data/-Verzeichnis ist hier überlebenswichtig.

Von der On-Premise-Welt in die Cloud

Ein immer häufigeres Szenario ist die Migration einer lokalen Nextcloud-Instanz zu einem Cloud-Hoster oder in ein eigenes Rechenzentrum. Dabei ändern sich oft die Netzwerkparameter. Die neue Instanz hat eine andere öffentliche IP-Adresse oder Domain. Das erfordert Anpassungen an der Konfiguration, vor allem aber am Trusted Domains-Eintrag in der config.php. Sonst weigert sich Nextcloud, Anfragen der neuen Adresse zu bedienen.

Zudem können sich Performance-Charakteristika ändern. Ein Cloud-Speicher (Block Storage) kann andere I/O-Latenzen aufweisen als die alte lokale Festplatte. Das kann die Geschwindigkeit von Dateioperationen beeinflussen. Es kann sinnvoll sein, nach der Migration die Performance mit realistischen Lasttests zu überprüfen und Parameter wie PHP-Speicherlimit oder Datenbank-Connection-Pooling anzupassen.

Ein oft übersehener Punkt sind geplante Cron-Jobs. Auf dem alten System läuft vielleicht ein Cron-Job für occ cron oder für regelmäßige Backups. Diese Aufgaben müssen auf dem neuen System neu eingerichtet werden. Sonst fallen Hintergrundaufgaben wie die Erstellung von Vorschaubildern oder die Bereinigung der Datenbank aus.

Praktische Checkliste für eine reibungslose Migration

1. **Vorbereitung ist alles:** Dokumentiere die komplette alte Umgebung – Pfade, Datenbankversion, PHP-Version, installierte Apps mit Versionsnummern. Erstelle vollständige Backups und teste die Wiederherstellung aus diesen Backups in einer isolierten Testumgebung.

2. **Testumgebung aufbauen:** Spiele die Migration zuerst in einer nicht-produktiven Umgebung durch. Das gibt Sicherheit und offenbart mögliche Abhängigkeiten.

3. **Kommunikation:** Informiere die Nutzer rechtzeitig über den geplanten Wartungszeitraum. Setze realistische Erwartungen.

4. **Wartungsmodus aktivieren:** Keine Migration ohne occ maintenance:mode --on. Das ist das Schloss an der Tür.

5. **Reihenfolge beachten:** Datenbank exportieren, dann Dateien übertragen. Oder bei Live-Migrationen: Erst inkrementelle Dateien, dann finalen DB-Sync.

6. **Konfiguration anpassen:** Die config.php auf dem neuen System muss alle Pfade, Hostnamen und Zugangsdaten korrekt widerspiegeln. Besonderes Augenmerk auf `datadirectory`, `db-*` Einträge und `trusted_domains`.

7. **Berechtigungen prüfen:** Nextcloud läuft meist unter einem bestimmten Nutzer (www-data, nginx, apache). Stellen Sie sicher, dass dieser Nutzer Lese- und Schreibrechte auf das gesamte Datenverzeichnis und den Webroot hat. Ein klassischer Befehl hierfür ist occ maintenance:repair.

8. **Filescan durchführen:** Nach dem ersten Start den occ files:scan --all laufen lassen, um die Datenbank mit dem Dateisystem zu synchronisieren.

9. **Funktionstest:** Nach dem Abschalten des Wartungsmodus systematisch testen: Datei-Upload/Download, Freigaben, App-spezifische Funktionen (Kalender, Kontakte, Talk).

10. **Altes System warmhalten:** Schalte die alte Instanz nicht sofort ab. Lasse sie für einige Tage im Wartungsmodus oder mit read-only Zugriff laufen. Das gibt ein Sicherheitsnetz für den Fall, dass doch eine übersehene Datei oder Konfiguration benötigt wird.

Wenn es schiefgeht: Typische Probleme und ihre Lösung

Trotz bester Vorbereitung kann es zu Problemen kommen. Ein häufiges Symptom sind weiße Seiten oder 500-Fehler direkt nach dem Umzug. Hier ist der PHP-Error-Log der erste Anlaufpunkt. Oft liegt die Ursache in falschen Pfaden in der Konfiguration oder in fehlenden PHP-Modulen auf dem neuen System (z.B. `redis`, `apcu`, oder das passende Datenbank-Modul).

Ein anderes Problem sind fehlende Dateien nach dem Scan. Das kann passieren, wenn rsync mit falschen Optionen lief und symbolische Links oder Berechtigungen nicht korrekt übernommen hat. Ein erneuter rsync-Lauf mit den Optionen `-a` (archive, bewahrt u.a. Rechte und Links) und `-X` (bewahrt ACLs) kann Abhilfe schaffen.

Datenbank-Fehler deuten oft auf eine inkompatible Version oder fehlgeschlagene Zeichenkodierung hin. Ein Blick in den Export- und Import-Log der Datenbank ist hier essenziell. Manchmal helfen die integrierten Reparatur-Kommandos von Nextcloud: occ maintenance:repair kann Tabellen reparieren, und occ db:add-missing-indices sowie occ db:add-missing-columns bringen die Schema-Struktur auf den neuesten Stand.

Letztlich ist eine Nextcloud-Migration ein handwerklicher Akt. Sie profitiert von systematischem Vorgehen, einem gesunden Respekt vor der Komplexität der Daten und dem Mut, in einer Testumgebung auch mal etwas kaputt machen zu dürfen. Die Belohnung ist eine moderne, performante und stabile Infrastruktur, die wieder Luft zum Wachstum bietet. Mit den richtigen Werkzeugen und der nötigen Geduld ist der Umzug keine Hexerei, sondern ein planbares IT-Projekt. Es lohnt sich, die Zeit in die Planung zu investieren – der reibungslose Betrieb danach ist der beste Lohn.