Установка и настройка Stirling-PDF на VPS: Полное руководство по self-hosted управлению PDF с OCR

1. Что такое Stirling-PDF и зачем он нужен на собственном сервере

К 2026 году вопрос приватности данных стал критическим. Каждый раз, когда вы загружаете документ на бесплатный онлайн-сервис для "быстрого объединения PDF", вы передаете свои персональные данные, финансовые отчеты или корпоративные секреты третьим лицам. Stirling-PDF — это open-source решение, которое переносит функционал профессиональных PDF-редакторов в ваш браузер, работая при этом исключительно на вашем оборудовании.

В отличие от десктопных приложений, Stirling-PDF доступен с любого устройства: смартфона, планшета или ноутбука. В отличие от SaaS-решений, здесь нет подписок, лимитов на количество страниц или "премиум-функций". Вы получаете полный контроль над процессом обработки.

Ключевые возможности:

• Объединение, разделение, поворот и удаление страниц.
• Сжатие PDF с выбором алгоритмов оптимизации.
• Добавление водяных знаков, подписей и штампов.
• Преобразование PDF в форматы Word, Excel, PowerPoint, HTML и обратно.
• OCR (Optical Character Recognition): превращение сканов в текстовые документы с возможностью поиска.
• Удаление паролей и установка новых (AES-256).
• Инструменты для организации страниц: изменение порядка, нумерация, обрезка.

Self-hosting на VPS дает вам независимость от санкций провайдеров, стабильную скорость обработки (зависящую только от ресурсов вашего сервера) и уверенность в том, что ваши файлы не используются для обучения нейросетей без вашего согласия.

2. Какой VPS-конфиг нужен под эту задачу

Stirling-PDF — это Java-приложение (Spring Boot), которое активно использует внешние библиотеки, такие как LibreOffice и Tesseract OCR. Эти компоненты требовательны к ресурсам, особенно во время конвертации объемных файлов или распознавания текста в высоком разрешении.

Для стабильной работы OCR, особенно если вы планируете обрабатывать документы объемом более 100 страниц, критически важен объем оперативной памяти. Java-процесс может потреблять значительные ресурсы при пиковых нагрузках. Для комфортной работы без задержек можно взять подходящий VPS с 4 или 8 ГБ оперативной памяти — это обеспечит плавную работу интерфейса и быструю обработку очередей задач.

Когда стоит выбрать Dedicated сервер? Если ваша задача — автоматизированная обработка тысяч документов в день через API Stirling-PDF, или если вы строите внутренний корпоративный сервис для штата в 50+ сотрудников. В остальных случаях современного VPS будет более чем достаточно.

Локация: Выбирайте сервер максимально близко к вам или вашей целевой аудитории. Несмотря на то, что PDF-обработка происходит на бэкенде, задержка (latency) влияет на скорость загрузки и скачивания тяжелых файлов.

3. Подготовка сервера: базовое укрепление и утилиты

Прежде чем устанавливать само приложение, необходимо подготовить среду. Мы будем использовать Ubuntu 24.04, но инструкции применимы и к более новым версиям 2026 года.

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

sudo apt update && sudo apt upgrade -y
sudo apt install -y curl wget git htop ufw fail2ban

Настройка безопасности — важный этап. Мы закроем все порты, кроме SSH и стандартных веб-портов:

# Разрешаем SSH (убедитесь, что у вас есть доступ!)
sudo ufw allow 22/tcp
# Разрешаем HTTP и HTTPS
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
# Включаем брандмауэр
sudo ufw enable

Для предотвращения брутфорс-атак на SSH настроим fail2ban. Создадим локальный конфиг:

sudo cp /etc/fail2ban/jail.conf /etc/fail2ban/jail.local
sudo systemctl enable fail2ban
sudo systemctl start fail2ban

Рекомендуется также создать отдельного пользователя с правами sudo, чтобы не работать под root постоянно:

adduser pdfadmin
usermod -aG sudo pdfadmin
# Переключаемся на нового пользователя
su - pdfadmin

4. Установка Docker и Docker Compose (актуально на 2026 год)

Stirling-PDF официально поставляется в виде Docker-образа. Это идеальный способ установки, так как он включает в себя все зависимости (Python, LibreOffice, Java, Tesseract) в изолированном контейнере, не "засоряя" основную систему.

