> For the complete documentation index, see [llms.txt](https://ayakaleaf-pro.ayaka.space/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ayakaleaf-pro.ayaka.space/on-premises/de/support/support-guides/v5.5.7-migration-binary-files-migration.md). # (Migration v5.5.7) Migration von Binärdateien ## Migration von Binärdateien Die bevorstehende Hauptversion `6.0` Die Veröffentlichung von Server Pro und Community Edition wird den Speicherbedarf von Binärdateien halbieren. Eine Online-Migration ist in Version enthalten `5.5.7` , was als Teil des Upgrades minimale Ausfallzeiten ermöglicht. Seit Server Pro `4.x`, werden Binärdateien zweimal gespeichert: im aktiven Dateispeicher im „filestore“ und im vollständigen Projektverlaufsystem. Künftig wird von jeder Datei nur noch eine Kopie im vollständigen Projektverlaufsystem gespeichert. Die Migration zum konsolidierten Speichersystem besteht aus zwei Teilen: einem neuen Flag zur Steuerung der Migrationsphase und einem Skript, das alle aktiven und weich gelöschten Projekte verarbeitet. Phasen: * `OVERLEAF_FILESTORE_MIGRATION_LEVEL=0` (Standard), Dateien werden aus dem filestore gelesen und dort geschrieben. Dateien werden asynchron in den Verlauf geschrieben. * `OVERLEAF_FILESTORE_MIGRATION_LEVEL=1` , Dateien werden aus dem Verlauf mit Fallback auf den filestore gelesen und sowohl in den filestore als auch in den Verlauf geschrieben. Ein Downgrade auf `OVERLEAF_FILESTORE_MIGRATION_LEVEL=0` ist möglich. * `OVERLEAF_FILESTORE_MIGRATION_LEVEL=2` Dateien werden nur aus dem Verlauf gelesen und dorthin geschrieben. Ein Downgrade auf `OVERLEAF_FILESTORE_MIGRATION_LEVEL=1` ist nicht möglich, es sei denn, es wurde „offline“ durchgeführt. Beim Speichern von Daten in [S3](https://docs.overleaf.com/on-premises/configuration/overleaf-toolkit/s3) und bei der Verwendung getrennter Dienstkonten für den filestore (`OVERLEAF_FILESTORE_S3_ACCESS_KEY_ID`) und den Verlauf (`OVERLEAF_HISTORY_S3_ACCESS_KEY_ID`): Bitte gewähren Sie dem filestore-Benutzer Lesezugriff auf den Verlauf-Bucket für Blobs `OVERLEAF_HISTORY_PROJECT_BLOBS_BUCKET` . Der filestore-Dienst wird künftig Lesezugriffe vom Compiler-Dienst bedienen. {% hint style="warning" %} Es wird dringend empfohlen, die Migration von Binärdateien zunächst in einer Nicht-Produktions-/Sandbox-Umgebung durchzuführen. {% endhint %} {% hint style="success" %} Die Standardlizenz von Server Pro erlaubt den Betrieb der Anwendung in einer Produktionsumgebung sowie in einer Nicht-Produktions-/Sandbox-Umgebung; es wird dringend empfohlen, eine Nicht-Produktionsumgebung zum Testen bereitzustellen. {% endhint %} {% hint style="info" %} Wenn Sie auf Server Pro/CE Version `6.0` aktualisieren und später entscheiden, dass Sie auf eine frühere Version zurückstufen möchten, sollten Sie aus einem vollständigen System-Backup wiederherstellen. {% endhint %} ### Migrationsverfahren {% stepper %} {% step %} #### Erstellen Sie ein Backup Erstellen Sie ein vollständiges [Backup](https://docs.overleaf.com/on-premises/maintenance/data-and-backups#performing-a-consistent-backup) Ihrer Instanz mit einem konsistenten Snapshot der **mongo**, **redis** und **sharelatex** Verzeichnisse. {% endstep %} {% step %} #### Aktualisieren Sie **Toolkit:** Verwenden Sie den `$ bin/upgrade` Skript zum Aktualisieren des **Toolkits** Wenn Sie dazu aufgefordert werden, nicht **nicht** die Eingabeaufforderung bestätigen **Aktualisieren** image? — stattdessen manuell bearbeiten **config/version** Datei und setzen Sie den Wert auf `5.5.7`. **Alte docker-compose.yml:** Aktualisieren Sie die Version des `sharelatex` Dienst auf `5.5.7`. {% endstep %} {% step %} #### Schätzen Sie die Anzahl der betroffenen Projekte {% code overflow="wrap" %} ```bash # Für Benutzer des Overleaf Toolkits: $ bin/docker-compose exec sharelatex /bin/bash -c "source /etc/overleaf/env.sh && source /etc/container_environment.sh && cd /overleaf/services/history-v1 && /sbin/setuser www-data node storage/scripts/back_fill_file_hash.mjs --report" # Benutzer der alten docker-compose.yml: $ docker compose exec sharelatex /bin/bash -c "source /etc/overleaf/env.sh && source /etc/container_environment.sh && cd /overleaf/services/history-v1 && /sbin/setuser www-data node storage/scripts/back_fill_file_hash.mjs --report" ``` {% endcode %} Beispielausgabe: {% code fullWidth="false" %} ``` Aktueller Status: - Gesamtzahl der Projekte: 10 - Gesamtzahl der gelöschten Projekte: 5 Es werden 1000 Projekte stichprobenartig erfasst, um den Fortschritt abzuschätzen... Statistiken der Stichprobe für Projekte: - Stichprobenprojekte: 9 (90 % aller Projekte) - Stichprobenprojekte mit allen vorhandenen Hashes: 5 - Prozentsatz der Projekte, bei denen Hashes nachträglich aufgefüllt werden müssen: 44 % (geschätzt) - Die Stichprobenprojekte haben 11 Dateien, die gegen das vollständige Projektverlaufsystem geprüft werden müssen. - Die Stichprobenprojekte haben 3 Dateien, die in das vollständige Projektverlaufsystem hochgeladen werden müssen (schätzungsweise 27 % aller Dateien). Stichprobenstatistiken für gelöschte Projekte: - Stichprobenartig erfasste gelöschte Projekte: 4 (80 % aller gelöschten Projekte) - Stichprobenartig erfasste gelöschte Projekte mit allen vorhandenen Hashes: 3 - Prozentsatz der gelöschten Projekte, bei denen Hashes nachträglich aufgefüllt werden müssen: 25 % (geschätzt) - Die stichprobenartig erfassten gelöschten Projekte haben 2 Dateien, die gegen das vollständige Projektverlaufsystem geprüft werden müssen. - Die stichprobenartig erfassten gelöschten Projekte haben 1 Datei, die in das vollständige Projektverlaufsystem hochgeladen werden muss (schätzungsweise 50 % aller Dateien). ``` {% endcode %} {% endstep %} {% step %} #### Projektverlaufswarteschlangen leeren {% code overflow="wrap" %} ```bash # Für Benutzer des Overleaf Toolkits: $ bin/docker-compose exec sharelatex /overleaf/bin/flush-history-queues # Benutzer der alten docker-compose.yml: $ docker compose exec sharelatex /overleaf/bin/flush-history-queues ``` {% endcode %} Wiederholen Sie das Leeren, bis alle Projekte geleert wurden (`"project_ids":0`). ``` found projects {"project_ids":0,"limit":100000,"ts":"2025-09-01T10:35:33.353Z"} total {"succeededProjects":0,"failedProjects":0} ``` {% hint style="danger" %} Falls "failedProjects" nicht null ist, wenden Sie sich bitte an den Support und setzen Sie die Migration der Binärdateien nicht fort. {% endhint %} {% endstep %} {% step %} #### Die Migrationsphase auf 1 vorziehen Toolkit: Setzen Sie `OVERLEAF_FILESTORE_MIGRATION_LEVEL=1` in `config/variables.env`. Alte docker-compose.yml: Setzen Sie `OVERLEAF_FILESTORE_MIGRATION_LEVEL: '1'` in der `Umgebung` Abschnitt der `sharelatex` Dienst. {% endstep %} {% step %} #### Übernehmen Sie die Konfigurationsänderung und starten Sie die Instanz Toolkit: `bin/up -d` Alte docker-compose.yml: `docker compose up -d` {% endstep %} {% step %} #### Zugriff auf Binärdateien überprüfen Öffnen Sie in Ihrem Browser ein Projekt im Overleaf-Editor und wählen Sie eine Binärdatei aus, z. B. ein Bild. {% endstep %} {% step %} #### Führen Sie das Migrationsskript aus {% code overflow="wrap" %} ```bash # Für Benutzer des Overleaf Toolkits: $ bin/docker-compose exec sharelatex /bin/bash -c "source /etc/overleaf/env.sh && source /etc/container_environment.sh && cd /overleaf/services/history-v1 && /sbin/setuser www-data node storage/scripts/back_fill_file_hash.mjs --all" # Benutzer der alten docker-compose.yml: $ docker compose exec sharelatex /bin/bash -c "source /etc/overleaf/env.sh && source /etc/container_environment.sh && cd /overleaf/services/history-v1 && /sbin/setuser www-data node storage/scripts/back_fill_file_hash.mjs --all" ``` {% endcode %} {% hint style="danger" %} Wenn Sie [Protokolldateien](https://docs.overleaf.com/on-premises/configuration/overleaf-toolkit/logging#persisting-logs) außerhalb des **sharelatex** Containers speichern, stellen Sie sicher, dass der Besitzer des Logs-Verzeichnisses auf den `www-data` Benutzer (uid=33) gesetzt ist, damit die ausgegebene Protokolldatei geschrieben werden kann. {% endhint %} Die Ausgabe sollte wie folgt aussehen: ```bash Setzen Sie UV_THREADPOOL_SIZE=16 {"name":"default","hostname":"c25e9faaeb53","pid":971,"level":30,"backend":"fs","msg":"Loading backend","time":"2025-07-25T15:00:58.166Z","v":0} Protokolle werden in /var/log/overleaf/file-migration-2025-07-25T15_00_58_199Z.log geschrieben Sicherung der Projektdateien wird gestartet... Globale Blobs geladen: 0 Nicht gelöschte Projekte werden verarbeitet... 1 Projekt verarbeitet, vergangene Zeit 0 s Aktualisierung der Live-Projekte abgeschlossen Gelöschte Projekte werden verarbeitet... Die Sammlung deletedProjects scheint leer zu sein. Aktualisierung der gelöschten Projekte abgeschlossen Abgeschlossen. ``` Wenn die Migration erfolgreich ist, erhalten Sie einen Exit-Code von `0`, und die letzten Zeilen weisen auf keine Fehler hin: ```bash Abgeschlossen. ``` Die Protokolldatei sieht dann so aus (verwenden Sie den vom Skript ausgegebenen Pfad): {% code overflow="wrap" %} ```bash $ docker cp sharelatex:/var/log/overleaf/file-migration-2025-07-25T15_00_58_199Z.log . $ cat file-migration-2025-07-25T15_00_58_199Z.log {"name":"file-migration","hostname":"c25e9faaeb53","pid":971,"level":30,"end":"68839a8f577b9f009d947b27 (2025-07-25T14:54:07.000Z)","msg":"actually completed batch","time":"2025-07-25T15:00:58.379Z","v":0} {"name":"file-migration","hostname":"c25e9faaeb53","pid":971,"level":30,"time":"2025-07-25T15:00:58.383Z","LOGGING_IDENTIFIER":"4effa2000000000000000000","projects":1,"blobs":6,"filesWithHash":5,"filesWithoutHash":2,"filesDuplicated":0,"filesRetries":0,"filesFailed":0,"fileTreeUpdated":0,"badFileTrees":0,"globalBlobsCount":0,"globalBlobsEgress":0,"projectDeleted":0,"projectHardDeleted":0,"fileHardDeleted":0,"mongoUpdates":1,"readFromGCSCount":7,"readFromGCSIngress":28532,"writeToGCSCount":5,"writeToGCSEgress":300,"readFromGCSThroughputMiBPerSecond":0.14925639825786063,"eventLoop":{"idle":48.277844,"active":381.53244699971054,"utilization":0.8876763888372498},"diff":{"eventLoop":{"idle":48.223536,"active":134.04030200059555,"utilization":0.7354190687027976},"projects":1,"blobs":6,"filesWithHash":5,"filesWithoutHash":2,"filesDuplicated":0,"filesRetries":0,"filesFailed":0,"fileTreeUpdated":0,"badFileTrees":0,"globalBlobsCount":0,"globalBlobsEgress":0,"projectDeleted":0,"projectHardDeleted":0,"fileHardDeleted":0,"mongoUpdates":1,"readFromGCSCount":7,"readFromGCSIngress":28532,"writeToGCSCount":5,"writeToGCSEgress":300,"readFromGCSThroughputMiBPerSecond":0.14925639825786063},"deferredBatches":[],"msg":"file-migration stats","v":0} ``` {% endcode %} {% endstep %} {% step %} #### Instanz stoppen Toolkit: `bin/stop sharelatex` Alte docker-compose.yml: `docker compose stop sharelatex` {% endstep %} {% step %} #### Alte Dateien für die Anwendung unzugänglich machen Sie können die alten Dateien jetzt in den Sekundärspeicher verschieben. Wir empfehlen, die Dateien noch eine Weile aufzubewahren, falls später Probleme auftreten. {% code overflow="wrap" %} ```bash # Toolkit-Benutzer: $ bin/docker-compose run --rm --entrypoint mv sharelatex --no-clobber --verbose /var/lib/overleaf/data/user_files /var/lib/overleaf/data/old_user_files # Benutzer der alten docker-compose.yml: # Wir gehen davon aus, dass Sie den standardmäßigen Bind-Mount in /var/lib/overleaf verwenden $ docker compose run --rm --entrypoint mv sharelatex --no-clobber --verbose /var/lib/overleaf/data/user_files /var/lib/overleaf/data/old_user_files # Falls Sie selektive Bind-Mounts verwenden, können Sie den Bind-Mount für /var/lib/overleaf/data/user_files innerhalb des Containers einfach entfernen. ``` {% endcode %} {% endstep %} {% step %} #### Die Migrationsphase auf 2 vorziehen Toolkit: Setzen Sie `OVERLEAF_FILESTORE_MIGRATION_LEVEL=2` in `config/variables.env`. Alte docker-compose.yml: Setzen Sie `OVERLEAF_FILESTORE_MIGRATION_LEVEL: '2'` in der `Umgebung` Abschnitt der `sharelatex` Dienst. {% endstep %} {% step %} #### Übernehmen Sie die Konfigurationsänderung und starten Sie die Instanz Toolkit: `bin/up -d` Alte docker-compose.yml: `docker compose up -d` {% endstep %} {% step %} #### Zugriff auf Binärdateien überprüfen Öffnen Sie in Ihrem Browser ein Projekt im Overleaf-Editor und wählen Sie eine Binärdatei aus, z. B. ein Bild. {% endstep %} {% endstepper %} #### Offline-Migration Wenn Sie verhindern möchten, dass sich Benutzer anmelden können, während das Migrationsskript für Binärdateien ausgeführt wird, gehen Sie bitte wie folgt vor: * Melden Sie sich mit einem Administratorkonto bei Ihrer Overleaf-Instanz an * Klicken Sie auf die **Admin** Schaltfläche und wählen Sie **Website verwalten** * Klicken Sie auf die **Editor öffnen/schließen** Tab * Klicken Sie auf die **Editor schließen** Schaltfläche * Klicken Sie auf die **Alle Benutzer trennen** Schaltfläche Sobald dies erledigt ist, werden bereits angemeldete Benutzer auf die Wartungsseite umgeleitet, und neue Benutzer, die die Anmeldeseite aufrufen, sehen die Wartungsseite und **können sich nicht** anmelden. Sie müssen diese Schritte bei jedem Neustart der Instanz wiederholen. Um die Seite wieder zu öffnen, starten Sie die Instanz einfach neu. #### Online-Migration Es ist möglich, die Migrationsskripte auszuführen, während die Anwendung weiterhin läuft. Es gibt einige Punkte zu beachten: * Der Migrationsprozess ist E/A-intensiv; Sie sollten die Ressourcennutzung überwachen, während das Skript läuft. * Bei hoher Verarbeitungskonkurrenz kann die Ereignisschleife im `filestore` Dienst zu Blockierungen kommen, was zu einer beeinträchtigten Benutzererfahrung führen würde. Wir empfehlen, mit den Standardwerten von zu beginnen `--concurrency=10` und `--concurrent-batches=1` . * Sie können das Skript jederzeit stoppen. Wenn Sie es erneut starten, werden die vorherigen Projekte validiert und Dateien übersprungen, die bereits verarbeitet wurden. Das ist nützlich, wenn Sie die Migration lieber zu weniger ausgelasteten Zeiten ausführen möchten (z. B. nachts). Unsere Empfehlung ist, die Seite zu schließen und die Migration offline in einem Wartungsfenster auszuführen, wenn Ihre Projektanzahl unter 1000 Projekten liegt (siehe Ausgabe des Migrationsskripts beim Ausführen mit `--report`). Wenn die Anzahl der Projekte groß ist, können Sie das Skript ausführen und seinen Fortschritt überwachen und dann je nach Situation entscheiden, ob Sie es online oder offline weiter ausführen. #### Veraltete Binärdateidaten bereinigen Wenn Sie mit der Migration fertig sind und überprüft haben, dass Projekte weiterhin auf alle ihre Dateien zugreifen können, können Sie den alten Dateispeicher in `/var/lib/overleaf/data/user_files`. Wir empfehlen dringend, diese Dateien noch eine Weile aufzubewahren – Sie können sie für die Anwendung unzugänglich machen, indem Sie zuerst den Ordner umbenennen. ### Fehlerbehebung Wir werden hier Hinweise zur Fehlerbehebung hinzufügen. Bitte beachten Sie, dass wir normalerweise nur Server-Pro-Kunden Support anbieten, wir aufgrund der Art dieser Migration jedoch auch unser Bestes tun werden, CE-Kunden zu unterstützen, die Probleme speziell mit der Migration von Binärdateien haben. Wenn das Migrationsskript für Binärdateien fehlschlägt (d. h. mit einem Fehler endet oder eine von null verschiedene Anzahl fehlgeschlagener Projekte ausgibt), senden Sie bitte die folgenden Details per E-Mail an unser Support-Team [support+filestoremigration@overleaf.com](mailto:support+filestoremigration@overleaf.com?subject=Binary%20file%20migration%20problem\&body=Instance%20Type%3A%20CE%20or%20Server%20Pro%20%28delete%20as%20appropriate%29%0A%0AInstallation%20Type%3A%20Overleaf%20toolkit%20or%20docker-compose.yml%20or%20other%20%28delete%20as%20appropriate%29%0A%0AScript%20output%3A%0A%0Abin%2Fdoctor%20output%20%28if%20using%20toolkit%29%3A%0A), mit folgenden Angaben: Betreff: Problem bei der Migration von Binärdateien Inhalt: * Instanztyp: CE oder Server Pro (je nach Bedarf löschen) * Installationstyp: Overleaf Toolkit oder `docker-compose.yml` oder andere (je nach Bedarf löschen) * Version: 5.5.x (Toolkit: `$ cat config/version`) * Ausgabe des Migrationsskripts (die sich im Container unter `/var/log/overleaf`) * Bericht: (Migrationsskript ausführen mit `--report`) * Verarbeitete Projekte: (gemäß dem letzten Lauf des Skripts) * Dauer der Migration: * `bin/doctor` Ausgabe (bei Verwendung des Toolkits) * Toolkit-Version: `$ git rev-parse HEAD` (bei Verwendung des Toolkits) Erwägen Sie, die Protokolldateien für die `filestore` Dienst an die E-Mail. Sie finden ihn unter `/var/log/overleaf/filestore.log` im `sharelatex` Container und exportieren Sie sie wie folgt: ```bash $ docker cp sharelatex:/var/log/overleaf/filestore.log . # durch den vom Skript ausgegebenen Zeitstempel ersetzen $ docker cp sharelatex:/var/log/overleaf/file-migration-.log . ``` Bitte schwärzen Sie alle sensiblen Informationen in den Protokolldateien, bevor Sie sie anhängen. #### Fehlende Dateien Ältere Versionen von Server Pro/CE erstellten Dateibaumeinträge, bevor der Upload durch den Benutzer abgeschlossen war, was dazu führen konnte, dass Dateien als fehlend angezeigt wurden, wenn ein Upload fehlschlug. Möglicherweise finden Sie einige dieser Fälle bei der Verarbeitung aller Dateibäume als Fehler gemeldet. Falls die Anzahl der fehlenden Dateien gering ist, sollten Sie diese Fälle manuell prüfen und sie im Browser-Editor löschen. Falls die Anzahl der fehlenden Dateien hoch ist, sollten Sie sich an den Support wenden, siehe E-Mail-Vorlage oben. #### Fehlerhafte Dateibäume finden Die Migration kann bei Projekten fehlschlagen, die einen fehlerhaften Dateibaum haben (zum Beispiel, wenn Dateinamen leer sind). Eine Liste dieser Probleme finden Sie mit dem `find_malformed_filetrees` Skript, das alle Projekte in der Datenbank überprüft: {% code overflow="wrap" %} ```bash $ bin/docker-compose exec sharelatex /bin/bash -c "cd /overleaf/services/web && /sbin/setuser www-data node scripts/find_malformed_filetrees.mjs > /tmp/malformed-file-trees.json" ``` {% endcode %} Um die ungültigen Pfade zu beheben, verwenden Sie das `fix_malformed_filetree` Skript und führen Sie den Befehl für jeden fehlerhaften Pfad einmal aus: {% code overflow="wrap" %} ```bash $ bin/docker-compose exec sharelatex /bin/bash -c "cd /overleaf/services/web && /sbin/setuser www-data node scripts/fix_malformed_filetree.mjs --logs=/tmp/malformed-file-trees.json" ``` {% endcode %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://ayakaleaf-pro.ayaka.space/on-premises/de/support/support-guides/v5.5.7-migration-binary-files-migration.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.