Как развернуть Stirling PDF на своём сервере в 2026 году: загрузка файлов, OCR и безопасность входа

Существует две версии «запустить Stirling PDF»: контейнер существует или сервис действительно выполняет свою работу. Важна только вторая. В данном случае проверка заключается в объединении двух PDF, распознавании отсканированной страницы, сжатии результата, а также проверке загрузки и скачивания через публичный proxy.

Stirling PDF предназначен именно для этого: он предоставляет web-интерфейс и API для распространённых операций с PDF. При развёртывании необходимо сохранить все компоненты, обеспечивающие такую работу; порт, volume и сертификат — это входные данные, а не результат.

Параметры контейнера, которые стоит проверить

Первый контейнер должен легко удаляться и создаваться заново. Храните данные вне writable layer, привязывайте порт 8080 только там, откуда до него может достучаться proxy, и передавайте конфигурацию во время запуска.

docker run -d \
  --name stirling-pdf \
  --restart unless-stopped \
  -p 127.0.0.1:8080:8080 \
  -v stirling-pdf-data:/configs \
  -e SECURITY_ENABLELOGIN=true \
  stirlingtools/stirling-pdf:latest

После первоначальной проверки зафиксируйте версию image. Изучайте самую раннюю ошибку запуска, а не итоговое сообщение о перезапуске, проверяйте каждый mount с помощью docker inspect и отслеживайте логи, пока объединяете два PDF, распознаёте отсканированную страницу, сжимаете результат и проверяете загрузку и скачивание через публичный proxy. Такая последовательность помогает отличить ошибку в команде запуска image от проблемы с зависимостью или правами доступа.

Сначала определите критерии успеха для Stirling PDF

Разделите для Stirling PDF четыре зоны ответственности: ingress, listener на порту 8080, постоянное состояние и вспомогательные сервисы или локальные ресурсы. Локальное требование для runtime — дополнительные языковые данные для OCR и достаточный объём временного диска для крупных задач. Зафиксируйте это рядом с image и портом, чтобы при переносе на другой host сохранить те же локальные возможности.

До завершения такой проверки выполните заведомо успешную операцию — объедините два PDF, распознайте отсканированную страницу, сожмите результат и проверьте загрузку и скачивание через публичный proxy. Измерьте объём временного диска, языковые пакеты OCR, потребление памяти JVM и количество одновременных задач конвертации, а результат сохраните вместе с записью о развёртывании. Это даст и критерий приёмки, и первоначальную оценку ёмкости.

После начальной настройки ограничьте доступ к Stirling PDF

Основной риск безопасности на уровне приложения — оставить отключённой security на публичном сервисе обработки документов. Для экземпляра, доступного из интернета, необходимо включить login и не хранить загруженные документы дольше, чем требуется для выполнения задачи. Завершите bootstrap через ограниченный маршрут и сразу после этого удалите временный доступ для настройки.

SECURITY_ENABLELOGIN управляет поведением приложения, а не конфиденциальностью; проверьте его тип и значение, а настоящие credentials Stirling PDF храните отдельно. Предоставьте процессу Stirling PDF только документированные mount и маршруты к зависимостям; не давайте ему доступ к root host и Docker socket. Записывайте неудачные попытки аутентификации и ошибки конфигурации, но удаляйте из логов tokens, connection strings и пользовательские данные.

Назначьте Stirling PDF один канонический адрес

Браузер, API client и Stirling PDF должны использовать один origin. Для этого задайте публичный HTTPS origin и лимиты proxy на загрузку файлов. Сохраняйте исходные host и protocol, не делая порт 8080 конкурирующим публичным адресом.

Руководство по диагностике недоступного сайта помогает отличить недоступный маршрут от приложения, которое отвечает. В данном случае это важно: размер загружаемых файлов превышает лимит proxy или контейнер не может записывать временные файлы. Только первую проблему можно решить изменениями в ingress; во втором случае потребуются логи Stirling PDF, проверка состояния или анализ нагрузки.

Отделите заменяемые контейнеры от постоянных данных

В набор данных для восстановления входят конфигурация, пользовательские файлы и любые языковые данные OCR, которые вы установили намеренно. Подключите /configs до bootstrap, запишите безвредные тестовые данные и замените контейнер, чтобы доказать фактическую постоянность этого пути. Volume защищает данные от замены контейнера, но не от потери host, случайного удаления или повреждения на уровне приложения.

Создавайте резервные копии с учётом источника данных: при необходимости используйте logical dump для работающих баз данных, а файлы копируйте только из согласованного состояния. Храните одну зашифрованную копию отдельно от host Stirling PDF. Критерий успешного восстановления должен быть конкретным: конфигурация и OCR assets возвращаются, а фиксированный тестовый документ даёт приемлемый и читаемый результат. В руководстве по резервному копированию с проверкой восстановления объясняется, почему одного успешного выполнения job недостаточно.

