Przejdź do głównej treści
Ayakaleaf Pro obsługuje skalowanie poziome. Przetestowaliśmy i zweryfikowaliśmy jego poprawne działanie z wieloma replikami.
Ten dokument przedstawia wymagania techniczne i wytyczne dotyczące uruchamiania Ayakaleaf Pro na więcej niż jednym węźle. Skonfigurowanie skalowania poziomego wymaga znacznego nakładu pracy. Zalecamy rozważenie skalowania poziomego wyłącznie po osiągnięciu określonej skali. Na przykład Overleaf informował o instalacji on-premises dla łącznie 1000 użytkowników, która z powodzeniem działała na pojedynczym serwerze wyposażonym w dwa 4-rdzeniowe procesory i 32GB pamięci operacyjnej. Zalecenia znajdziesz w dokumentacji wymagań sprzętowych. Wdrożenie Ayakaleaf Pro ze skalowaniem poziomym obejmuje zestaw komponentów zewnętrznych, takich jak load balancer i backend pamięci masowej zgodnej z S3.

Wymagania

Zewnętrzne, centralne przechowywanie danych

Przechowywanie danych w Ayakaleaf Pro można podzielić na cztery magazyny danych:
  • MongoDB
    • Większość danych jest utrwalana w MongoDB.
    • Obsługujemy zarówno instancję lokalną, jak i zewnętrzną, taką jak MongoDB Atlas (w pełni zarządzana usługa MongoDB działająca w infrastrukturze AWS).
    Uwaga: niestety obecnie nie ma oficjalnego wsparcia dla baz danych zgodnych z MongoDB, takich jak CosmoDB/DocumentDB, ponieważ nie testowaliśmy z nimi Ayakaleaf Pro. Choć wdrożenie Ayakaleaf Pro z kompatybilnymi bazami danych może być możliwe, oficjalnie wspieramy wyłącznie wdrożenia korzystające z MongoDB.
  • Redis
    • Redis przechowuje dane tymczasowe, takie jak oczekujące aktualizacje dokumentów przed ich zapisaniem do MongoDB.
    • Redis służy do przekazywania aktualizacji dokumentów między różnymi usługami oraz powiadamiania edytora o zmianach stanu w danym projekcie.
    • Redis służy do przechowywania sesji użytkowników.
    • Obsługujemy zarówno instancję lokalną, jak i zewnętrzną.
    Uwaga: niestety obecnie nie ma oficjalnego wsparcia dla magazynów klucz-wartość zgodnych z Redis, takich jak KeyDB/Valkey, ponieważ nie testowaliśmy z nimi Ayakaleaf Pro. Choć wdrożenie Ayakaleaf Pro z kompatybilnymi magazynami może być możliwe, oficjalnie wspieramy wyłącznie wdrożenia korzystające z Redis.
  • Pliki projektów i pliki historii
    • Nieedytowalne pliki projektów są przechowywane poza MongoDB. System historii projektów również przechowuje historię poza MongoDB.
    • W przypadku małych pojedynczych instancji obsługujemy lokalny system plików (oparty np. na lokalnym dysku SSD, NFS lub EBS) albo system przechowywania danych zgodny z S3.
    • W przypadku skalowania poziomego obsługujemy wyłącznie systemy przechowywania danych zgodne z S3.
    Ważne: NFS/Amazon EFS/Amazon EBS nie są obsługiwane przy skalowaniu poziomym. Więcej szczegółów znajdziesz w sekcji wymagań dotyczących pamięci masowej, opisującej skalowanie pamięci masowej w Ayakaleaf Pro.
  • Pliki tymczasowe
    • Kompilacje LaTeX powinny działać na szybkich dyskach lokalnych, aby zapewnić optymalną wydajność. Wynik kompilacji nie musi być utrwalany ani objęty kopią zapasową.
    • Buforowanie nowo przesyłanych plików i tworzenie plików zip projektów również korzysta na użyciu dysku lokalnego.
Zdecydowanie zalecamy używanie dysku lokalnego. Użycie jakiegokolwiek dysku sieciowego (takiego jak NFS lub EBS) może powodować nieoczekiwane błędy kompilacji i inne problemy z wydajnością.

Git-bridge

