> 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/pt/suporte/support-guides/v5.5.7-migration-binary-files-migration.md). # (Migração v5.5.7) Migração de ficheiros binários ## Migração de ficheiros binários A próxima versão principal `6.0` do Server Pro e da Community Edition reduzirá para metade o uso de armazenamento dos ficheiros binários. Está incluída uma migração online na versão `5.5.7` , permitindo um tempo de inatividade mínimo como parte da atualização. Desde o Server Pro `4.x`, os ficheiros binários são armazenados duas vezes: no armazenamento de ficheiros ativos em "filestore" e no sistema de histórico completo do projeto. A partir daqui, será armazenada uma única cópia de cada ficheiro no sistema de histórico completo do projeto. A migração para o sistema de armazenamento consolidado é composta por duas partes: uma nova flag para controlar a fase da migração e um script que processa todos os projetos ativos e eliminados suavemente. Fases: * `OVERLEAF_FILESTORE_MIGRATION_LEVEL=0` (predefinição), os ficheiros são lidos e escritos no filestore. Os ficheiros são escritos no histórico de forma assíncrona. * `OVERLEAF_FILESTORE_MIGRATION_LEVEL=1` , os ficheiros são lidos do histórico com recurso de fallback para o filestore e escritos tanto no filestore como no histórico. Reversão para `OVERLEAF_FILESTORE_MIGRATION_LEVEL=0` é possível. * `OVERLEAF_FILESTORE_MIGRATION_LEVEL=2` os ficheiros são lidos e escritos apenas no histórico. Reversão para `OVERLEAF_FILESTORE_MIGRATION_LEVEL=1` não é possível, a menos que tenha sido realizada "offline". Ao armazenar dados em [S3](https://docs.overleaf.com/on-premises/configuration/overleaf-toolkit/s3) e ao usar contas de serviço separadas para o filestore (`OVERLEAF_FILESTORE_S3_ACCESS_KEY_ID`) e o histórico (`OVERLEAF_HISTORY_S3_ACCESS_KEY_ID`): Conceda ao utilizador do filestore acesso de leitura ao bucket do histórico para blobs `OVERLEAF_HISTORY_PROJECT_BLOBS_BUCKET` . O serviço filestore passará a servir as leituras a partir do serviço do compilador. {% hint style="warning" %} É altamente recomendável realizar primeiro a migração dos ficheiros binários num ambiente não produtivo/sandbox. {% endhint %} {% hint style="success" %} A licença standard do Server Pro permite-lhe executar a aplicação num ambiente de produção, bem como num ambiente não produtivo/sandbox; é altamente recomendável que crie um ambiente não produtivo para testes. {% endhint %} {% hint style="info" %} Se atualizar para a versão Server Pro/CE `6.0` e mais tarde decidir que quer reverter para uma versão anterior, então deverá restaurar a partir de uma cópia de segurança completa do sistema. {% endhint %} ### Procedimento de migração {% stepper %} {% step %} #### Criar uma cópia de segurança Criar uma cópia de segurança completa [cópia de segurança](https://docs.overleaf.com/on-premises/maintenance/data-and-backups#performing-a-consistent-backup) da sua instância com uma snapshot consistente dos **mongo**, **redis** e **sharelatex** diretórios. {% endstep %} {% step %} #### Atualize **Toolkit:** Use o `$ bin/upgrade` script para atualizar o **toolkit** para a versão mais recente. Quando lhe for pedido, faça **não** confirme a solicitação **Atualizar** imagem? — em vez disso, edite manualmente **config/version** o ficheiro e defina o valor para `5.5.7`. **docker-compose.yml legado:** Atualize a versão da `sharelatex` serviço para `5.5.7`. {% endstep %} {% step %} #### Estime o número de projetos afetados {% code overflow="wrap" %} ```bash # Utilizadores do 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" # Utilizadores do docker-compose.yml legado: $ 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 %} Exemplo de saída: {% code fullWidth="false" %} ``` Estado atual: - Número total de projetos: 10 - Número total de projetos eliminados: 5 A amostrar 1000 projetos para estimar o progresso... Estatísticas amostradas dos projetos: - Projetos amostrados: 9 (90% de todos os projetos) - Projetos amostrados com todos os hashes presentes: 5 - Percentagem de projetos que precisam de backfilling de hashes: 44% (estimado) - Os projetos amostrados têm 11 ficheiros que precisam de ser verificados contra o sistema de histórico completo do projeto. - Os projetos amostrados têm 3 ficheiros que precisam de ser carregados para o sistema de histórico completo do projeto (estimando 27% de todos os ficheiros). Estatísticas amostradas dos projetos eliminados: - Projetos eliminados amostrados: 4 (80% de todos os projetos eliminados) - Projetos eliminados amostrados com todos os hashes presentes: 3 - Percentagem de projetos eliminados que precisam de backfilling de hashes: 25% (estimado) - Os projetos eliminados amostrados têm 2 ficheiros que precisam de ser verificados contra o sistema de histórico completo do projeto. - Os projetos eliminados amostrados têm 1 ficheiro que precisa de ser carregado para o sistema de histórico completo do projeto (estimando 50% de todos os ficheiros). ``` {% endcode %} {% endstep %} {% step %} #### Esvaziar filas do histórico do projeto {% code overflow="wrap" %} ```bash # Utilizadores do Overleaf Toolkit: $ bin/docker-compose exec sharelatex /overleaf/bin/flush-history-queues # Utilizadores do docker-compose.yml legado: $ docker compose exec sharelatex /overleaf/bin/flush-history-queues ``` {% endcode %} Repita o esvaziamento até que todos os projetos tenham sido esvaziados (`"project_ids":0`). ``` projetos encontrados {"project_ids":0,"limit":100000,"ts":"2025-09-01T10:35:33.353Z"} total {"succeededProjects":0,"failedProjects":0} ``` {% hint style="danger" %} No caso de "failedProjects" não ser zero, entre em contacto com o suporte e não continue com a migração de ficheiros binários. {% endhint %} {% endstep %} {% step %} #### Avance a fase da migração para 1 Toolkit: Defina `OVERLEAF_FILESTORE_MIGRATION_LEVEL=1` em `config/variables.env`. docker-compose.yml legado: Defina `OVERLEAF_FILESTORE_MIGRATION_LEVEL: '1'` no `ambiente` secção do `sharelatex` serviço. {% endstep %} {% step %} #### Aplique a alteração de configuração e inicie a instância Toolkit: `bin/up -d` docker-compose.yml legado: `docker compose up -d` {% endstep %} {% step %} #### Verifique o acesso aos ficheiros binários Abra um projeto no editor do Overleaf no navegador e selecione um ficheiro binário, como uma imagem. {% endstep %} {% step %} #### Execute o script de migração {% code overflow="wrap" %} ```bash # Utilizadores do 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" # Utilizadores do docker-compose.yml legado: $ 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" %} Se estiver [a persistir registos](https://docs.overleaf.com/on-premises/configuration/overleaf-toolkit/logging#persisting-logs) ficheiros fora do **sharelatex** contentor, certifique-se de que o proprietário do diretório de registos está definido como o `www-data` utilizador (uid=33) para que o ficheiro de registo gerado possa ser escrito. {% endhint %} A saída deverá ter um aspeto semelhante a este: ```bash Defina UV_THREADPOOL_SIZE=16 {"name":"default","hostname":"c25e9faaeb53","pid":971,"level":30,"backend":"fs","msg":"A carregar o backend","time":"2025-07-25T15:00:58.166Z","v":0} A escrever registos em /var/log/overleaf/file-migration-2025-07-25T15_00_58_199Z.log A iniciar a cópia de segurança dos ficheiros do projeto... Blobs globais carregados: 0 A processar projetos não eliminados... Processados 1 projetos, tempo decorrido 0s Atualização dos projetos ativos concluída A processar projetos eliminados... A coleção deletedProjects parece estar vazia. Atualização dos projetos eliminados concluída Concluído. ``` Se a migração for bem-sucedida, obterá um código de saída de `0`, e as últimas linhas indicam que não houve falhas: ```bash Concluído. ``` O ficheiro de registo terá o seguinte aspeto (use o caminho tal como impresso pelo 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 concluído de facto","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":"estatísticas da migração de ficheiros","v":0} ``` {% endcode %} {% endstep %} {% step %} #### Pare a instância Toolkit: `bin/stop sharelatex` docker-compose.yml legado: `docker compose stop sharelatex` {% endstep %} {% step %} #### Torne os ficheiros antigos inacessíveis à aplicação Pode agora mover os ficheiros antigos para armazenamento secundário. Recomendamos manter os ficheiros por algum tempo, caso surjam problemas mais tarde. {% code overflow="wrap" %} ```bash # Utilizadores do 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 # Utilizadores do docker-compose.yml legado: # Estamos a assumir que está a usar o bind-mount predefinido em /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 # No caso de estar a usar bind-mounts seletivos, pode simplesmente remover o bind-mount de /var/lib/overleaf/data/user_files dentro do contentor. ``` {% endcode %} {% endstep %} {% step %} #### Avance a fase da migração para 2 Toolkit: Defina `OVERLEAF_FILESTORE_MIGRATION_LEVEL=2` em `config/variables.env`. docker-compose.yml legado: Defina `OVERLEAF_FILESTORE_MIGRATION_LEVEL: '2'` no `ambiente` secção do `sharelatex` serviço. {% endstep %} {% step %} #### Aplique a alteração de configuração e inicie a instância Toolkit: `bin/up -d` docker-compose.yml legado: `docker compose up -d` {% endstep %} {% step %} #### Verifique o acesso aos ficheiros binários Abra um projeto no editor do Overleaf no navegador e selecione um ficheiro binário, como uma imagem. {% endstep %} {% endstepper %} #### migração offline Se quiser impedir que os utilizadores consigam iniciar sessão enquanto o script de migração de ficheiros binários estiver a ser executado, siga estes passos: * Inicie sessão na sua instância Overleaf com uma conta de administrador * Clique no **Administração** botão e escolha **Gerir site** * Clique no **Abrir/Fechar editor** separador * Clique no **Fechar editor** botão * Clique no **Desligar todos os utilizadores** botão Depois de isto ser feito, se houver utilizadores com sessão iniciada, estes serão redirecionados para a página de manutenção, e quaisquer novos utilizadores que visitem a página de início de sessão verão a página de manutenção e **não** conseguirão iniciar sessão. Tem de repetir estes passos ao reiniciar a instância. Para reabrir o site, basta reiniciar a instância. #### Migração online É possível executar os scripts de migração enquanto a aplicação ainda está em execução. Há algumas considerações a ter em conta: * O processo de migração é intensivo em E/S; deve monitorizar a utilização de recursos enquanto o script estiver em execução. * Com uma elevada concorrência de processamento, o event loop no `filestore` serviço pode sofrer algum bloqueio, o que levaria a uma experiência de utilização degradada. Recomendamos começar com os valores predefinidos de `--concurrency=10` e `--concurrent-batches=1` . * Pode parar o script em qualquer momento. Iniciá-lo novamente validará os projetos anteriores e ignorará os ficheiros que já tenham sido processados. Isto é útil caso prefira executar a migração em horas com menos movimento (por exemplo, à noite). A nossa recomendação é fechar o site e executar a migração offline numa janela de manutenção quando o seu número de projetos for inferior a 1000 projetos (ver saída do script de migração ao executar com `--report`). Se o número de projetos for grande, pode executar o script e monitorizar o progresso; depois decidir se continua a executá-lo online ou offline, com base no seu caso específico. #### Limpar dados legados de ficheiros binários Quando terminar a migração e verificar que os projetos ainda conseguem aceder a todos os seus ficheiros, pode remover o armazenamento antigo de ficheiros em `/var/lib/overleaf/data/user_files`. Recomendamos vivamente que mantenha estes ficheiros por algum tempo - pode torná-los inacessíveis à aplicação ao renomear primeiro a pasta. ### Resolução de problemas Adicionaremos aqui conselhos de resolução de problemas. Tenha em atenção que, embora normalmente só ofereçamos suporte aos clientes do Server Pro, dada a natureza desta migração, também faremos o possível para apoiar clientes CE que tenham problemas específicos da migração de ficheiros binários. Se o script de migração de ficheiros binários falhar (ou seja, terminar com erro ou apresentar um número não nulo de projetos com falha), envie os seguintes detalhes à nossa equipa de suporte por e-mail [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), detalhando: Assunto: Problema de migração de ficheiros binários Corpo: * Tipo de instância: CE ou Server Pro (apagar conforme apropriado) * Tipo de instalação: Overleaf toolkit ou `docker-compose.yml` ou outro (apagar conforme apropriado) * Versão: 5.5.x (toolkit: `$ cat config/version`) * Saída do script de migração (que deve estar localizada no contentor em `/var/log/overleaf`) * Relatório: (execute o script de migração com `--report`) * Projetos processados: (de acordo com a última execução do script) * Duração da migração: * `bin/doctor` saída (ao usar o toolkit) * Versão do toolkit: `$ git rev-parse HEAD` (ao usar o Toolkit) Considere anexar os ficheiros de registo dos `filestore` serviço para o e-mail. Pode encontrá-lo em `/var/log/overleaf/filestore.log` dentro do `sharelatex` contentor e exportá-los assim: ```bash $ docker cp sharelatex:/var/log/overleaf/filestore.log . # substitua pelo timestamp tal como impresso pelo script $ docker cp sharelatex:/var/log/overleaf/file-migration-.log . ``` Remova qualquer informação sensível dos ficheiros de registo antes de os anexar. #### Ficheiros em falta Versões mais antigas do Server Pro/CE criavam entradas na árvore de ficheiros antes de as cargas dos utilizadores terminarem, o que podia fazer com que os ficheiros parecessem em falta quando uma carga falhava. Poderá encontrar alguns destes casos assinalados como erros ao processar todas as árvores de ficheiros. Caso o número de ficheiros em falta seja baixo, considere rever manualmente estes casos e eliminá-los no editor no navegador. Caso o número de ficheiros em falta seja elevado, considere contactar o suporte; veja o modelo de e-mail acima. #### Encontrar árvores de ficheiros corrompidas A migração pode falhar para projetos que tenham uma árvore de ficheiros malformada (por exemplo, onde os nomes dos ficheiros estejam vazios). Pode encontrar uma lista destes problemas usando o `find_malformed_filetrees` script que verifica todos os projetos na base de dados: {% 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 corrigir os caminhos inválidos, use o `fix_malformed_filetree` script, executando o comando uma vez para cada caminho inválido: {% 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/pt/suporte/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.