Vai al contenuto principale
Ayakaleaf Pro supporta la scalabilità orizzontale. Abbiamo testato e verificato che funziona correttamente con più repliche.
Questo documento elenca i requisiti tecnici e fornisce linee guida per eseguire Ayakaleaf Pro su più di un nodo. La configurazione della scalabilità orizzontale richiede uno sforzo considerevole. Ti consigliamo di prendere in considerazione la scalabilità orizzontale solo al raggiungimento di una certa scala. Ad esempio, Overleaf ha segnalato un’installazione on-premises per 1.000 utenti totali che funziona con successo su un singolo server dotato di due processori a 4 core e 32GB di memoria di sistema. Consulta la documentazione sui requisiti hardware per le raccomandazioni. Un’installazione di Ayakaleaf Pro con scalabilità orizzontale richiede un insieme di componenti esterni, come un load balancer e un backend di storage compatibile con S3.

Requisiti

Storage dei dati esterno e centralizzato

Lo storage dei dati in Ayakaleaf Pro può essere suddiviso in quattro archivi:
  • MongoDB
    • La maggior parte dei dati viene resa persistente in MongoDB.
    • Supportiamo sia un’istanza locale sia un’istanza esterna, come MongoDB Atlas (un servizio MongoDB completamente gestito che gira all’interno dell’infrastruttura AWS).
    Nota: purtroppo al momento non esiste un supporto ufficiale per database compatibili con MongoDB come CosmoDB/DocumentDB, poiché non abbiamo testato Ayakaleaf Pro con essi. Sebbene installare Ayakaleaf Pro con database compatibili possa essere possibile, supportiamo ufficialmente solo le installazioni che utilizzano MongoDB.
  • Redis
    • Redis memorizza dati temporanei, come gli aggiornamenti dei documenti in sospeso prima che vengano scritti in MongoDB.
    • Redis viene utilizzato per comunicare gli aggiornamenti dei documenti tra i diversi servizi e per notificare all’editor i cambiamenti di stato in un determinato progetto.
    • Redis viene utilizzato per memorizzare le sessioni utente.
    • Supportiamo sia un’istanza locale sia un’istanza esterna.
    Nota: purtroppo al momento non esiste un supporto ufficiale per key/value store compatibili con Redis come KeyDB/Valkey, poiché non abbiamo testato Ayakaleaf Pro con essi. Sebbene installare Ayakaleaf Pro con store compatibili possa essere possibile, supportiamo ufficialmente solo le installazioni che utilizzano Redis.
  • File dei progetti e file della cronologia
    • I file di progetto non modificabili sono memorizzati al di fuori di MongoDB. Anche il sistema di cronologia dei progetti memorizza la cronologia al di fuori di MongoDB.
    • Per piccole istanze singole supportiamo sia un file system locale (che potrebbe essere basato su un SSD locale, NFS o EBS) sia un sistema di storage dei dati compatibile con S3.
    • Per la scalabilità orizzontale supportiamo solo sistemi di storage dei dati compatibili con S3.
    Importante: NFS/Amazon EFS/Amazon EBS non sono supportati per la scalabilità orizzontale. Consulta la sezione sui requisiti di storage hardware relativa alla scalabilità dello storage in Ayakaleaf Pro per maggiori dettagli.
  • File effimeri
    • Le compilazioni LaTeX devono essere eseguite su dischi locali veloci per prestazioni ottimali. L’output della compilazione non deve essere reso persistente né sottoposto a backup.
    • Anche il buffering dei nuovi caricamenti di file e la creazione dei file zip dei progetti traggono vantaggio dall’uso di un disco locale.
Ti consigliamo vivamente di utilizzare un disco locale. L’uso di qualsiasi tipo di disco di rete (come NFS o EBS) può causare errori di compilazione imprevisti e altri problemi di prestazioni.

Git-bridge