Repozytoria git są przechowywane lokalnie na dysku. Nie są dostępne żadne opcje replikacji. Git-bridge powinien działać jako singleton (pojedyncza instancja). Dla optymalnej wydajności zalecamy używanie dysku lokalnego do przechowywania danych git-bridge. Dysk z danymi git-bridge powinien być regularnie objęty kopią zapasową. Do przechowywania danych przy skalowaniu poziomym potrzebujesz:
  • centralnej instancji MongoDB dostępnej ze wszystkich instancji Ayakaleaf Pro
  • centralnej instancji Redis dostępnej ze wszystkich instancji Ayakaleaf Pro
  • centralnego backendu pamięci masowej zgodnej z S3 dla plików projektów i historii
  • dysku lokalnego na każdej instancji dla plików tymczasowych
  • dysku lokalnego na instancji hostującej kontener git-bridge dla danych git-bridge

Wymagania dotyczące load balancera

  • Trwałe routowanie (sticky sessions), np. za pomocą pliku cookie To wymaganie wynika z następujących komponentów:
    • Funkcja edycji w czasie rzeczywistym w Ayakaleaf Pro korzysta z WebSockets z mechanizmem awaryjnym w postaci odpytywania XHR. Każda sesja edycji ma lokalny stan po stronie serwera, a żądania danej sesji edycji muszą być zawsze kierowane do tej samej instancji Ayakaleaf Pro. Funkcja współpracy używa mechanizmu Redis Pub/Sub do udostępniania aktualizacji między wieloma instancjami Ayakaleaf Pro.
    • Kompilacja LaTeX przechowuje wynik i pamięć podręczną kompilacji lokalnie w celu zwiększenia wydajności. Po wysłaniu żądania kompilacji do jednej instancji Ayakaleaf Pro kolejne żądania pobrania PDF/dziennika muszą być kierowane do tej samej instancji Ayakaleaf Pro.
  • Długie limity czasu żądań, aby obsłużyć kompilację dużych dokumentów LaTeX
  • Obsługa WebSocket dla optymalnej wydajności
  • Rozmiar ładunku POST wynoszący 50MB
  • Limit czasu keep-alive musi być niższy niż limit czasu keep-alive w Ayakaleaf Pro Limit czasu keep-alive w Ayakaleaf Pro można skonfigurować za pomocą zmiennej środowiskowej NGINX_KEEPALIVE_TIMEOUT. Wartość domyślna to 65s. Przy wartości domyślnej sprawdzi się limit czasu keep-alive w load balancerze wynoszący 60s. Przy NGINX_KEEPALIVE_TIMEOUT=120 load balancer mógłby użyć wartości 115s.
  • Adresy IP klientów Ustaw nagłówek żądania X-Forwarded-For na adres IP klienta.
  • Przy terminowaniu SSL Load balancer musi dodawać nagłówek żądania X-Forwarded-Proto: https.

Konfiguracja Ayakaleaf Pro

Sekrety Instancje Ayakaleaf Pro muszą korzystać ze wspólnych sekretów:
  • WEB_API_PASSWORD (uwierzytelnianie web api)
  • STAGING_PASSWORD i V1_HISTORY_PASSWORD o tej samej wartości (uwierzytelnianie historii)
  • CRYPTO_RANDOM (dla pliku cookie sesji)
  • OT_JWT_AUTH_KEY (uwierzytelnianie historii)
  • OVERLEAF_INVITE_TOKEN_SECRET (tokeny udostępniania przez link, wymagany: bez niego Ayakaleaf Pro odmawia uruchomienia)
Każdy z tych sekretów musi mieć własną, unikalną wartość, wspólną dla wszystkich instancji. Jeśli nie zostaną skonfigurowane, a żądania użytkownika trafią do różnych instancji Ayakaleaf Pro, nie przejdą one kontroli uwierzytelniania — użytkownicy będą często przekierowywani na stronę logowania albo ich działania w interfejsie będą kończyć się niepowodzeniem w nieoczekiwany sposób. Jeśli sekrety nie są skonfigurowane, Ayakaleaf Pro używa dla każdego z nich nowej losowej wartości opartej na 32 losowych bajtach z /dev/urandom (256 losowych bitów).
MongoDB Skieruj OVERLEAF_MONGO_URL na centralną instancję MongoDB. Redis Skieruj OVERLEAF_REDIS_HOST oraz REDIS_HOST na centralną instancję Redis. Pamięć masowa zgodna z S3 dla plików projektów i historii Szczegóły znajdziesz w dokumentacji pamięci masowej zgodnej z S3. Pliki tymczasowe Wystarczy domyślne montowanie typu bind lokalnego dysku SSD w /var/lib/overleaf. Pamiętaj, aby skierować SANDBOXED_COMPILES_HOST_DIR na punkt montowania na hoście.
Zdecydowanie zalecamy używanie dysku lokalnego. Użycie jakiegokolwiek dysku sieciowego (takiego jak NFS lub EBS) może powodować nieoczekiwane błędy kompilacji i inne problemy z wydajnością.
Konfiguracja proxy
  • Ustaw OVERLEAF_TRUSTED_PROXY_IPS na loopback oraz adresy IP load balancerów, np. loopback,198.18.0.1, aby uzyskać prawidłowe adresy IP klientów. Można podać wiele adresów IP lub zakresów CIDR, rozdzielonych przecinkami.
