Сколько RAM нужно для Stirling PDF

MAATRIX

Stirling PDF ставят как свой швейцарский нож для PDF: слияние, разбивка, сжатие, водяные знаки, конвертация в Word и обратно, OCR по сканам — всё через веб-интерфейс и API, без облачных лимитов и без утечки документов третьим сервисам. Дальше начинается лотерея: кто-то держит его на 1 ГБ и не видит проблем, у кого-то контейнер падает по OOM ровно на конвертации отчёта из Word. Разгадка не в мистике — в том, что Stirling PDF на самом деле три разных приложения под одной крышей, и память они просят по-разному.

Короткий ответ: сколько закладывать

Цифры — ориентир для одного экземпляра контейнера на Ubuntu 24.04 без соседей на той же машине. Разброс большой, потому что зависит от размера файлов и от того, включена ли конвертация через LibreOffice.

Ключевой водораздел — не число пользователей, а то, включаете ли вы OCR и конвертацию Office-документов. Без них Stirling PDF — лёгкое Java-приложение, которое живёт и на 1 ГБ. С ними в контейнер въезжает LibreOffice, и требования меняются на порядок.

Из чего состоит Stirling PDF и куда уходит память

Под капотом это Spring Boot приложение на Java плюс набор внешних инструментов, которые оно вызывает как отдельные процессы:

• JVM-ядро. Сам веб-сервер и обработка большинства операций с PDF (через библиотеку PDFBox) — merge, split, rotate, watermark, page numbers, извлечение страниц. Как у любого Spring Boot сервиса такого размера, в простое память в основном уходит на прогретый JVM-heap и загруженные классы, а не на реальные данные.
• PDFBox-операции масштабируются с размером файла. Когда вы сливаете десять PDF по 50 МБ или разбиваете PDF на 800 страниц, документ читается в память целиком, а не потоково — большой файл на входе означает пропорционально больший всплеск RAM на время запроса, а не только на диске.
• LibreOffice (soffice) — для конвертации в Word/Excel/PowerPoint и обратно. Каждый запрос на конвертацию поднимает процесс soffice.bin, который открывает файл фактически как настольный редактор в headless-режиме — со шрифтами, стилями, встроенными изображениями. Это исторически самый прожорливый компонент связки, и по памяти он ведёт себя как обычный LibreOffice, а не как лёгкая библиотека.
• OCR-модуль (через OCRmyPDF и Tesseract) рендерит каждую страницу скана в растровое изображение при заданном DPI, затем распознаёт текст и вклеивает невидимый текстовый слой обратно в PDF. Чем выше DPI и чем больше страниц обрабатывается разом, тем выше пик — это тот случай, где 20-страничный скан и 400-страничная книга требуют принципиально разного бюджета памяти, и точную цифру стоит не искать в интернете, а измерить на своих файлах.

Full-образ или ultra-lite — что выбрать по памяти

Проект распространяет Docker-образ в двух весовых категориях, и выбор образа — первое, что определяет требования к серверу ещё до всякой настройки. Актуальные названия тегов стоит сверить на Docker Hub перед деплоем — они меняются между релизами, — но смысл деления стабилен:

• Полный образ несёт внутри LibreOffice, Python, Tesseract и прочий инструментарий для конвертации и OCR. Он тяжелее на диске, дольше стартует и держит более высокий базовый уровень памяти даже без активных запросов — просто потому, что внутри контейнера живёт весь этот набор бинарников и его окружение.
• Ultra-lite образ — это только сама Java-часть: операции с готовым PDF без обращения к внешним конвертерам. Эндпоинты конвертации и OCR в нём либо отсутствуют, либо отключены. Зато контейнер компактный, стартует быстро и комфортно живёт на минимальном VPS.

Практическое правило: если вам нужны только операции над самим PDF — слияние, разбивка, сжатие, повороты, водяные знаки, извлечение страниц, подпись, редактирование метаданных — берите ultra-lite и не переплачивайте за память впустую. Если хотя бы иногда нужна конвертация Word↔PDF или распознавание сканов, берите полный образ и сразу закладывайте память по разделу выше, а не пытайтесь сэкономить и упереться в OOM на первой же реальной задаче.

OCR и конвертация — где реально спрашивает память

Это два узких места, из-за которых сервер на 1–2 ГБ, спокойно работавший неделю, вдруг падает.

Конвертация в Word и обратно. Каждый запрос — это отдельный процесс soffice.bin. Если сервер получает несколько запросов на конвертацию одновременно (несколько вкладок пользователя, параллельные вызовы API), процессов LibreOffice становится несколько, и память складывается линейно, а не размазывается. На слабом сервере это главная причина внезапного падения: система держится на редких одиночных конвертациях и обрушивается, как только два человека одновременно нажали «конвертировать в Word».

