Перейти к основному содержанию
Ayakaleaf Pro позволяет выполнять компиляцию в защищённой изолированной среде (песочнице), что обеспечивает безопасность корпоративного уровня. Для этого каждый проект запускается в собственной защищённой среде Docker.

Повышенная безопасность

Изолированная компиляция (Sandboxed Compiles) — рекомендуемый подход для Ayakaleaf Pro, поскольку многие документы LaTeX требуют (или имеют возможность) выполнения произвольных команд оболочки в процессе компиляции PDF. При использовании изолированной компиляции каждая компиляция выполняется в отдельном Docker-контейнере с ограниченными возможностями, который не используется совместно с другими пользователями или проектами и не имеет доступа к внешним ресурсам, таким как сеть хоста.
Если вы попытаетесь запустить Ayakaleaf Pro без изолированной компиляции, компиляция будет выполняться вместе с другими одновременными компиляциями внутри основного Docker-контейнера, и при компиляции LaTeX пользователи будут иметь полный доступ на чтение и запись к ресурсам контейнера sharelatex (файловой системе, сети и переменным окружения).

Упрощённое управление пакетами

Чтобы не устанавливать пакеты вручную, рекомендуем включить изолированную компиляцию. Это настраиваемый параметр Ayakaleaf Pro, который предоставит вашим пользователям доступ к той же среде TeX Live, что и на overleaf.com, но в рамках вашей собственной локальной установки. Образы TeX Live, используемые для изолированной компиляции, содержат самые популярные пакеты и шрифты, протестированные на шаблонах из нашей галереи, что обеспечивает максимальную совместимость локальных проектов. Включение изолированной компиляции позволяет настроить, из каких версий TeX Live пользователи смогут выбирать в своих проектах, а также задать версию образа TeX Live по умолчанию для новых проектов.
Если вы попытаетесь запустить Ayakaleaf Pro без изолированной компиляции, ваш экземпляр по умолчанию будет использовать для компиляции версию TeX Live с базовой схемой (basic scheme). Эта базовая версия легковесна и содержит лишь очень ограниченный набор пакетов LaTeX, что, скорее всего, приведёт к ошибкам об отсутствующих пакетах у ваших пользователей, особенно при использовании готовых шаблонов.
Поскольку Ayakaleaf Pro спроектирован для работы в автономном режиме, автоматического способа интеграции шаблонов из галереи overleaf.com в локальную установку нет; однако это можно сделать вручную для каждого шаблона отдельно. Подробнее о том, как это работает, см. в нашем руководстве по переносу шаблонов с overleaf.com: #transferring-templates-from-overleaf.com.
Для изолированной компиляции контейнер sharelatex должен иметь доступ к сокету Docker на хост-машине (через bind mount), чтобы управлять соседними контейнерами компиляции.

Как это работает

Когда изолированная компиляция включена, сокет Docker монтируется с хост-машины в контейнер sharelatex, чтобы сервис компиляции в контейнере мог создавать новые Docker-контейнеры на хосте. Затем при каждом запуске компилятора в каждом проекте сервис компиляции LaTeX (CLSI) делает следующее:
  • Записывает файлы проекта в каталог внутри OVERLEAF_DATA_PATH.
  • С помощью смонтированного сокета Docker создаёт новый контейнер texlive для данного запуска компиляции.
  • Контейнер texlive считывает данные проекта из каталога в OVERLEAF_DATA_PATH.
  • Компилирует проект внутри контейнера texlive.

Включение изолированной компиляции

Для пользователей Toolkit

Чтобы включить изолированную компиляцию (также известную как Sibling containers), задайте следующие параметры конфигурации в overleaf-toolkit/config/overleaf.rc:
config/overleaf.rc
Чтобы отключить их, задайте SIBLING_CONTAINERS_ENABLED=false и выполните bin/up. Тогда компиляции выполняются внутри контейнера sharelatex с его базовым TeX Live.

Для пользователей Docker Compose

Настройка образа TeX Live