Integracja z git-bridge Kontener git-bridge potrzebuje towarzyszącego (sibling) kontenera Ayakaleaf Pro do obsługi przychodzących żądań git. Ten kontener może jednocześnie obsługiwać zwykły ruch użytkowników. W przykładowej konfiguracji pierwsza instancja pełni rolę kontenera towarzyszącego dla git-bridge, ale w praktyce może to być dowolna instancja. Dlaczego trzeba wyznaczyć jeden kontener Ayakaleaf Pro jako towarzyszący dla git-bridge? Ayakaleaf Pro przekazuje git-bridge adresy URL do pobierania z usługi historii. Te adresy URL historii muszą być skonfigurowane tak, aby były dostępne z kontenera git-bridge. Konfiguracja kontenera Ayakaleaf Pro:
  • Ustaw GIT_BRIDGE_ENABLED na 'true'
  • Ustaw GIT_BRIDGE_HOST na <git-bridge container name>, np. git-bridge
  • Ustaw GIT_BRIDGE_PORT na 8000
  • Ustaw V1_HISTORY_URL na http://<server-pro sibling container name>:3100/api. Uwaga: jest to konieczne tylko w kontenerze towarzyszącym kontenerowi git-bridge. Pozostałe instancje mogą używać adresu URL localhost, który jest wartością domyślną.
Konfiguracja kontenera git-bridge:
  • Ustaw GIT_BRIDGE_API_BASE_URL na http://<server-pro sibling container name>/api/v0, np. http://server-pro-ha-1/api/v0
  • Ustaw GIT_BRIDGE_OAUTH2_SERVER na http://<server-pro sibling container name>, np. http://server-pro-ha-1
  • Ustaw GIT_BRIDGE_POSTBACK_BASE_URL na http://<git-bridge container name>:8000, np. http://git-bridge:8000
  • Ustaw GIT_BRIDGE_ROOT_DIR na zamontowany (bind mount) dysk z danymi git-bridge, np. /data/git-bridge
Poniższa konfiguracja przedstawia samodzielne środowisko. Aby demonstracja działała, musisz dostarczyć prawidłowy klucz/certyfikat SSL i dostosować OVERLEAF_SITE_URL. W rzeczywistym wdrożeniu musisz zastąpić przykładowe sekrety prawdziwymi, zgodnie z komentarzami w kodzie. W rzeczywistym wdrożeniu musisz też przenieść poszczególne kontenery na dedykowane węzły i dostosować adresy IP do konfiguracji sieci lokalnej.Kompilacje są uruchamiane w kontenerach TeX Live obok każdej instancji Ayakaleaf Pro. Najpierw pobierz obraz TeX Live na każdym hoście Ayakaleaf Pro, na przykład docker pull ghcr.io/ayaka-notes/texlive-full:2026.1.

Sprzęt

Zalecamy stosowanie tej samej specyfikacji sprzętowej dla wszystkich instancji Ayakaleaf Pro biorących udział w skalowaniu poziomym. Obowiązują ogólne zalecenia dotyczące specyfikacji sprzętowej instancji Ayakaleaf Pro.

Aktualizacja Ayakaleaf Pro

W ramach procesu aktualizacji Ayakaleaf Pro automatycznie uruchamia migracje bazy danych. Migracje te nie są przeznaczone do równoległego uruchamiania z wielu instancji. Migracje muszą się zakończyć przed uruchomieniem właściwej aplikacji internetowej. Możesz sprawdzić w dziennikach wpis Finished migrations lub poczekać, aż aplikacja zacznie przyjmować ruch. Procedura aktualizacji wygląda następująco:
  1. Zaplanuj okno serwisowe
  2. Zatrzymaj wszystkie instancje Ayakaleaf Pro
  3. Wykonaj spójną kopię zapasową zgodnie z opisem w dokumentacji
  4. Uruchom pojedynczą instancję Ayakaleaf Pro w nowej wersji
  5. Sprawdź, czy nowa instancja działa zgodnie z oczekiwaniami
  6. Uruchom pozostałe instancje w nowej wersji
Ostatnia modyfikacja 2 listopada 2026