> For the complete documentation index, see [llms.txt](https://overleaf-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://overleaf-pro.ayaka.space/on-premises/de/support/support-guides/v5.5.7-migration-binary-files-migration.md). # (Migration v5.5.7) Migration binärer Dateien ## Migration binärer Dateien Die kommende Hauptversion `6.0` der Veröffentlichung von Server Pro und Community Edition wird die Speichernutzung binärer Dateien halbieren. Eine Online-Migration ist in Version enthalten `5.5.7` , wodurch minimale Ausfallzeiten im Rahmen des Upgrades möglich sind. Seit Server Pro `4.x`, werden binäre Dateien doppelt gespeichert: im aktiven Dateispeicher in "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 soft-gelöschten Projekte verarbeitet. Phasen: * `OVERLEAF_FILESTORE_MIGRATION_LEVEL=0` (Standard), Dateien werden aus dem Filestore gelesen und dort geschrieben. Dateien werden asynchron in die Historie geschrieben. * `OVERLEAF_FILESTORE_MIGRATION_LEVEL=1` , Dateien werden aus der Historie mit Fallback auf den Filestore gelesen und sowohl in den Filestore als auch in die Historie geschrieben. Ein Downgrade auf `OVERLEAF_FILESTORE_MIGRATION_LEVEL=0` ist möglich. * `OVERLEAF_FILESTORE_MIGRATION_LEVEL=2` Dateien werden nur noch aus der Historie gelesen und dorthin geschrieben. Ein Downgrade auf `OVERLEAF_FILESTORE_MIGRATION_LEVEL=1` ist nicht möglich, es sei denn, es wurde "offline" durchgeführt. Wenn Daten in [S3](https://docs.overleaf.com/on-premises/configuration/overleaf-toolkit/s3) gespeichert werden und separate Servicekonten für den Filestore (`OVERLEAF_FILESTORE_S3_ACCESS_KEY_ID`) und die Historie (`OVERLEAF_HISTORY_S3_ACCESS_KEY_ID`) verwendet werden: Bitte gewähren Sie dem Filestore-Benutzer Lesezugriff auf den Historien-Bucket für Blobs `OVERLEAF_HISTORY_PROJECT_BLOBS_BUCKET` . Der Filestore-Service wird künftig Lesevorgänge vom Compiler-Service bedienen. {% hint style="warning" %} Es wird dringend empfohlen, die Migration binärer Dateien zunächst in einer Nicht-Produktions-/Sandbox-Umgebung durchzuführen. {% endhint %} {% hint style="success" %} Die standardmäßige Server-Pro-Lizenz erlaubt es Ihnen, die Anwendung in einer Produktionsumgebung sowie in einer Nicht-Produktions-/Sandbox-Umgebung zu betreiben; es wird dringend empfohlen, für Tests eine Nicht-Produktionsumgebung bereitzustellen. {% endhint %} {% hint style="info" %} Wenn Sie auf Server Pro/CE Version upgraden `6.0` und später entscheiden, dass Sie auf eine frühere Version downgraden möchten, sollten Sie aus einem vollständigen System-Backup wiederherstellen. {% endhint %} ### Migrationsverfahren {% stepper %} {% step %} #### Ein Backup erstellen 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 erstellen. {% endstep %} {% step %} #### Aktualisieren Sie **Toolkit:** Verwenden Sie den `$ bin/upgrade` Skript zum Upgrade des **Toolkits** auf die neueste Version. Wenn Sie dazu aufgefordert werden, **nicht** bestätigen Sie die Eingabeaufforderung **Aktualisieren** image? — bearbeiten Sie stattdessen manuell **config/version** die Datei und setzen Sie den Wert auf `5.5.7`. **Legacy 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 # Overleaf-Toolkit-Benutzer: $ 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" # Nutzer der Legacy 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 1000 Projekte werden gesampelt, um den Fortschritt zu schätzen... Statistiken für gesampelte Projekte: - Gesampelte Projekte: 9 (90 % aller Projekte) - Gesampelte Projekte mit allen vorhandenen Hashes: 5 - Anteil der Projekte, bei denen Hashes nachgetragen werden müssen: 44 % (geschätzt) - Gesampelte Projekte haben 11 Dateien, die gegen das vollständige Projektverlaufsystem geprüft werden müssen. - Gesampelte Projekte haben 3 Dateien, die in das vollständige Projektverlaufsystem hochgeladen werden müssen (geschätzt 27 % aller Dateien). Statistiken für gesampelte gelöschte Projekte: - Gesampelte gelöschte Projekte: 4 (80 % aller gelöschten Projekte) - Gesampelte gelöschte Projekte mit allen vorhandenen Hashes: 3 - Anteil der gelöschten Projekte, bei denen Hashes nachgetragen werden müssen: 25 % (geschätzt) - Gesampelte gelöschte Projekte haben 2 Dateien, die gegen das vollständige Projektverlaufsystem geprüft werden müssen. - Gesampelte gelöschte Projekte haben 1 Datei, die in das vollständige Projektverlaufsystem hochgeladen werden muss (geschätzt 50 % aller Dateien). ``` {% endcode %} {% endstep %} {% step %} #### Projektverlaufswarteschlangen leeren {% code overflow="wrap" %} ```bash # Overleaf-Toolkit-Benutzer: $ bin/docker-compose exec sharelatex /overleaf/bin/flush-history-queues # Nutzer der Legacy 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`). ``` gefundene Projekte {"project_ids":0,"limit":100000,"ts":"2025-09-01T10:35:33.353Z"} gesamt {"succeededProjects":0,"failedProjects":0} ``` {% hint style="danger" %} Falls "failedProjects" nicht null ist, wenden Sie sich bitte an den Support und fahren Sie nicht mit der Migration binärer Dateien fort. {% endhint %} {% endstep %} {% step %} #### Migrationsphase auf 1 voranbringen Toolkit: Setzen Sie `OVERLEAF_FILESTORE_MIGRATION_LEVEL=1` in `config/variables.env`. Legacy 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` Legacy docker-compose.yml: `docker compose up -d` {% endstep %} {% step %} #### Zugriff auf binäre Dateien überprüfen Öffnen Sie ein Projekt im Overleaf-Editor im Browser und wählen Sie eine binäre Datei aus, z. B. ein Bild. {% endstep %} {% step %} #### Führen Sie das Migrationsskript aus {% code overflow="wrap" %} ```bash # Overleaf-Toolkit-Benutzer: $ 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" # Nutzer der Legacy 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" %} Falls Sie [Protokolldateien speichern](https://docs.overleaf.com/on-premises/configuration/overleaf-toolkit/logging#persisting-logs) außerhalb des **sharelatex** Containers, 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 so aussehen: ```bash Setzen Sie UV_THREADPOOL_SIZE=16 {"name":"default","hostname":"c25e9faaeb53","pid":971,"level":30,"backend":"fs","msg":"Backend wird geladen","time":"2025-07-25T15:00:58.166Z","v":0} Protokolle werden geschrieben nach /var/log/overleaf/file-migration-2025-07-25T15_00_58_199Z.log 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 Zeile ausgegeben wurde, oder warten Sie darauf ``` Wenn die Migration erfolgreich ist, erhalten Sie einen Exit-Code von `0`, und die letzten Zeilen weisen auf keine Fehler hin: ```bash Zeile ausgegeben wurde, oder warten Sie darauf ``` Die Protokolldatei sieht 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":"Batch tatsächlich abgeschlossen","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":"Statistiken zur datei-Migration","v":0} ``` {% endcode %} {% endstep %} {% step %} #### Instanz stoppen Toolkit: `bin/stop sharelatex` Legacy 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 auf einen sekundären Speicher verschieben. Wir empfehlen, die Dateien noch eine Weile aufzubewahren, falls später Probleme auftreten. {% code overflow="wrap" %} ```bash # Nutzer des Toolkits: $ bin/docker-compose run --rm --entrypoint mv sharelatex --no-clobber --verbose /var/lib/overleaf/data/user_files /var/lib/overleaf/data/old_user_files # Nutzer der Legacy docker-compose.yml: # Wir gehen davon aus, dass Sie den standardmäßigen Bind-Mount unter /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 im Container einfach entfernen. ``` {% endcode %} {% endstep %} {% step %} #### Migrationsphase auf 2 voranbringen Toolkit: Setzen Sie `OVERLEAF_FILESTORE_MIGRATION_LEVEL=2` in `config/variables.env`. Legacy 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` Legacy docker-compose.yml: `docker compose up -d` {% endstep %} {% step %} #### Zugriff auf binäre Dateien überprüfen Öffnen Sie ein Projekt im Overleaf-Editor im Browser und wählen Sie eine binäre Datei aus, z. B. ein Bild. {% endstep %} {% endstepper %} #### Offline-Migration Wenn Sie verhindern möchten, dass sich Benutzer anmelden können, während das Skript zur Migration binärer Dateien 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 im Projektdashboard auf die **Editor öffnen/schließen** Registerkarte * Klicken Sie auf die **Editor schließen** Schaltfläche * Klicken Sie auf die **Alle Benutzer trennen** Schaltfläche Sobald dies erledigt ist, werden alle angemeldeten Benutzer zur Wartungsseite weitergeleitet, und alle neuen Benutzer, die die Anmeldeseite aufrufen, sehen die Wartungsseite und **werden nicht** sich anmelden können. Sie müssen diese Schritte beim Neustart der Instanz wiederholen. Um die Website wieder zu öffnen, starten Sie die Instanz einfach neu. #### Online-Migration Es ist möglich, die Migrationsskripte auszuführen, während die Anwendung noch läuft. Dabei sind einige Punkte zu beachten: * Der Migrationsprozess ist I/O-intensiv, Sie sollten die Ressourcennutzung überwachen, während das Skript läuft. * Bei hoher Verarbeitungskonkurrenz kann die Event-Loop im `filestore` Dienst einige Blockierungen erfahren, was zu einer schlechteren 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 bereits verarbeitete Dateien übersprungen. Das ist nützlich, wenn Sie die Migration lieber zu ruhigeren Zeiten ausführen möchten (z. B. nachts). Unsere Empfehlung ist, die Website zu schließen und die Migration offline in einem Wartungsfenster auszuführen, wenn Ihre Projektanzahl weniger als 1000 Projekte beträgt (siehe Ausgabe des Migrationsskripts, wenn es mit `--report`). Wenn die Anzahl der Projekte groß ist, können Sie das Skript ausführen und den Fortschritt überwachen; danach können Sie je nach Situation entscheiden, ob Sie es online oder offline weiter ausführen. #### Legacy-Binärdateidaten bereinigen Wenn Sie mit der Migration fertig sind und bestätigt haben, dass Projekte weiterhin auf alle ihre Dateien zugreifen können, können Sie den alten Dateispeicher in `/var/lib/overleaf/data/user_files`entfernen. Wir empfehlen dringend, diese Dateien noch eine Weile aufzubewahren - Sie können sie der Anwendung unzugänglich machen, indem Sie zunächst 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 uns jedoch angesichts der Natur dieser Migration auch nach Kräften bemühen werden, CE-Kunden zu unterstützen, die Probleme speziell mit der Migration binärer Dateien haben. Falls das Skript zur Migration binärer Dateien fehlschlägt (d. h. mit einem Fehler beendet wird 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), und geben Sie dabei Folgendes an: Betreff: Problem bei der Migration binärer Dateien Text: * Instanztyp: CE oder Server Pro (je nach Zutreffendem löschen) * Installationstyp: Overleaf Toolkit oder `docker-compose.yml` oder andere (je nach Zutreffendem löschen) * Version: 5.5.x (Toolkit: `$ cat config/version`) * Ausgabe des Migrationsskripts (die sich im Container unter befinden sollte `/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 Logdateien der `filestore` Dienst an die E-Mail. Sie finden sie unter `/var/log/overleaf/filestore.log` im `sharelatex` Container und exportieren Sie sie so: ```bash $ docker cp sharelatex:/var/log/overleaf/filestore.log . # ersetzen Sie durch den vom Skript ausgegebenen Zeitstempel $ docker cp sharelatex:/var/log/overleaf/file-migration-.log . ``` Bitte schwärzen Sie alle sensiblen Informationen in den Logdateien, bevor Sie sie anhängen. #### Fehlende Dateien Ältere Versionen von Server Pro/CE haben Datei-Baumeinträge erstellt, bevor Benutzer-Uploads abgeschlossen waren, was dazu führen konnte, dass Dateien als fehlend erschienen, wenn ein Upload fehlschlug. Möglicherweise finden Sie einige dieser Fälle beim Verarbeiten aller Dateibäume als Fehler gemeldet. Falls die Anzahl fehlender Dateien gering ist, sollten Sie diese Fälle manuell überprüfen und sie im Editor im Browser löschen. Falls die Anzahl fehlender Dateien hoch ist, sollten Sie den Support kontaktieren, siehe obige E-Mail-Vorlage. #### Beschädigte Dateistrukturen finden Die Migration kann bei Projekten fehlschlagen, die eine fehlerhafte Dateistruktur 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 prü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://overleaf-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.