> ## 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.
# (Migration v5.5.7) Migration des fichiers binaires
## Migration des fichiers binaires
La prochaine version majeure `6.0` de Server Pro et de la Community Edition réduira de moitié l'espace de stockage utilisé par les fichiers binaires. Une migration en ligne est incluse dans la version `5.5.7`, permettant de limiter au maximum l'interruption de service lors de la mise à niveau.
Depuis Server Pro `4.x`, les fichiers binaires sont stockés deux fois : dans le stockage des fichiers actifs de « filestore » et dans le système d'historique complet des projets. Désormais, une seule copie de chaque fichier sera stockée dans le système d'historique complet des projets.
La migration vers le système de stockage consolidé se compose de deux parties : un nouvel indicateur permettant de contrôler la phase de la migration, et un script qui traite tous les projets actifs et supprimés de manière réversible (soft-deleted).
Phases :
* `OVERLEAF_FILESTORE_MIGRATION_LEVEL=0` (par défaut) : les fichiers sont lus et écrits dans filestore. Les fichiers sont écrits dans l'historique de manière asynchrone.
* `OVERLEAF_FILESTORE_MIGRATION_LEVEL=1` : les fichiers sont lus depuis l'historique avec repli sur filestore, et écrits à la fois dans filestore et dans l'historique. Un retour à `OVERLEAF_FILESTORE_MIGRATION_LEVEL=0` est possible.
* `OVERLEAF_FILESTORE_MIGRATION_LEVEL=2` : les fichiers sont lus et écrits uniquement dans l'historique. Un retour à `OVERLEAF_FILESTORE_MIGRATION_LEVEL=1` n'est pas possible, sauf si la migration a été effectuée « hors ligne ».
Si vous stockez vos données dans [S3](https://docs.overleaf.com/on-premises/configuration/overleaf-toolkit/s3) et utilisez des comptes de service distincts pour filestore (`OVERLEAF_FILESTORE_S3_ACCESS_KEY_ID`) et l'historique (`OVERLEAF_HISTORY_S3_ACCESS_KEY_ID`) : accordez à l'utilisateur filestore un accès en lecture au bucket de l'historique pour les blobs `OVERLEAF_HISTORY_PROJECT_BLOBS_BUCKET`. Le service filestore servira désormais les lectures du service de compilation.
Il est vivement recommandé d'effectuer d'abord la migration des fichiers binaires dans un environnement hors production/sandbox.
La licence Server Pro standard vous permet d'exécuter l'application dans un environnement de production ainsi que dans un environnement hors production/sandbox ; nous vous recommandons vivement de prévoir un environnement hors production pour les tests.
Si vous passez à Server Pro/CE version `6.0` et décidez ensuite de revenir à une version antérieure, vous devrez restaurer une sauvegarde complète du système.
### Procédure de migration
Créez une [sauvegarde](https://docs.overleaf.com/on-premises/maintenance/data-and-backups#performing-a-consistent-backup) complète de votre instance avec un instantané cohérent des répertoires **mongo**, **redis** et **sharelatex**.
Toolkit : utilisez le script `$ bin/upgrade` pour mettre à jour le **toolkit** vers la dernière version. Lorsque la question **Upgrade** image? vous est posée, ne la confirmez **pas** — modifiez plutôt manuellement le fichier **config/version** et définissez la valeur sur `5.5.7`.
Ancien docker-compose.yml : mettez à jour la version du service `sharelatex` vers `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"
```
Exemple de sortie :
```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
```
Répétez le vidage jusqu'à ce que tous les projets aient été vidés (`"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}
```
Si « failedProjects » n'est pas égal à zéro, contactez le support et ne poursuivez pas la migration des fichiers binaires.
Toolkit : définissez `OVERLEAF_FILESTORE_MIGRATION_LEVEL=1` dans `config/variables.env`.
Ancien docker-compose.yml : définissez `OVERLEAF_FILESTORE_MIGRATION_LEVEL: '1'` dans la section `environment` du service `sharelatex`.
Toolkit : `bin/up -d`
Ancien docker-compose.yml : `docker compose up -d`
Ouvrez un projet dans l'éditeur Overleaf depuis le navigateur et sélectionnez un fichier binaire, comme une image.
```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"
```
Si vous [conservez les fichiers journaux](https://docs.overleaf.com/on-premises/configuration/overleaf-toolkit/logging#persisting-logs) en dehors du conteneur **sharelatex**, assurez-vous que le propriétaire du répertoire des journaux est l'utilisateur `www-data` (uid=33) afin que le fichier journal produit puisse être écrit.
La sortie devrait ressembler à ceci :
```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.
```
Si la migration réussit, vous obtiendrez un code de sortie `0` et les dernières lignes n'indiqueront aucun échec :
```bash theme={null}
Done.
```
Le fichier journal ressemblera à ceci (utilisez le chemin affiché par le script) :
```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`
Ancien docker-compose.yml : `docker compose stop sharelatex`
Vous pouvez maintenant déplacer les anciens fichiers vers un stockage secondaire. Nous vous recommandons de les conserver un certain temps au cas où des problèmes surviendraient par la suite.
```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 : définissez `OVERLEAF_FILESTORE_MIGRATION_LEVEL=2` dans `config/variables.env`.
Ancien docker-compose.yml : définissez `OVERLEAF_FILESTORE_MIGRATION_LEVEL: '2'` dans la section `environment` du service `sharelatex`.
Toolkit : `bin/up -d`
Ancien docker-compose.yml : `docker compose up -d`
Ouvrez un projet dans l'éditeur Overleaf depuis le navigateur et sélectionnez un fichier binaire, comme une image.
#### Migration hors ligne
Si vous souhaitez empêcher les utilisateurs de se connecter pendant l'exécution du script de migration des fichiers binaires, suivez ces étapes :
* Connectez-vous à votre instance Overleaf avec un compte administrateur
* Cliquez sur le bouton **Admin** et choisissez **Manage Site**
* Cliquez sur l'onglet **Open/Close Editor**
* Cliquez sur le bouton **Close Editor**
* Cliquez sur le bouton **Disconnect all users**
Une fois cela fait, les utilisateurs connectés seront redirigés vers la page de maintenance, et tout nouvel utilisateur visitant la page de connexion verra la page de maintenance et **ne pourra pas** se connecter.
Vous devez répéter ces étapes à chaque redémarrage de l'instance. Pour rouvrir le site, il suffit de redémarrer l'instance.
#### Migration en ligne
Il est possible d'exécuter les scripts de migration pendant que l'application continue de fonctionner. Quelques points sont à prendre en compte :
* Le processus de migration est gourmand en E/S ; surveillez l'utilisation des ressources pendant l'exécution du script.
* Avec une forte concurrence de traitement, la boucle d'événements du service `filestore` peut subir des blocages, ce qui dégraderait l'expérience utilisateur. Nous recommandons de commencer avec les valeurs par défaut `--concurrency=10` et `--concurrent-batches=1`.
* Vous pouvez arrêter le script à tout moment. En le relançant, il validera les projets précédents et ignorera les fichiers déjà traités. C'est utile si vous préférez exécuter la migration pendant les heures creuses (par ex. la nuit).
Nous recommandons de fermer le site et d'exécuter la migration hors ligne pendant une fenêtre de maintenance lorsque vous avez moins de 1000 projets (voir la sortie du script de migration exécuté avec `--report`). Si le nombre de projets est élevé, vous pouvez lancer le script, surveiller sa progression, puis décider de poursuivre en ligne ou hors ligne selon votre situation.
#### Nettoyer les anciennes données des fichiers binaires
Une fois la migration terminée et après avoir vérifié que les projets ont toujours accès à tous leurs fichiers, vous pouvez supprimer l'ancien stockage de fichiers dans `/var/lib/overleaf/data/user_files`. Nous vous recommandons vivement de conserver ces fichiers un certain temps — vous pouvez d'abord les rendre inaccessibles à l'application en renommant le dossier.
### Dépannage
Nous ajouterons ici des conseils de dépannage. Notez que, bien que nous ne proposions normalement du support qu'aux clients Server Pro, compte tenu de la nature de cette migration, nous ferons également de notre mieux pour aider les utilisateurs de CE qui rencontrent des problèmes spécifiques à la migration des fichiers binaires.
Si le script de migration des fichiers binaires échoue (c'est-à-dire s'il se termine avec une erreur ou affiche un nombre non nul de projets en échec), envoyez les informations suivantes à notre équipe de support par e-mail [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), en précisant :
Objet : Binary file migration problem
Corps du message :
* Type d'instance : CE ou Server Pro (rayez la mention inutile)
* Type d'installation : Overleaf toolkit, `docker-compose.yml` ou autre (rayez la mention inutile)
* Version : 5.5.x (toolkit : `$ cat config/version`)
* Sortie du script de migration (qui devrait se trouver dans le conteneur sous `/var/log/overleaf`)
* Rapport : (exécutez le script de migration avec `--report`)
* Projets traités : (d'après la dernière exécution du script)
* Durée de la migration :
* Sortie de `bin/doctor` (si vous utilisez le toolkit)
* Version du Toolkit : `$ git rev-parse HEAD` (si vous utilisez le Toolkit)
Pensez à joindre à l'e-mail les fichiers journaux du service `filestore`. Vous les trouverez dans `/var/log/overleaf/filestore.log` à l'intérieur du conteneur `sharelatex` et pouvez les exporter ainsi :
```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 .
```
Veuillez masquer toute information sensible dans les fichiers journaux avant de les joindre.
#### Fichiers manquants
Les anciennes versions de Server Pro/CE créaient les entrées de l'arborescence de fichiers avant la fin des téléversements des utilisateurs, ce qui pouvait faire apparaître des fichiers comme manquants en cas d'échec d'un téléversement. Il est possible que quelques-uns de ces cas soient signalés comme erreurs lors du traitement de l'ensemble des arborescences de fichiers.
Si le nombre de fichiers manquants est faible, envisagez d'examiner ces cas manuellement et de les supprimer depuis l'éditeur dans le navigateur.
Si le nombre de fichiers manquants est élevé, envisagez de contacter le support ; voir le modèle d'e-mail ci-dessus.
#### Trouver les arborescences de fichiers endommagées
La migration peut échouer pour les projets dont l'arborescence de fichiers est malformée (par exemple, lorsque des noms de fichiers sont vides). Vous pouvez obtenir la liste de ces problèmes à l'aide du script `find_malformed_filetrees`, qui vérifie tous les projets de la base de données :
```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"
```
Pour corriger les chemins invalides, utilisez le script `fix_malformed_filetree`, en exécutant la commande une fois pour chaque chemin incorrect :
```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.