Установим Docker через официальный скрипт:

curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

Добавим нашего пользователя в группу docker, чтобы запускать контейнеры без sudo:

sudo usermod -aG docker $USER
# Примените изменения групп (или перезайдите в SSH)
newgrp docker

Проверим установку:

docker compose version
docker --version

В 2026 году Docker Compose является встроенной частью команды docker (плагин compose), поэтому отдельная установка docker-compose больше не требуется.

5. Развертывание Stirling-PDF: пошаговая инструкция

Мы будем использовать Stirling-PDF-Ultra — это наиболее полная версия образа, включающая все OCR-языки и дополнительные инструменты. Создадим рабочую директорию:

mkdir -p ~/stirling-pdf/configs ~/stirling-pdf/logs
cd ~/stirling-pdf

Создадим файл docker-compose.yml. В этом файле мы опишем параметры запуска приложения:

nano docker-compose.yml

Вставьте следующее содержимое:

services:
  stirling-pdf:
    image: frooodle/s-pdf:latest-ultra
    container_name: stirling-pdf
    restart: always
    ports:
      - "8080:8080"
    environment:
      - DOCKER_ENABLE_SECURITY=true
      - INSTALL_BOOK_AND_ADVANCED_HTML_OPS=true
      - LANGS=ru_RU,en_GB
      - APP_LOCALE=ru_RU
      - SYSTEM_DEFAULT_LOCALE=ru_RU
      - TZ=Europe/Moscow
    volumes:
      - ./configs:/configs
      - ./logs:/logs
      - /usr/share/tesseract-ocr/4.00/tessdata:/usr/share/tesseract-ocr/4.00/tessdata # Опционально для своих словарей

Разберем ключевые переменные окружения:

• DOCKER_ENABLE_SECURITY: включает систему авторизации (логин/пароль). По умолчанию логин admin, пароль stirling. Обязательно смените после первого входа!
• LANGS: список языков для OCR. Мы указали русский и английский.
• INSTALL_BOOK_AND_ADVANCED_HTML_OPS: включает поддержку конвертации электронных книг и расширенные операции с HTML.

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

docker compose up -d

Проверить статус запуска можно командой docker ps или просмотрев логи: docker logs -f stirling-pdf. При первом запуске скачивание образа "Ultra" может занять несколько минут, так как он весит около 2-3 ГБ из-за встроенного LibreOffice и языковых пакетов.

6. Настройка доступа через HTTPS (Caddy)

Запускать сервис на порту 8080 без шифрования — плохая идея, особенно если вы работаете с документами. Нам нужен HTTPS. Самый простой и современный способ — использовать веб-сервер Caddy, который автоматически получает и обновляет SSL-сертификаты от Let's Encrypt.

Установим Caddy:

sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https
curl -1G 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1G 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list
sudo apt update
sudo apt install caddy

Настроим проксирование. Отредактируйте файл /etc/caddy/Caddyfile:

sudo nano /etc/caddy/Caddyfile

Замените содержимое на следующее (укажите ваш домен):

pdf.yourdomain.com {
    reverse_proxy localhost:8080
    
    encode gzip
    
    log {
        output file /var/log/caddy/pdf_access.log
    }
}

Перезапустите Caddy:

sudo systemctl restart caddy

Теперь, при условии, что ваша A-запись домена указывает на IP вашего VPS, сервис будет доступен по адресу https://pdf.yourdomain.com с валидным SSL-сертификатом.

7. Глубокая настройка: OCR, локализация и безопасность

Stirling-PDF позволяет тонко настраивать процесс распознавания текста. OCR базируется на движке Tesseract. Если вы обнаружили, что качество распознавания русского языка недостаточно высокое, вы можете добавить дополнительные тренированные данные.

Настройка авторизации

После первого входа перейдите в раздел Settings -> Security Settings. Здесь вы можете:

• Изменить стандартный пароль администратора.
• Включить API-ключи для интеграции с другими сервисами (например, для автоматизации через скрипты Python или n8n).
• Настроить время жизни сессии.

Оптимизация производительности

Если сервер начинает "тормозить" при обработке PDF, можно ограничить ресурсы контейнера в docker-compose.yml:

    deploy:
      resources:
        limits:
          cpus: '2.0'
          memory: 4G

