> 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/it/supporto/support-guides/v5.5.7-migration-binary-files-migration.md). # (Migrazione v5.5.7) Migrazione dei file binari ## Migrazione dei file binari La prossima versione principale `6.0` del rilascio di Server Pro e Community Edition ridurrà della metà l'uso di spazio di archiviazione dei file binari. Una migrazione online è inclusa nella versione `5.5.7` , consentendo tempi di inattività minimi nell'ambito dell'aggiornamento. Poiché Server Pro `4.x`, i file binari sono archiviati due volte: nell'archiviazione attiva dei file in "filestore" e nel sistema completo della cronologia del progetto. In futuro, per ogni file verrà conservata una sola copia nel sistema completo della cronologia del progetto. La migrazione al sistema di archiviazione consolidato è composta da due parti: un nuovo flag per controllare la fase della migrazione e uno script che elabora tutti i progetti attivi e quelli eliminati in modo non definitivo. Fasi: * `OVERLEAF_FILESTORE_MIGRATION_LEVEL=0` (predefinito), i file vengono letti e scritti in filestore. I file vengono scritti nella cronologia in modo asincrono. * `OVERLEAF_FILESTORE_MIGRATION_LEVEL=1` , i file vengono letti dalla cronologia con fallback al filestore e scritti sia nel filestore sia nella cronologia. Il downgrade a `OVERLEAF_FILESTORE_MIGRATION_LEVEL=0` è possibile. * `OVERLEAF_FILESTORE_MIGRATION_LEVEL=2` i file vengono letti e scritti solo nella cronologia. Il downgrade a `OVERLEAF_FILESTORE_MIGRATION_LEVEL=1` non è possibile, a meno che non sia stato eseguito "offline". Quando si archiviano i dati in [S3](https://docs.overleaf.com/on-premises/configuration/overleaf-toolkit/s3) e si utilizzano account di servizio separati per filestore (`OVERLEAF_FILESTORE_S3_ACCESS_KEY_ID`) e cronologia (`OVERLEAF_HISTORY_S3_ACCESS_KEY_ID`): concedere all'utente filestore l'accesso in lettura al bucket della cronologia per i blob `OVERLEAF_HISTORY_PROJECT_BLOBS_BUCKET` . In futuro, il servizio filestore servirà le letture dal servizio compiler. {% hint style="warning" %} È vivamente consigliato eseguire prima la migrazione dei file binari in un ambiente non di produzione/sandbox. {% endhint %} {% hint style="success" %} La licenza standard di Server Pro consente di eseguire l'applicazione in un ambiente di produzione e in uno non di produzione/sandbox; è fortemente consigliato predisporre un ambiente non di produzione per i test. {% endhint %} {% hint style="info" %} Se esegui l'aggiornamento alla versione Server Pro/CE `6.0` e in seguito decidi di voler eseguire il downgrade a una versione precedente, allora dovresti ripristinare da un backup completo del sistema. {% endhint %} ### Procedura di migrazione {% stepper %} {% step %} #### Crea un backup Crea un backup completo [backup](https://docs.overleaf.com/on-premises/maintenance/data-and-backups#performing-a-consistent-backup) della tua istanza con un'istantanea coerente delle **mongo**, **redis** e **sharelatex** directory. {% endstep %} {% step %} #### Aggiorna **Toolkit:** Usa il `$ bin/upgrade` script per aggiornare il **toolkit** all'ultima versione. Quando richiesto, non **non** confermare la richiesta **Aggiorna** immagine? — invece, modifica manualmente **config/version** file e imposta il valore su `5.5.7`. **Vecchio docker-compose.yml:** Aggiorna la versione della `sharelatex` servizio a `5.5.7`. {% endstep %} {% step %} #### Stima il numero di progetti interessati {% code overflow="wrap" %} ```bash # Utenti di 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" # Utenti di 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 %} Esempio di output: {% code fullWidth="false" %} ``` Stato attuale: - Numero totale di progetti: 10 - Numero totale di progetti eliminati: 5 Campionamento di 1000 progetti per stimare l'avanzamento... Statistiche campionate per i progetti: - Progetti campionati: 9 (90% di tutti i progetti) - Progetti campionati con tutti gli hash presenti: 5 - Percentuale di progetti che richiedono il backfilling degli hash: 44% (stimato) - I progetti campionati hanno 11 file che devono essere verificati rispetto al sistema completo della cronologia del progetto. - I progetti campionati hanno 3 file che devono essere caricati nel sistema completo della cronologia del progetto (stima del 27% di tutti i file). Statistiche campionate per i progetti eliminati: - Progetti eliminati campionati: 4 (80% di tutti i progetti eliminati) - Progetti eliminati campionati con tutti gli hash presenti: 3 - Percentuale di progetti eliminati che richiedono il backfilling degli hash: 25% (stimato) - I progetti eliminati campionati hanno 2 file che devono essere verificati rispetto al sistema completo della cronologia del progetto. - I progetti eliminati campionati hanno 1 file che deve essere caricato nel sistema completo della cronologia del progetto (stima del 50% di tutti i file). ``` {% endcode %} {% endstep %} {% step %} #### Svuota le code della cronologia del progetto {% code overflow="wrap" %} ```bash # Utenti di Overleaf Toolkit: $ bin/docker-compose exec sharelatex /overleaf/bin/flush-history-queues # Utenti di Legacy docker-compose.yml: $ docker compose exec sharelatex /overleaf/bin/flush-history-queues ``` {% endcode %} Ripeti lo svuotamento finché tutti i progetti non saranno stati svuotati (`"project_ids":0`). ``` progetti trovati {"project_ids":0,"limit":100000,"ts":"2025-09-01T10:35:33.353Z"} totale {"succeededProjects":0,"failedProjects":0} ``` {% hint style="danger" %} Se "failedProjects" non è zero, contatta l'assistenza e non continuare con la migrazione dei file binari. {% endhint %} {% endstep %} {% step %} #### Avanza la fase di migrazione a 1 Toolkit: imposta `OVERLEAF_FILESTORE_MIGRATION_LEVEL=1` in `config/variables.env`. Vecchio docker-compose.yml: imposta `OVERLEAF_FILESTORE_MIGRATION_LEVEL: '1'` nel `ambiente` sezione del `sharelatex` servizio. {% endstep %} {% step %} #### Applica la modifica di configurazione e avvia l'istanza Toolkit: `bin/up -d` Vecchio docker-compose.yml: `docker compose up -d` {% endstep %} {% step %} #### Verifica l'accesso ai file binari Apri un progetto nell'editor di Overleaf nel browser e seleziona un file binario, ad esempio un'immagine. {% endstep %} {% step %} #### Esegui lo script di migrazione {% code overflow="wrap" %} ```bash # Utenti di 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" # Utenti di 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" %} Se stai [persistendo i log](https://docs.overleaf.com/on-premises/configuration/overleaf-toolkit/logging#persisting-logs) i file al di fuori del **sharelatex** container, assicurati che il proprietario della directory dei log sia impostato sull' `www-data` utente (uid=33) in modo che il file di log generato possa essere scritto. {% endhint %} L'output dovrebbe apparire così: ```bash Set UV_THREADPOOL_SIZE=16 {"name":"default","hostname":"c25e9faaeb53","pid":971,"level":30,"backend":"fs","msg":"Caricamento del backend","time":"2025-07-25T15:00:58.166Z","v":0} Scrittura dei log in /var/log/overleaf/file-migration-2025-07-25T15_00_58_199Z.log Avvio del backup dei file del progetto... Blob globali caricati: 0 Elaborazione dei progetti non eliminati... Elaborati 1 progetti, tempo trascorso 0s Aggiornamento dei progetti attivi completato Elaborazione dei progetti eliminati... La raccolta deletedProjects sembra essere vuota. Aggiornamento dei progetti eliminati completato Fatto. ``` Se la migrazione ha successo, otterrai un codice di uscita pari a `0`, e le ultime righe indicheranno che non ci sono stati fallimenti: ```bash Fatto. ``` Il file di log apparirà così (usa il percorso come stampato dallo 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":"batch completato effettivamente","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":"statistiche di file-migration","v":0} ``` {% endcode %} {% endstep %} {% step %} #### Arresta l'istanza Toolkit: `bin/stop sharelatex` Vecchio docker-compose.yml: `docker compose stop sharelatex` {% endstep %} {% step %} #### Rendi i vecchi file inaccessibili all'applicazione Ora puoi spostare i vecchi file su un archivio secondario. Consigliamo di conservare i file per un po' nel caso sorgano problemi in seguito. {% code overflow="wrap" %} ```bash # Utenti di 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 # Utenti di Legacy docker-compose.yml: # Supponiamo che tu stia utilizzando il bind-mount predefinito 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 # Nel caso in cui tu stia utilizzando bind-mount selettivi, puoi semplicemente rimuovere il bind-mount per /var/lib/overleaf/data/user_files all'interno del container. ``` {% endcode %} {% endstep %} {% step %} #### Avanza la fase di migrazione a 2 Toolkit: imposta `OVERLEAF_FILESTORE_MIGRATION_LEVEL=2` in `config/variables.env`. Vecchio docker-compose.yml: imposta `OVERLEAF_FILESTORE_MIGRATION_LEVEL: '2'` nel `ambiente` sezione del `sharelatex` servizio. {% endstep %} {% step %} #### Applica la modifica di configurazione e avvia l'istanza Toolkit: `bin/up -d` Vecchio docker-compose.yml: `docker compose up -d` {% endstep %} {% step %} #### Verifica l'accesso ai file binari Apri un progetto nell'editor di Overleaf nel browser e seleziona un file binario, ad esempio un'immagine. {% endstep %} {% endstepper %} #### Migrazione offline Se vuoi impedire agli utenti di accedere mentre lo script di migrazione dei file binari è in esecuzione, segui questi passaggi: * Accedi alla tua istanza Overleaf con un account amministratore * Fai clic sul **Amministratore** pulsante e scegli **Gestisci il sito** * Fai clic sul **Apri/chiudi editor** scheda * Fai clic sul **Chiudi editor** pulsante * Fai clic sul **Disconnetti tutti gli utenti** pulsante Una volta fatto ciò, se ci sono utenti connessi verranno reindirizzati alla pagina di manutenzione, e qualsiasi nuovo utente che visiti la pagina di accesso vedrà la pagina di manutenzione e **non potranno** accedere. Devi ripetere questi passaggi quando riavvii l'istanza. Per riaprire il sito, è sufficiente riavviare l'istanza. #### Migrazione online È possibile eseguire gli script di migrazione mentre l'applicazione è ancora in esecuzione. Ci sono alcune considerazioni da tenere a mente: * Il processo di migrazione è intensivo in termini di I/O; dovresti monitorare l'utilizzo delle risorse mentre lo script è in esecuzione. * Con un'elevata concorrenza di elaborazione, l'event loop nel `filestore` servizio potrebbe subire dei blocchi, il che porterebbe a un'esperienza utente degradata. Consigliamo di iniziare con i valori predefiniti di `--concurrency=10` e `--concurrent-batches=1` . * Puoi interrompere lo script in qualsiasi momento. Riavviandolo convaliderà i progetti precedenti e salterà i file già elaborati. Questo è utile nel caso in cui tu preferisca eseguire la migrazione in orari meno trafficati (ad es. di notte). La nostra raccomandazione è di chiudere il sito ed eseguire la migrazione offline in una finestra di manutenzione quando il numero dei progetti è inferiore a 1000 (vedi l'output dello script di migrazione eseguito con `--report`). Se il numero di progetti è elevato, puoi eseguire lo script e monitorarne l'avanzamento, quindi decidere se continuare a eseguirlo online o offline in base al tuo caso specifico. #### Pulisci i dati legacy dei file binari Quando hai terminato la migrazione e verificato che i progetti possano ancora accedere a tutti i loro file, puoi rimuovere il vecchio archivio file in `/var/lib/overleaf/data/user_files`. Consigliamo vivamente di conservare questi file per un po' - puoi renderli inaccessibili all'applicazione rinominando prima la cartella. ### Risoluzione dei problemi Aggiungeremo qui consigli per la risoluzione dei problemi. Tieni presente che, sebbene normalmente offriamo supporto solo ai clienti Server Pro, data la natura di questa migrazione faremo del nostro meglio per supportare anche i clienti CE che riscontrano problemi specifici della migrazione dei file binari. Se lo script di migrazione dei file binari fallisce (cioè termina con un errore o stampa un numero non nullo di progetti falliti), invia i seguenti dettagli al nostro team di supporto via email [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), specificando: Oggetto: Problema di migrazione dei file binari Corpo: * Tipo di istanza: CE o Server Pro (elimina la voce non pertinente) * Tipo di installazione: Overleaf toolkit o `docker-compose.yml` o altro (elimina la voce non pertinente) * Versione: 5.5.x (toolkit: `$ cat config/version`) * Output dello script di migrazione (che dovrebbe trovarsi nel container in `/var/log/overleaf`) * Report: (esegui lo script di migrazione con `--report`) * Progetti elaborati: (secondo l'ultima esecuzione dello script) * Durata della migrazione: * `bin/doctor` output (quando si usa toolkit) * Versione del Toolkit: `$ git rev-parse HEAD` (quando si usa Toolkit) Valuta di allegare i file di log dei `filestore` servizio all'email. Lo puoi trovare in `/var/log/overleaf/filestore.log` all'interno del `sharelatex` container ed esportarli così: ```bash $ docker cp sharelatex:/var/log/overleaf/filestore.log . # sostituisci con il timestamp stampato dallo script $ docker cp sharelatex:/var/log/overleaf/file-migration-.log . ``` Rimuovi eventuali informazioni sensibili dai file di log prima di allegarli. #### File mancanti Le versioni precedenti di Server Pro/CE creavano voci nell'albero dei file prima del completamento degli upload degli utenti, il che poteva far apparire mancanti dei file quando un upload falliva. Potresti trovare alcuni di questi casi segnalati come errori durante l'elaborazione di tutti gli alberi dei file. Se il numero di file mancanti è basso, considera di esaminare manualmente questi casi ed eliminarli dall'editor nel browser. Se il numero di file mancanti è alto, considera di contattare l'assistenza; vedi il modello di email sopra. #### Individuazione degli alberi di file danneggiati La migrazione può fallire per i progetti che hanno una struttura di file malformata (ad esempio, quando i nomi dei file sono vuoti). Puoi trovare un elenco di questi problemi usando lo `find_malformed_filetrees` script che controlla tutti i progetti nel database: {% 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 %} Per correggere i percorsi non validi, usa lo `fix_malformed_filetree` script, eseguendo il comando una volta per ogni percorso non valido: {% 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/it/supporto/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.