Свой сервис для работы с PDF без ограничений и подписок: развертывание Stirling-PDF на VDS в Docker Compose

Работа с PDF-документами — ежедневная рутина любого бизнеса: бухгалтерия объединяет акты и счета, юристы подписывают договоры, маркетологи сжимают презентации для отправки клиентам, а разработчики конвертируют чеки и отчеты. Большинство пользователей привыкли пользоваться популярными веб-сервисами (iLovePDF, Smallpdf, Adobe Acrobat Pro). Однако в 2026 году этот подход создает критические проблемы: зарубежные подписки требуют валютных карт и стоят от $15 до $30 в месяц за каждого сотрудника, а бесплатные тарифы накладывают жесткие лимиты на 2–3 операции в час.

Но главная опасность облачных онлайн-конвертеров — утечка конфиденциальных данных. Загружая договор с реквизитами, скан паспорта или финансовую отчетность на сторонний сайт, вы передаете коммерческую тайну на чужие серверы, нарушая законодательство о защите персональных данных (152-ФЗ). Идеальное инженерное решение этой проблемы — развертывание Stirling-PDF на собственном VDS.

1. Зачем разворачивать свой PDF-сервер вместо Adobe, iLovePDF и Smallpdf

Stirling-PDF — это мощный open-source проект (более 45 000 звёзд на GitHub), представляющий собой полноценную веб-платформу для любых операций с PDF. Приложение работает локально на вашем сервере, потребляет минимум ресурсов и предоставляет интуитивный интерфейс на русском языке.

2. Возможности Stirling-PDF: 50+ инструментов для работы с документами

Stirling-PDF объединяет в одном окне функционал десятка платных программ:

• Базовые операции со страницами: объединение нескольких PDF в один, разделение документа по страницам или диапазонам, удаление лишних листов, поворот, сортировка и вырезание фрагментов.
• Оптимизация и сжатие: эффективное уменьшение размера файлов без потери читаемости текста за счет оптимизации DPI растровых изображений и удаления дубликатов встроенных шрифтов.
• Распознавание текста (OCR): преобразование отсканированных бумажных документов, фотографий и скриншотов в полноценный текстовый PDF с возможностью поиска и копирования (Searchable PDF).
• Безопасность и цифровая подпись: установка и снятие паролей, шифрование AES-256, удаление метаданных (автор, дата создания, версия софта), водяные знаки и электронная подпись документов сертификатом.
• Конвертация форматов: преобразование PDF в изображения (PNG, JPG), текстовые файлы, а также обратная конвертация сканов и фото в единый документ.

3. Системные требования и подготовка Linux VDS (RAM, Swap, Docker)

Stirling-PDF построен на базе Java (Spring Boot) и производительных низкоуровневых библиотек обработки графики (Tesseract OCR, Apache PDFBox, qpdf). Архитектура приложения требует реалистичной оценки системных ресурсов:

• Официальная рекомендация: 2 vCPU и 4 ГБ RAM. Это стандарт для комфортной одновременной работы команды, гарантирующий стабильную обработку многостраничных сканов и оптическое распознавание текста (OCR) без риска аварийного падения.
• Минимальная конфигурация: 1–2 vCPU и 2 ГБ RAM при обязательном подключении файла подкачки Swap от 2 до 4 ГБ. Базовый контейнер в режиме ожидания потребляет около 400–600 МБ RAM, однако во время выполнения тяжелых операций (распознавание текста, сжатие сотен страниц) пиковое потребление памяти мгновенно подскакивает до 1.2–2 ГБ. Развертывание на серверах с 1 ГБ RAM возможно исключительно для простых операций и требует жесткого контроля памяти и активного Swap.
• Дисковое пространство: от 15–20 ГБ быстрого NVMe. Документы размером до 50 МБ обрабатываются непосредственно в оперативной памяти, однако более крупные PDF-файлы буферизируются во временный каталог на диске (/tmp), что требует запаса свободного места.

Перед началом установки убедитесь, что на сервере настроен Swap-файл (подробная инструкция приведена в нашей статье о том, как настроить Swap и zRAM для защиты от OOM Killer):

# Проверка наличия файла подкачки
free -h

