Перейти до основного вмісту
Ayakaleaf Pro підтримує горизонтальне масштабування. Ми протестували та підтвердили, що він коректно працює з кількома репліками.
У цьому документі наведено технічні вимоги та рекомендації щодо запуску Ayakaleaf Pro на більш ніж одному вузлі. Налаштування горизонтального масштабування потребує значних зусиль. Ми радимо розглядати горизонтальне масштабування лише після досягнення певного масштабу. Наприклад, Overleaf повідомляв про локальну інсталяцію для 1000 користувачів загалом, яка успішно працює на одному сервері з двома 4-ядерними процесорами та 32 ГБ оперативної пам’яті. Рекомендації див. у документації щодо апаратних вимог. Розгортання Ayakaleaf Pro з горизонтальним масштабуванням передбачає використання набору зовнішніх компонентів, таких як балансувальник навантаження та S3-сумісне сховище.

Вимоги

Зовнішнє централізоване сховище даних

Сховище даних в Ayakaleaf Pro можна поділити на чотири сховища:
  • MongoDB
    • Більшість даних зберігається в MongoDB.
    • Ми підтримуємо як локальний, так і зовнішній екземпляр, наприклад MongoDB Atlas (повністю керований сервіс MongoDB, що працює в інфраструктурі AWS).
    Примітка: на жаль, наразі немає офіційної підтримки MongoDB-сумісних баз даних, таких як CosmoDB/DocumentDB, оскільки ми не тестували з ними Ayakaleaf Pro. Хоча розгортання Ayakaleaf Pro із сумісними базами даних може бути можливим, офіційно ми підтримуємо лише розгортання з MongoDB.
  • Redis
    • Redis зберігає тимчасові дані, наприклад незастосовані оновлення документів до їх запису в MongoDB.
    • Redis використовується для передавання оновлень документів між різними сервісами та сповіщення редактора про зміни стану в певному проєкті.
    • Redis використовується для зберігання сеансів користувачів.
    • Ми підтримуємо як локальний, так і зовнішній екземпляр.
    Примітка: на жаль, наразі немає офіційної підтримки Redis-сумісних сховищ «ключ-значення», таких як KeyDB/Valkey, оскільки ми не тестували з ними Ayakaleaf Pro. Хоча розгортання Ayakaleaf Pro із сумісними сховищами може бути можливим, офіційно ми підтримуємо лише розгортання з Redis.
  • Файли проєктів і файли історії
    • Нередаговані файли проєктів зберігаються поза MongoDB. Система історії проєктів також зберігає історію поза MongoDB.
    • Для невеликих одиночних екземплярів ми підтримуємо або локальну файлову систему (яка може базуватися на локальному SSD, NFS або EBS), або S3-сумісну систему зберігання даних.
    • Для горизонтального масштабування ми підтримуємо лише S3-сумісні системи зберігання даних.
    Важливо: NFS/Amazon EFS/Amazon EBS не підтримуються для горизонтального масштабування. Докладніше див. розділ вимог до апаратного сховища щодо масштабування сховища в Ayakaleaf Pro.
  • Тимчасові файли
    • Для оптимальної продуктивності компіляції LaTeX мають виконуватися на швидких локальних дисках. Результати компіляції не потрібно зберігати постійно чи резервувати.
    • Буферизація нових завантажених файлів і створення zip-файлів проєктів також виграють від використання локального диска.
Ми наполегливо радимо використовувати локальний диск. Використання будь-якого мережевого диска (наприклад, NFS або EBS) може спричинити неочікувані помилки компіляції та інші проблеми з продуктивністю.

Git-bridge

Git-репозиторії зберігаються локально на диску. Можливостей реплікації немає. Git-bridge слід запускати як singleton (в одному екземплярі). Для оптимальної продуктивності радимо використовувати для даних git-bridge локальний диск. Диск із даними git-bridge слід регулярно резервувати. Для зберігання даних із горизонтальним масштабуванням вам потрібні:
  • центральний екземпляр MongoDB, доступний з усіх екземплярів Ayakaleaf Pro
  • центральний екземпляр Redis, доступний з усіх екземплярів Ayakaleaf Pro
  • центральне S3-сумісне сховище для файлів проєктів і історії
  • локальний диск на кожному екземплярі для тимчасових файлів
  • локальний диск на екземплярі, де розміщено контейнер git-bridge, для даних git-bridge