Это предотвратит ситуацию, когда один тяжелый файл "вешает" весь VPS, лишая вас доступа по SSH.

Кастомные шрифты

Для корректного отображения кириллицы при конвертации из PDF в Word/HTML иногда требуются специфические шрифты. Вы можете смонтировать папку со шрифтами вашего сервера в контейнер:

      - /usr/share/fonts:/usr/share/fonts:ro

8. Бэкапы и автоматическое обновление системы

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

Скрипт резервного копирования

Создадим простой скрипт backup.sh:

#!/bin/bash
BACKUP_DIR="/home/pdfadmin/backups"
DATE=$(date +%Y-%m-%d)
mkdir -p $BACKUP_DIR

# Останавливаем контейнер для консистентности данных (опционально)
cd /home/pdfadmin/stirling-pdf
docker compose stop

# Архивация конфигов
tar -czf $BACKUP_DIR/stirling_conf_$DATE.tar.gz ./configs

# Запуск контейнера
docker compose start

# Удаление старых бэкапов (старше 30 дней)
find $BACKUP_DIR -type f -mtime +30 -delete

Добавьте скрипт в crontab для ежедневного запуска в 3 часа ночи:

0 3   * /bin/bash /home/pdfadmin/stirling-pdf/backup.sh

Обновление Stirling-PDF

Разработчики активно выпускают обновления. Чтобы обновиться до последней версии, выполните:

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

Docker автоматически скачает новые слои образа и перезапустит сервис с сохранением всех ваших настроек (так как они хранятся во внешних volumes).

9. Troubleshooting + FAQ

Почему OCR работает очень медленно?

OCR — это процесс, максимально нагружающий CPU. Если у вашего VPS всего 1-2 ядра, распознавание 50-страничного документа может занять несколько минут. Проверьте нагрузку командой htop. Если CPU загружен на 100%, рассмотрите возможность апгрейда тарифа VPS.

Ошибка "Out of Memory" при загрузке больших файлов

Это связано с лимитами Java Heap Size. Вы можете увеличить лимит, добавив переменную в docker-compose.yml:

      - JAVA_OPTS=-Xmx2g

Это выделит 2 ГБ оперативной памяти специально под нужды Java-процесса.

Какой VPS-конфиг минимально подойдет?

Минимально — 2 ядра CPU и 4 ГБ RAM. На 2 ГБ RAM приложение запустится, но при попытке использовать OCR или конвертировать PDF в DOCX контейнер, скорее всего, будет убит системой (OOM Killer).

Что выбрать — VPS или dedicated для этой задачи?

Для личного использования и малых команд (до 10 человек) VPS — идеальный выбор. Он гибкий, его легко масштабировать. Dedicated сервер стоит брать только если вы планируете обрабатывать огромные архивы документов (десятки тысяч страниц в сутки), где важна многопоточность и отсутствие "соседей" по гипервизору.

Безопасно ли хранить документы на сервере?

Stirling-PDF спроектирован так, чтобы удалять файлы сразу после того, как вы закрыли страницу или скачали результат. Однако, для максимальной безопасности, убедитесь, что вы используете HTTPS и сложный пароль для входа в систему.

Как добавить поддержку других языков OCR?

В переменной LANGS в файле docker-compose.yml добавьте нужные коды через запятую (например, deu для немецкого, fra для французского). Полный список кодов доступен в документации Tesseract.

10. Выводы и следующие шаги

Мы успешно развернули профессиональный инструмент управления PDF на собственном сервере. Теперь у вас есть полный контроль над вашими документами, отсутствие подписок и мощный движок OCR, доступный из любой точки мира.

Что делать дальше?

• Интеграция: Попробуйте использовать API Stirling-PDF для автоматизации рутинных задач. Например, вы можете настроить скрипт, который автоматически накладывает водяной знак на все PDF в определенной папке.
• Мобильное приложение: Поскольку интерфейс адаптивен, вы можете добавить ярлык страницы на экран смартфона — это будет работать как полноценное PWA-приложение.
• Оптимизация: Если вы планируете публичный доступ, настройте Cloudflare перед вашим VPS для защиты от DDoS-атак и дополнительного кэширования статики.

Self-hosting — это не только экономия денег, но и важный шаг к цифровому суверенитету. С Stirling-PDF ваши данные принадлежат только вам.