# Если Swap отсутствует, создаем файл подкачки на 2 ГБ:
sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab

Обновите пакеты системы и установите Docker с плагином Docker Compose:

sudo apt update && sudo apt install -y curl jq nginx certbot python3-certbot-nginx
# Установка Docker и добавление пользователя в группу
curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER && newgrp docker

4. Развертывание Stirling-PDF в Docker Compose: базовый манифест и тома

Создайте рабочую директорию проекта, например /opt/stirling-pdf, и необходимые подпапки для конфигурации, логов и языковых моделей OCR:

sudo mkdir -p /opt/stirling-pdf/trainingData
sudo mkdir -p /opt/stirling-pdf/extraConfigs
sudo mkdir -p /opt/stirling-pdf/customFiles
sudo mkdir -p /opt/stirling-pdf/logs
cd /opt/stirling-pdf

Создайте файл docker-compose.yml:

services:
  stirling-pdf:
    image: stirlingtools/stirling-pdf:latest
    container_name: stirling-pdf
    restart: unless-stopped
    ports:
      # Привязка к локальному адресу (защита от прямого доступа в обход Nginx)
      - "127.0.0.1:8080:8080"
    volumes:
      # Папка для файлов языковых моделей Tesseract OCR
      - ./trainingData:/usr/share/tesseract-ocr/5/tessdata
      # Пользовательские конфигурации и настройки авторизации
      - ./extraConfigs:/configs
      # Системные журналы приложения
      - ./logs:/logs
      # Пользовательские файлы и водяные знаки
      - ./customFiles:/customFiles
    environment:
      # Включение экрана авторизации и многопользовательской защиты (v1.0+)
      - SECURITY_ENABLELOGIN=true
      # Язык интерфейса по умолчанию (русский)
      - SYSTEM_DEFAULTLOCALE=ru-RU
      - UI_APPNAME=SysKit PDF Studio
    mem_limit: 2048m
    deploy:
      resources:
        limits:
          memory: 2048M

5. Настройка оптического распознавания текста (OCR) на русском языке

По умолчанию в базовый образ Stirling-PDF включена только базовая англоязычная языковая модель Tesseract. Если попытаться распознать отсканированный документ на русском языке, на выходе получится нечитаемый набор символов («кракозябры»).

Чтобы добавить качественную поддержку русского языка, скачаем официальный тренировочный файл rus.traineddata из репозитория проекта Tesseract прямо в каталог trainingData:

# Скачивание быстрой и точной модели русского языка Tesseract
sudo curl -L -o /opt/stirling-pdf/trainingData/rus.traineddata   https://github.com/tesseract-ocr/tessdata_fast/raw/main/rus.traineddata

# Установка правильных прав на чтение
sudo chmod 644 /opt/stirling-pdf/trainingData/rus.traineddata

Теперь при выборе инструмента «Оптическое распознавание (OCR)» в выпадающем списке доступных языков автоматически появится русский язык. Вы сможете загрузить любой скан накладной или договора в виде картинки или «глухого» PDF и получить полноценный документ, в котором можно выделять, искать и копировать текст.

6. Включение авторизации и многопользовательского режима

Благодаря переменной SECURITY_ENABLELOGIN=true (в версиях до v1.0 использовался устаревший параметр DOCKER_ENABLE_SECURITY), веб-панель Stirling-PDF защищена экраном аутентификации. Кроме того, детальные настройки безопасности можно задать напрямую в конфигурационном файле extraConfigs/settings.yml. Это исключает несанкционированный доступ посторонних лиц к ресурсам вашего сервера.

Запустите контейнер:

cd /opt/stirling-pdf
sudo docker compose up -d

При первом запуске с включенной безопасностью создается учетная запись администратора со стандартными учетными данными:

• Логин: admin
• Пароль по умолчанию: stirling

Перед публикацией сервиса в интернет сгенерируйте криптостойкий пароль для защиты учетной записи:

После первого входа перейдите в правый верхний угол в раздел «Account Settings» → «Change Password» и смените дефолтный пароль. Во вкладке «User Management» вы сможете создать индивидуальные аккаунты для коллег или сотрудников компании с разграничением прав.