I repository git sono memorizzati localmente su disco. Non sono disponibili opzioni di replica. Git-bridge deve essere eseguito come singleton. Per prestazioni ottimali, ti consigliamo di utilizzare un disco locale per i dati di git-bridge. Il disco dei dati di git-bridge deve essere sottoposto regolarmente a backup. Per lo storage dei dati con scalabilità orizzontale, hai bisogno di:
  • un’istanza MongoDB centrale accessibile da tutte le istanze di Ayakaleaf Pro
  • un’istanza Redis centrale accessibile da tutte le istanze di Ayakaleaf Pro
  • un backend di storage centrale compatibile con S3 per i file dei progetti e della cronologia
  • un disco locale su ogni istanza per i file effimeri
  • un disco locale sull’istanza che ospita il container git-bridge per i dati di git-bridge

Requisiti del load balancer

  • Instradamento persistente, ad es. tramite un cookie Questo requisito deriva dai seguenti componenti:
    • La funzionalità di modifica in tempo reale di Ayakaleaf Pro utilizza i WebSocket con fallback al polling XHR. Ogni sessione di modifica ha uno stato locale lato server e le richieste di una data sessione di modifica devono sempre essere instradate alla stessa istanza di Ayakaleaf Pro. La funzionalità di collaborazione utilizza il Pub/Sub di Redis per condividere gli aggiornamenti tra più istanze di Ayakaleaf Pro.
    • La compilazione LaTeX conserva localmente l’output e la cache di compilazione per prestazioni ottimali. Dopo l’invio di una richiesta di compilazione a un’istanza di Ayakaleaf Pro, le successive richieste di download del PDF/log devono essere instradate alla stessa istanza di Ayakaleaf Pro.
  • Timeout delle richieste lunghi per supportare la compilazione di documenti LaTeX di grandi dimensioni
  • Supporto WebSocket per prestazioni ottimali
  • Dimensione del payload POST di 50MB
  • Il timeout keep-alive deve essere inferiore al timeout keep-alive di Ayakaleaf Pro Il timeout keep-alive in Ayakaleaf Pro può essere configurato con la variabile d’ambiente NGINX_KEEPALIVE_TIMEOUT. Il valore predefinito è 65s. Con il valore predefinito, un timeout keep-alive di 60s nel load balancer funziona. Con NGINX_KEEPALIVE_TIMEOUT=120, il load balancer potrebbe usare 115s.
  • IP dei client Imposta l’header di richiesta X-Forwarded-For sull’IP del client.
  • Quando si effettua la terminazione SSL Il load balancer deve aggiungere l’header di richiesta X-Forwarded-Proto: https.

Configurazione di Ayakaleaf Pro

Segreti Le istanze di Ayakaleaf Pro devono condividere gli stessi segreti:
  • WEB_API_PASSWORD (autenticazione web api)
  • STAGING_PASSWORD e V1_HISTORY_PASSWORD con lo stesso valore (autenticazione della cronologia)
  • CRYPTO_RANDOM (per il cookie di sessione)
  • OT_JWT_AUTH_KEY (autenticazione della cronologia)
  • OVERLEAF_INVITE_TOKEN_SECRET (token per la condivisione tramite link, obbligatorio: senza di esso Ayakaleaf Pro si rifiuta di avviarsi)
Ciascuno di questi segreti deve essere configurato con un proprio valore univoco e condiviso tra le istanze. Se non sono configurati e le richieste degli utenti vengono instradate a istanze di Ayakaleaf Pro diverse, le loro richieste non supereranno i controlli di autenticazione e gli utenti verranno reindirizzati frequentemente alla pagina di accesso oppure le loro azioni nell’interfaccia falliranno in modi imprevisti. Se non sono configurati, Ayakaleaf Pro utilizza un nuovo valore casuale per ciascun segreto, basato su 32 byte casuali da /dev/urandom (256 bit casuali).
MongoDB Punta OVERLEAF_MONGO_URL all’istanza MongoDB centrale. Redis Punta OVERLEAF_REDIS_HOST e REDIS_HOST all’istanza Redis centrale. Storage compatibile con S3 per i file dei progetti e della cronologia Consulta la documentazione sullo storage compatibile con S3 per i dettagli. File effimeri Il bind-mount predefinito di un SSD locale su /var/lib/overleaf sarà sufficiente. Assicurati di puntare SANDBOXED_COMPILES_HOST_DIR al punto di mount sull’host.
Ti consigliamo vivamente di utilizzare un disco locale. L’uso di qualsiasi tipo di disco di rete (come NFS o EBS) può causare errori di compilazione imprevisti e altri problemi di prestazioni.
Configurazione del proxy
  • Imposta OVERLEAF_TRUSTED_PROXY_IPS su loopback più gli IP dei load balancer, ad es. loopback,198.18.0.1, per ottenere IP dei client accurati. È possibile specificare più IP o CIDR, separati da una virgola.
