Zum Hauptinhalt springen
Ayakaleaf Pro unterstützt horizontale Skalierung. Wir haben getestet und bestätigt, dass es mit mehreren Replikaten korrekt läuft.
Dieses Dokument listet die technischen Anforderungen auf und bietet Richtlinien für den Betrieb von Ayakaleaf Pro auf mehr als einem Knoten. Die Einrichtung einer horizontalen Skalierung erfordert erheblichen Aufwand. Wir empfehlen, horizontale Skalierung nur ab einer gewissen Größenordnung in Betracht zu ziehen. Beispielsweise hat Overleaf von einer On-Premises-Installation für insgesamt 1.000 Benutzer berichtet, die erfolgreich auf einem einzigen Server mit zwei 4-Kern-Prozessoren und 32 GB Arbeitsspeicher läuft. Empfehlungen finden Sie in der Dokumentation zu den Hardwareanforderungen. Eine Bereitstellung von Ayakaleaf Pro mit horizontaler Skalierung umfasst eine Reihe externer Komponenten, etwa einen Load Balancer und ein S3-kompatibles Speicher-Backend.

Anforderungen

Externer, zentraler Datenspeicher

Die Datenspeicherung in Ayakaleaf Pro lässt sich in vier Datenspeicher aufteilen:
  • MongoDB
    • Der Großteil der Daten wird in MongoDB gespeichert.
    • Wir unterstützen entweder eine lokale oder eine externe Instanz, etwa MongoDB Atlas (ein vollständig verwalteter MongoDB-Dienst, der innerhalb der AWS-Infrastruktur läuft).
    Hinweis: Leider gibt es derzeit keine offizielle Unterstützung für MongoDB-kompatible Datenbanken wie CosmoDB/DocumentDB, da wir Ayakaleaf Pro nicht damit getestet haben. Auch wenn eine Bereitstellung von Ayakaleaf Pro mit kompatiblen Datenbanken möglicherweise funktioniert, unterstützen wir offiziell nur Bereitstellungen mit MongoDB.
  • Redis
    • Redis speichert temporäre Daten, etwa ausstehende Dokumentaktualisierungen, bevor sie in MongoDB geschrieben werden.
    • Redis wird verwendet, um Dokumentaktualisierungen zwischen verschiedenen Diensten auszutauschen und den Editor über Zustandsänderungen in einem bestimmten Projekt zu benachrichtigen.
    • Redis wird zum Speichern der Benutzersitzungen verwendet.
    • Wir unterstützen entweder eine lokale oder eine externe Instanz.
    Hinweis: Leider gibt es derzeit keine offizielle Unterstützung für Redis-kompatible Key/Value-Stores wie KeyDB/Valkey, da wir Ayakaleaf Pro nicht damit getestet haben. Auch wenn eine Bereitstellung von Ayakaleaf Pro mit kompatiblen Stores möglicherweise funktioniert, unterstützen wir offiziell nur Bereitstellungen mit Redis.
  • Projektdateien und Verlaufsdateien
    • Nicht bearbeitbare Projektdateien werden außerhalb von MongoDB gespeichert. Das Projektverlaufssystem speichert den Verlauf ebenfalls außerhalb von MongoDB.
    • Für kleine Einzelinstanzen unterstützen wir entweder ein lokales Dateisystem (z. B. auf Basis einer lokalen SSD, NFS oder EBS) oder ein S3-kompatibles Datenspeichersystem.
    • Für horizontale Skalierung unterstützen wir ausschließlich S3-kompatible Datenspeichersysteme.
    Wichtig: NFS/Amazon EFS/Amazon EBS werden für horizontale Skalierung nicht unterstützt. Weitere Details zur Skalierung des Speichers in Ayakaleaf Pro finden Sie im Abschnitt zu den Hardware-Speicheranforderungen.
  • Kurzlebige Dateien
    • LaTeX-Kompilierungen müssen für optimale Leistung auf schnellen, lokalen Datenträgern laufen. Die Ausgabe der Kompilierung muss nicht dauerhaft gespeichert oder gesichert werden.
    • Auch das Puffern neuer Datei-Uploads und das Erstellen von Projekt-ZIP-Dateien profitieren von einem lokalen Datenträger.
Wir empfehlen dringend, einen lokalen Datenträger zu verwenden. Die Verwendung jeglicher Art von Netzwerkdatenträgern (wie NFS oder EBS) kann zu unerwarteten Kompilierungsfehlern und anderen Leistungsproblemen führen.

Git-bridge

