Ana içeriğe atla
Ayakaleaf Pro yatay ölçeklendirmeyi destekler. Birden fazla replika ile doğru şekilde çalıştığını test ettik ve doğruladık.
Bu belge, Ayakaleaf Pro’yu birden fazla düğümde çalıştırmak için teknik gereksinimleri listeler ve yönergeler sunar. Yatay ölçeklendirmeyi kurmak önemli miktarda çaba gerektirir. Yatay ölçeklendirmeyi yalnızca belirli bir ölçeğe ulaşıldığında düşünmenizi öneririz. Örnek olarak Overleaf, toplam 1.000 kullanıcılı bir şirket içi kurulumun, iki adet 4 çekirdekli işlemci ve 32GB sistem belleğiyle donatılmış tek bir sunucuda başarıyla çalıştığını bildirmiştir. Öneriler için donanım gereksinimleri belgelerine bakın. Yatay ölçeklendirmeli bir Ayakaleaf Pro kurulumu, Yük Dengeleyici ve S3 uyumlu depolama arka ucu gibi bir dizi harici bileşen içerir.

Gereksinimler

Harici, merkezi veri depolama

Ayakaleaf Pro’daki veri depolama dört veri deposuna ayrılabilir:
  • MongoDB
    • Verilerin çoğu MongoDB’de kalıcı olarak saklanır.
    • Yerel bir örneği veya MongoDB Atlas (AWS altyapısı içinde çalışan, tamamen yönetilen bir MongoDB hizmeti) gibi harici bir örneği destekliyoruz.
    Not: Ne yazık ki Ayakaleaf Pro’yu CosmoDB/DocumentDB gibi MongoDB uyumlu veritabanlarıyla test etmediğimiz için şu anda bunlara resmi destek bulunmamaktadır. Ayakaleaf Pro’yu uyumlu veritabanlarıyla dağıtmak mümkün olabilir, ancak resmi olarak yalnızca MongoDB kullanan kurulumları destekliyoruz.
  • Redis
    • Redis, MongoDB’ye aktarılmadan önce bekleyen belge güncellemeleri gibi geçici verileri depolar.
    • Redis, farklı hizmetler arasında belge güncellemelerini iletmek ve belirli bir projedeki durum değişiklikleri hakkında düzenleyiciyi bilgilendirmek için kullanılır.
    • Redis, kullanıcı oturumlarını depolamak için kullanılır.
    • Yerel bir örneği veya harici bir örneği destekliyoruz.
    Not: Ne yazık ki Ayakaleaf Pro’yu KeyDB/Valkey gibi Redis uyumlu anahtar/değer depolarıyla test etmediğimiz için şu anda bunlara resmi destek bulunmamaktadır. Ayakaleaf Pro’yu uyumlu depolarla dağıtmak mümkün olabilir, ancak resmi olarak yalnızca Redis kullanan kurulumları destekliyoruz.
  • Proje dosyaları ve Geçmiş dosyaları
    • Düzenlenemeyen proje dosyaları MongoDB dışında depolanır. Proje geçmişi sistemi geçmişi de MongoDB dışında depolar.
    • Küçük tekil örnekler için yerel bir dosya sistemini (yerel bir SSD, NFS veya EBS ile desteklenebilir) ya da S3 uyumlu bir veri depolama sistemini destekliyoruz.
    • Yatay ölçeklendirme için yalnızca S3 uyumlu veri depolama sistemlerini destekliyoruz.
    Önemli: NFS/Amazon EFS/Amazon EBS yatay ölçeklendirme için desteklenmez. Daha fazla ayrıntı için lütfen Ayakaleaf Pro’da depolamanın ölçeklendirilmesine ilişkin donanım depolama gereksinimleri bölümüne bakın.
  • Geçici dosyalar
    • LaTeX derlemelerinin en iyi performans için hızlı, yerel disklerde çalışması gerekir. Derleme çıktısının kalıcı olarak saklanmasına veya yedeklenmesine gerek yoktur.
    • Yeni dosya yüklemelerinin arabelleğe alınması ve proje zip dosyalarının oluşturulması da yerel disk kullanımından fayda sağlar.
Yerel disk kullanmanızı şiddetle öneririz. Herhangi bir ağ diski (NFS veya EBS gibi) kullanmak beklenmeyen derleme hatalarına ve diğer performans sorunlarına yol açabilir.

Git-bridge

