> ## Documentation Index
> Fetch the complete documentation index at: https://ayakaleaf-pro.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# (v5.5.7-Migration) Migration von Binärdateien
## Migration von Binärdateien
Das kommende Hauptversions-Release `6.0` von Server Pro und Community Edition halbiert den Speicherbedarf von Binärdateien. Version `5.5.7` enthält eine Online-Migration, die im Rahmen des Upgrades nur minimale Ausfallzeiten verursacht.
Seit Server Pro `4.x` werden Binärdateien doppelt gespeichert: im Speicher für aktive Dateien in „filestore" und im System für den vollständigen Projektverlauf. Künftig wird nur noch eine einzige Kopie jeder Datei im System für den vollständigen Projektverlauf gespeichert.
Die Migration auf das konsolidierte Speichersystem besteht aus zwei Teilen: einem neuen Flag zur Steuerung der Migrationsphase und einem Skript, das alle aktiven und vorläufig gelöschten Projekte verarbeitet.
Phasen:
* `OVERLEAF_FILESTORE_MIGRATION_LEVEL=0` (Standard): Dateien werden aus filestore gelesen und dorthin geschrieben. Dateien werden asynchron in den Verlauf geschrieben.
* `OVERLEAF_FILESTORE_MIGRATION_LEVEL=1`: Dateien werden aus dem Verlauf gelesen, mit filestore als Fallback, und sowohl in 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 ausschließlich aus dem Verlauf gelesen und dorthin geschrieben. Ein Downgrade auf `OVERLEAF_FILESTORE_MIGRATION_LEVEL=1` ist nicht möglich, es sei denn, die Migration wurde „offline" durchgeführt.
Wenn Sie Daten in [S3](https://docs.overleaf.com/on-premises/configuration/overleaf-toolkit/s3) speichern und separate Dienstkonten für filestore (`OVERLEAF_FILESTORE_S3_ACCESS_KEY_ID`) und den Verlauf (`OVERLEAF_HISTORY_S3_ACCESS_KEY_ID`) verwenden: Gewähren Sie dem filestore-Benutzer bitte Lesezugriff auf den History-Bucket für Blobs `OVERLEAF_HISTORY_PROJECT_BLOBS_BUCKET`. Der filestore-Dienst bedient künftig die Lesezugriffe des Compiler-Dienstes.
Es wird dringend empfohlen, die Migration der Binärdateien zunächst in einer Nicht-Produktions-/Sandbox-Umgebung durchzuführen.
Die Standardlizenz von Server Pro erlaubt Ihnen, die Anwendung sowohl in einer Produktionsumgebung als auch in einer Nicht-Produktions-/Sandbox-Umgebung zu betreiben; wir empfehlen dringend, eine Nicht-Produktionsumgebung zum Testen bereitzustellen.
Wenn Sie auf Server Pro/CE Version `6.0` aktualisieren und später auf eine frühere Version zurückstufen möchten, sollten Sie ein vollständiges System-Backup wiederherstellen.
### Migrationsablauf
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 Verzeichnisse **mongo**, **redis** und **sharelatex**.
Toolkit: Verwenden Sie das Skript `$ bin/upgrade`, um das **Toolkit** auf die neueste Version zu aktualisieren. Bestätigen Sie die Abfrage **Upgrade** image? **nicht** – bearbeiten Sie stattdessen manuell die Datei **config/version** und setzen Sie den Wert auf `5.5.7`.
Legacy docker-compose.yml: Aktualisieren Sie die Version des Dienstes `sharelatex` auf `5.5.7`.
```bash wrap theme={null}
# Overleaf Toolkit users:
$ 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"
# Legacy docker-compose.yml users:
$ 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"
```
Beispielausgabe:
```text theme={null}
Current status:
- Total number of projects: 10
- Total number of deleted projects: 5
Sampling 1000 projects to estimate progress...
Sampled stats for projects:
- Sampled projects: 9 (90% of all projects)
- Sampled projects with all hashes present: 5
- Percentage of projects that need back-filling hashes: 44% (estimated)
- Sampled projects have 11 files that need to be checked against the full project history system.
- Sampled projects have 3 files that need to be uploaded to the full project history system (estimating 27% of all files).
Sampled stats for deleted projects:
- Sampled deleted projects: 4 (80% of all deleted projects)
- Sampled deleted projects with all hashes present: 3
- Percentage of deleted projects that need back-filling hashes: 25% (estimated)
- Sampled deleted projects have 2 files that need to be checked against the full project history system.
- Sampled deleted projects have 1 files that need to be uploaded to the full project history system (estimating 50% of all files).
```
```bash wrap theme={null}
# Overleaf Toolkit users:
$ bin/docker-compose exec sharelatex /overleaf/bin/flush-history-queues
# Legacy docker-compose.yml users:
$ docker compose exec sharelatex /overleaf/bin/flush-history-queues
```
Wiederholen Sie das Leeren, bis alle Projekte geleert wurden (`"project_ids":0`).
```text theme={null}
found projects {"project_ids":0,"limit":100000,"ts":"2025-09-01T10:35:33.353Z"}
total {"succeededProjects":0,"failedProjects":0}
```
Falls "failedProjects" nicht null ist, wenden Sie sich bitte an den Support und setzen Sie die Migration der Binärdateien nicht fort.
Toolkit: Setzen Sie `OVERLEAF_FILESTORE_MIGRATION_LEVEL=1` in `config/variables.env`.
Legacy docker-compose.yml: Setzen Sie `OVERLEAF_FILESTORE_MIGRATION_LEVEL: '1'` im Abschnitt `environment` des Dienstes `sharelatex`.
Toolkit: `bin/up -d`
Legacy docker-compose.yml: `docker compose up -d`
Öffnen Sie ein Projekt im Overleaf-Editor im Browser und wählen Sie eine Binärdatei aus, etwa ein Bild.
```bash wrap theme={null}
# Overleaf Toolkit users:
$ 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"
# Legacy docker-compose.yml users:
$ 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"
```
Wenn Sie [Log-Dateien persistent](https://docs.overleaf.com/on-premises/configuration/overleaf-toolkit/logging#persisting-logs) außerhalb des Containers **sharelatex** speichern, stellen Sie sicher, dass der Eigentümer des Log-Verzeichnisses der Benutzer `www-data` (uid=33) ist, damit die ausgegebene Log-Datei geschrieben werden kann.
Die Ausgabe sollte etwa so aussehen:
```bash theme={null}
Set 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}
Writing logs into /var/log/overleaf/file-migration-2025-07-25T15_00_58_199Z.log
Starting project file backup...
Loaded global blobs: 0
Processing non-deleted projects...
Processed 1 projects, elapsed time 0s
Done updating live projects
Processing deleted projects...
The collection deletedProjects appears to be empty.
Done updating deleted projects
Done.
```
Ist die Migration erfolgreich, erhalten Sie den Exit-Code `0`, und die letzten Zeilen zeigen an, dass keine Fehler aufgetreten sind:
```bash theme={null}
Done.
```
Die Log-Datei sieht etwa so aus (verwenden Sie den vom Skript ausgegebenen Pfad):
```bash wrap theme={null}
$ 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}
```
Toolkit: `bin/stop sharelatex`
Legacy docker-compose.yml: `docker compose stop sharelatex`
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.
```bash wrap theme={null}
# Toolkit users:
$ bin/docker-compose run --rm --entrypoint mv sharelatex --no-clobber --verbose /var/lib/overleaf/data/user_files /var/lib/overleaf/data/old_user_files
# Legacy docker-compose.yml users:
# We are assuming that you are using the default bind-mount in /var/lib/overleaf
$ docker compose run --rm --entrypoint mv sharelatex --no-clobber --verbose /var/lib/overleaf/data/user_files /var/lib/overleaf/data/old_user_files
# In case you are using selective bind-mounts, you can simply remove the bind-mount for /var/lib/overleaf/data/user_files inside the container.
```
Toolkit: Setzen Sie `OVERLEAF_FILESTORE_MIGRATION_LEVEL=2` in `config/variables.env`.
Legacy docker-compose.yml: Setzen Sie `OVERLEAF_FILESTORE_MIGRATION_LEVEL: '2'` im Abschnitt `environment` des Dienstes `sharelatex`.
Toolkit: `bin/up -d`
Legacy docker-compose.yml: `docker compose up -d`
Öffnen Sie ein Projekt im Overleaf-Editor im Browser und wählen Sie eine Binärdatei aus, etwa ein Bild.
#### Offline-Migration
Wenn Sie verhindern möchten, dass sich Benutzer anmelden können, während das Migrationsskript für Binärdateien 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.
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 weiterlä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 Verarbeitungsparallelität kann die Event-Loop im Dienst `filestore` teilweise blockiert werden, was die Benutzererfahrung beeinträchtigt. Wir empfehlen, mit den Standardwerten `--concurrency=10` und `--concurrent-batches=1` zu beginnen.
* Sie können das Skript jederzeit stoppen. Beim erneuten Start werden die vorherigen Projekte validiert und bereits verarbeitete Dateien übersprungen. Das ist nützlich, wenn Sie die Migration lieber zu weniger ausgelasteten Zeiten (z. B. nachts) durchfü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 (siehe die Ausgabe des Migrationsskripts bei Ausführung mit `--report`). Bei einer großen Anzahl von Projekten können Sie das Skript ausführen, seinen Fortschritt beobachten und dann je nach Ihrem konkreten Fall entscheiden, ob Sie es online oder offline weiterlaufen lassen.
#### Alte Binärdateien bereinigen
Wenn die Migration abgeschlossen ist und Sie überprüft haben, dass Projekte weiterhin auf alle ihre Dateien zugreifen können, können Sie den alten Dateispeicher unter `/var/lib/overleaf/data/user_files` entfernen. Wir empfehlen dringend, diese Dateien noch eine Weile aufzubewahren – Sie können sie für die Anwendung unzugänglich machen, indem Sie den Ordner zunächst umbenennen.
### Fehlerbehebung
Wir werden hier Hinweise zur Fehlerbehebung ergänzen. Bitte beachten Sie: Obwohl wir normalerweise nur Server Pro-Kunden Support leisten, werden wir uns angesichts der Art dieser Migration auch bemühen, CE-Kunden zu unterstützen, die Probleme speziell mit der Migration der Binärdateien haben.
Schlägt das Migrationsskript für Binärdateien fehl (d. h. es beendet sich mit einem Fehler oder gibt eine Anzahl fehlgeschlagener Projekte ungleich null aus), senden Sie bitte die folgenden Angaben per E-Mail an unser Support-Team unter [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 Details:
Betreff: Binary file migration problem
Nachricht:
* Instanztyp: CE oder Server Pro (Nichtzutreffendes streichen)
* Installationstyp: Overleaf Toolkit oder `docker-compose.yml` oder andere (Nichtzutreffendes streichen)
* Version: 5.5.x (Toolkit: `$ cat config/version`)
* Ausgabe des Migrationsskripts (sollte sich im Container unter `/var/log/overleaf` befinden)
* Bericht: (Migrationsskript mit `--report` ausführen)
* Verarbeitete Projekte: (laut letztem Lauf des Skripts)
* Dauer der Migration:
* Ausgabe von `bin/doctor` (bei Verwendung des Toolkits)
* Toolkit-Version: `$ git rev-parse HEAD` (bei Verwendung des Toolkits)
Erwägen Sie, die Log-Dateien des Dienstes `filestore` an die E-Mail anzuhängen. Sie finden sie unter `/var/log/overleaf/filestore.log` im Container `sharelatex` und können sie wie folgt exportieren:
```bash theme={null}
$ docker cp sharelatex:/var/log/overleaf/filestore.log .
# replace with the timestamp as printed by the script
$ docker cp sharelatex:/var/log/overleaf/file-migration-.log .
```
Bitte entfernen Sie vor dem Anhängen alle sensiblen Informationen aus den Log-Dateien.
#### Fehlende Dateien
Ältere Versionen von Server Pro/CE haben Einträge im Dateibaum erstellt, bevor Uploads von Benutzern abgeschlossen waren. Schlug ein Upload fehl, konnten Dateien dadurch als fehlend erscheinen. Bei der Verarbeitung aller Dateibäume werden einige dieser Fälle möglicherweise als Fehler gemeldet.
Ist die Anzahl fehlender Dateien gering, sollten Sie diese Fälle manuell prüfen und im Editor im Browser löschen.
Ist die Anzahl fehlender Dateien hoch, sollten Sie sich an den Support wenden, siehe die E-Mail-Vorlage oben.
#### Beschädigte Dateibäume finden
Die Migration kann bei Projekten mit fehlerhaftem Dateibaum (zum Beispiel mit leeren Dateinamen) fehlschlagen. Eine Liste dieser Probleme erhalten Sie mit dem Skript `find_malformed_filetrees`, das alle Projekte in der Datenbank prüft:
```bash wrap theme={null}
$ 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"
```
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:
```bash wrap theme={null}
$ 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"
```
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.