> For the complete documentation index, see [llms.txt](https://ayakaleaf-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://ayakaleaf-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` rilascio di Server Pro ed Edizione Community ridurrà della metà l'utilizzo di archiviazione dei file binari. Una migrazione online è inclusa nella versione `5.5.7` , consentendo tempi di inattività minimi come parte dell'aggiornamento. Poiché Server Pro `4.x`, i file binari vengono archiviati due volte: nell'archiviazione dei file attivi in "filestore" e nel sistema completo della cronologia del progetto. In futuro, verrà archiviata una sola copia di ciascun file 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 temporaneo. 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 a filestore e scritti sia in filestore sia nella cronologia. È possibile il downgrade a `OVERLEAF_FILESTORE_MIGRATION_LEVEL=0` . * `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`): concedi 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" %} Si raccomanda vivamente di 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 raccomandato predisporre un ambiente non di produzione per i test. {% endhint %} {% hint style="info" %} Se aggiorni a Server Pro/CE versione `6.0` e in seguito decidi di 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](https://docs.overleaf.com/on-premises/maintenance/data-and-backups#performing-a-consistent-backup) completo della tua istanza con uno snapshot 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`. **docker-compose.yml legacy:** Aggiorna la versione del `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 con docker-compose.yml legacy: $ 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 necessitano del backfilling degli hash: 44% (stimata) - I progetti campionati hanno 11 file che devono essere controllati 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 (stimando il 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 necessitano del backfilling degli hash: 25% (stimata) - I progetti eliminati campionati hanno 2 file che devono essere controllati 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 (stimando il 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 con docker-compose.yml legacy: $ docker compose exec sharelatex /overleaf/bin/flush-history-queues ``` {% endcode %} Ripeti lo svuotamento finché tutti i progetti non sono 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" %} Nel caso in cui "failedProjects" non sia zero, contatta il supporto 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`. docker-compose.yml legacy: imposta `OVERLEAF_FILESTORE_MIGRATION_LEVEL: '1'` nel `ambiente` sezione del `sharelatex` servizio. {% endstep %} {% step %} #### Applica la modifica alla configurazione e avvia l'istanza Toolkit: `bin/up -d` docker-compose.yml legacy: `docker compose up -d` {% endstep %} {% step %} #### Verifica l'accesso ai file binari Apri un progetto nell'editor Overleaf nel browser e seleziona un file binario, come 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 con docker-compose.yml legacy: $ 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 [archiviando i log](https://docs.overleaf.com/on-premises/configuration/overleaf-toolkit/logging#persisting-logs) 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 essere simile a questo: ```bash Imposta 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... Elaborato 1 progetto, 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 avrà questo aspetto (usa il percorso 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` docker-compose.yml legacy: `docker compose stop sharelatex` {% endstep %} {% step %} #### Rendi i vecchi file inaccessibili all'applicazione Ora puoi spostare i vecchi file in un archivio secondario. Consigliamo di conservare i file per un po' di tempo nel caso in cui emergano problemi in seguito. {% code overflow="wrap" %} ```bash # Utenti 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 con docker-compose.yml legacy: # Stiamo assumendo 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 usando 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`. docker-compose.yml legacy: imposta `OVERLEAF_FILESTORE_MIGRATION_LEVEL: '2'` nel `ambiente` sezione del `sharelatex` servizio. {% endstep %} {% step %} #### Applica la modifica alla configurazione e avvia l'istanza Toolkit: `bin/up -d` docker-compose.yml legacy: `docker compose up -d` {% endstep %} {% step %} #### Verifica l'accesso ai file binari Apri un progetto nell'editor Overleaf nel browser e seleziona un file binario, come un'immagine. {% endstep %} {% endstepper %} #### Migrazione offline Se vuoi impedire agli utenti di effettuare l'accesso mentre lo script di migrazione dei file binari è in esecuzione, segui questi passaggi: * Accedi alla tua istanza Overleaf con un account amministratore * Fai clic su **Amministratore** pulsante e scegli **Gestisci sito** * Fai clic sul **Apri/chiudi editor** scheda * Fai clic su **Chiudi editor** pulsante * Fai clic su **Disconnetti tutti gli utenti** pulsante Una volta fatto questo, 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** potrà accedere. Devi ripetere questi passaggi quando riavvii l'istanza. Per riaprire il sito, basta riavviare l'istanza. #### Migrazione online È possibile eseguire gli script di migrazione mentre l'applicazione è ancora in esecuzione. Ci sono alcune considerazioni da tenere presenti: * 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 alcuni 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, verranno convalidati i progetti precedenti e verranno saltati i file già elaborati. Questo è utile nel caso in cui preferisca eseguire la migrazione in orari meno affollati (ad esempio di notte). La nostra raccomandazione è di chiudere il sito ed eseguire la migrazione offline in una finestra di manutenzione quando il numero di progetti è inferiore a 1000 (vedi l'output dello script di migrazione quando 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. #### Pulizia dei dati legacy dei file binari Quando hai terminato la migrazione e hai verificato che i progetti possano ancora accedere a tutti i loro file, puoi rimuovere il vecchio archivio dei file in `/var/lib/overleaf/data/user_files`. Consigliamo vivamente di conservare questi file per un po' di tempo: puoi renderli inaccessibili all'applicazione rinominando prima la cartella. ### Risoluzione dei problemi Qui aggiungeremo consigli per la risoluzione dei problemi. Nota che, sebbene normalmente offriamo supporto solo ai clienti Server Pro, data la natura di questa migrazione, faremo anche del nostro meglio per supportare i clienti CE che riscontrano problemi specifici della migrazione dei file binari. Se lo script di migrazione dei file binari fallisce (ad esempio termina con un errore o stampa un numero non nullo di progetti falliti), invia i seguenti dettagli al nostro team di supporto via 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), specificando: Oggetto: problema di migrazione dei file binari Corpo: * Tipo di istanza: CE o Server Pro (elimina se appropriato) * Tipo di installazione: Overleaf Toolkit o `docker-compose.yml` o altro (elimina se appropriato) * 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: (in base all'ultima esecuzione dello script) * Durata della migrazione: * `bin/doctor` output (quando si usa il Toolkit) * Versione del Toolkit: `$ git rev-parse HEAD` (quando si usa il Toolkit) Considera di allegare i file di log dei `filestore` servizio all'e-mail. Puoi trovarlo in `/var/log/overleaf/filestore.log` all'interno del `sharelatex` container ed esportarli in questo modo: ```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 qualsiasi informazione sensibile dai file di log prima di allegarli. #### File mancanti Le versioni precedenti di Server Pro/CE creavano voci dell'albero dei file prima del completamento dei caricamenti degli utenti, il che poteva far apparire i file come mancanti quando un caricamento falliva. Potresti trovare alcuni di questi casi segnalati come errori durante l'elaborazione di tutti gli alberi dei file. Nel caso in cui il numero di file mancanti sia basso, valuta di esaminare manualmente questi casi ed eliminarli dall'editor nel browser. Nel caso in cui il numero di file mancanti sia alto, considera di contattare il supporto, vedi il modello di e-mail sopra. #### Individuare alberi di file danneggiati La migrazione potrebbe fallire per progetti che hanno un albero dei file malformato (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 errato: {% 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://ayakaleaf-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.