Saltar para o conteúdo principal
O Ayakaleaf Pro suporta escalabilidade horizontal. Testamos e verificamos que ele funciona corretamente com múltiplas réplicas.
Este documento lista os requisitos técnicos e fornece orientações para executar o Ayakaleaf Pro em mais de um nó. Configurar a escalabilidade horizontal exige um esforço considerável. Aconselhamos considerar a escalabilidade horizontal apenas ao atingir uma determinada escala. Como exemplo, o Overleaf relatou uma instalação on-premises para 1.000 usuários no total funcionando com sucesso num único servidor equipado com dois processadores de 4 núcleos e 32GB de memória. Consulte a documentação de requisitos de hardware para ver as recomendações. Uma implantação do Ayakaleaf Pro com escalabilidade horizontal envolve um conjunto de componentes externos, como um balanceador de carga e um backend de armazenamento compatível com S3.

Requisitos

Armazenamento de dados externo e centralizado

O armazenamento de dados no Ayakaleaf Pro pode ser dividido em quatro repositórios de dados:
  • MongoDB
    • A maior parte dos dados é persistida no MongoDB.
    • Suportamos uma instância local ou uma instância externa, como o MongoDB Atlas (um serviço MongoDB totalmente gerenciado que é executado na infraestrutura da AWS).
    Observação: infelizmente, não há suporte oficial para bancos de dados compatíveis com MongoDB, como CosmoDB/DocumentDB, no momento, pois não testamos o Ayakaleaf Pro com eles. Embora possa ser possível implantar o Ayakaleaf Pro com bancos de dados compatíveis, só oferecemos suporte oficial a implantações que usam o MongoDB.
  • Redis
    • O Redis armazena dados temporários, como atualizações pendentes de documentos antes de serem gravadas no MongoDB.
    • O Redis é usado para comunicar atualizações de documentos entre diferentes serviços e notificar o editor sobre mudanças de estado num determinado projeto.
    • O Redis é usado para armazenar as sessões dos usuários.
    • Suportamos uma instância local ou uma instância externa.
    Observação: infelizmente, não há suporte oficial para armazenamentos de chave/valor compatíveis com Redis, como KeyDB/Valkey, no momento, pois não testamos o Ayakaleaf Pro com eles. Embora possa ser possível implantar o Ayakaleaf Pro com armazenamentos compatíveis, só oferecemos suporte oficial a implantações que usam o Redis.
  • Arquivos de projeto e arquivos de histórico
    • Os arquivos de projeto não editáveis são armazenados fora do MongoDB. O sistema de histórico de projetos também armazena o histórico fora do MongoDB.
    • Para instâncias únicas pequenas, suportamos um sistema de arquivos local (que pode ser baseado num SSD local, NFS ou EBS) ou um sistema de armazenamento de dados compatível com S3.
    • Para a escalabilidade horizontal, suportamos apenas sistemas de armazenamento de dados compatíveis com S3.
    Importante: NFS/Amazon EFS/Amazon EBS não são suportados para escalabilidade horizontal. Consulte a seção de requisitos de armazenamento de hardware sobre o dimensionamento do armazenamento no Ayakaleaf Pro para mais detalhes.
  • Arquivos efêmeros
    • As compilações LaTeX precisam ser executadas em discos locais rápidos para um desempenho ideal. O resultado da compilação não precisa ser persistido nem copiado em backup.
    • O buffer de novos uploads de arquivos e a criação de arquivos zip de projetos também se beneficiam do uso de um disco local.
Recomendamos fortemente o uso de um disco local. Usar qualquer tipo de disco em rede (como NFS ou EBS) pode resultar em erros de compilação inesperados e outros problemas de desempenho.

Git-bridge