Die Git-Repositorys werden lokal auf dem Datenträger gespeichert. Es stehen keine Replikationsoptionen zur Verfügung. Git-bridge sollte als Singleton betrieben werden. Für optimale Leistung empfehlen wir, für die Git-bridge-Daten einen lokalen Datenträger zu verwenden. Der Datenträger mit den Git-bridge-Daten sollte regelmäßig gesichert werden. Für die Datenspeicherung bei horizontaler Skalierung benötigen Sie:
  • eine zentrale MongoDB-Instanz, die von allen Ayakaleaf Pro-Instanzen aus erreichbar ist
  • eine zentrale Redis-Instanz, die von allen Ayakaleaf Pro-Instanzen aus erreichbar ist
  • ein zentrales S3-kompatibles Speicher-Backend für Projekt- und Verlaufsdateien
  • einen lokalen Datenträger auf jeder Instanz für kurzlebige Dateien
  • einen lokalen Datenträger auf der Instanz, die den Git-bridge-Container hostet, für die Git-bridge-Daten

Anforderungen an den Load Balancer

  • Persistentes Routing, z. B. per Cookie Diese Anforderung ergibt sich aus folgenden Komponenten:
    • Die Echtzeit-Bearbeitung in Ayakaleaf Pro verwendet WebSockets mit einem Fallback auf XHR-Polling. Jede Bearbeitungssitzung hat einen lokalen Zustand auf der Serverseite, und die Anfragen einer bestimmten Bearbeitungssitzung müssen immer an dieselbe Ayakaleaf Pro-Instanz geleitet werden. Die Kollaborationsfunktion nutzt Redis Pub/Sub, um Aktualisierungen zwischen mehreren Ayakaleaf Pro-Instanzen auszutauschen.
    • Die LaTeX-Kompilierung hält die Ausgabe und den Kompilierungs-Cache für optimale Leistung lokal vor. Nachdem eine Kompilierungsanfrage an eine Ayakaleaf Pro-Instanz gesendet wurde, müssen die nachfolgenden PDF-/Log-Download-Anfragen an dieselbe Ayakaleaf Pro-Instanz geleitet werden.
  • Lange Request-Timeouts zur Unterstützung der Kompilierung großer LaTeX-Dokumente
  • WebSocket-Unterstützung für optimale Leistung
  • POST-Payload-Größe von 50 MB
  • Keep-alive-Timeout muss niedriger sein als das Keep-alive-Timeout von Ayakaleaf Pro Das Keep-alive-Timeout in Ayakaleaf Pro kann über die Umgebungsvariable NGINX_KEEPALIVE_TIMEOUT konfiguriert werden. Der Standardwert beträgt 65 s. Mit dem Standardwert funktioniert ein Keep-alive-Timeout von 60 s im Load Balancer. Mit NGINX_KEEPALIVE_TIMEOUT=120 könnte der Load Balancer 115 s wählen.
  • Client-IPs Setzen Sie den Request-Header X-Forwarded-For auf die Client-IP.
  • Beim Terminieren von SSL Der Load Balancer muss den Request-Header X-Forwarded-Proto: https hinzufügen.

Ayakaleaf Pro-Konfiguration

Secrets Die Ayakaleaf Pro-Instanzen müssen gemeinsame Secrets verwenden:
  • WEB_API_PASSWORD (Web-API-Authentifizierung)
  • STAGING_PASSWORD und V1_HISTORY_PASSWORD mit demselben Wert (Verlaufs-Authentifizierung)
  • CRYPTO_RANDOM (für das Sitzungscookie)
  • OT_JWT_AUTH_KEY (Verlaufs-Authentifizierung)
  • OVERLEAF_INVITE_TOKEN_SECRET (Token für die Linkfreigabe, erforderlich: Ohne es verweigert Ayakaleaf Pro den Start)
Jedes dieser Secrets muss mit einem eigenen, eindeutigen Wert konfiguriert und zwischen den Instanzen geteilt werden. Sind sie nicht konfiguriert und werden Benutzeranfragen an verschiedene Ayakaleaf Pro-Instanzen geleitet, schlagen die Authentifizierungsprüfungen fehl, und die Benutzer werden entweder häufig auf die Anmeldeseite umgeleitet oder ihre Aktionen in der Benutzeroberfläche schlagen auf unerwartete Weise fehl. Sind sie nicht konfiguriert, verwendet Ayakaleaf Pro für jedes Secret einen neuen Zufallswert auf Basis von 32 zufälligen Bytes aus /dev/urandom (256 Zufallsbits).
MongoDB Richten Sie OVERLEAF_MONGO_URL auf die zentrale MongoDB-Instanz. Redis Richten Sie OVERLEAF_REDIS_HOST und REDIS_HOST auf die zentrale Redis-Instanz. S3-kompatibler Speicher für Projekt- und Verlaufsdateien Details finden Sie in der Dokumentation zu S3-kompatiblem Speicher. Kurzlebige Dateien Der standardmäßige Bind-Mount einer lokalen SSD nach /var/lib/overleaf ist ausreichend. Achten Sie darauf, SANDBOXED_COMPILES_HOST_DIR auf den Mountpoint auf dem Host zu setzen.
Wir empfehlen dringend, einen lokalen Datenträger zu verwenden. Die Verwendung jeglicher Art von Netzwerkdatenträgern (wie NFS oder EBS) kann zu unerwarteten Kompilierungsfehlern und anderen Leistungsproblemen führen.
Proxy-Konfiguration
  • Setzen Sie OVERLEAF_TRUSTED_PROXY_IPS auf loopback plus die IPs der Load Balancer, z. B. loopback,198.18.0.1, um korrekte Client-IPs zu erhalten. Mehrere IPs oder CIDRs können durch Kommas getrennt angegeben werden.