OCR многостраничных сканов. Всплеск пропорционален количеству страниц, обрабатываемых в моменте, и выбранному DPI. 150 DPI для обычного текста заметно легче 300–600 DPI, которые имеет смысл ставить только для мелкого шрифта или таблиц. Если планируете гонять через OCR сканы толщиной в сотни страниц, стоит один раз прогнать типичный файл на тестовом сервере и посмотреть на docker stats, а не полагаться на общие цифры из статьи — разброс между «скан текста» и «скан с фотографиями на каждой странице» велик.

Практический вывод один: на серверах до 4 ГБ не давайте Stirling PDF выполнять конвертацию или OCR параллельно. Даже без специальной очереди в приложении это можно ограничить снаружи — например, через nginx limit_conn на конкретный путь API, если конвертацию дёргают программно, а не только руками из веб-интерфейса.

Docker-лимиты: как ограничить и не словить OOM

По умолчанию контейнер не ограничен и может забрать всю память хоста — на VPS без соседей это не страшно, но полезно всё равно поставить потолок, чтобы при пике Stirling PDF падал сам, изолированно, а не утаскивал в OOM что-то ещё на той же машине.

# docker-compose.yml
services:
  stirling-pdf:
    image: stirlingtools/stirling-pdf:latest
    container_name: stirling-pdf
    restart: unless-stopped
    ports:
      - "8080:8080"
    environment:
      - DOCKER_ENABLE_SECURITY=false
      - JAVA_TOOL_OPTIONS=-Xmx1536m
    volumes:
      - ./data:/usr/share/tessdata
      - ./configs:/configs
    mem_limit: 2g
    mem_reservation: 512m

JAVA_TOOL_OPTIONS=-Xmx1536m ограничивает именно JVM-heap — это защита от разрастания самой Java-части, а не от процессов LibreOffice, которые JVM не контролирует и которые едят память отдельно. Поэтому mem_limit на весь контейнер нужен обязательно: он — общий потолок и для JVM, и для soffice.bin, и для Tesseract вместе взятых. Ставьте его с запасом над -Xmx, иначе первая же конвертация упрётся в лимит контейнера раньше, чем в лимит JVM.

Смотреть реальное потребление стоит не по текущему значению, а по пику — как и с любым контейнерным сервисом (подробный разбор — в статье про лимиты CPU и памяти для Docker):

docker stats stirling-pdf --no-stream
docker exec stirling-pdf cat /sys/fs/cgroup/memory.peak

Если контейнер регулярно упирается в mem_limit при конвертации, в логах будет characterный обрыв: контейнер просто перезапускается по restart: unless-stopped, а в dmesg -T | tail -30 на хосте — запись oom-kill с именем soffice.bin или java. Это надёжный сигнал поднимать mem_limit, а не симптом, который можно вылечить настройками приложения.

Какой сервер брать под Stirling PDF

Личный инструмент: 1 vCPU, 2 ГБ RAM. Достаточно для образа ultra-lite или для полного образа без параллельных конвертаций — слияние счетов, разбивка сканов, подпись договоров, водяные знаки. Диск — 20–40 ГБ NVMe, файлы PDF места много не просят.

Небольшая команда: 2 vCPU, 4 ГБ RAM. Полный образ, несколько человек пользуются через браузер, изредка конвертируют документы и распознают короткие сканы. Второе ядро важно отдельно от памяти: LibreOffice и Tesseract процессорно нагружают систему не меньше, чем по памяти, и на одном ядре конвертация тормозит весь остальной интерфейс.

Активная нагрузка или интеграция по API: 4 vCPU, 8 ГБ RAM. Здесь уже осмысленно выставлять mem_limit с запасом, добавлять swap как подушку на случай пикового скана (см. статью про размер swap для VPS) и следить за метриками, а не гадать по ощущениям.

Локация для Stirling PDF почти не влияет на удобство работы — это не видеозвонок и не синхронизация файлов с задержкой на каждый чих, задержка в 20–50 мс на загрузку файла и получение результата не заметна. Выбирайте по тому, где физически находятся ваши документы и пользователи, и по требованиям к хранению данных, если работаете с чужими договорами или персональными данными.

В каталоге apps.maatrix.io Stirling PDF ставится автоматически при заказе сервера — сборка образа и первый запуск не требуют ручной работы в консоли, адрес и доступ приходят в личный кабинет. Оплата — картой российского банка, по СБП, криптовалютой или токеном MAAT, без необходимости в иностранной карте даже для площадок за пределами России.

Частые вопросы