> 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/es/soporte/support-guides/v5.5.7-migration-binary-files-migration.md). # Migración de archivos binarios ## Migración de archivos binarios La próxima versión principal `6.0` la versión de Server Pro y Community Edition reducirá a la mitad el uso de almacenamiento de los archivos binarios. Se incluye una migración en línea en la versión `5.5.7` , lo 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 en "filestore" y en el sistema completo de historial del proyecto. A partir de ahora, se almacenará una sola copia de cada archivo en el sistema completo de historial del proyecto. 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 temporalmente. 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 respaldo a filestore y se escriben tanto en filestore como en el historial. Degradar a `OVERLEAF_FILESTORE_MIGRATION_LEVEL=0` es posible. * `OVERLEAF_FILESTORE_MIGRATION_LEVEL=2` los archivos se leen y escriben solo en el historial. Degradar a `OVERLEAF_FILESTORE_MIGRATION_LEVEL=1` no es posible, a menos que se haya realizado "sin conexión". Al almacenar datos en [S3](https://docs.overleaf.com/on-premises/configuration/overleaf-toolkit/s3) y usar cuentas de servicio separadas para filestore (`OVERLEAF_FILESTORE_S3_ACCESS_KEY_ID`) y el historial (`OVERLEAF_HISTORY_S3_ACCESS_KEY_ID`): Conceda al usuario de filestore acceso de lectura al bucket del historial para los blobs `OVERLEAF_HISTORY_PROJECT_BLOBS_BUCKET` . El servicio filestore servirá las lecturas desde el servicio compilador a partir de ahora. {% hint style="warning" %} Se recomienda encarecidamente realizar primero la migración de archivos binarios en un entorno que no sea de producción/de pruebas. {% endhint %} {% hint style="success" %} La licencia estándar de Server Pro le permite ejecutar la aplicación en un entorno de producción así como en un entorno que no sea de producción/de pruebas; se recomienda encarecidamente aprovisionar un entorno que no sea de producción para pruebas. {% endhint %} {% hint style="info" %} Si actualiza a la versión de Server Pro/CE `6.0` y luego decide que desea degradar a una versión anterior, entonces debe restaurar desde una copia de seguridad completa del sistema. {% endhint %} ### Procedimiento de migración {% stepper %} {% step %} #### Crear una copia de seguridad Crear 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 consistente de los **mongo**, **redis** y **sharelatex** directorios. {% endstep %} {% step %} #### Actualiza **Kit de herramientas:** Use el `$ bin/upgrade` script para actualizar el **kit de herramientas** a la versión más reciente. Cuando se le pregunte, no **no** confirme el aviso **Actualizar** imagen? — en su lugar, edite manualmente **config/version** el archivo y establezca el valor en `5.5.7`. **docker-compose.yml heredado:** Actualiza la versión de la `sharelatex` servicio a `5.5.7`. {% endstep %} {% step %} #### Estime el número de proyectos afectados {% code overflow="wrap" %} ```bash # Usuarios de 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" # Usuarios del docker-compose.yml heredado: $ 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 %} Ejemplo de salida: {% code fullWidth="false" %} ``` Estado actual: - Número total de proyectos: 10 - Número total de proyectos eliminados: 5 Muestreando 1000 proyectos para estimar el progreso... Estadísticas de la muestra de proyectos: - Proyectos muestreados: 9 (90% de todos los proyectos) - Proyectos muestreados con todos los hashes presentes: 5 - Porcentaje de proyectos que necesitan completar hashes: 44% (estimado) - Los proyectos muestreados tienen 11 archivos que deben comprobarse con el sistema completo de historial del proyecto. - Los proyectos muestreados tienen 3 archivos que deben cargarse en el sistema completo de historial del proyecto (estimando el 27% de todos los archivos). Estadísticas de la muestra de proyectos eliminados: - Proyectos eliminados muestreados: 4 (80% de todos los proyectos eliminados) - Proyectos eliminados muestreados con todos los hashes presentes: 3 - Porcentaje de proyectos eliminados que necesitan completar hashes: 25% (estimado) - Los proyectos eliminados muestreados tienen 2 archivos que deben comprobarse con el sistema completo de historial del proyecto. - Los proyectos eliminados muestreados tienen 1 archivo que debe cargarse en el sistema completo de historial del proyecto (estimando el 50% de todos los archivos). ``` {% endcode %} {% endstep %} {% step %} #### Vaciar las colas del historial del proyecto {% code overflow="wrap" %} ```bash # Usuarios de Overleaf Toolkit: $ bin/docker-compose exec sharelatex /overleaf/bin/flush-history-queues # Usuarios del docker-compose.yml heredado: $ docker compose exec sharelatex /overleaf/bin/flush-history-queues ``` {% endcode %} Repita el vaciado hasta que todos los proyectos se hayan vaciado (`"project_ids":0`). ``` proyectos encontrados {"project_ids":0,"limit":100000,"ts":"2025-09-01T10:35:33.353Z"} total {"succeededProjects":0,"failedProjects":0} ``` {% hint style="danger" %} En caso de que "failedProjects" no sea cero, póngase en contacto con soporte y no continúe con la migración de archivos binarios. {% endhint %} {% endstep %} {% step %} #### Avance la fase de migración a 1 Kit de herramientas: establezca `OVERLEAF_FILESTORE_MIGRATION_LEVEL=1` en `config/variables.env`. docker-compose.yml heredado: establezca `OVERLEAF_FILESTORE_MIGRATION_LEVEL: '1'` en el `entorno` sección de `sharelatex` servicio. {% endstep %} {% step %} #### Aplique el cambio de configuración e inicie la instancia Kit de herramientas: `bin/up -d` docker-compose.yml heredado: `docker compose up -d` {% endstep %} {% step %} #### Verifique el acceso a los archivos binarios Abra un proyecto en el editor de Overleaf en el navegador y seleccione un archivo binario, como una imagen. {% endstep %} {% step %} #### Ejecuta el script de migración {% code overflow="wrap" %} ```bash # Usuarios de 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" # Usuarios del docker-compose.yml heredado: $ 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" %} Si está [persistiendo registros](https://docs.overleaf.com/on-premises/configuration/overleaf-toolkit/logging#persisting-logs) archivos fuera del **sharelatex** contenedor, asegúrese de que el propietario del directorio de registros esté configurado como el `www-data` usuario (uid=33) para que se pueda escribir el archivo de registro generado. {% endhint %} La salida debería verse así: ```bash Set UV_THREADPOOL_SIZE=16 {"name":"default","hostname":"c25e9faaeb53","pid":971,"level":30,"backend":"fs","msg":"Cargando backend","time":"2025-07-25T15:00:58.166Z","v":0} Escribiendo registros en /var/log/overleaf/file-migration-2025-07-25T15_00_58_199Z.log Iniciando copia de seguridad de archivos del proyecto... Blobs globales cargados: 0 Procesando proyectos no eliminados... Se procesó 1 proyecto, tiempo transcurrido 0 s Actualización de proyectos activos completada Procesando proyectos eliminados... La colección deletedProjects parece estar vacía. Actualización de proyectos eliminados completada Hecho. ``` Si la migración tiene éxito, obtendrás un código de salida de `0`, y las últimas líneas indicarán que no hubo fallos: ```bash Hecho. ``` El archivo de registro tendrá este aspecto (use la ruta tal como la imprime el 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":"lote completado realmente","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":"estadísticas de migración de archivos","v":0} ``` {% endcode %} {% endstep %} {% step %} #### Detenga la instancia Kit de herramientas: `bin/stop sharelatex` docker-compose.yml heredado: `docker compose stop sharelatex` {% endstep %} {% step %} #### Haga que los archivos antiguos sean inaccesibles para la aplicación Ahora puede mover los archivos antiguos a almacenamiento secundario. Recomendamos conservar los archivos durante un tiempo por si surgen problemas más adelante. {% code overflow="wrap" %} ```bash # Usuarios del kit de herramientas: $ bin/docker-compose run --rm --entrypoint mv sharelatex --no-clobber --verbose /var/lib/overleaf/data/user_files /var/lib/overleaf/data/old_user_files # Usuarios del docker-compose.yml heredado: # Suponemos que está usando el bind-mount predeterminado en /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 # En caso de que esté usando bind-mounts selectivos, simplemente puede eliminar el bind-mount de /var/lib/overleaf/data/user_files dentro del contenedor. ``` {% endcode %} {% endstep %} {% step %} #### Avance la fase de migración a 2 Kit de herramientas: establezca `OVERLEAF_FILESTORE_MIGRATION_LEVEL=2` en `config/variables.env`. docker-compose.yml heredado: establezca `OVERLEAF_FILESTORE_MIGRATION_LEVEL: '2'` en el `entorno` sección de `sharelatex` servicio. {% endstep %} {% step %} #### Aplique el cambio de configuración e inicie la instancia Kit de herramientas: `bin/up -d` docker-compose.yml heredado: `docker compose up -d` {% endstep %} {% step %} #### Verifique el acceso a los archivos binarios Abra un proyecto en el editor de Overleaf en el navegador y seleccione un archivo binario, como una imagen. {% endstep %} {% endstepper %} #### Migración sin conexión Si desea evitar que los usuarios puedan iniciar sesión mientras se ejecuta el script de migración de archivos binarios, siga estos pasos: * Inicia sesión en tu instancia de Overleaf con una cuenta de administrador * Haga clic en el **Administrador** botón y elige **Administrar el sitio** * Haga clic en el **Abrir/Cerrar el editor** pestaña * Haga clic en el **Cerrar el editor** botón * Haga clic en el **Desconectar a todos los usuarios** botón Una vez hecho esto, si hay usuarios conectados serán redirigidos a la página de mantenimiento, y cualquier nuevo usuario que visite la página de inicio de sesión verá la página de mantenimiento y **no** podrá iniciar sesión. Debe repetir estos pasos al reiniciar la instancia. Para volver a abrir el sitio, simplemente reinicie 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 tener en cuenta: * El proceso de migración es intensivo en E/S, debería supervisar el uso de recursos mientras se ejecuta el script. * Con una alta concurrencia de procesamiento, el bucle de eventos en `filestore` servicio puede experimentar algún bloqueo, lo que provocaría una experiencia de usuario degradada. Recomendamos empezar con los valores predeterminados de `--concurrency=10` y `--concurrent-batches=1` . * Puede detener el script en cualquier momento. Al volver a iniciarlo, validará los proyectos anteriores y omitirá los archivos que ya se hayan procesado. Esto es útil en caso de que prefiera ejecutar la migración en horas de menor carga (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 su número de proyectos sea inferior a 1000 proyectos (vea la salida del script de migración al ejecutarlo con `--report`). Si el número de proyectos es grande, 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 datos heredados de archivos binarios Cuando haya terminado con la migración y haya verificado que los proyectos aún pueden acceder a todos sus archivos, puede eliminar el almacenamiento de archivos antiguo en `/var/lib/overleaf/data/user_files`. Recomendamos encarecidamente conservar estos archivos durante un tiempo; puede hacerlos inaccesibles para la aplicación renombrando primero la carpeta. ### Solución de problemas Añadiremos aquí consejos para la resolución de problemas. Tenga en cuenta que, aunque normalmente solo ofrecemos soporte a los clientes de Server Pro, dada la naturaleza de esta migración, también haremos todo lo posible por ayudar a los clientes de CE que experimenten problemas específicos de la migración de archivos binarios. Si el script de migración de archivos binarios falla (es decir, finaliza con un error o muestra un número distinto de cero de proyectos fallidos), envíe por correo electrónico los siguientes detalles a nuestro equipo de soporte [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), detallando: Asunto: Problema de migración de archivos binarios Cuerpo: * Tipo de instancia: CE o Server Pro (eliminar según corresponda) * Tipo de instalación: Overleaf Toolkit o `docker-compose.yml` u otro (eliminar según corresponda) * Versión: 5.5.x (kit de herramientas: `$ cat config/version`) * Salida del script de migración (que debería estar ubicada en el contenedor en `/var/log/overleaf`) * Informe: (ejecute el script de migración con `--report`) * Proyectos procesados: (según la última ejecución del script) * Duración de la migración: * `bin/doctor` salida (al usar Toolkit) * Versión del toolkit: `$ git rev-parse HEAD` (al usar Toolkit) Considera adjuntar los archivos de registro de los `filestore` servicio al correo electrónico. Puede encontrarlo en `/var/log/overleaf/filestore.log` dentro del `sharelatex` contenedor y exportarlos así: ```bash $ docker cp sharelatex:/var/log/overleaf/filestore.log . # sustituya por la marca de tiempo tal como la imprime el script $ docker cp sharelatex:/var/log/overleaf/file-migration-.log . ``` Por favor, elimina cualquier información sensible de los archivos de registro antes de adjuntarlos. #### Archivos faltantes Las versiones anteriores de Server Pro/CE creaban entradas del árbol de archivos antes de que finalizaran las cargas de los usuarios, lo que podía hacer que los archivos aparecieran como faltantes cuando una carga fallaba. Es posible que encuentre algunos de estos casos informados como errores al procesar todos los árboles de archivos. En caso de que el número de archivos faltantes sea bajo, considere revisar manualmente estos casos y eliminarlos del editor en el navegador. En caso de que el número de archivos faltantes sea alto, considere ponerse en contacto con soporte; consulte la plantilla de correo electrónico anterior. #### Encontrar árboles de archivos dañados La migración puede fallar en proyectos que tienen un árbol de archivos mal formado (por ejemplo, cuando los nombres de archivo están vacíos). Puedes encontrar una lista de estos problemas usando el `find_malformed_filetrees` script que comprueba todos los proyectos en la base de datos: {% 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 %} Para corregir las rutas inválidas, usa el `fix_malformed_filetree` script, ejecutando el comando una vez por cada ruta incorrecta: {% 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/es/soporte/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.