Spring til hovedindhold
Ayakaleaf Pro understøtter horisontal skalering. Vi har testet og bekræftet, at det kører korrekt med flere replikaer.
Dette dokument beskriver de tekniske krav og giver retningslinjer for at køre Ayakaleaf Pro på mere end én node. Opsætning af horisontal skalering kræver en betydelig indsats. Vi råder til kun at overveje horisontal skalering, når man når en vis størrelse. For eksempel har Overleaf rapporteret om en on-premises-installation til i alt 1.000 brugere, der kører med succes på en enkelt server udstyret med to 4-kerne-processorer og 32 GB systemhukommelse. Se dokumentationen om hardwarekrav for at få anbefalinger. En installation af Ayakaleaf Pro med horisontal skalering omfatter en række eksterne komponenter, såsom en load balancer og et S3-kompatibelt lagringsbackend.

Krav

Eksternt, centralt datalager

Datalagringen i Ayakaleaf Pro kan opdeles i fire datalagre:
  • MongoDB
    • Størstedelen af dataene gemmes i MongoDB.
    • Vi understøtter enten en lokal instans eller en ekstern instans, såsom MongoDB Atlas (en fuldt administreret MongoDB-tjeneste, der kører i AWS-infrastrukturen).
    Bemærk: Desværre er der i øjeblikket ingen officiel understøttelse af MongoDB-kompatible databaser som CosmoDB/DocumentDB, da vi ikke har testet Ayakaleaf Pro med dem. Selvom det måske er muligt at installere Ayakaleaf Pro med kompatible databaser, understøtter vi officielt kun installationer, der bruger MongoDB.
  • Redis
    • Redis gemmer midlertidige data, såsom ventende dokumentopdateringer, før de skrives til MongoDB.
    • Redis bruges til at formidle dokumentopdateringer mellem forskellige tjenester og til at underrette editoren om tilstandsændringer i et givet projekt.
    • Redis bruges til at gemme brugersessioner.
    • Vi understøtter enten en lokal instans eller en ekstern instans.
    Bemærk: Desværre er der i øjeblikket ingen officiel understøttelse af Redis-kompatible key/value-lagre som KeyDB/Valkey, da vi ikke har testet Ayakaleaf Pro med dem. Selvom det måske er muligt at installere Ayakaleaf Pro med kompatible lagre, understøtter vi officielt kun installationer, der bruger Redis.
  • Projektfiler og historikfiler
    • Ikke-redigerbare projektfiler gemmes uden for MongoDB. Projekthistoriksystemet gemmer også historikken uden for MongoDB.
    • Til små enkeltinstanser understøtter vi enten et lokalt filsystem (som kan være baseret på en lokal SSD, NFS eller EBS) eller et S3-kompatibelt datalagringssystem.
    • Til horisontal skalering understøtter vi kun S3-kompatible datalagringssystemer.
    Vigtigt: NFS/Amazon EFS/Amazon EBS understøttes ikke til horisontal skalering. Se afsnittet om krav til hardwarelager om skalering af lager i Ayakaleaf Pro for at få flere detaljer.
  • Midlertidige filer
    • LaTeX-kompileringer skal køre på hurtige, lokale diske for at opnå optimal ydeevne. Kompileringsoutputtet behøver ikke at blive gemt permanent eller sikkerhedskopieret.
    • Buffering af nye filuploads og oprettelse af zip-filer med projekter har også fordel af at bruge en lokal disk.
Vi anbefaler kraftigt at bruge en lokal disk. Brug af enhver form for netværksdisk (såsom NFS eller EBS) kan resultere i uventede kompileringsfejl og andre ydeevneproblemer.

Git-bridge

Git-repositorierne gemmes lokalt på disken. Der er ingen replikeringsmuligheder. Git-bridge skal køres som en singleton. For at opnå optimal ydeevne anbefaler vi at bruge en lokal disk til git-bridge-data. Git-bridge-datadisken bør sikkerhedskopieres regelmæssigt. Til datalagringen ved horisontal skalering skal du bruge:
  • en central MongoDB-instans, der er tilgængelig fra alle Ayakaleaf Pro-instanser
  • en central Redis-instans, der er tilgængelig fra alle Ayakaleaf Pro-instanser
  • et centralt S3-kompatibelt lagringsbackend til projekt- og historikfiler
  • en lokal disk på hver instans til midlertidige filer
  • en lokal disk på den instans, der hoster git-bridge-containeren, til git-bridge-data

