(Migrazione v5.5.7) Migrazione dei file binari

​

Migrazione dei file binari

La prossima versione principale 6.0 di Server Pro e Community Edition dimezzerà lo spazio di archiviazione utilizzato dai file binari. Nella versione 5.5.7 è inclusa una migrazione online, che consente di ridurre al minimo i tempi di inattività durante l’aggiornamento.

A partire da Server Pro 4.x, i file binari vengono memorizzati due volte: nell’archivio dei file attivi in “filestore” e nel sistema di cronologia completa dei progetti. D’ora in poi, verrà memorizzata un’unica copia di ciascun file nel sistema di cronologia completa dei progetti.

La migrazione al sistema di archiviazione consolidato si compone di due parti: un nuovo flag per controllare la fase della migrazione e uno script che elabora tutti i progetti attivi ed eliminati in modo reversibile (soft-deleted).

Fasi:

• OVERLEAF_FILESTORE_MIGRATION_LEVEL=0 (predefinito): i file vengono letti e scritti nel filestore. I file vengono scritti nella cronologia in modo asincrono.
• OVERLEAF_FILESTORE_MIGRATION_LEVEL=1: i file vengono letti dalla cronologia con fallback sul filestore e scritti sia nel filestore sia nella cronologia. È possibile tornare a OVERLEAF_FILESTORE_MIGRATION_LEVEL=0.
• OVERLEAF_FILESTORE_MIGRATION_LEVEL=2: i file vengono letti e scritti solo nella cronologia. Non è possibile tornare a OVERLEAF_FILESTORE_MIGRATION_LEVEL=1, a meno che la migrazione non sia stata eseguita “offline”.

Se memorizzi i dati in S3 e usi account di servizio separati per filestore (OVERLEAF_FILESTORE_S3_ACCESS_KEY_ID) e history (OVERLEAF_HISTORY_S3_ACCESS_KEY_ID): concedi all’utente del filestore l’accesso in lettura al bucket della cronologia per i blob OVERLEAF_HISTORY_PROJECT_BLOBS_BUCKET. D’ora in poi il servizio filestore gestirà le letture provenienti dal servizio di compilazione.

Si consiglia vivamente di eseguire prima la migrazione dei file binari in un ambiente non di produzione/sandbox.

La licenza standard di Server Pro consente di eseguire l’applicazione in un ambiente di produzione e in uno non di produzione/sandbox; ti consigliamo vivamente di predisporre un ambiente non di produzione per i test.

Se esegui l’aggiornamento a Server Pro/CE versione 6.0 e in seguito decidi di tornare a una versione precedente, dovrai eseguire il ripristino da un backup completo del sistema.

​

Procedura di migrazione

1. Creare un backup

   Crea un backup completo della tua istanza con uno snapshot coerente delle directory mongo, redis e sharelatex.

2. Aggiornare

   Toolkit: usa lo script $ bin/upgrade per aggiornare il toolkit all’ultima versione. Quando richiesto, non confermare la domanda Upgrade image?; modifica invece manualmente il file config/version e imposta il valore su 5.5.7.

   docker-compose.yml legacy: aggiorna la versione del servizio sharelatex a 5.5.7.

3. Stimare il numero di progetti interessati

   # 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"
   

   Output di esempio:

   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).
   
4. Svuotare le code della cronologia dei progetti

   # 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
   

   Ripeti lo svuotamento finché tutti i progetti non sono stati elaborati ("project_ids":0).

   found projects {"project_ids":0,"limit":100000,"ts":"2025-09-01T10:35:33.353Z"}
   total {"succeededProjects":0,"failedProjects":0}
   

   Se “failedProjects” è diverso da zero, contatta il supporto e non proseguire con la migrazione dei file binari.

5. Avanzare 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' nella sezione environment del servizio sharelatex.

6. Applicare la modifica alla configurazione e avviare l'istanza

   Toolkit: bin/up -d

   Legacy docker-compose.yml: docker compose up -d

7. Verificare l'accesso ai file binari

   Apri un progetto nell’editor di Overleaf nel browser e seleziona un file binario, ad esempio un’immagine.

8. Eseguire lo script di migrazione

   # 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"
   

   Se stai rendendo persistenti i file di log all’esterno del container sharelatex, assicurati che il proprietario della directory dei log sia l’utente www-data (uid=33), in modo che il file di log prodotto possa essere scritto.

   L’output dovrebbe essere simile a questo:

   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.
   
   

   Se la migrazione va a buon fine, otterrai un codice di uscita 0 e le ultime righe non indicheranno errori:

   Done.
   

   Il file di log sarà simile a questo (usa il percorso stampato dallo script):

   $ 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}
   
9. Arrestare l'istanza

   Toolkit: bin/stop sharelatex

   Legacy docker-compose.yml: docker compose stop sharelatex

