Перейти к основному содержанию
Ayakaleaf Pro поддерживает горизонтальное масштабирование. Мы протестировали и проверили его корректную работу с несколькими репликами.
В этом документе перечислены технические требования и приведены рекомендации по запуску Ayakaleaf Pro более чем на одном узле. Настройка горизонтального масштабирования требует значительных усилий. Мы советуем рассматривать горизонтальное масштабирование только при достижении определённого масштаба. Например, по данным Overleaf, локальная установка на 1 000 пользователей успешно работала на одном сервере с двумя 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 следует запускать в единственном экземпляре. Для оптимальной производительности мы рекомендуем использовать локальный диск для данных 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-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-mount) диск с данными 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 г.