(Migración v5.5.7) Migración de archivos binarios

​

Migración de archivos binarios

La próxima versión principal 6.0 de Server Pro y Community Edition reducirá a la mitad el uso de almacenamiento de los archivos binarios. La versión 5.5.7 incluye una migración en línea, que permite un tiempo de inactividad mínimo como parte de la actualización.

Desde Server Pro 4.x, los archivos binarios se almacenan dos veces: en el almacenamiento de archivos activos de “filestore” y en el sistema de historial completo de los proyectos. A partir de ahora, se almacenará una única copia de cada archivo en el sistema de historial completo de los proyectos.

La migración al sistema de almacenamiento consolidado consta de dos partes: un nuevo indicador para controlar la fase de la migración y un script que procesa todos los proyectos activos y eliminados de forma no definitiva (soft-deleted).

Fases:

• OVERLEAF_FILESTORE_MIGRATION_LEVEL=0 (predeterminado): los archivos se leen y escriben en filestore. Los archivos se escriben en el historial de forma asíncrona.
• OVERLEAF_FILESTORE_MIGRATION_LEVEL=1: los archivos se leen del historial, con filestore como alternativa, y se escriben tanto en filestore como en el historial. Es posible volver a OVERLEAF_FILESTORE_MIGRATION_LEVEL=0.
• OVERLEAF_FILESTORE_MIGRATION_LEVEL=2: los archivos se leen y escriben únicamente en el historial. No es posible volver a OVERLEAF_FILESTORE_MIGRATION_LEVEL=1, a menos que la migración se haya realizado “sin conexión”.

Si almacenas los datos en S3 y usas cuentas de servicio independientes para filestore (OVERLEAF_FILESTORE_S3_ACCESS_KEY_ID) y el historial (OVERLEAF_HISTORY_S3_ACCESS_KEY_ID): concede al usuario de filestore acceso de lectura al bucket del historial para blobs OVERLEAF_HISTORY_PROJECT_BLOBS_BUCKET. A partir de ahora, el servicio filestore atenderá las lecturas del servicio de compilación.

Se recomienda encarecidamente realizar primero la migración de archivos binarios en un entorno que no sea de producción/sandbox.

La licencia estándar de Server Pro te permite ejecutar la aplicación en un entorno de producción y también en uno que no sea de producción/sandbox; se recomienda encarecidamente que aprovisiones un entorno que no sea de producción para las pruebas.

Si actualizas a la versión 6.0 de Server Pro/CE y más adelante decides volver a una versión anterior, deberás restaurar a partir de una copia de seguridad completa del sistema.

​

Procedimiento de migración

1. Crear una copia de seguridad

   Crea una copia de seguridad completa de tu instancia con una instantánea coherente de los directorios mongo, redis y sharelatex.

2. Actualizar

   Toolkit: usa el script $ bin/upgrade para actualizar el toolkit a la última versión. Cuando se te pregunte, no confirmes la pregunta Upgrade image?; en su lugar, edita manualmente el archivo config/version y establece el valor en 5.5.7.

   docker-compose.yml heredado: actualiza la versión del servicio sharelatex a 5.5.7.

3. Estimar el número de proyectos afectados

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

   Ejemplo de salida:

   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. Vaciar las colas del historial de proyectos

   # 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
   

   Repite el vaciado hasta que se hayan vaciado todos los proyectos ("project_ids":0).

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

   Si “failedProjects” no es cero, contacta con el soporte y no continúes con la migración de archivos binarios.

5. Avanzar la fase de migración a 1

   Toolkit: establece OVERLEAF_FILESTORE_MIGRATION_LEVEL=1 en config/variables.env.

   docker-compose.yml heredado: establece OVERLEAF_FILESTORE_MIGRATION_LEVEL: '1' en la sección environment del servicio sharelatex.

6. Aplicar el cambio de configuración e iniciar la instancia

   Toolkit: bin/up -d

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

7. Verificar el acceso a los archivos binarios

   Abre un proyecto en el editor de Overleaf en el navegador y selecciona un archivo binario, como una imagen.

