Ayakaleaf Pro podporuje horizontální škálování. Otestovali a ověřili jsme, že s více replikami funguje správně.
Požadavky

Externí centrální úložiště dat
Úložiště dat v Ayakaleaf Pro lze rozdělit do čtyř datových úložišť:-
MongoDB
- Většina dat je trvale ukládána do MongoDB.
- Podporujeme lokální instanci i externí instanci, například MongoDB Atlas (plně spravovaná služba MongoDB běžící v infrastruktuře AWS).
-
Redis
- Redis ukládá dočasná data, například čekající aktualizace dokumentů předtím, než jsou zapsány do MongoDB.
- Redis slouží k předávání aktualizací dokumentů mezi různými službami a k upozorňování editoru na změny stavu v daném projektu.
- Redis slouží k ukládání uživatelských relací.
- Podporujeme lokální instanci i externí instanci.
-
Soubory projektů a soubory historie
- Neupravitelné soubory projektů jsou uloženy mimo MongoDB. Systém historie projektů ukládá historii rovněž mimo MongoDB.
- Pro malé samostatné instance podporujeme buď lokální souborový systém (který může být založen na lokálním SSD, NFS nebo EBS), nebo systém úložiště dat kompatibilní s S3.
-
Pro horizontální škálování podporujeme pouze systémy úložiště dat kompatibilní s S3.
-
Dočasné soubory
- Kompilace LaTeXu musí pro optimální výkon běžet na rychlých lokálních discích. Výstup kompilace není třeba trvale ukládat ani zálohovat.
- Lokální disk je přínosný také pro ukládání nově nahrávaných souborů do vyrovnávací paměti a pro vytváření zip souborů projektů.
Důrazně doporučujeme používat lokální disk. Použití jakéhokoli síťového disku (například NFS nebo EBS) může vést k neočekávaným chybám kompilace a dalším problémům s výkonem.
Git-bridge
Git repozitáře jsou uloženy lokálně na disku. Nejsou k dispozici žádné možnosti replikace. Git-bridge by měl běžet jako singleton (jediná instance). Pro optimální výkon doporučujeme pro data git-bridge používat lokální disk. Datový disk git-bridge by se měl pravidelně zálohovat. Pro úložiště dat s horizontálním škálováním potřebujete:- centrální instanci MongoDB, která je přístupná ze všech instancí Ayakaleaf Pro
- centrální instanci Redis, která je přístupná ze všech instancí Ayakaleaf Pro
- centrální úložný backend kompatibilní s S3 pro soubory projektů a historie
- lokální disk na každé instanci pro dočasné soubory
- lokální disk na instanci, která hostuje kontejner git-bridge, pro data git-bridge
Požadavky na load balancer
-
Trvalé směrování (persistent routing), např. pomocí cookie
Tento požadavek vyplývá z těchto komponent:
- Funkce úprav v reálném čase v Ayakaleaf Pro používá WebSockets se záložním řešením v podobě XHR pollingu. Každá relace úprav má na straně serveru lokální stav a požadavky dané relace úprav musí být vždy směrovány na stejnou instanci Ayakaleaf Pro. Funkce spolupráce používá Redis Pub/Sub ke sdílení aktualizací mezi více instancemi Ayakaleaf Pro.
- Kompilace LaTeXu uchovává výstup a mezipaměť kompilace lokálně kvůli výkonu. Po odeslání požadavku na kompilaci na jednu instanci Ayakaleaf Pro musí být následné požadavky na stažení PDF/protokolu směrovány na stejnou instanci Ayakaleaf Pro.
- Dlouhé časové limity požadavků pro podporu kompilace velkých dokumentů LaTeX
- Podpora WebSocket pro optimální výkon
- Velikost těla požadavku POST 50 MB
-
Časový limit keep-alive musí být nižší než časový limit keep-alive v Ayakaleaf Pro
Časový limit keep-alive v Ayakaleaf Pro lze nastavit pomocí proměnné prostředí
NGINX_KEEPALIVE_TIMEOUT. Výchozí hodnota je 65 s. Při výchozím nastavení funguje časový limit keep-alive 60 s v load balanceru. PřiNGINX_KEEPALIVE_TIMEOUT=120by load balancer mohl zvolit 115 s. -
IP adresy klientů
Nastavte hlavičku požadavku
X-Forwarded-Forna IP adresu klienta. -
Při ukončování SSL
Load balancer musí přidat hlavičku požadavku
X-Forwarded-Proto: https.
Ukázková konfigurace HAProxy
Ukázková konfigurace HAProxy
Konfigurace Ayakaleaf Pro
Tajné klíče Instance Ayakaleaf Pro se musí shodovat na sdílených tajných klíčích:WEB_API_PASSWORD(ověřování web api)STAGING_PASSWORDaV1_HISTORY_PASSWORDse stejnou hodnotou (ověřování historie)CRYPTO_RANDOM(pro cookie relace)OT_JWT_AUTH_KEY(ověřování historie)OVERLEAF_INVITE_TOKEN_SECRET(tokeny pro sdílení odkazem, povinné: bez něj se Ayakaleaf Pro odmítne spustit)
/dev/urandom (256 náhodných bitů).
OVERLEAF_MONGO_URL na centrální instanci MongoDB.
Redis
Nasměrujte OVERLEAF_REDIS_HOST a REDIS_HOST na centrální instanci Redis.
Úložiště kompatibilní s S3 pro soubory projektů a historie
Podrobnosti najdete v dokumentaci k úložišti kompatibilnímu s S3.
Dočasné soubory
Výchozí bind-mount lokálního SSD do /var/lib/overleaf bude dostačující. Nezapomeňte nasměrovat SANDBOXED_COMPILES_HOST_DIR na přípojný bod na hostiteli.
Důrazně doporučujeme používat lokální disk. Použití jakéhokoli síťového disku (například NFS nebo EBS) může vést k neočekávaným chybám kompilace a dalším problémům s výkonem.
- Pro získání přesných IP adres klientů nastavte
OVERLEAF_TRUSTED_PROXY_IPSnaloopbackplus IP adresy load balancerů, např.loopback,198.18.0.1. Lze zadat více IP adres nebo CIDR oddělených čárkou.
-
Nastavte
GIT_BRIDGE_ENABLEDna'true' -
Nastavte
GIT_BRIDGE_HOSTna<git-bridge container name>, např.git-bridge -
Nastavte
GIT_BRIDGE_PORTna8000 -
Nastavte
V1_HISTORY_URLnahttp://<server-pro sibling container name>:3100/api. Poznámka: To je nutné pouze u sesterského kontejneru pro kontejner git-bridge. Ostatní instance mohou používat URL localhost, což je výchozí nastavení.
- Nastavte
GIT_BRIDGE_API_BASE_URLnahttp://<server-pro sibling container name>/api/v0, např.http://server-pro-ha-1/api/v0 - Nastavte
GIT_BRIDGE_OAUTH2_SERVERnahttp://<server-pro sibling container name>, např.http://server-pro-ha-1 - Nastavte
GIT_BRIDGE_POSTBACK_BASE_URLnahttp://<git-bridge container name>:8000, např.http://git-bridge:8000 - Nastavte
GIT_BRIDGE_ROOT_DIRna datový disk git-bridge připojený pomocí bind-mount, např./data/git-bridge
Ukázková konfigurace docker-compose.yml
Ukázková konfigurace docker-compose.yml
Následující konfigurace ukazuje samostatné nastavení. Aby ukázka fungovala, musíte poskytnout platný klíč/certifikát SSL a upravit
OVERLEAF_SITE_URL. Pro skutečné nasazení musíte nahradit fiktivní tajné klíče skutečnými, jak je uvedeno v komentářích. Pro skutečné nasazení musíte jednotlivé kontejnery přesunout na vyhrazené uzly a upravit IP adresy podle nastavení vaší místní sítě.Kompilace běží v kontejnerech TeX Live vedle každé instance Ayakaleaf Pro. Nejprve stáhněte image TeX Live na každého hostitele Ayakaleaf Pro, například docker pull ghcr.io/ayaka-notes/texlive-full:2026.1.Hardware
Doporučujeme používat stejné hardwarové specifikace pro všechny instance Ayakaleaf Pro, které se účastní horizontálního škálování. Pro instance Ayakaleaf Pro platí obecná doporučení k hardwarovým specifikacím.Upgrade Ayakaleaf Pro
V rámci procesu upgradu Ayakaleaf Pro automaticky spouští migrace databáze. Tyto migrace nejsou navrženy pro paralelní spouštění z více instancí. Migrace musí být dokončeny před spuštěním samotné webové aplikace. Můžete buď v protokolech vyhledat záznamFinished migrations, nebo počkat, až aplikace začne přijímat provoz.
Postup upgradu vypadá takto:
- Naplánujte okno údržby
- Zastavte všechny instance Ayakaleaf Pro
- Pořiďte konzistentní zálohu podle popisu v dokumentaci
- Spusťte jednu instanci Ayakaleaf Pro s novou verzí
- Ověřte, že nová instance funguje podle očekávání
- Spusťte ostatní instance s novou verzí