Os repositórios git são armazenados localmente em disco. Não há opções de replicação disponíveis. O Git-bridge deve ser executado como singleton. Para um desempenho ideal, aconselhamos usar um disco local para os dados do git-bridge. O disco de dados do git-bridge deve ser copiado em backup regularmente. Para o armazenamento de dados com escalabilidade horizontal, você precisa de:
  • uma instância central do MongoDB acessível a partir de todas as instâncias do Ayakaleaf Pro
  • uma instância central do Redis acessível a partir de todas as instâncias do Ayakaleaf Pro
  • um backend de armazenamento central compatível com S3 para os arquivos de projeto e de histórico
  • um disco local em cada instância para os arquivos efêmeros
  • um disco local na instância que hospeda o contêiner do git-bridge para os dados do git-bridge

Requisitos do balanceador de carga

  • Roteamento persistente, por exemplo usando um cookie Este requisito decorre destes componentes:
    • A capacidade de edição em tempo real do Ayakaleaf Pro usa WebSockets, com fallback para polling XHR. Cada sessão de edição tem estado local no lado do servidor, e as requisições de uma determinada sessão de edição precisam sempre ser roteadas para a mesma instância do Ayakaleaf Pro. O recurso de colaboração usa o Pub/Sub do Redis para partilhar atualizações entre várias instâncias do Ayakaleaf Pro.
    • A compilação LaTeX mantém o resultado e o cache de compilação localmente para melhor desempenho. Ao emitir uma requisição de compilação para uma instância do Ayakaleaf Pro, as requisições seguintes de download do PDF/log precisam ser roteadas para a mesma instância do Ayakaleaf Pro.
  • Tempos limite de requisição longos para suportar a compilação de documentos LaTeX grandes
  • Suporte a WebSocket para um desempenho ideal
  • Tamanho de payload POST de 50MB
  • O tempo limite de keep-alive deve ser inferior ao tempo limite de keep-alive do Ayakaleaf Pro O tempo limite de keep-alive no Ayakaleaf Pro pode ser configurado usando a variável de ambiente NGINX_KEEPALIVE_TIMEOUT. O valor padrão é 65s. Com o padrão, funciona um tempo limite de keep-alive de 60s no balanceador de carga. Com NGINX_KEEPALIVE_TIMEOUT=120, o balanceador de carga poderia usar 115s.
  • IPs dos clientes Defina o cabeçalho de requisição X-Forwarded-For com o IP do cliente.
  • Ao terminar o SSL O balanceador de carga precisa adicionar o cabeçalho de requisição X-Forwarded-Proto: https.

Configuração do Ayakaleaf Pro

Segredos As instâncias do Ayakaleaf Pro precisam compartilhar os mesmos segredos:
  • WEB_API_PASSWORD (autenticação da web api)
  • STAGING_PASSWORD e V1_HISTORY_PASSWORD com o mesmo valor (autenticação do histórico)
  • CRYPTO_RANDOM (para o cookie de sessão)
  • OT_JWT_AUTH_KEY (autenticação do histórico)
  • OVERLEAF_INVITE_TOKEN_SECRET (tokens de compartilhamento por link; obrigatório: sem ele, o Ayakaleaf Pro se recusa a iniciar)
Todos estes segredos precisam ser configurados com o seu próprio valor único e compartilhados entre as instâncias. Se não estiverem configurados e as requisições dos usuários forem roteadas para diferentes instâncias do Ayakaleaf Pro, as requisições falharão nas verificações de autenticação, e os usuários serão frequentemente redirecionados para a página de login ou as suas ações na interface falharão de formas inesperadas. Quando não estão configurados, o Ayakaleaf Pro usa um novo valor aleatório para cada segredo, baseado em 32 bytes aleatórios de /dev/urandom (256 bits aleatórios).
MongoDB Aponte OVERLEAF_MONGO_URL para a instância central do MongoDB. Redis Aponte OVERLEAF_REDIS_HOST e REDIS_HOST para a instância central do Redis. Armazenamento compatível com S3 para arquivos de projeto e de histórico Consulte a documentação sobre armazenamento compatível com S3 para mais detalhes. Arquivos efêmeros O bind-mount padrão de um SSD local em /var/lib/overleaf será suficiente. Certifique-se de apontar SANDBOXED_COMPILES_HOST_DIR para o ponto de montagem no host.
Recomendamos fortemente o uso de um disco local. Usar qualquer tipo de disco em rede (como NFS ou EBS) pode resultar em erros de compilação inesperados e outros problemas de desempenho.
Configuração do proxy
  • Defina OVERLEAF_TRUSTED_PROXY_IPS como loopback mais os IPs dos balanceadores de carga, por exemplo loopback,198.18.0.1, para obter IPs de cliente corretos. É possível especificar vários IPs ou CIDRs, separados por vírgula.