Вимоги до балансувальника навантаження

  • Постійна маршрутизація (sticky), наприклад за допомогою cookie Ця вимога зумовлена такими компонентами:
    • Можливість редагування в реальному часі в Ayakaleaf Pro використовує WebSockets із резервним переходом на XHR polling. Кожен сеанс редагування має локальний стан на стороні сервера, і запити певного сеансу редагування завжди мають спрямовуватися до того самого екземпляра Ayakaleaf Pro. Функція спільної роботи використовує Redis Pub/Sub для обміну оновленнями між кількома екземплярами Ayakaleaf Pro.
    • Компіляція LaTeX зберігає результати та кеш компіляції локально для оптимальної продуктивності. Після надсилання запиту на компіляцію до одного екземпляра Ayakaleaf Pro наступні запити на завантаження PDF/журналу мають спрямовуватися до того самого екземпляра Ayakaleaf Pro.
  • Тривалі тайм-аути запитів для підтримки компіляції великих документів LaTeX
  • Підтримка WebSocket для оптимальної продуктивності
  • Розмір тіла POST-запиту 50MB
  • Тайм-аут keep-alive має бути меншим за тайм-аут keep-alive в Ayakaleaf Pro Тайм-аут keep-alive в Ayakaleaf Pro можна налаштувати за допомогою змінної середовища NGINX_KEEPALIVE_TIMEOUT. Значення за замовчуванням — 65s. За типового значення працює тайм-аут keep-alive 60s у балансувальнику навантаження. За NGINX_KEEPALIVE_TIMEOUT=120 балансувальник навантаження може використовувати 115s.
  • IP-адреси клієнтів Встановіть заголовок запиту X-Forwarded-For на IP-адресу клієнта.
  • У разі термінації SSL Балансувальник навантаження має додавати заголовок запиту X-Forwarded-Proto: https.

Налаштування Ayakaleaf Pro

Секрети Екземпляри Ayakaleaf Pro мають використовувати спільні секрети:
  • WEB_API_PASSWORD (автентифікація web api)
  • STAGING_PASSWORD і V1_HISTORY_PASSWORD з однаковим значенням (автентифікація історії)
  • CRYPTO_RANDOM (для cookie сеансу)
  • OT_JWT_AUTH_KEY (автентифікація історії)
  • OVERLEAF_INVITE_TOKEN_SECRET (токени спільного доступу за посиланням, обов’язковий: без нього Ayakaleaf Pro відмовляється запускатися)
Кожен із цих секретів потрібно налаштувати з власним унікальним значенням і використовувати спільно між екземплярами. Якщо їх не налаштовано, а запити користувачів спрямовуються до різних екземплярів Ayakaleaf Pro, ці запити не пройдуть перевірки автентифікації, і користувачів або часто перенаправлятиме на сторінку входу, або їхні дії в інтерфейсі несподівано завершуватимуться помилками. Якщо секрети не налаштовано, Ayakaleaf Pro використовує для кожного з них нове випадкове значення на основі 32 випадкових байтів із /dev/urandom (256 випадкових бітів).
MongoDB Спрямуйте OVERLEAF_MONGO_URL на центральний екземпляр MongoDB. Redis Спрямуйте OVERLEAF_REDIS_HOST і REDIS_HOST на центральний екземпляр Redis. S3-сумісне сховище для файлів проєктів і історії Докладніше див. документацію щодо S3-сумісного сховища. Тимчасові файли Достатньо типового bind-монтування локального SSD до /var/lib/overleaf. Обов’язково спрямуйте SANDBOXED_COMPILES_HOST_DIR на точку монтування на хості.
Ми наполегливо радимо використовувати локальний диск. Використання будь-якого мережевого диска (наприклад, NFS або EBS) може спричинити неочікувані помилки компіляції та інші проблеми з продуктивністю.
Налаштування проксі
  • Встановіть OVERLEAF_TRUSTED_PROXY_IPS на loopback разом з IP-адресами балансувальників навантаження, наприклад loopback,198.18.0.1, щоб отримувати точні IP-адреси клієнтів. Можна вказати кілька IP-адрес або CIDR через кому.