Какие данные собрать до запуска Stirling PDF

Для Stirling PDF заранее определите заведомо успешную операцию: объедините два PDF, распознайте отсканированную страницу, сожмите результат и проверьте загрузку и скачивание через публичный proxy. Храните её prerequisites, ожидаемый response и шаги очистки в version control, не добавляя секретные значения. Зафиксируйте image, использованный для создания этого эталона.

Используйте эту операцию для проверки замены контейнера и независимого восстановления. Восстановленный сервис можно считать работоспособным только тогда, когда возвращаются конфигурация и OCR assets, а фиксированный тестовый документ даёт приемлемый и читаемый результат. Одновременно отслеживайте временный диск, языковые пакеты OCR, память JVM и количество одновременных задач конвертации, а самый медленный или ограниченный ресурс превратите в service-level alert.

В gate также должен входить negative case: отправьте безопасные входные данные, близкие к лимиту ресурса или формата, связанному с этой границей: размер загружаемых файлов превышает лимит proxy или контейнер не может записывать временные файлы. Убедитесь, что Stirling PDF выдаёт понятную ошибку и сохраняет данные, восстановите корректное состояние и повторите заведомо успешную операцию. Сохранение обоих результатов не позволит поверхностной health endpoint стать единственным свидетельством работоспособности в production.

Эксплуатируйте Stirling PDF с учётом реального узкого места

Отслеживайте работу, которую выполняет Stirling PDF: временный диск, языковые пакеты OCR, память JVM и количество одновременных задач конвертации. Задавайте limits с запасом для этой нагрузки и не используйте liveness probe, которая конкурирует с ней за ресурсы. Operator check по расписанию всё равно должен пытаться объединить два PDF, распознать отсканированную страницу, сжать результат и проверить загрузку и скачивание через публичный proxy.

При обновлениях учитывайте, что перед upgrade image необходимо сравнить установленные OCR data, пользовательскую конфигурацию и security settings. Разверните candidate на основе восстановленной копии и повторите известную тестовую операцию. Если размер загружаемых файлов превышает лимит proxy или контейнер не может записывать временные файлы, используйте runtime logs и фактический network request, чтобы выяснить, какое предположение изменилось.

Разверните Stirling PDF в Dockup, не нарушая границы компонентов

Dockup устраняет ручную работу с reverse proxy и lifecycle вокруг Stirling PDF. Во время замены сервис получает стабильный HTTPS route к порту 8080, injected configuration и persistent storage. Подключённый customer server работает по той же модели, что и compute, размещённый в Dockup.

После запуска выполните требования application contract: задайте публичный HTTPS origin и лимиты proxy на загрузку файлов, подтвердите локальное требование — дополнительные языковые данные OCR и достаточный объём временного диска для крупных задач — и выполните проверку: объедините два PDF, распознайте отсканированную страницу, сожмите результат и проверьте загрузку и скачивание через публичный proxy. Это позволяет сохранить пользу one-click experience, не скрывая детали, от которых зависят восстановление и безопасность Stirling PDF.

Часто задаваемые вопросы

Что нужно Stirling PDF для production-развёртывания?

Направьте контейнер Stirling PDF на порту 8080 через один HTTPS origin. Локальное требование для runtime — дополнительные языковые данные OCR и достаточный объём временного диска для крупных задач. Не объявляйте Stirling PDF готовым, пока не сможете объединить два PDF, распознать отсканированную страницу, сжать результат и проверить загрузку и скачивание через публичный proxy.

Какие данные Stirling PDF нужно включить в резервную копию?

Сохраните /configs и включите конфигурацию, пользовательские файлы и любые языковые данные OCR, которые вы установили намеренно, в один recovery manifest. Восстановление Stirling PDF можно считать успешным только тогда, когда возвращаются конфигурация и OCR assets, а фиксированный тестовый документ даёт приемлемый и читаемый результат.

Требуется ли Stirling PDF HTTPS за reverse proxy?

Используйте HTTPS для публичного origin Stirling PDF, а порт 8080 оставьте во внутреннем маршруте. Корректно примените setting Stirling PDF: задайте публичный HTTPS origin и лимиты proxy на загрузку файлов. Для Stirling PDF HTTPS защищает credentials и пользовательские данные при передаче и обеспечивает согласованное поведение клиента, зависящее от origin.

Как тестировать обновление Stirling PDF?

Восстановите текущее состояние Stirling PDF в изолированном deployment, примените candidate version и повторите acceptance transaction. Будьте особенно внимательны: перед upgrade image необходимо сравнить установленные OCR data, пользовательскую конфигурацию и security settings. Сохраняйте предыдущий image Stirling PDF, пока не будут понятны границы миграции данных и rollback.