Krav til load balanceren

  • Vedvarende routing, f.eks. ved hjælp af en cookie Dette krav skyldes følgende komponenter:
    • Realtidsredigeringen i Ayakaleaf Pro bruger WebSockets med XHR-polling som fallback. Hver redigeringssession har lokal tilstand på serversiden, og anmodningerne i en given redigeringssession skal altid routes til den samme Ayakaleaf Pro-instans. Samarbejdsfunktionen bruger Redis Pub/Sub til at dele opdateringer mellem flere Ayakaleaf Pro-instanser.
    • LaTeX-kompileringen gemmer output og kompileringscache lokalt af hensyn til ydeevnen. Når der sendes en kompileringsanmodning til én Ayakaleaf Pro-instans, skal de efterfølgende anmodninger om download af PDF/log routes til den samme Ayakaleaf Pro-instans.
  • Lange timeouts for anmodninger for at understøtte kompilering af store LaTeX-dokumenter
  • WebSocket-understøttelse for optimal ydeevne
  • POST-payloadstørrelse på 50 MB
  • Keep-alive-timeout skal være lavere end keep-alive-timeouten i Ayakaleaf Pro Keep-alive-timeouten i Ayakaleaf Pro kan konfigureres med miljøvariablen NGINX_KEEPALIVE_TIMEOUT. Standardværdien er 65 s. Med standardværdien fungerer en keep-alive-timeout på 60 s i load balanceren. Med NGINX_KEEPALIVE_TIMEOUT=120 kan load balanceren vælge 115 s.
  • Klient-IP’er Sæt anmodningsheaderen X-Forwarded-For til klientens IP.
  • Ved SSL-terminering Load balanceren skal tilføje anmodningsheaderen X-Forwarded-Proto: https.

Konfiguration af Ayakaleaf Pro

Hemmeligheder Ayakaleaf Pro-instanserne skal være enige om fælles hemmeligheder:
  • WEB_API_PASSWORD (godkendelse af web-API)
  • STAGING_PASSWORD og V1_HISTORY_PASSWORD med samme værdi (godkendelse af historik)
  • CRYPTO_RANDOM (til sessionscookie)
  • OT_JWT_AUTH_KEY (godkendelse af historik)
  • OVERLEAF_INVITE_TOKEN_SECRET (tokens til linkdeling, påkrævet: uden den nægter Ayakaleaf Pro at starte)
Alle disse hemmeligheder skal konfigureres med hver sin unikke værdi og deles mellem instanserne. Hvis de ikke er konfigureret, og brugeranmodninger routes til forskellige Ayakaleaf Pro-instanser, vil anmodningerne fejle i godkendelseskontrollerne, og brugerne vil enten ofte blive omdirigeret til login-siden, eller deres handlinger i brugergrænsefladen vil fejle på uventede måder. Hvis de ikke er konfigureret, bruger Ayakaleaf Pro en ny tilfældig værdi for hver hemmelighed baseret på 32 tilfældige bytes fra /dev/urandom (256 tilfældige bits).
MongoDB Lad OVERLEAF_MONGO_URL pege på den centrale MongoDB-instans. Redis Lad OVERLEAF_REDIS_HOST og REDIS_HOST pege på den centrale Redis-instans. S3-kompatibelt lager til projekt- og historikfiler Se dokumentationen om S3-kompatibelt lager for at få flere detaljer. Midlertidige filer Standard-bind-mountet af en lokal SSD til /var/lib/overleaf er tilstrækkeligt. Sørg for at lade SANDBOXED_COMPILES_HOST_DIR pege på mountpunktet på værten.
Vi anbefaler kraftigt at bruge en lokal disk. Brug af enhver form for netværksdisk (såsom NFS eller EBS) kan resultere i uventede kompileringsfejl og andre ydeevneproblemer.
Proxykonfiguration
  • Sæt OVERLEAF_TRUSTED_PROXY_IPS til loopback plus load balancernes IP’er, f.eks. loopback,198.18.0.1, for at få korrekte klient-IP’er. Flere IP’er eller CIDR’er kan angives, adskilt af komma.
