(v3.5.13-Migration) Migration des vollständigen Projektverlaufs

​

Migration des vollständigen Projektverlaufs

Das Release 3.5.x der Community Edition enthält die Funktion Full Project History, die in unserem SaaS-Angebot overleaf.com bereits verfügbar ist

Nach dem Upgrade Ihrer Instanz auf Overleaf CE 3.5.13 verwenden alle neuen Projekte standardmäßig Full Project History. Bestehende Projekte nutzen weiterhin das alte Verlaufssystem, bis sie migriert werden.

Wenn Sie auf 3.5.13 upgraden und sich anschließend für ein Downgrade auf eine frühere Version entscheiden, sollten Sie ein vollständiges System-Backup wiederherstellen. Der Verlauf von in 3.5.13 erstellten Projekten ist nicht mit früheren Versionen von Overleaf CE kompatibel.

Der neue vollständige Projektverlauf bringt für Benutzer mehrere Verbesserungen:

• Er verfolgt Änderungen an Binärdateien, was im alten System nicht unterstützt wird.
• Benannte Versionen (Labels) werden unterstützt.
• Das System ist insgesamt robuster, und das Risiko von Datenverlust ist geringer.

Weitere Informationen zum vollständigen Projektverlauf finden Sie in der Dokumentation zu Full Project History.

​

Bestehende Projekte migrieren

1. Backup erstellen

   Erstellen Sie ein vollständiges Backup Ihrer Instanz mit einem konsistenten Snapshot der Verzeichnisse mongo, redis und sharelatex.

2. Aktualisieren

   Aktualisieren Sie die Version des Images sharelatex/sharelatex auf 3.5.13.

   Toolkit: Verwenden Sie das Skript $ bin/upgrade, um das Toolkit auf die neueste Version zu aktualisieren, und setzen Sie config/version auf 3.5.13.

3. Instanz starten

   Idealerweise sollten Sie verhindern, dass Benutzer während der Migration auf Ihre Instanz zugreifen, um Datenverlust zu vermeiden, falls Sie Ihr Backup wiederherstellen müssen. Weitere Informationen dazu finden Sie unter Offline-Migration.

4. Warten, bis alle Dienste laufen

   Warten Sie, bis alle Dienste gestartet sind und laufen (siehe Befehl unten)

   $ bin/docker-compose exec sharelatex /bin/bash -c "curl http://localhost:3000/status"
   web sharelatex is alive (api)%
   
5. Migrationsskript ausführen

   # Overleaf Toolkit users:
   $ bin/docker-compose exec sharelatex /bin/bash -c "cd /overleaf/services/web; VERBOSE_LOGGING=true node scripts/history/migrate_history.js --force-clean --fix-invalid-characters --convert-large-docs-to-file"
   
   # legacy docker-compose.yml users:
   $ docker exec sharelatex /bin/bash -c "cd /overleaf/services/web; VERBOSE_LOGGING=true node scripts/history/migrate_history.js --force-clean --fix-invalid-characters --convert-large-docs-to-file"
   

   --force-clean entfernt teilweise migrierte Projektverlaufsdaten im neuen System; dadurch kann die Migration für einzelne Projekte, die bei früheren Versuchen fehlgeschlagen sind, erneut versucht werden;

   --fix-invalid-characters ersetzt nicht druckbare Zeichen, die vom neuen Verlaufssystem nicht unterstützt werden;

   --convert-large-docs-to-file wandelt Dokumente, die den Schwellenwert von 2 MB für bearbeitbare Dateien überschreiten, in eine nicht bearbeitbare Datei um)

   Die Ausgabe sollte etwa so aussehen:

   Migrated Projects  :  1
   Total Projects     :  51
   Remaining Projects :  51
   Total history records to migrate: 98
   Starting migration...
   Migrating project: 63d29b5772dd80015a81bffe
   migration result { upgraded: true, historyType: 'NoneWithoutConversion' }
   Migrating project: 63d29c2e72dd80015a81c0a2
   migration result { upgraded: true, historyType: 'NoneWithoutConversion' }
   
   // …
   
   Migration complete
   ==================
   Projects migrated:  51
   Projects failed:  0
   Done.
   

   Ist die Migration erfolgreich, erhalten Sie den Exit-Code 0, und die letzten Zeilen zeigen an, dass keine Fehler aufgetreten sind:

   Projects failed:  0
   Done.
   

   Sie können den Zugriff für Ihre Benutzer wieder freigeben (siehe nächster Schritt). Treten Fehler auf, lesen Sie den Abschnitt zur Fehlerbehebung weiter unten. Sie können die Website auch dann wieder öffnen, wenn die Probleme nicht sofort behoben werden; die nicht migrierten Projekte verbleiben dann im alten Verlaufssystem.