Integração com o Git-bridge O contêiner do git-bridge precisa de um contêiner irmão do Ayakaleaf Pro para processar as requisições git recebidas. Este contêiner irmão também pode atender ao tráfego normal dos usuários. Na configuração de exemplo, a primeira instância atua como contêiner irmão do git-bridge, mas na verdade qualquer instância poderia desempenhar esse papel. Por que precisamos designar um contêiner do Ayakaleaf Pro como irmão do git-bridge? O Ayakaleaf Pro fornece ao git-bridge URLs de download do serviço de histórico. Precisamos configurar estas URLs de histórico para que sejam acessíveis a partir do contêiner do git-bridge. Configuração do contêiner do Ayakaleaf Pro:
  • Defina GIT_BRIDGE_ENABLED como 'true'
  • Defina GIT_BRIDGE_HOST como <git-bridge container name>, por exemplo git-bridge
  • Defina GIT_BRIDGE_PORT como 8000
  • Defina V1_HISTORY_URL como http://<server-pro sibling container name>:3100/api. Observação: isto só é necessário no contêiner irmão do contêiner do git-bridge. As outras instâncias podem usar uma URL localhost, que é o padrão.
Configuração do contêiner do git-bridge:
  • Defina GIT_BRIDGE_API_BASE_URL como http://<server-pro sibling container name>/api/v0, por exemplo http://server-pro-ha-1/api/v0
  • Defina GIT_BRIDGE_OAUTH2_SERVER como http://<server-pro sibling container name>, por exemplo http://server-pro-ha-1
  • Defina GIT_BRIDGE_POSTBACK_BASE_URL como http://<git-bridge container name>:8000, por exemplo http://git-bridge:8000
  • Defina GIT_BRIDGE_ROOT_DIR como o disco de dados do git-bridge montado via bind-mount, por exemplo /data/git-bridge
A configuração a seguir mostra uma instalação autônoma. Para que a demonstração funcione, é necessário fornecer uma chave/certificado SSL válido e ajustar o OVERLEAF_SITE_URL. Numa instalação real, você deve substituir os segredos fictícios por segredos reais, conforme indicado nos comentários. Numa instalação real, é necessário mover os contêineres individuais para nós dedicados e ajustar os endereços IP à configuração da sua rede local.As compilações são executadas em contêineres do TeX Live ao lado de cada instância do Ayakaleaf Pro. Primeiro, baixe a imagem do TeX Live em cada host do Ayakaleaf Pro, por exemplo docker pull ghcr.io/ayaka-notes/texlive-full:2026.1.

Hardware

Recomendamos usar as mesmas especificações de hardware para todas as instâncias do Ayakaleaf Pro que participam da escalabilidade horizontal. Aplicam-se as recomendações gerais sobre as especificações de hardware das instâncias do Ayakaleaf Pro.

Atualizar o Ayakaleaf Pro

Como parte do processo de atualização, o Ayakaleaf Pro executa automaticamente migrações do banco de dados. Estas migrações não foram concebidas para serem executadas a partir de várias instâncias em paralelo. As migrações precisam terminar antes de a aplicação web propriamente dita ser iniciada. Você pode verificar nos logs a entrada Finished migrations ou aguardar até que a aplicação aceite tráfego. O procedimento de atualização é o seguinte:
  1. Agende uma janela de manutenção
  2. Pare todas as instâncias do Ayakaleaf Pro
  3. Faça um backup consistente, conforme descrito na documentação
  4. Inicie uma única instância do Ayakaleaf Pro com a nova versão
  5. Verifique se a nova instância funciona como esperado
  6. Inicie as outras instâncias com a nova versão
Última modificação em 2 de novembro de 2026