10. Rendere i vecchi file inaccessibili all'applicazione

    Ora puoi spostare i vecchi file su uno storage secondario. Ti consigliamo di conservarli per un po’ di tempo nel caso in cui emergano problemi in seguito.

    # 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.
    
11. Avanzare 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' nella sezione environment del servizio sharelatex.

12. Applicare la modifica alla configurazione e avviare l'istanza

    Toolkit: bin/up -d

    Legacy docker-compose.yml: docker compose up -d

13. Verificare l'accesso ai file binari

    Apri un progetto nell’editor di Overleaf nel browser e seleziona un file binario, ad esempio un’immagine.

​

Migrazione offline

Se vuoi impedire agli utenti di accedere mentre è in esecuzione lo script di migrazione dei file binari, segui questi passaggi:

• Accedi alla tua istanza di Overleaf con un account amministratore
• Fai clic sul pulsante Admin e scegli Manage Site
• Fai clic sulla scheda Open/Close Editor
• Fai clic sul pulsante Close Editor
• Fai clic sul pulsante Disconnect all users

Una volta fatto, gli eventuali utenti connessi verranno reindirizzati alla pagina di manutenzione, e i nuovi utenti che visitano la pagina di accesso vedranno 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 presenti:

• Il processo di migrazione è intensivo in termini di I/O; dovresti monitorare l’utilizzo delle risorse durante l’esecuzione dello script.
• Con un’elevata concorrenza di elaborazione, l’event loop del servizio filestore potrebbe subire dei blocchi, con un conseguente peggioramento dell’esperienza utente. Ti consigliamo di iniziare con i valori predefiniti --concurrency=10 e --concurrent-batches=1.
• Puoi interrompere lo script in qualsiasi momento. Riavviandolo, verranno convalidati i progetti precedenti e saltati i file già elaborati. Ciò è utile se preferisci eseguire la migrazione nelle ore di minor traffico (ad es. di notte).

Ti consigliamo 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 eseguito con --report). Se il numero di progetti è elevato, puoi eseguire lo script e monitorarne l’avanzamento, quindi decidere se continuare l’esecuzione online o offline in base al tuo caso specifico.

​

Pulire i dati legacy dei file binari

Una volta completata la migrazione e verificato che i progetti possano ancora accedere a tutti i propri file, puoi rimuovere il vecchio archivio dei file in /var/lib/overleaf/data/user_files. Ti consigliamo vivamente di conservare questi file per un po’ di tempo: puoi prima renderli inaccessibili all’applicazione rinominando la cartella.

​

Risoluzione dei problemi

Aggiungeremo qui dei consigli per la risoluzione dei problemi. Tieni presente che, sebbene normalmente offriamo supporto solo ai clienti di Server Pro, data la natura di questa migrazione faremo del nostro meglio per assistere anche i clienti CE che riscontrano problemi specifici della migrazione dei file binari.

Se lo script di migrazione dei file binari fallisce (ovvero termina con un errore o stampa un numero di progetti non riusciti diverso da zero), invia i seguenti dettagli al nostro team di supporto via email [e-mail], indicando:

Oggetto: Binary file migration problem

Corpo:

• Tipo di istanza: CE o Server Pro (elimina la voce non pertinente)
• Tipo di installazione: Overleaf toolkit, docker-compose.yml o altro (elimina le voci non pertinenti)
• 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:
• Output di bin/doctor (se usi il toolkit)
• Versione del Toolkit: $ git rev-parse HEAD (se usi il Toolkit)

Valuta la possibilità di allegare all’email i file di log del servizio filestore. Li trovi in /var/log/overleaf/filestore.log all’interno del container sharelatex e puoi esportarli così:

$ docker cp sharelatex:/var/log/overleaf/filestore.log .
# replace <timestamp> with the timestamp as printed by the script
$ docker cp sharelatex:/var/log/overleaf/file-migration-<timestamp>.log .

Rimuovi eventuali informazioni sensibili dai file di log prima di allegarli.

​

File mancanti

Le versioni precedenti di Server Pro/CE creavano le 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. Durante l’elaborazione di tutti gli alberi dei file potresti trovare alcuni di questi casi segnalati come errori.

Se il numero di file mancanti è basso, valuta di esaminare manualmente questi casi ed eliminarli dall’editor nel browser.

Se il numero di file mancanti è elevato, valuta di contattare il supporto; vedi il modello di email riportato sopra.

​

Individuare gli alberi dei file danneggiati

La migrazione potrebbe non riuscire per i progetti con un albero dei file malformato (ad esempio, con nomi di file vuoti). Puoi trovare un elenco di questi problemi usando lo script find_malformed_filetrees, che controlla tutti i progetti nel database:

$ 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"

Per correggere i percorsi non validi, usa lo script fix_malformed_filetree, eseguendo il comando una volta per ogni percorso errato:

$ 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"