Пользователи из материкового Китая могут загружать образы с зеркала ghcr.nju.edu.cn, чтобы ускорить загрузку, а затем присваивать им теги с именем ghcr.io:
НЕ указывайте ghcr.nju.edu.cn в настройках окружения Toolkit: оставьте там имена ghcr.io. Чтобы bin/up не загружал образы с ghcr.io повторно, задайте SIBLING_CONTAINERS_PULL=false в config/overleaf.rc. Чтобы поддерживать образы в актуальном состоянии через зеркало, см. Автоматическое обновление образов TeX Live Full.
Ayakaleaf Pro использует три переменные окружения, чтобы определить, какие образы TeX Live использовать для изолированной компиляции:
  • TEX_LIVE_DOCKER_IMAGE (необязательная) — образ TeX Live, используемый новыми проектами. Он должен быть одним из образов в ALL_TEX_LIVE_DOCKER_IMAGES. Если переменная не задана, новые проекты используют первый образ из ALL_TEX_LIVE_DOCKER_IMAGES.
  • ALL_TEX_LIVE_DOCKER_IMAGE_NAMES (необязательная) — список названий образов через запятую в том же порядке, отображаемых в настройках компилятора. Если переменная не задана или список короче списка образов, образ отображается по своему тегу, например 2026.1.
  • ALL_TEX_LIVE_DOCKER_IMAGES (обязательная) — список используемых образов TeX Live через запятую. Если для развёртывания используется Overleaf Toolkit, эти образы будут скачаны или обновлены. Чтобы пропустить скачивание, задайте SIBLING_CONTAINERS_PULL=false в config/overleaf.rc.
При запуске экземпляра Ayakaleaf Pro командой bin/up Toolkit автоматически скачивает все образы, перечисленные в ALL_TEX_LIVE_DOCKER_IMAGES. Ниже приведён пример, в котором для новых проектов по умолчанию используется TeX Live 2026, а для старых проектов сохраняется 2025.
Следующая конфигурация устанавливает полные Docker-образы TeX Live за 2025–2026 годы. Перед использованием этой конфигурации рекомендуем иметь не менее 64 ГБ свободного места.
config/variables.env
Настоятельно рекомендуется задать как минимум 2 образа texlive-full. Подробнее о причинах см. #known-issues

Доступные образы TeX Live

Ниже приведена серия образов TeX Live, специально оптимизированных для Overleaf; их также можно указывать в TEX_LIVE_DOCKER_IMAGE и ALL_TEX_LIVE_DOCKER_IMAGES:
  • ghcr.io/ayaka-notes/texlive-full:2026.1 (также тег latest)
  • ghcr.io/ayaka-notes/texlive-full:2025.1
  • ghcr.io/ayaka-notes/texlive-full:2024.1
  • ghcr.io/ayaka-notes/texlive-full:2023.1
  • ghcr.io/ayaka-notes/texlive-full:2022.1
  • ghcr.io/ayaka-notes/texlive-full:2021.1
  • ghcr.io/ayaka-notes/texlive-full:2020.1
Существует строгая схема того, как должны быть помечены теги образов (применяется регулярное выражение ^[0-9]+.[0-9]+, где первое число определяет год TeX Live, а второе — версию патча).

Можно ли использовать другой реестр образов

Некоторые спрашивают: можно ли заменить ghcr.io другим зеркалом или переключить texlive на другой образ из Docker Hub?
Нет, мы не рекомендуем этого делать, поскольку настройка относительно сложна. Если вы скачиваете образы с зеркала, можно переименовать образ в ghcr.io/ayaka-notes/texlive-full. Но если вы действительно хотите использовать собственный реестр образов, добавьте:
config/variables.env
Затем нужно убедиться, что все образы texlive находятся в your-repo, например:
  • hub.your.com/your-repo/texlive-full:2025.1
  • hub.your.com/your-repo/texlive-full:2024.1
Подробнее — изучите приведённый ниже исходный код, чтобы понять, как разбираются ваши переменные окружения:
sandboxed-compiles/index.mjs

Автоматическая синхронизация образов TeX Live

Чтобы не обновлять экземпляр вручную с помощью bin/up каждый раз, можно автоматизировать обновление образов TeX Live. См. updating-tex-live-full-images-automatically.md.

Известные проблемы