8. Ejecutar el script de migración

   # 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 conservas los archivos de log fuera del contenedor sharelatex, asegúrate de que el propietario del directorio de logs sea el usuario www-data (uid=33) para que se pueda escribir el archivo de log generado.

   La salida debería tener este aspecto:

   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 migración se realiza correctamente, obtendrás un código de salida 0 y las últimas líneas indicarán que no hay errores:

   Done.
   

   El archivo de log tendrá este aspecto (usa la ruta que muestra el 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. Detener la instancia

   Toolkit: bin/stop sharelatex

   docker-compose.yml heredado: docker compose stop sharelatex

10. Hacer que los archivos antiguos sean inaccesibles para la aplicación

    Ahora puedes mover los archivos antiguos a un almacenamiento secundario. Te recomendamos conservar los archivos durante un tiempo por si surgen problemas más adelante.

    # 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. Avanzar la fase de migración a 2

    Toolkit: establece OVERLEAF_FILESTORE_MIGRATION_LEVEL=2 en config/variables.env.

    docker-compose.yml heredado: establece OVERLEAF_FILESTORE_MIGRATION_LEVEL: '2' en la sección environment del servicio sharelatex.

12. Aplicar el cambio de configuración e iniciar la instancia

    Toolkit: bin/up -d

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

13. Verificar el acceso a los archivos binarios

    Abre un proyecto en el editor de Overleaf en el navegador y selecciona un archivo binario, como una imagen.

​

Migración sin conexión

Si quieres impedir que los usuarios puedan iniciar sesión mientras se ejecuta el script de migración de archivos binarios, sigue estos pasos:

• Inicia sesión en tu instancia de Overleaf con una cuenta de administrador
• Haz clic en el botón Admin y elige Manage Site
• Haz clic en la pestaña Open/Close Editor
• Haz clic en el botón Close Editor
• Haz clic en el botón Disconnect all users

Una vez hecho esto, los usuarios que hayan iniciado sesión serán redirigidos a la página de mantenimiento, y los nuevos usuarios que visiten la página de inicio de sesión verán la página de mantenimiento y no podrán iniciar sesión.

Debes repetir estos pasos al reiniciar la instancia. Para volver a abrir el sitio, basta con reiniciar la instancia.

​

Migración en línea

Es posible ejecutar los scripts de migración mientras la aplicación sigue en funcionamiento. Hay algunas consideraciones que debes tener en cuenta:

• El proceso de migración hace un uso intensivo de E/S; debes supervisar el uso de recursos mientras se ejecuta el script.
• Con una concurrencia de procesamiento alta, el bucle de eventos del servicio filestore podría sufrir algunos bloqueos, lo que empeoraría la experiencia de usuario. Te recomendamos empezar con los valores predeterminados --concurrency=10 y --concurrent-batches=1.
• Puedes detener el script en cualquier momento. Al volver a iniciarlo, validará los proyectos anteriores y omitirá los archivos que ya se hayan procesado. Esto resulta útil si prefieres ejecutar la migración en horas de menor actividad (p. ej., por la noche).

Nuestra recomendación es cerrar el sitio y ejecutar la migración sin conexión en una ventana de mantenimiento cuando tengas menos de 1000 proyectos (consulta la salida del script de migración al ejecutarlo con --report). Si el número de proyectos es elevado, puedes ejecutar el script y supervisar su progreso, y luego decidir si continuar ejecutándolo en línea o sin conexión según tu caso particular.

​

Limpiar los datos heredados de archivos binarios

Cuando hayas terminado la migración y verificado que los proyectos siguen pudiendo acceder a todos sus archivos, puedes eliminar el almacenamiento de archivos antiguo en /var/lib/overleaf/data/user_files. Te recomendamos encarecidamente conservar estos archivos durante un tiempo; puedes hacerlos inaccesibles para la aplicación renombrando primero la carpeta.

​

Solución de problemas

Añadiremos aquí consejos para la solución de problemas. Ten en cuenta que, aunque normalmente solo ofrecemos soporte a los clientes de Server Pro, dada la naturaleza de esta migración, también haremos lo posible por ayudar a los clientes de CE que tengan problemas específicos de la migración de archivos binarios.

Si el script de migración de archivos binarios falla (es decir, sale con un error o muestra un número de proyectos fallidos distinto de cero), envía los siguientes detalles a nuestro equipo de soporte por correo electrónico a [e-mail], indicando:

Asunto: Binary file migration problem

Cuerpo:

• Tipo de instancia: CE o Server Pro (elimina lo que no corresponda)
• Tipo de instalación: Overleaf toolkit, docker-compose.yml u otro (elimina lo que no corresponda)
• Versión: 5.5.x (toolkit: $ cat config/version)
• Salida del script de migración (que debería encontrarse en el contenedor en /var/log/overleaf)
• Informe: (ejecuta el script de migración con --report)
• Proyectos procesados: (según la última ejecución del script)
• Duración de la migración:
• Salida de bin/doctor (si usas el toolkit)
• Versión del Toolkit: $ git rev-parse HEAD (si usas el Toolkit)

Considera adjuntar al correo los archivos de log del servicio filestore. Puedes encontrarlos en /var/log/overleaf/filestore.log dentro del contenedor sharelatex y exportarlos así:

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

Elimina cualquier información sensible de los archivos de log antes de adjuntarlos.

​

Archivos que faltan

Las versiones anteriores de Server Pro/CE creaban las entradas del árbol de archivos antes de que terminaran las subidas de los usuarios, lo que podía hacer que los archivos aparecieran como ausentes cuando una subida fallaba. Es posible que encuentres algunos de estos casos notificados como errores al procesar todos los árboles de archivos.

Si el número de archivos que faltan es bajo, considera revisar estos casos manualmente y eliminarlos desde el editor en el navegador.

Si el número de archivos que faltan es alto, considera contactar con el soporte; consulta la plantilla de correo anterior.

​

Encontrar árboles de archivos dañados

La migración puede fallar en los proyectos que tengan un árbol de archivos mal formado (por ejemplo, con nombres de archivo vacíos). Puedes obtener una lista de estos problemas con el script find_malformed_filetrees, que comprueba todos los proyectos de la base de datos:

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

Para corregir las rutas no válidas, usa el script fix_malformed_filetree, ejecutando el comando una vez por cada ruta incorrecta:

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