Integrazione Git-bridge Il container git-bridge necessita di un container Ayakaleaf Pro “gemello” per gestire le richieste git in arrivo. Questo container gemello può servire anche il normale traffico degli utenti. Nella configurazione di esempio, la prima istanza funge da container gemello per git-bridge, ma in realtà qualsiasi istanza potrebbe svolgere questo ruolo. Perché dobbiamo designare un container Ayakaleaf Pro come gemello per git-bridge? Ayakaleaf Pro fornisce a git-bridge gli URL di download del servizio di cronologia. Dobbiamo configurare questi URL della cronologia in modo che siano accessibili dal container git-bridge. Configurazione del container Ayakaleaf Pro:
  • Imposta GIT_BRIDGE_ENABLED su 'true'
  • Imposta GIT_BRIDGE_HOST su <git-bridge container name>, ad es. git-bridge
  • Imposta GIT_BRIDGE_PORT su 8000
  • Imposta V1_HISTORY_URL su http://<server-pro sibling container name>:3100/api. Nota: questo è necessario solo sul container gemello del container git-bridge. Le altre istanze possono usare un URL localhost, che è il valore predefinito.
Configurazione del container git-bridge:
  • Imposta GIT_BRIDGE_API_BASE_URL su http://<server-pro sibling container name>/api/v0, ad es. http://server-pro-ha-1/api/v0
  • Imposta GIT_BRIDGE_OAUTH2_SERVER su http://<server-pro sibling container name>, ad es. http://server-pro-ha-1
  • Imposta GIT_BRIDGE_POSTBACK_BASE_URL su http://<git-bridge container name>:8000, ad es. http://git-bridge:8000
  • Imposta GIT_BRIDGE_ROOT_DIR sul disco dei dati di git-bridge montato tramite bind-mount, ad es. /data/git-bridge
La seguente configurazione mostra un setup autonomo. Perché la demo funzioni, devi fornire una chiave/certificato SSL valido e adattare OVERLEAF_SITE_URL. Per un setup reale, devi sostituire i segreti fittizi con segreti reali, come indicato nei commenti. Per un setup reale, devi spostare i singoli container su nodi dedicati e adattare gli indirizzi IP alla configurazione della tua rete locale.I compile vengono eseguiti in container TeX Live accanto a ciascuna istanza di Ayakaleaf Pro. Scarica prima l’immagine TeX Live su ogni host di Ayakaleaf Pro, ad esempio docker pull ghcr.io/ayaka-notes/texlive-full:2026.1.

Hardware

Ti consigliamo di utilizzare le stesse specifiche hardware per tutte le istanze di Ayakaleaf Pro che partecipano alla scalabilità orizzontale. Si applicano le raccomandazioni generali sulle specifiche hardware per le istanze di Ayakaleaf Pro.

Aggiornare Ayakaleaf Pro

Durante il processo di aggiornamento, Ayakaleaf Pro esegue automaticamente le migrazioni del database. Queste migrazioni non sono progettate per essere eseguite da più istanze in parallelo. Le migrazioni devono terminare prima che venga avviata l’applicazione web vera e propria. Puoi controllare nei log la presenza di una voce Finished migrations oppure attendere che l’applicazione accetti traffico. La procedura di aggiornamento è la seguente:
  1. Pianifica una finestra di manutenzione
  2. Arresta tutte le istanze di Ayakaleaf Pro
  3. Esegui un backup coerente come descritto nella documentazione
  4. Avvia una singola istanza di Ayakaleaf Pro con la nuova versione
  5. Verifica che la nuova istanza funzioni come previsto
  6. Avvia le altre istanze con la nuova versione
Ultima modifica il 2 novembre 2026