Přejít na hlavní obsah
Ayakaleaf Pro podporuje horizontální škálování. Otestovali a ověřili jsme, že s více replikami funguje správně.
Tento dokument uvádí technické požadavky a poskytuje pokyny pro provoz Ayakaleaf Pro na více než jednom uzlu. Nastavení horizontálního škálování vyžaduje značné úsilí. Doporučujeme zvažovat horizontální škálování až po dosažení určitého rozsahu. Například Overleaf uvedl on-premise instalaci pro celkem 1 000 uživatelů, která byla úspěšně provozována na jediném serveru se dvěma čtyřjádrovými procesory a 32 GB systémové paměti. Doporučení najdete v dokumentaci hardwarových požadavků. Nasazení Ayakaleaf Pro s horizontálním škálováním zahrnuje sadu externích komponent, jako je nástroj pro vyrovnávání zátěže (load balancer) a úložný backend kompatibilní s S3.

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).
    Poznámka: Bohužel v současnosti neexistuje oficiální podpora databází kompatibilních s MongoDB, jako jsou CosmoDB/DocumentDB, protože jsme s nimi Ayakaleaf Pro netestovali. Nasazení Ayakaleaf Pro s kompatibilními databázemi může být možné, oficiálně však podporujeme pouze nasazení využívající MongoDB.
  • 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.
    Poznámka: Bohužel v současnosti neexistuje oficiální podpora úložišť klíč/hodnota kompatibilních s Redisem, jako jsou KeyDB/Valkey, protože jsme s nimi Ayakaleaf Pro netestovali. Nasazení Ayakaleaf Pro s kompatibilními úložišti může být možné, oficiálně však podporujeme pouze nasazení využívající Redis.
  • 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.
    Důležité: NFS/Amazon EFS/Amazon EBS nejsou pro horizontální škálování podporovány. Další podrobnosti o škálování úložiště v Ayakaleaf Pro najdete v části požadavků na hardwarové úložiště.
  • 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ři NGINX_KEEPALIVE_TIMEOUT=120 by load balancer mohl zvolit 115 s.
  • IP adresy klientů Nastavte hlavičku požadavku X-Forwarded-For na IP adresu klienta.
  • Při ukončování SSL Load balancer musí přidat hlavičku požadavku X-Forwarded-Proto: https.

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_PASSWORD a V1_HISTORY_PASSWORD se 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)
Každý z těchto tajných klíčů musí být nakonfigurován s vlastní jedinečnou hodnotou a sdílen mezi instancemi. Pokud nejsou nakonfigurovány a požadavky uživatelů jsou směrovány na různé instance Ayakaleaf Pro, jejich požadavky neprojdou kontrolami ověření a uživatelé budou buď často přesměrováváni na přihlašovací stránku, nebo jejich akce v uživatelském rozhraní budou selhávat neočekávaným způsobem. Pokud nejsou nakonfigurovány, Ayakaleaf Pro použije pro každý tajný klíč novou náhodnou hodnotu založenou na 32 náhodných bajtech z /dev/urandom (256 náhodných bitů).
MongoDB Nasměrujte 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.
Konfigurace proxy
  • Pro získání přesných IP adres klientů nastavte OVERLEAF_TRUSTED_PROXY_IPS na loopback plus IP adresy load balancerů, např. loopback,198.18.0.1. Lze zadat více IP adres nebo CIDR oddělených čárkou.
Integrace git-bridge Kontejner git-bridge potřebuje sesterský kontejner Ayakaleaf Pro, který obsluhuje příchozí git požadavky. Tento sesterský kontejner může obsluhovat i běžný uživatelský provoz. V ukázkové konfiguraci slouží jako sesterský kontejner pro git-bridge první instance, ve skutečnosti však může tuto roli plnit kterákoli instance. Proč je potřeba určit jeden kontejner Ayakaleaf Pro jako sesterský pro git-bridge? Ayakaleaf Pro předává git-bridge URL pro stahování ze služby historie. Tyto URL historie je nutné nakonfigurovat tak, aby byly přístupné z kontejneru git-bridge. Konfigurace kontejneru Ayakaleaf Pro:
  • Nastavte GIT_BRIDGE_ENABLED na 'true'
  • Nastavte GIT_BRIDGE_HOST na <git-bridge container name>, např. git-bridge
  • Nastavte GIT_BRIDGE_PORT na 8000
  • Nastavte V1_HISTORY_URL na http://<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í.
Konfigurace kontejneru git-bridge:
  • Nastavte GIT_BRIDGE_API_BASE_URL na http://<server-pro sibling container name>/api/v0, např. http://server-pro-ha-1/api/v0
  • Nastavte GIT_BRIDGE_OAUTH2_SERVER na http://<server-pro sibling container name>, např. http://server-pro-ha-1
  • Nastavte GIT_BRIDGE_POSTBACK_BASE_URL na http://<git-bridge container name>:8000, např. http://git-bridge:8000
  • Nastavte GIT_BRIDGE_ROOT_DIR na datový disk git-bridge připojený pomocí bind-mount, např. /data/git-bridge
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áznam Finished migrations, nebo počkat, až aplikace začne přijímat provoz. Postup upgradu vypadá takto:
  1. Naplánujte okno údržby
  2. Zastavte všechny instance Ayakaleaf Pro
  3. Pořiďte konzistentní zálohu podle popisu v dokumentaci
  4. Spusťte jednu instanci Ayakaleaf Pro s novou verzí
  5. Ověřte, že nová instance funguje podle očekávání
  6. Spusťte ostatní instance s novou verzí
Naposledy změněno 2. listopadu 2026