Вот реальный случай из сообщества Overleaf:
Используя 6.0.1-ext-v3.3, я задал в variables.env следующие настройки:
С texlive/texlive:latest-full всё работает. Однако я скачал другой образ texlive danteev/texlive:2025-10-15 и изменил обе переменные на имя нового образа, но это не работает:
В логах я вижу следующее:
Похоже, что обновлённые настройки в variables.env не применяются. Компиляция по-прежнему пытается запустить образ texlive/texlive:latest-full, а не новый образ. Я пробовал перезагрузку, удаление контейнеров и повторный запуск, но проблема остаётся. Есть ли решение?
Из-за некоторых технических ограничений, если вы настроили только один Docker-образ TeXLive, например texlive-fullA:latest
а через некоторое время работы экземпляра Overleaf захотите изменить образ TeXLive на texlive-fullB:latest, то обнаружите, что ваши пользователи не могут скомпилировать ни один проект.
Это происходит потому, что имя образа TeXLive-Full (для изолированной компиляции) для каждого проекта сохраняется в базе данных. Имя образа в базе данных изменяется только тогда, когда пользователь переключает версию TeXLive своего проекта, например с 2024 на 2025. При компиляции проекта CLSI использует имя образа контейнера, найденное в базе данных, и напрямую компилирует проект с ним. Если вы предоставляете только один Docker-образ, пользователи не смогут изменить образ, используемый для компиляции проекта. В этом случае вам нужно написать скрипт, чтобы вручную изменить образ TeXLive для всех проектов пользователей в MongoDB.

Отладка и сообщения об ошибках

Чтобы посмотреть лог clsi через Toolkit, выполните следующую команду:
Если вы столкнулись с проблемами при компиляции с образами TeX Live, создайте issue здесь: https://github.com/ayaka-notes/texlive-full/issues/new?template=texlive-image-bug.yml Чтобы помочь нам воспроизвести и диагностировать проблему, вас могут попросить загрузить проект в Overleaf. Затем мы скачаем проект и выполним тестовую компиляцию с помощью GitHub Action.

Вопросы и ответы

Ответ: Контейнеры и файлы компиляции — да, с задержкой; образы TeX Live — нет.
  • Контейнеры компиляции (project-<project id>-<hash>) повторно используются при компиляциях одного и того же проекта, поэтому остаются после компиляции. Каждый час выполняется проверка, которая удаляет контейнеры старше одного часа, проект которых не компилировался в течение последнего часа. Обычно контейнер исчезает через один-два часа после последней компиляции. Перезапуск Overleaf их не удаляет; это делает следующая ежечасная проверка.
  • Контейнеры подсчёта слов, SyncTeX и конвертации удаляются сразу после завершения работы.
  • Файлы компиляции (data/overleaf/data/compiles и output) удаляются, если проект не использовался в течение одного дня; проверка выполняется каждые 10 минут. Когда на диске заканчивается место, этот период постепенно сокращается, вплоть до половины дня.
  • Образы TeX Live никогда не удаляются, поскольку они нужны для каждой компиляции. Чтобы освободить место после удаления образа из ALL_TEX_LIVE_DOCKER_IMAGES, удалите его командой docker image rm <image>.
Удалять эти контейнеры вручную не нужно.
Ответ: Нет. Каждый контейнер компиляции монтирует только каталог компиляции своего проекта в /compile и не имеет доступа к сети; настройки для монтирования других каталогов хоста в него не существует. Вместо этого загрузите нужные проекту файлы в сам проект.
Ответ: Да. ghcr.io/ayaka-notes/texlive-basic:<year>.1 (от 2020.1 до 2026.1) содержит базовую схему TeX Live (basic scheme) и несколько пакетов, таких как latexmk, xetex и fontspec, но без полного набора шрифтов. Он гораздо меньше, чем texlive-full, однако в проектах, использующих другие пакеты, будут возникать ошибки об отсутствующих пакетах. Для TeX Live 2025 basic:
config/variables.env
ghcr.io/ayaka-notes/texlive-full:base не является базовым образом: в нём нет TeX Live, и он не может выполнять компиляцию.
Ответ: Редактор этого не показывает, а журнал clsi записывает это только на уровне debug. Однако каждый запрос на компиляцию возвращает эти данные: откройте инструменты разработчика в браузере, перейдите на вкладку Network, перекомпилируйте проект и выберите запрос compile. Его JSON-ответ содержит timings в миллисекундах, где compileE2E — вся компиляция в сервисе компиляции, а compile — сам запуск LaTeX.
Последнее изменение 13 ноября 2026 г.