Інтеграція Git-bridge Контейнеру git-bridge потрібен сусідній (sibling) контейнер Ayakaleaf Pro для обробки вхідних git-запитів. Цей сусідній контейнер може також обслуговувати звичайний трафік користувачів. У прикладі конфігурації перший екземпляр виконує роль сусіднього контейнера для git-bridge, але насправді цю функцію може виконувати будь-який екземпляр. Навіщо призначати один контейнер Ayakaleaf Pro сусіднім для git-bridge? Ayakaleaf Pro передає git-bridge URL-адреси для завантаження з сервісу історії. Ці URL-адреси історії потрібно налаштувати так, щоб вони були доступні з контейнера git-bridge. Налаштування контейнера Ayakaleaf Pro:
  • Встановіть GIT_BRIDGE_ENABLED у 'true'
  • Встановіть GIT_BRIDGE_HOST у <git-bridge container name>, наприклад git-bridge
  • Встановіть GIT_BRIDGE_PORT у 8000
  • Встановіть V1_HISTORY_URL у http://<server-pro sibling container name>:3100/api. Примітка: це потрібно лише на сусідньому контейнері для контейнера git-bridge. Інші екземпляри можуть використовувати URL localhost, що є значенням за замовчуванням.
Налаштування контейнера git-bridge:
  • Встановіть GIT_BRIDGE_API_BASE_URL у http://<server-pro sibling container name>/api/v0, наприклад http://server-pro-ha-1/api/v0
  • Встановіть GIT_BRIDGE_OAUTH2_SERVER у http://<server-pro sibling container name>, наприклад http://server-pro-ha-1
  • Встановіть GIT_BRIDGE_POSTBACK_BASE_URL у http://<git-bridge container name>:8000, наприклад http://git-bridge:8000
  • Встановіть GIT_BRIDGE_ROOT_DIR на bind-змонтований диск даних git-bridge, наприклад /data/git-bridge
Наведена нижче конфігурація демонструє самодостатнє налаштування. Щоб демонстрація працювала, потрібно надати дійсний SSL-ключ/сертифікат і змінити OVERLEAF_SITE_URL. Для реального розгортання необхідно замінити фіктивні секрети на справжні, як зазначено в коментарях. Для реального розгортання потрібно перенести окремі контейнери на виділені вузли та змінити IP-адреси відповідно до налаштувань вашої локальної мережі.Компіляції виконуються в контейнерах TeX Live поруч із кожним екземпляром Ayakaleaf Pro. Спершу завантажте образ TeX Live на кожен хост Ayakaleaf Pro, наприклад docker pull ghcr.io/ayaka-notes/texlive-full:2026.1.

Апаратне забезпечення

Ми рекомендуємо використовувати однакові апаратні характеристики для всіх екземплярів Ayakaleaf Pro, що беруть участь у горизонтальному масштабуванні. Застосовуються загальні рекомендації щодо апаратних характеристик для екземплярів Ayakaleaf Pro.

Оновлення Ayakaleaf Pro

У межах процесу оновлення Ayakaleaf Pro автоматично виконує міграції бази даних. Ці міграції не розраховані на паралельний запуск із кількох екземплярів. Міграції мають завершитися до запуску самого вебзастосунку. Можна або перевірити журнали на наявність запису Finished migrations, або дочекатися, доки застосунок почне приймати трафік. Процедура оновлення виглядає так:
  1. Заплануйте вікно технічного обслуговування
  2. Зупиніть усі екземпляри Ayakaleaf Pro
  3. Створіть узгоджену резервну копію, як описано в документації
  4. Запустіть один екземпляр Ayakaleaf Pro з новою версією
  5. Переконайтеся, що новий екземпляр працює належним чином
  6. Запустіть інші екземпляри з новою версією
Останнє оновлення 2 листопада 2026 р.