Git depoları yerel olarak diskte saklanır. Herhangi bir replikasyon seçeneği mevcut değildir. Git-bridge tekil (singleton) olarak çalıştırılmalıdır. En iyi performans için git-bridge verileri için yerel disk kullanmanızı öneririz. Git-bridge veri diski düzenli olarak yedeklenmelidir. Yatay ölçeklendirmede veri depolama için şunlara ihtiyacınız vardır:
  • tüm Ayakaleaf Pro örneklerinden erişilebilen merkezi bir MongoDB örneği
  • tüm Ayakaleaf Pro örneklerinden erişilebilen merkezi bir Redis örneği
  • proje ve geçmiş dosyaları için merkezi bir S3 uyumlu depolama arka ucu
  • geçici dosyalar için her örnekte yerel bir disk
  • git-bridge verileri için git-bridge konteynerini barındıran örnekte yerel bir disk

Yük dengeleyici gereksinimleri

  • Kalıcı yönlendirme, ör. bir çerez kullanarak Bu gereksinim şu bileşenlerden kaynaklanır:
    • Ayakaleaf Pro’daki gerçek zamanlı düzenleme özelliği, XHR yoklamasına geri dönüş seçeneğiyle WebSocket’leri kullanır. Her düzenleme oturumunun sunucu tarafında yerel bir durumu vardır ve belirli bir düzenleme oturumunun istekleri her zaman aynı Ayakaleaf Pro örneğine yönlendirilmelidir. İşbirliği özelliği, güncellemeleri birden fazla Ayakaleaf Pro örneği arasında paylaşmak için Redis Pub/Sub kullanır.
    • LaTeX derlemesi, isteğe bağlı performans için çıktıyı ve derleme önbelleğini yerel olarak tutar. Bir Ayakaleaf Pro örneğine derleme isteği gönderildiğinde, ardından gelen PDF/günlük indirme isteklerinin de aynı Ayakaleaf Pro örneğine yönlendirilmesi gerekir.
  • Büyük LaTeX belgelerinin derlenmesini desteklemek için uzun istek zaman aşımları
  • En iyi performans için WebSocket desteği
  • 50MB POST yük boyutu
  • Keep-alive zaman aşımı, Ayakaleaf Pro keep-alive zaman aşımından düşük olmalıdır Ayakaleaf Pro’daki keep-alive zaman aşımı NGINX_KEEPALIVE_TIMEOUT ortam değişkeni kullanılarak yapılandırılabilir. Varsayılan değer 65 sn’dir. Varsayılan değerle, yük dengeleyicide 60 sn’lik bir keep-alive zaman aşımı çalışır. NGINX_KEEPALIVE_TIMEOUT=120 ile yük dengeleyici 115 sn seçebilir.
  • İstemci IP’leri X-Forwarded-For istek başlığını istemci IP’sine ayarlayın.
  • SSL sonlandırma yapılırken Yük dengeleyicinin X-Forwarded-Proto: https istek başlığını eklemesi gerekir.

Ayakaleaf Pro yapılandırması

Gizli anahtarlar Ayakaleaf Pro örneklerinin ortak gizli anahtarlar üzerinde uzlaşması gerekir:
  • WEB_API_PASSWORD (web api kimlik doğrulaması)
  • STAGING_PASSWORD ve V1_HISTORY_PASSWORD aynı değer (geçmiş kimlik doğrulaması)
  • CRYPTO_RANDOM (oturum çerezi için)
  • OT_JWT_AUTH_KEY (geçmiş kimlik doğrulaması)
  • OVERLEAF_INVITE_TOKEN_SECRET (bağlantı paylaşım belirteçleri, zorunlu: bu olmadan Ayakaleaf Pro başlamayı reddeder)
Bu gizli anahtarların her biri kendine özgü benzersiz bir değerle yapılandırılmalı ve örnekler arasında paylaşılmalıdır. Yapılandırılmadıklarında ve kullanıcı istekleri farklı Ayakaleaf Pro örneklerine yönlendirildiğinde, istekleri kimlik doğrulama kontrollerinde başarısız olur ve kullanıcılar ya sık sık giriş sayfasına yönlendirilir ya da arayüzdeki işlemleri beklenmedik şekillerde başarısız olur. Yapılandırılmadığında Ayakaleaf Pro, her gizli anahtar için /dev/urandom’dan alınan 32 rastgele bayta (256 rastgele bit) dayanan yeni bir rastgele değer kullanır.
MongoDB OVERLEAF_MONGO_URL değişkenini merkezi MongoDB örneğine yönlendirin. Redis OVERLEAF_REDIS_HOST ve REDIS_HOST değişkenlerini merkezi Redis örneğine yönlendirin. Proje ve geçmiş dosyaları için S3 uyumlu depolama Ayrıntılar için lütfen S3 uyumlu depolama belgelerine bakın. Geçici dosyalar Yerel bir SSD’nin /var/lib/overleaf konumuna varsayılan bind-mount’u yeterli olacaktır. SANDBOXED_COMPILES_HOST_DIR değişkenini ana makinedeki bağlama noktasına yönlendirdiğinizden emin olun.
Yerel disk kullanmanızı şiddetle öneririz. Herhangi bir ağ diski (NFS veya EBS gibi) kullanmak beklenmeyen derleme hatalarına ve diğer performans sorunlarına yol açabilir.
Proxy yapılandırması
  • Doğru istemci IP’leri için OVERLEAF_TRUSTED_PROXY_IPS değişkenini loopback ile birlikte yük dengeleyicilerin IP’lerine ayarlayın, örn. loopback,198.18.0.1. Virgülle ayrılmış birden fazla IP veya CIDR belirtilebilir.