Git-bridge-Integration Der Git-bridge-Container benötigt einen Ayakaleaf Pro-Geschwistercontainer zur Verarbeitung eingehender Git-Anfragen. Dieser Geschwistercontainer kann auch regulären Benutzerverkehr bedienen. In der Beispielkonfiguration fungiert die erste Instanz als Geschwistercontainer für Git-bridge, grundsätzlich kann aber jede Instanz diese Rolle übernehmen. Warum muss ein Ayakaleaf Pro-Container als Geschwister für Git-bridge festgelegt werden? Ayakaleaf Pro gibt Download-URLs für den Verlaufsdienst an Git-bridge aus. Diese Verlaufs-URLs müssen so konfiguriert werden, dass sie vom Git-bridge-Container aus erreichbar sind. Konfiguration des Ayakaleaf Pro-Containers:
  • Setzen Sie GIT_BRIDGE_ENABLED auf 'true'
  • Setzen Sie GIT_BRIDGE_HOST auf <git-bridge container name>, z. B. git-bridge
  • Setzen Sie GIT_BRIDGE_PORT auf 8000
  • Setzen Sie V1_HISTORY_URL auf http://<server-pro sibling container name>:3100/api. Hinweis: Dies ist nur auf dem Geschwistercontainer des Git-bridge-Containers erforderlich. Die anderen Instanzen können eine localhost-URL verwenden, was der Standard ist.
Konfiguration des Git-bridge-Containers:
  • Setzen Sie GIT_BRIDGE_API_BASE_URL auf http://<server-pro sibling container name>/api/v0, z. B. http://server-pro-ha-1/api/v0
  • Setzen Sie GIT_BRIDGE_OAUTH2_SERVER auf http://<server-pro sibling container name>, z. B. http://server-pro-ha-1
  • Setzen Sie GIT_BRIDGE_POSTBACK_BASE_URL auf http://<git-bridge container name>:8000, z. B. http://git-bridge:8000
  • Setzen Sie GIT_BRIDGE_ROOT_DIR auf den per Bind-Mount eingebundenen Git-bridge-Datenträger, z. B. /data/git-bridge
Die folgende Konfiguration zeigt ein in sich geschlossenes Setup. Damit die Demo funktioniert, müssen Sie einen gültigen SSL-Schlüssel bzw. ein gültiges Zertifikat bereitstellen und OVERLEAF_SITE_URL anpassen. Für ein echtes Setup müssen Sie die Dummy-Secrets wie inline vermerkt durch echte Secrets ersetzen. Für ein echtes Setup müssen Sie außerdem die einzelnen Container auf dedizierte Knoten verschieben und die IP-Adressen an Ihr lokales Netzwerk anpassen.Kompilierungen laufen in TeX Live-Containern neben jeder Ayakaleaf Pro-Instanz. Pullen Sie das TeX Live-Image zuerst auf jedem Ayakaleaf Pro-Host, zum Beispiel docker pull ghcr.io/ayaka-notes/texlive-full:2026.1.

Hardware

Wir empfehlen, für alle an der horizontalen Skalierung beteiligten Ayakaleaf Pro-Instanzen dieselben Hardwarespezifikationen zu verwenden. Es gelten die allgemeinen Empfehlungen zu den Hardwarespezifikationen für Ayakaleaf Pro-Instanzen.

Ayakaleaf Pro aktualisieren

Im Rahmen des Upgrade-Prozesses führt Ayakaleaf Pro automatisch Datenbankmigrationen aus. Diese Migrationen sind nicht dafür ausgelegt, von mehreren Instanzen parallel ausgeführt zu werden. Die Migrationen müssen abgeschlossen sein, bevor die eigentliche Webanwendung startet. Sie können entweder in den Logs nach dem Eintrag Finished migrations suchen oder warten, bis die Anwendung Datenverkehr annimmt. Der Upgrade-Ablauf sieht wie folgt aus:
  1. Planen Sie ein Wartungsfenster
  2. Stoppen Sie alle Ayakaleaf Pro-Instanzen
  3. Erstellen Sie ein konsistentes Backup wie in der Dokumentation beschrieben
  4. Starten Sie eine einzelne Ayakaleaf Pro-Instanz mit der neuen Version
  5. Prüfen Sie, ob die neue Instanz wie erwartet funktioniert
  6. Starten Sie die übrigen Instanzen mit der neuen Version
Zuletzt geändert am 2. November 2026