> 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/fr/support/support-guides/v5.5.7-migration-binary-files-migration.md). # (Migration v5.5.7) Migration des fichiers binaires ## Migration des fichiers binaires La prochaine version majeure `6.0` de Server Pro et Community Edition réduira de moitié l'utilisation du stockage des fichiers binaires. Une migration en ligne est incluse dans la version `5.5.7` , permettant un temps d'arrêt minimal dans le cadre de la mise à niveau. Depuis Server Pro `4.x`, les fichiers binaires sont stockés deux fois : dans le stockage des fichiers actifs dans « filestore » et dans le système d'historique complet du projet. À l'avenir, une seule copie de chaque fichier sera stockée dans le système d'historique complet du projet. La migration vers le système de stockage consolidé comprend deux parties : un nouveau drapeau 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. Phases : * `OVERLEAF_FILESTORE_MIGRATION_LEVEL=0` (par défaut), les fichiers sont lus et écrits dans le 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 vers le filestore et écrits à la fois dans le 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 cela a été effectué « hors ligne ». Lors du stockage des données dans [S3](https://docs.overleaf.com/on-premises/configuration/overleaf-toolkit/s3) et lors de l'utilisation de comptes de service distincts pour le filestore (`OVERLEAF_FILESTORE_S3_ACCESS_KEY_ID`) et l'historique (`OVERLEAF_HISTORY_S3_ACCESS_KEY_ID`) : veuillez accorder à l'utilisateur du filestore l'accès en lecture au bucket d'historique pour les blobs `OVERLEAF_HISTORY_PROJECT_BLOBS_BUCKET` . Le service filestore servira désormais les lectures depuis le service de compilation. {% hint style="warning" %} Il est fortement recommandé d'effectuer d'abord la migration des fichiers binaires dans un environnement de préproduction/sandbox. {% endhint %} {% hint style="success" %} La licence standard Server Pro vous permet d'exécuter l'application dans un environnement de production ainsi que dans un environnement de préproduction/sandbox ; il est fortement recommandé de provisionner un environnement de préproduction pour les tests. {% endhint %} {% hint style="info" %} Si vous mettez à niveau vers Server Pro/CE version `6.0` et décidez ensuite de revenir à une version antérieure, vous devez alors restaurer une sauvegarde complète du système. {% endhint %} ### Procédure de migration {% stepper %} {% step %} #### Créer une sauvegarde Créez une [sauvegarde complète](https://docs.overleaf.com/on-premises/maintenance/data-and-backups#performing-a-consistent-backup) de votre instance avec un instantané cohérent des **mongo**, **redis** et **conteneur sharelatex.** répertoires. {% endstep %} {% step %} #### Mettez à jour **Toolkit :** Utilisez la `$ bin/upgrade` script pour mettre à niveau le **toolkit** vers la version la plus récente. Lorsque cela vous est demandé, ne **ne pas** confirmez pas l'invite **Mettre à niveau** image ? — à la place, modifiez manuellement **config/version** le fichier et définissez la valeur sur `5.5.7`. **Ancien docker-compose.yml :** Mettez à jour la version du `conteneur sharelatex.` service à `5.5.7`. {% endstep %} {% step %} #### Estimez le nombre de projets concernés {% code overflow="wrap" %} ```bash # utilisateurs de Overleaf Toolkit : $ 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" # Utilisateurs de l'ancien 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 %} Exemple de sortie : {% code fullWidth="false" %} ``` État actuel : - Nombre total de projets : 10 - Nombre total de projets supprimés : 5 Échantillonnage de 1000 projets pour estimer l'avancement... Statistiques d'échantillon pour les projets : - Projets échantillonnés : 9 (90 % de tous les projets) - Projets échantillonnés avec tous les hachages présents : 5 - Pourcentage de projets nécessitant un réapprovisionnement des hachages : 44 % (estimé) - Les projets échantillonnés comportent 11 fichiers à vérifier par rapport au système d'historique complet du projet. - Les projets échantillonnés comportent 3 fichiers à téléverser vers le système d'historique complet du projet (estimation de 27 % de tous les fichiers). Statistiques d'échantillon pour les projets supprimés : - Projets supprimés échantillonnés : 4 (80 % de tous les projets supprimés) - Projets supprimés échantillonnés avec tous les hachages présents : 3 - Pourcentage de projets supprimés nécessitant un réapprovisionnement des hachages : 25 % (estimé) - Les projets supprimés échantillonnés comportent 2 fichiers à vérifier par rapport au système d'historique complet du projet. - Les projets supprimés échantillonnés comportent 1 fichier à téléverser vers le système d'historique complet du projet (estimation de 50 % de tous les fichiers). ``` {% endcode %} {% endstep %} {% step %} #### Vider les files d'attente de l'historique des projets {% code overflow="wrap" %} ```bash # utilisateurs de Overleaf Toolkit : $ bin/docker-compose exec sharelatex /overleaf/bin/flush-history-queues # Utilisateurs de l'ancien docker-compose.yml : $ docker compose exec sharelatex /overleaf/bin/flush-history-queues ``` {% endcode %} Répétez le vidage jusqu'à ce que tous les projets aient été vidés (`"project_ids":0`). ``` projets trouvés {"project_ids":0,"limit":100000,"ts":"2025-09-01T10:35:33.353Z"} total {"succeededProjects":0,"failedProjects":0} ``` {% hint style="danger" %} Si « failedProjects » n'est pas égal à zéro, veuillez contacter le support et ne pas poursuivre la migration des fichiers binaires. {% endhint %} {% endstep %} {% step %} #### Faire passer la phase de migration à 1 Toolkit : définir `OVERLEAF_FILESTORE_MIGRATION_LEVEL=1` dans `config/variables.env`. Ancien docker-compose.yml : définir `OVERLEAF_FILESTORE_MIGRATION_LEVEL: '1'` dans le `environnement` section du `conteneur sharelatex.` service. {% endstep %} {% step %} #### Appliquez le changement de configuration et démarrez l'instance Toolkit : `bin/up -d` Ancien docker-compose.yml : `docker compose up -d` {% endstep %} {% step %} #### Vérifier l'accès aux fichiers binaires Ouvrez un projet dans l'éditeur Overleaf dans le navigateur et sélectionnez un fichier binaire, comme une image. {% endstep %} {% step %} #### Exécutez le script de migration {% code overflow="wrap" %} ```bash # utilisateurs de Overleaf Toolkit : $ 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" # Utilisateurs de l'ancien 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" %} Si vous [conservez des journaux](https://docs.overleaf.com/on-premises/configuration/overleaf-toolkit/logging#persisting-logs) fichiers en dehors du **conteneur sharelatex.** conteneur, assurez-vous que le propriétaire du répertoire des journaux est défini sur l'utilisateur `www-data` (uid=33) afin que le fichier journal généré puisse être écrit. {% endhint %} La sortie devrait ressembler à ceci : ```bash Définissez UV_THREADPOOL_SIZE=16 {"name":"default","hostname":"c25e9faaeb53","pid":971,"level":30,"backend":"fs","msg":"Chargement du backend","time":"2025-07-25T15:00:58.166Z","v":0} Écriture des journaux dans /var/log/overleaf/file-migration-2025-07-25T15_00_58_199Z.log Démarrage de la sauvegarde des fichiers de projet... Blobs globaux chargés : 0 Traitement des projets non supprimés... 1 projet traité, temps écoulé 0 s Mise à jour des projets actifs terminée Traitement des projets supprimés... La collection deletedProjects semble être vide. Mise à jour des projets supprimés terminée Terminé. ``` Si la migration réussit, vous obtiendrez un code de sortie de `0`, ainsi que les dernières lignes indiquant qu’il n’y a eu aucun échec : ```bash Terminé. ``` Le fichier journal ressemblera à ceci (utilisez le chemin tel qu'affiché par le script) : {% 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":"lot réellement terminé","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":"statistiques de file-migration","v":0} ``` {% endcode %} {% endstep %} {% step %} #### Arrêter l'instance Toolkit : `bin/stop sharelatex` Ancien docker-compose.yml : `docker compose stop sharelatex` {% endstep %} {% step %} #### Rendre les anciens fichiers inaccessibles à l'application Vous pouvez maintenant déplacer les anciens fichiers vers un stockage secondaire. Nous recommandons de conserver les fichiers pendant un certain temps au cas où des problèmes surviendraient plus tard. {% code overflow="wrap" %} ```bash # Utilisateurs de Toolkit : $ bin/docker-compose run --rm --entrypoint mv sharelatex --no-clobber --verbose /var/lib/overleaf/data/user_files /var/lib/overleaf/data/old_user_files # Utilisateurs de l'ancien docker-compose.yml : # Nous supposons que vous utilisez le bind-mount par défaut dans /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 # Si vous utilisez des bind-mounts sélectifs, vous pouvez simplement supprimer le bind-mount pour /var/lib/overleaf/data/user_files à l'intérieur du conteneur. ``` {% endcode %} {% endstep %} {% step %} #### Faire passer la phase de migration à 2 Toolkit : définir `OVERLEAF_FILESTORE_MIGRATION_LEVEL=2` dans `config/variables.env`. Ancien docker-compose.yml : définir `OVERLEAF_FILESTORE_MIGRATION_LEVEL: '2'` dans le `environnement` section du `conteneur sharelatex.` service. {% endstep %} {% step %} #### Appliquez le changement de configuration et démarrez l'instance Toolkit : `bin/up -d` Ancien docker-compose.yml : `docker compose up -d` {% endstep %} {% step %} #### Vérifier l'accès aux fichiers binaires Ouvrez un projet dans l'éditeur Overleaf dans le navigateur et sélectionnez un fichier binaire, comme une image. {% endstep %} {% endstepper %} #### la migration hors ligne Si vous souhaitez empêcher les utilisateurs de se connecter pendant l'exécution du script de migration des fichiers binaires, veuillez suivre ces étapes : * Connectez-vous à votre instance Overleaf avec un compte administrateur * Cliquez sur le **Admin** bouton et choisissez **Gérer le site** * Cliquez sur le **Ouvrir/Fermer l’éditeur** onglet * Cliquez sur le **Fermer l’éditeur** bouton * Cliquez sur le **Déconnecter tous les utilisateurs** bouton Une fois cela fait, si des utilisateurs sont connectés, ils seront redirigés vers la page de maintenance, et tout nouvel utilisateur visitant la page de connexion verra la page de maintenance et **ne le fera pas** pourra se connecter. Vous devez répéter ces étapes lors du redémarrage de l'instance. Pour rouvrir le site, redémarrez simplement l'instance. #### Migration en ligne Il est possible d’exécuter les scripts de migration pendant que l’application est encore en cours d’exécution. Il y a quelques points à prendre en compte : * Le processus de migration est intensif en E/S ; vous devez surveiller l'utilisation des ressources pendant l'exécution du script. * Avec une forte concurrence de traitement, la boucle d'événements du `filestore` service peut subir un certain blocage, ce qui entraînerait une expérience utilisateur dégradée. Nous recommandons de commencer avec les valeurs par défaut de `--concurrency=10` et `--concurrent-batches=1` . * Vous pouvez arrêter le script à tout moment. Le relancer 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 des heures moins chargées (par exemple la nuit). Notre recommandation est de fermer le site et d'exécuter la migration hors ligne pendant une fenêtre de maintenance lorsque votre nombre de projets est inférieur à 1000 projets (voir la sortie du script de migration lors de l'exécution avec `--report`). Si le nombre de projets est important, vous pouvez exécuter le script et suivre sa progression, puis décider s’il faut continuer à l’exécuter en ligne ou hors ligne selon votre cas particulier. #### Nettoyer les anciennes données de fichiers binaires Une fois la migration terminée et après avoir vérifié que les projets peuvent toujours accéder à tous leurs fichiers, vous pouvez supprimer l'ancien stockage de fichiers dans `/var/lib/overleaf/data/user_files`. Nous recommandons fortement de conserver ces fichiers pendant un certain temps - vous pouvez les rendre inaccessibles à l'application en renommant d'abord le dossier. ### Dépannage Nous ajouterons ici des conseils de dépannage. Veuillez noter que, bien que nous offrions normalement une assistance uniquement aux clients Server Pro, compte tenu de la nature de cette migration, nous ferons également de notre mieux pour aider les clients CE qui rencontrent des problèmes spécifiques à la migration des fichiers binaires. Si le script de migration des fichiers binaires échoue (c.-à-d. se termine avec une erreur ou affiche un nombre non nul de projets en échec), veuillez envoyer les détails suivants à 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 : Problème de migration des fichiers binaires Corps : * Type d’instance : CE ou Server Pro (supprimez la mention inutile) * Type d’installation : Overleaf Toolkit ou `docker-compose.yml` ou autre (supprimez 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 : (selon le dernier lancement du script) * Durée de la migration : * `bin/doctor` sortie (lors de l’utilisation du toolkit) * Version du toolkit : `$ git rev-parse HEAD` (lors de l’utilisation du toolkit) Pensez à joindre les fichiers journaux des `filestore` service au courrier électronique. Vous pouvez le trouver à `/var/log/overleaf/filestore.log` à l’intérieur du `conteneur sharelatex.` conteneur et les exporter ainsi : ```bash $ docker cp sharelatex:/var/log/overleaf/filestore.log . # remplacez par l'horodatage tel qu'affiché par le 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 des entrées de l'arborescence des fichiers avant la fin des téléversements des utilisateurs, ce qui pouvait faire apparaître des fichiers comme manquants lorsqu'un téléversement échouait. Vous pourriez trouver quelques-uns de ces cas signalés comme des erreurs lors du traitement de toutes les arborescences de fichiers. Si le nombre de fichiers manquants est faible, envisagez d'examiner manuellement ces cas et de les supprimer dans l'éditeur du navigateur. Si le nombre de fichiers manquants est élevé, envisagez de contacter le support, voir le modèle d'e-mail ci-dessus. #### Recherche d’arbres de fichiers corrompus La migration peut échouer pour les projets dont l’arborescence de fichiers est mal formée (par exemple, lorsque les noms de fichiers sont vides). Vous pouvez trouver une liste de ces problèmes à l’aide du `find_malformed_filetrees` script qui vérifie tous les projets dans la base de données : {% 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 %} Pour corriger les chemins invalides, utilisez le `fix_malformed_filetree` script, en exécutant la commande une fois pour chaque chemin incorrect : {% 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/fr/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.