6. Website wieder öffnen

   Wenn Sie sich für eine Offline-Migration entschieden haben, müssen Sie die Website wieder öffnen. Wenn Sie noch angemeldet sind, gehen Sie wie folgt vor:

   1. Klicken Sie auf die Schaltfläche Admin und wählen Sie Manage Site
   2. Klicken Sie auf den Tab Open/Close Editor
   3. Klicken Sie auf die Schaltfläche Reopen Editor

   Wenn Sie Ihren Browser geschlossen haben, müssen Sie die Website mit $ bin/up neu starten.

​

Offline-Migration

Um zu verhindern, dass sich Benutzer anmelden können, während das Skript zur Verlaufsmigration läuft, gehen Sie wie folgt vor:

• Melden Sie sich mit einem Administratorkonto bei Ihrer Overleaf-Instanz an
• Klicken Sie auf die Schaltfläche Admin und wählen Sie Manage Site
• Klicken Sie auf den Tab Open/Close Editor
• Klicken Sie auf die Schaltfläche Close Editor
• Klicken Sie auf die Schaltfläche Disconnect all users

Danach werden angemeldete Benutzer auf die Wartungsseite umgeleitet, und neue Benutzer, die die Anmeldeseite aufrufen, sehen die Wartungsseite und können sich nicht anmelden.

​

Online-Migration

Es ist möglich, die Migrationsskripte auszuführen, während die Anwendung weiterläuft. Dabei gibt es einige Punkte zu beachten:

• Der Migrationsprozess ist CPU-intensiv; Sie sollten die Ressourcennutzung überwachen, während das Skript läuft.
• Bei einem hohen --concurrency-Wert kann die Event-Loop in einigen Diensten (insbesondere track-changes) blockiert werden, was zu einer schlechteren Benutzererfahrung führt. Wir empfehlen, mit dem Standardwert --concurrency=1 zu beginnen.
• Sie können das Skript jederzeit stoppen. Ein erneuter Start setzt die Migration an der Stelle fort, an der sie unterbrochen wurde. Das ist nützlich, wenn Sie die Migration lieber zu weniger ausgelasteten Zeiten (z. B. nachts) ausführen möchten.

Wir empfehlen, die Website zu schließen und die Migration offline in einem Wartungsfenster durchzuführen, wenn Sie weniger als 1000 Projekte haben (db.projects.count()). Bei einer großen Anzahl von Projekten können Sie das Skript ausführen, den Fortschritt beobachten und dann je nach Ihrer Situation entscheiden, ob Sie es online oder offline weiterlaufen lassen.

​

Alte Verlaufsdaten bereinigen

Ein Skript zur Bereinigung alter Verlaufsdaten wurde in Server Pro 3.5.6, 4.0.6 und 4.1.0 hinzugefügt.

bin/docker-compose exec sharelatex /bin/bash -c "cd /overleaf/services/web; node scripts/history/clean_sl_history_data.js"

Das Skript kann ausgeführt werden, nachdem alle Projekte migriert wurden. Es kann auch verwendet werden, um während einer Online-Migration Speicherplatz freizugeben.

In Server Pro vor Version 3.5.13 löscht das Skript den Inhalt der Collections docHistory und docHistoryIndex. MongoDB gibt nach dem Löschen von Dokumenten keinen Speicherplatz frei, sondern verwendet diesen Platz für zukünftige Dokumente in derselben Collection wieder. Nach der Verlaufsmigration wird nichts mehr in diese Collections geschrieben, sodass der Speicherplatz ungenutzt bleibt.

Wenn Sie den Speicherplatz wieder verfügbar machen möchten, können Sie auf Server Pro 3.5.13 (wenn Sie noch das 3.x-Release verwenden) oder Server Pro 4.2.5 (wenn Sie das 4.x-Release verwenden) upgraden und das Bereinigungsskript erneut ausführen.