Git-bridge entegrasyonu Git-bridge konteyneri, gelen git isteklerini işlemek için kardeş bir Ayakaleaf Pro konteynerine ihtiyaç duyar. Bu kardeş konteyner normal kullanıcı trafiğine de hizmet verebilir. Örnek yapılandırmada ilk örnek git-bridge için kardeş konteyner görevi görür, ancak aslında herhangi bir örnek bu işlevi üstlenebilir. Neden bir Ayakaleaf Pro konteynerini git-bridge için kardeş olarak belirlememiz gerekiyor? Ayakaleaf Pro, geçmiş hizmeti için indirme URL’lerini git-bridge’e verir. Bu geçmiş URL’lerinin git-bridge konteynerinden erişilebilir olacak şekilde yapılandırılması gerekir. Ayakaleaf Pro konteyner yapılandırması:
  • GIT_BRIDGE_ENABLED değerini 'true' olarak ayarlayın
  • GIT_BRIDGE_HOST değerini <git-bridge container name> olarak ayarlayın, ör. git-bridge
  • GIT_BRIDGE_PORT değerini 8000 olarak ayarlayın
  • V1_HISTORY_URL değerini http://<server-pro sibling container name>:3100/api olarak ayarlayın. Not: Bu yalnızca git-bridge konteynerinin kardeş konteynerinde gereklidir. Diğer örnekler varsayılan olan localhost URL’sini kullanabilir.
git-bridge konteyner yapılandırması:
  • GIT_BRIDGE_API_BASE_URL değerini http://<server-pro sibling container name>/api/v0 olarak ayarlayın, ör. http://server-pro-ha-1/api/v0
  • GIT_BRIDGE_OAUTH2_SERVER değerini http://<server-pro sibling container name> olarak ayarlayın, ör. http://server-pro-ha-1
  • GIT_BRIDGE_POSTBACK_BASE_URL değerini http://<git-bridge container name>:8000 olarak ayarlayın, ör. http://git-bridge:8000
  • GIT_BRIDGE_ROOT_DIR değerini bind-mount ile bağlanmış git-bridge veri diskine ayarlayın, ör. /data/git-bridge
Aşağıdaki yapılandırma kendi kendine yeten bir kurulumu göstermektedir. Demonun çalışması için geçerli bir SSL anahtarı/sertifikası sağlamanız ve OVERLEAF_SITE_URL değerini ayarlamanız gerekir. Gerçek bir kurulum için, satır içinde belirtildiği gibi sahte gizli anahtarları gerçek gizli anahtarlarla değiştirmeniz gerekir. Gerçek bir kurulum için ayrıca konteynerleri ayrı ayrı özel düğümlere taşımanız ve IP adreslerini yerel ağ kurulumunuza göre ayarlamanız gerekir.Derlemeler, her Ayakaleaf Pro örneğinin yanında TeX Live konteynerlerinde çalışır. Önce her Ayakaleaf Pro ana makinesinde TeX Live imajını çekin, örneğin docker pull ghcr.io/ayaka-notes/texlive-full:2026.1.

Donanım

Yatay ölçeklendirmeye katılan tüm Ayakaleaf Pro örnekleri için aynı donanım özelliklerini kullanmanızı öneririz. Ayakaleaf Pro örnekleri için genel donanım özellikleri önerileri geçerlidir.

Ayakaleaf Pro’yu yükseltme

Yükseltme sürecinin bir parçası olarak Ayakaleaf Pro, veritabanı geçişlerini otomatik olarak çalıştırır. Bu geçişler birden fazla örnekten paralel olarak çalıştırılmak üzere tasarlanmamıştır. Geçişlerin, asıl web uygulaması başlatılmadan önce tamamlanması gerekir. Günlüklerde Finished migrations girdisini kontrol edebilir veya uygulama trafik kabul edene kadar bekleyebilirsiniz. Yükseltme prosedürü şu şekildedir:
  1. Bir bakım penceresi planlayın
  2. Tüm Ayakaleaf Pro örneklerini durdurun
  3. Belgelerde açıklandığı gibi tutarlı bir yedek alın
  4. Yeni sürümle tek bir Ayakaleaf Pro örneği başlatın
  5. Yeni örneğin beklendiği gibi çalıştığını doğrulayın
  6. Diğer örnekleri yeni sürümle ayağa kaldırın
Son değiştirilme tarihi 2 Kasım 2026