Ayakaleaf Pro поддерживает горизонтальное масштабирование. Мы протестировали и проверили его корректную работу с несколькими репликами.
Требования

Внешнее централизованное хранилище данных
Хранилище данных в Ayakaleaf Pro можно разделить на четыре хранилища:-
MongoDB
- Большая часть данных сохраняется в MongoDB.
- Мы поддерживаем как локальный экземпляр, так и внешний, например MongoDB Atlas (полностью управляемый сервис MongoDB, работающий в инфраструктуре AWS).
-
Redis
- Redis хранит временные данные, например ожидающие обновления документов до их сброса в MongoDB.
- Redis используется для передачи обновлений документов между различными сервисами и для уведомления редактора об изменениях состояния в конкретном проекте.
- Redis используется для хранения пользовательских сеансов.
- Мы поддерживаем как локальный экземпляр, так и внешний.
-
Файлы проектов и файлы истории
- Нередактируемые файлы проектов хранятся вне MongoDB. Система истории проектов также хранит историю вне MongoDB.
- Для небольших одиночных экземпляров мы поддерживаем либо локальную файловую систему (которая может располагаться на локальном SSD, NFS или EBS), либо S3-совместимую систему хранения данных.
-
Для горизонтального масштабирования мы поддерживаем только S3-совместимые системы хранения данных.
-
Временные файлы
- Для оптимальной производительности компиляция LaTeX должна выполняться на быстрых локальных дисках. Результаты компиляции не нужно сохранять или резервировать.
- Буферизация загружаемых новых файлов и создание ZIP-архивов проектов также выигрывают от использования локального диска.
Мы настоятельно рекомендуем использовать локальный диск. Использование любого сетевого диска (например, NFS или EBS) может привести к неожиданным ошибкам компиляции и другим проблемам с производительностью.
Git-bridge
Git-репозитории хранятся локально на диске. Возможности репликации отсутствуют. Git-bridge следует запускать в единственном экземпляре. Для оптимальной производительности мы рекомендуем использовать локальный диск для данных git-bridge. Диск с данными git-bridge следует регулярно резервировать. Для хранения данных при горизонтальном масштабировании вам потребуются:- центральный экземпляр MongoDB, доступный со всех экземпляров Ayakaleaf Pro
- центральный экземпляр Redis, доступный со всех экземпляров Ayakaleaf Pro
- центральное S3-совместимое хранилище для файлов проектов и истории
- локальный диск на каждом экземпляре для временных файлов
- локальный диск на экземпляре, где размещён контейнер git-bridge, для данных git-bridge
Требования к балансировщику нагрузки
-
Постоянная маршрутизация (sticky sessions), например с использованием cookie
Это требование обусловлено следующими компонентами:
- Функция редактирования в реальном времени в Ayakaleaf Pro использует WebSockets с резервным переходом на XHR polling. Каждый сеанс редактирования имеет локальное состояние на стороне сервера, и запросы конкретного сеанса редактирования всегда должны направляться на один и тот же экземпляр Ayakaleaf Pro. Функция совместной работы использует Redis Pub/Sub для обмена обновлениями между несколькими экземплярами Ayakaleaf Pro.
- Компиляция LaTeX хранит результаты и кэш компиляции локально для повышения производительности. После отправки запроса на компиляцию одному экземпляру Ayakaleaf Pro последующие запросы на загрузку PDF/журнала должны направляться на тот же экземпляр Ayakaleaf Pro.
- Длительные тайм-ауты запросов для поддержки компиляции больших документов LaTeX
- Поддержка WebSocket для оптимальной производительности
- Размер полезной нагрузки POST 50 МБ
-
Тайм-аут keep-alive должен быть меньше тайм-аута keep-alive в Ayakaleaf Pro
Тайм-аут keep-alive в Ayakaleaf Pro настраивается с помощью переменной окружения
NGINX_KEEPALIVE_TIMEOUT. Значение по умолчанию — 65 с. При значении по умолчанию подойдёт тайм-аут keep-alive 60 с в балансировщике нагрузки. ПриNGINX_KEEPALIVE_TIMEOUT=120балансировщик нагрузки может использовать 115 с. -
IP-адреса клиентов
Задайте в заголовке запроса
X-Forwarded-ForIP-адрес клиента. -
При терминировании SSL
Балансировщик нагрузки должен добавлять заголовок запроса
X-Forwarded-Proto: https.
Пример конфигурации HAProxy
Пример конфигурации HAProxy
Настройка 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 отказывается запускаться)
/dev/urandom (256 случайных бит).
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_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_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-mount) диск с данными git-bridge, например/data/git-bridge
Пример конфигурации docker-compose.yml
Пример конфигурации docker-compose.yml
Следующая конфигурация демонстрирует самодостаточную установку. Чтобы демонстрация заработала, необходимо предоставить действительный 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, либо дождаться, пока приложение начнёт принимать трафик.
Процедура обновления выглядит так:
- Запланируйте окно обслуживания
- Остановите все экземпляры Ayakaleaf Pro
- Создайте согласованную резервную копию, как описано в документации
- Запустите один экземпляр Ayakaleaf Pro с новой версией
- Убедитесь, что новый экземпляр работает как ожидается
- Запустите остальные экземпляры с новой версией