Das in den neuesten Patch-Releases von 3.5.x und den neuesten 4.x.x-Versionen von Server Pro enthaltene Bereinigungsskript löscht die Collections als letzten Schritt.

Das Bereinigungsskript kann gefahrlos erneut ausgeführt werden.

​

Fehlerbehebung

Wir werden hier Hinweise zur Fehlerbehebung ergänzen. Bitte beachten Sie: Obwohl wir normalerweise nur Server Pro-Kunden Support anbieten, werden wir aufgrund der Art dieser Migration auch CE-Nutzer nach besten Kräften unterstützen, die Probleme speziell mit der Migration des vollständigen Projektverlaufs haben.

Wenn das Skript zur Migration des vollständigen Projektverlaufs fehlschlägt (d. h. mit einem Fehler beendet wird oder eine von null verschiedene Anzahl fehlgeschlagener Projekte ausgibt), senden Sie bitte die folgenden Angaben per E-Mail an unser Support-Team [e-mail]:

Betreff: Full project history migration problem

• Instanztyp: CE oder Server Pro (Nichtzutreffendes streichen)
• Installationstyp: Overleaf Toolkit, docker-compose.yml oder andere (Nichtzutreffendes streichen)
• Version: 3.5.x (Toolkit: $ cat config/version)
• Ausgabe des Migrationsskripts (sollte sich im Container unter /overleaf/services/web befinden)
• Migrierte Projekte: (laut Ausgabe des Migrationsskripts)
• Projekte insgesamt: (laut Ausgabe des Migrationsskripts)
• Verbleibende Projekte: (laut Ausgabe des Migrationsskripts)
• Dauer der Migration:
• Ausgabe von bin/doctor (bei Verwendung des Toolkits)
• Toolkit-Version: $ git rev-parse HEAD (bei Verwendung des Toolkits)

Erwägen Sie, der E-Mail die Logdateien der Dienste history-v1, project-history und track-changes beizufügen. Sie finden diese unter /var/log/sharelatex im Container sharelatex und können sie wie folgt exportieren:

$ docker cp sharelatex:/var/log/sharelatex/history-v1.log history-v1.log
$ docker cp sharelatex:/var/log/sharelatex/project-history.log project-history.log
$ docker cp sharelatex:/var/log/sharelatex/track-changes.log track-changes.log

Bitte entfernen Sie alle sensiblen Informationen aus den Logdateien, bevor Sie sie anhängen.

​

Fehlerhafte Dateibäume finden

Die Migration kann bei Projekten mit einem fehlerhaften Dateibaum fehlschlagen (z. B. wenn Dateinamen leer sind). Eine Liste dieser Probleme erhalten Sie mit dem Skript find_malformed_filetrees, das alle Projekte in der Datenbank überprüft:

$ bin/docker-compose exec sharelatex /bin/bash -c "cd /overleaf/services/web; node scripts/find_malformed_filetrees.js"
BAD PATH: 123456789012345678901234 rootFolder.0.1.2.3
BAD PATH: 123456789012345678901234 rootFolder.0.4.5.6
...

Um die ungültigen Pfade zu korrigieren, verwenden Sie das Skript fix_malformed_filetree und führen den Befehl für jeden fehlerhaften Pfad einmal aus:

$ bin/docker-compose exec sharelatex /bin/bash -c "cd /overleaf/services/web; node scripts/fix_malformed_filetree.js 123456789012345678901234 rootFolder.0.1.2.3"
$ bin/docker-compose exec sharelatex /bin/bash -c "cd /overleaf/services/web; node scripts/fix_malformed_filetree.js 123456789012345678901234 rootFolder.0.4.5.6"
...

​

Projekte vom vollständigen Projektverlauf auf den alten Verlauf zurückstufen

Wenn ein Projekt bereits auf den vollständigen Projektverlauf migriert wurde, Sie aber zum alten Verlauf zurückkehren möchten, verwenden Sie das Skript downgrade_project wie folgt:

$ bin/docker-compose exec sharelatex /bin/bash -c "cd /overleaf/services/web; PROJECT_ID=YOUR