> ## Documentation Index
> Fetch the complete documentation index at: https://ayakaleaf-pro.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# (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](https://docs.overleaf.com/on-premises/configuration/overleaf-toolkit/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
Crea una [copia de seguridad](https://docs.overleaf.com/on-premises/maintenance/data-and-backups#performing-a-consistent-backup) completa de tu instancia con una instantánea coherente de los directorios **mongo**, **redis** y **sharelatex**.
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`.
```bash wrap theme={null}
# 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:
```text theme={null}
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).
```
```bash wrap theme={null}
# 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`).
```text theme={null}
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.
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`.
Toolkit: `bin/up -d`
docker-compose.yml heredado: `docker compose up -d`
Abre un proyecto en el editor de Overleaf en el navegador y selecciona un archivo binario, como una imagen.
```bash wrap theme={null}
# 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](https://docs.overleaf.com/on-premises/configuration/overleaf-toolkit/logging#persisting-logs) 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:
```bash theme={null}
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:
```bash theme={null}
Done.
```
El archivo de log tendrá este aspecto (usa la ruta que muestra el script):
```bash wrap theme={null}
$ 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}
```
Toolkit: `bin/stop sharelatex`
docker-compose.yml heredado: `docker compose stop sharelatex`
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.
```bash wrap theme={null}
# 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.
```
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`.
Toolkit: `bin/up -d`
docker-compose.yml heredado: `docker compose up -d`
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 [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), 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í:
```bash theme={null}
$ docker cp sharelatex:/var/log/overleaf/filestore.log .
# replace with the timestamp as printed by the script
$ docker cp sharelatex:/var/log/overleaf/file-migration-.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:
```bash wrap theme={null}
$ 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:
```bash wrap theme={null}
$ 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"
```
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.