Git-bridge-integration Git-bridge-containeren har brug for en søskende-container med Ayakaleaf Pro til at håndtere indgående git-anmodninger. Denne søskende-container kan også betjene almindelig brugertrafik. I eksempelkonfigurationen fungerer den første instans som søskende-container for git-bridge, men i praksis kan enhver instans udfylde den rolle. Hvorfor skal vi udpege én Ayakaleaf Pro-container som søskende for git-bridge? Ayakaleaf Pro udleverer download-URL’er til historiktjenesten til git-bridge. Vi skal konfigurere disse historik-URL’er, så de er tilgængelige fra git-bridge-containeren. Konfiguration af Ayakaleaf Pro-containeren:
  • Sæt GIT_BRIDGE_ENABLED til 'true'
  • Sæt GIT_BRIDGE_HOST til <git-bridge container name>, f.eks. git-bridge
  • Sæt GIT_BRIDGE_PORT til 8000
  • Sæt V1_HISTORY_URL til http://<server-pro sibling container name>:3100/api. Bemærk: Dette er kun nødvendigt på søskende-containeren til git-bridge-containeren. De øvrige instanser kan bruge en localhost-URL, som er standard.
Konfiguration af git-bridge-containeren:
  • Sæt GIT_BRIDGE_API_BASE_URL til http://<server-pro sibling container name>/api/v0, f.eks. http://server-pro-ha-1/api/v0
  • Sæt GIT_BRIDGE_OAUTH2_SERVER til http://<server-pro sibling container name>, f.eks. http://server-pro-ha-1
  • Sæt GIT_BRIDGE_POSTBACK_BASE_URL til http://<git-bridge container name>:8000, f.eks. http://git-bridge:8000
  • Sæt GIT_BRIDGE_ROOT_DIR til den bind-mountede git-bridge-datadisk, f.eks. /data/git-bridge
Følgende konfiguration viser en selvstændig opsætning. For at demoen kan fungere, skal du angive en gyldig SSL-nøgle/-certifikat og tilpasse OVERLEAF_SITE_URL. I en rigtig opsætning skal du erstatte dummy-hemmelighederne med rigtige hemmeligheder som angivet i kommentarerne. I en rigtig opsætning skal du flytte de enkelte containere over på dedikerede noder og tilpasse IP-adresserne til din lokale netværksopsætning.Kompileringer kører i TeX Live-containere ved siden af hver Ayakaleaf Pro-instans. Hent først TeX Live-imaget på hver Ayakaleaf Pro-vært, for eksempel docker pull ghcr.io/ayaka-notes/texlive-full:2026.1.

Hardware

Vi anbefaler at bruge de samme hardwarespecifikationer til alle de Ayakaleaf Pro-instanser, der indgår i den horisontale skalering. De generelle anbefalinger om hardwarespecifikationer for Ayakaleaf Pro-instanser gælder.

Opgradering af Ayakaleaf Pro

Som en del af opgraderingsprocessen kører Ayakaleaf Pro automatisk databasemigreringer. Disse migreringer er ikke designet til at blive kørt fra flere instanser parallelt. Migreringerne skal være færdige, før selve webapplikationen startes. Du kan enten kontrollere loggene for en post med Finished migrations eller vente, til applikationen accepterer trafik. Opgraderingsproceduren ser således ud:
  1. Planlæg et vedligeholdelsesvindue
  2. Stop alle instanser af Ayakaleaf Pro
  3. Tag en konsistent sikkerhedskopi som beskrevet i dokumentationen
  4. Start en enkelt instans af Ayakaleaf Pro med den nye version
  5. Kontrollér, at den nye instans fungerer som forventet
  6. Start de øvrige instanser med den nye version
Sidst ændret 2. november 2026