> 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/es/soporte/support-guides/v5.5.7-migration-binary-files-migration.md). # (Migración v5.5.7) Migración de archivos binarios ## Migración de archivos binarios La próxima versión principal `6.0` la próxima 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. En adelante, 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: una nueva bandera 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 se 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 en filestore y se escriben tanto en filestore como en el historial. La degradación a `OVERLEAF_FILESTORE_MIGRATION_LEVEL=0` es posible. * `OVERLEAF_FILESTORE_MIGRATION_LEVEL=2` los archivos se leen y se escriben solo en el historial. La degradación 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 historial (`OVERLEAF_HISTORY_S3_ACCESS_KEY_ID`): conceda al usuario de filestore acceso de lectura al bucket del historial para blobs `OVERLEAF_HISTORY_PROJECT_BLOBS_BUCKET` . El servicio filestore atenderá las lecturas del servicio compilador en adelante. {% hint style="warning" %} Se recomienda encarecidamente realizar primero la migración de archivos binarios en un entorno de no producción/sandbox. {% 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 uno de no producción/sandbox; se recomienda encarecidamente aprovisionar un entorno de no 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 volver 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 completa [copia de seguridad](https://docs.overleaf.com/on-premises/maintenance/data-and-backups#performing-a-consistent-backup) de su instancia con una instantánea coherente de los **mongo**, **redis** y **sharelatex** directorios. {% endstep %} {% step %} #### Actualiza **Kit de herramientas:** Usa 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 de 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 muestreadas para proyectos: - Proyectos muestreados: 9 (90% de todos los proyectos) - Proyectos muestreados con todos los hashes presentes: 5 - Porcentaje de proyectos que necesitan completar hashes retroactivamente: 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 al sistema completo de historial del proyecto (estimando el 27% de todos los archivos). Estadísticas muestreadas para 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 retroactivamente: 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 al 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 de 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 la 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 del `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 archivos binarios Abra un proyecto en el editor de Overleaf en el navegador y seleccione un archivo binario, como una imagen. {% endstep %} {% step %} #### Ejecute 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 de 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á [almacenando 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é establecido en 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 la copia de seguridad de los archivos del proyecto... Bloques globales cargados: 0 Procesando proyectos no eliminados... Procesados 1 proyectos, 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 Terminado. ``` Si la migración tiene éxito, obtendrá un código de salida de `0`, y las últimas líneas indicarán que no hubo fallos: ```bash Terminado. ``` El archivo de registro se verá así (utilice 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 realmente completado","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 inaccesibles para la aplicación los archivos antiguos Ahora puede mover los archivos antiguos al almacenamiento secundario. Recomendamos conservar los archivos durante un tiempo por si surgen problemas más adelante. {% code overflow="wrap" %} ```bash # Usuarios de 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 # Usuarios de 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 la 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 del `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 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 impedir que los usuarios puedan iniciar sesión mientras se ejecuta el script de migración de archivos binarios, siga estos pasos: * Inicie sesión en su instancia de Overleaf con una cuenta de administrador * Haz clic en el **Administrador** botón y elija **Administrar sitio** * Haz clic en el **Abrir/Cerrar editor** pestaña * Haz clic en el **Cerrar editor** botón * Haz 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 usuario nuevo 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 a tener en cuenta: * El proceso de migración es intensivo en E/S; debe supervisar el uso de recursos mientras se ejecuta el script. * Con una alta concurrencia de procesamiento, el bucle de eventos en `filestore` el servicio podría experimentar cierto bloqueo, lo que provocaría una experiencia de usuario degradada. Recomendamos comenzar con los valores predeterminados de `--concurrency=10` y `--concurrent-batches=1` . * Puede detener el script en cualquier momento. Iniciarlo de nuevo 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 menos ocupadas (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 (vea la salida del script de migración al ejecutarlo con `--report`). Si el número de proyectos es grande, puede ejecutar el script y supervisar su progreso; luego decidir si continúa ejecutándolo en línea o sin conexión según su caso particular. #### Limpiar los 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 antiguo almacenamiento de archivos en `/var/lib/overleaf/data/user_files`. Recomendamos encarecidamente conservar estos archivos durante un tiempo: puede hacerlos inaccesibles para la aplicación cambiando primero el nombre de 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, termina con un error o imprime un número distinto de cero de proyectos fallidos), envíe los siguientes detalles a nuestro equipo de soporte por correo electrónico [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: Problema de migración de archivos binarios Cuerpo: * Tipo de instancia: CE o Server Pro (elimínese lo que corresponda) * Tipo de instalación: Overleaf toolkit o `docker-compose.yml` u otro (elimínese lo que corresponda) * Versión: 5.5.x (kit de herramientas: `$ cat config/version`) * Salida del script de migración (que debería encontrarse 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 el toolkit) * Versión del toolkit: `$ git rev-parse HEAD` (al usar Toolkit) Considere adjuntar los archivos de registro de los `filestore` del servicio al correo electrónico. Puede encontrarlo en `/var/log/overleaf/filestore.log` dentro del `sharelatex` contenedor y expórtelos así: ```bash $ docker cp sharelatex:/var/log/overleaf/filestore.log . # reemplace con la marca de tiempo tal como la imprime el script $ docker cp sharelatex:/var/log/overleaf/file-migration-.log . ``` Por favor, elimine 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 terminaran las cargas de usuario, lo que podía hacer que los archivos parecieran faltar 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 revisarlos manualmente y eliminarlos desde el editor en el navegador. En caso de que el número de archivos faltantes sea alto, considere ponerse en contacto con soporte; vea la plantilla de correo electrónico anterior. #### Encontrar árboles de archivos dañados La migración puede fallar en proyectos que tengan un árbol de archivos mal formado (por ejemplo, cuando los nombres de archivo están vacíos). Puede 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 no válidas, use 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://ayakaleaf-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.