> 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/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 de 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 completo de histórico do projeto. Daqui em diante, será armazenada uma única cópia de cada ficheiro no sistema completo de histórico 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 logicamente. Fases: * `OVERLEAF_FILESTORE_MIGRATION_LEVEL=0` (predefinição), os ficheiros são lidos e escritos em 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 filestore e escritos em ambos, filestore e histórico. É possível fazer downgrade para `OVERLEAF_FILESTORE_MIGRATION_LEVEL=0` é possível. * `OVERLEAF_FILESTORE_MIGRATION_LEVEL=2` os ficheiros são lidos e escritos apenas no histórico. Não é possível fazer downgrade para `OVERLEAF_FILESTORE_MIGRATION_LEVEL=1` , a menos que tenha sido feito "offline". Ao armazenar dados em [S3](https://docs.overleaf.com/on-premises/configuration/overleaf-toolkit/s3) e usar contas de serviço separadas para filestore (`OVERLEAF_FILESTORE_S3_ACCESS_KEY_ID`) e histórico (`OVERLEAF_HISTORY_S3_ACCESS_KEY_ID`): Por favor, 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 do serviço do compilador. {% hint style="warning" %} É altamente recomendável realizar primeiro a migração de ficheiros binários num ambiente não produtivo/sandbox. {% endhint %} {% hint style="success" %} A licença padrão 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 aprovisione 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 fazer downgrade 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](https://docs.overleaf.com/on-premises/maintenance/data-and-backups#performing-a-consistent-backup) da sua instância com uma captura consistente dos **mongo**, **redis** e **sharelatex** diretórios. {% endstep %} {% step %} #### Atualize **Kit de ferramentas:** Use o `$ bin/upgrade` script para atualizar o **kit de ferramentas** para a versão mais recente. Quando lhe for pedido, não **não** confirme o pedido **Atualização** 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 da amostra para os projetos: - Projetos amostrados: 9 (90% de todos os projetos) - Projetos amostrados com todos os hashes presentes: 5 - Percentagem de projetos que precisam de preenchimento retroativo de hashes: 44% (estimado) - Os projetos amostrados têm 11 ficheiros que precisam de ser verificados contra o sistema completo de histórico do projeto. - Os projetos amostrados têm 3 ficheiros que precisam de ser carregados para o sistema completo de histórico do projeto (estimando 27% de todos os ficheiros). Estatísticas da amostra para 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 preenchimento retroativo de hashes: 25% (estimado) - Os projetos eliminados amostrados têm 2 ficheiros que precisam de ser verificados contra o sistema completo de histórico do projeto. - Os projetos eliminados amostrados têm 1 ficheiro que precisa de ser carregado para o sistema completo de histórico do projeto (estimando 50% de todos os ficheiros). ``` {% endcode %} {% endstep %} {% step %} #### Esvaziar as 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" %} Caso "failedProjects" não seja zero, contacte 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 Kit de ferramentas: 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 Kit de ferramentas: `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) de ficheiros fora do **sharelatex** contentor, certifique-se de que o proprietário do diretório de registos está definido para o `www-data` utilizador (uid=33) para que o ficheiro de registo gerado possa ser escrito. {% endhint %} A saída deverá ser semelhante a isto: ```bash Defina UV_THREADPOOL_SIZE=16 {"name":"default","hostname":"c25e9faaeb53","pid":971,"level":30,"backend":"fs","msg":"A carregar 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 cópia de segurança dos ficheiros do projeto... Blobs globais carregados: 0 A processar projetos não eliminados... 1 projeto processado, 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 indicarão que não houve falhas: ```bash Concluído. ``` O ficheiro de registo terá este 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 realmente concluído","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 Kit de ferramentas: `bin/stop sharelatex` docker-compose.yml legado: `docker compose stop sharelatex` {% endstep %} {% step %} #### Tornar os ficheiros antigos inacessíveis à aplicação Agora pode mover os ficheiros antigos para armazenamento secundário. Recomendamos manter os ficheiros durante algum tempo caso surjam problemas mais tarde. {% code overflow="wrap" %} ```bash # Utilizadores do kit de ferramentas: $ 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 # Caso esteja a usar bind-mounts seletivos, pode simplesmente remover o bind-mount para /var/lib/overleaf/data/user_files dentro do contentor. ``` {% endcode %} {% endstep %} {% step %} #### Avance a fase da migração para 2 Kit de ferramentas: 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 Kit de ferramentas: `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 está a ser executado, siga estes passos: * Inicie sessão na sua instância do 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 **Desconectar 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 quando 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 a ser executado. * Com uma elevada concorrência de processamento, o event loop em `filestore` o serviço pode sofrer algum bloqueio, o que levaria a uma experiência do utilizador 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 a sua contagem de projetos for inferior a 1000 projetos (veja a saída do script de migração ao executar com `--report`). Se o número de projetos for elevado, pode executar o script e monitorizar o seu 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 tiver verificado 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 manter estes ficheiros durante algum tempo — pode torná-los inacessíveis à aplicação renomeando primeiro a pasta. ### Resolução de problemas Adicionaremos aqui conselhos de resolução de problemas. Note que, embora normalmente ofereçamos suporte apenas a clientes do Server Pro, dada a natureza desta migração, também faremos o nosso melhor para dar suporte a 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 imprimir um número diferente de zero de projetos falhados), envie os seguintes detalhes por email para a nossa equipa de suporte [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: Assunto: Problema na migração de ficheiros binários Corpo: * Tipo de instância: CE ou Server Pro (apague conforme aplicável) * Tipo de instalação: Overleaf toolkit ou `docker-compose.yml` ou outro (apague conforme aplicável) * Versão: 5.5.x (toolkit: `$ cat config/version`) * Saída do script de migração (que deverá estar localizada no contentor em `/var/log/overleaf`) * Relatório: (execute o script de migração com `--report`) * Projetos processados: (segundo 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 email. 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 . ``` Por favor, remova qualquer informação sensível dos ficheiros de registo antes de os anexar. #### Ficheiros em falta Versões anteriores do Server Pro/CE criavam entradas na file-tree antes de os carregamentos do utilizador terminarem, o que podia fazer com que os ficheiros parecessem em falta quando um carregamento falhava. Poderá encontrar alguns destes casos comunicados como erros ao processar todas as file-trees. 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 email acima. #### Encontrar árvores de ficheiros corrompidas A migração pode falhar em projetos que tenham uma árvore de ficheiros malformada (por exemplo, quando os nomes dos ficheiros estão 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 incorreto: {% 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/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.