7. Настройка Nginx Reverse Proxy, Let's Encrypt SSL и лимита загрузки

Чтобы сервис был доступен по красивому доменному имени (например, pdf.вашдомен.рф) с шифрованием HTTPS, настроим обратный прокси на базе Nginx.

Создайте конфигурационный файл /etc/nginx/sites-available/stirling-pdf:

server {
    listen 80;
    server_name pdf.example.com;

    # Критически важная директива: разрешаем загрузку файлов до 250 МБ
    client_max_body_size 250M;

    # Увеличенные таймауты для тяжелых операций сжатия и OCR
    proxy_read_timeout 300s;
    proxy_connect_timeout 300s;
    proxy_send_timeout 300s;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_http_version 1.1;

        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # Буферизация для передачи объемных файлов
        proxy_buffering off;
        proxy_request_buffering off;
    }
}

Активируйте сайт, проверьте синтаксис Nginx и выпустите бесплатный SSL-сертификат Let's Encrypt:

sudo ln -s /etc/nginx/sites-available/stirling-pdf /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

# Выпуск SSL-сертификата с автоматическим редиректом на HTTPS
sudo certbot --nginx -d pdf.example.com --redirect

После завершения выпуска сертификата обязательно проверьте корректность цепочки и протоколов через онлайн-чекер SSL SysKit.

8. Автоматизация рутины: конвейеры (Pipelines) и пакетная обработка

Одной из уникальных возможностей Stirling-PDF является встроенный механизм Pipelines (Конвейеры). Он позволяет создавать цепочки последовательных действий над файлами.

Типичный пример бизнес-конвейера для входящей первичной документации:

1. Шаг 1: Автоматическое удаление пустых страниц из отсканированной пачки.
2. Шаг 2: Запуск OCR на русском языке для создания текстового слоя.
3. Шаг 3: Сжатие документа до размера менее 5 МБ для отправки контрагенту по email.
4. Шаг 4: Наложение водяного знака компании («КОПИЯ ВЕРНА»).

Вы можете сохранить настроенный конвейер в закладки или подключить автоматическую обработку входящих файлов через локальную папку watchedFolders или REST API, отправляя документы прямо из скриптов на Python, Node.js или через n8n.

9. Резервное копирование настроек и обновление контейнера

Чтобы не потерять учетные записи пользователей и кастомные языковые модели, достаточно регулярно делать резервную копию папки /opt/stirling-pdf. Поскольку данные хранятся в обычных файлах и базе H2/SQLite, резервное копирование выполняется предельно просто:

# Создание архива настроек и языковых моделей
sudo tar -czvf /backup/stirling-pdf-$(date +%F).tar.gz -C /opt stirling-pdf

Для настройки автоматической отправки архивов в облачное хранилище воспользуйтесь практическим руководством по автоматическому бэкапу VDS в S3-хранилище.

Обновление сервиса до последней версии выполняется двумя стандартными командами Docker Compose:

cd /opt/stirling-pdf
sudo docker compose pull
sudo docker compose up -d --remove-orphans

10. Решение типичных проблем: ошибка 413, нехватка памяти и шрифты

В процессе эксплуатации Stirling-PDF администраторы могут столкнуться с тремя характерными нюансами:

• Ошибка 413 Request Entity Too Large: Возникает, если в конфигурации Nginx забыли прописать директиву client_max_body_size. По умолчанию Nginx сбрасывает файлы крупнее 1 МБ. Убедитесь, что в блоке server указано client_max_body_size 250M;.
• Аварийное завершение процесса при OCR (OOMKilled): Если при распознавании книги на 100+ страниц контейнер перезагружается, значит, серверу не хватило оперативной памяти. Убедитесь, что файл подкачки активен (swapon --show), и зарезервируйте не менее 2 ГБ Swap.
• Пропадание кириллических символов при конвертации: При конвертации файлов из форматов DOCX/ODT в PDF кириллические шрифты могут заменяться на квадраты. Для решения проблемы смонтируйте системные шрифты хоста в контейнер, добавив в блок volumes строку: - /usr/share/fonts:/usr/share/fonts:ro.