Как развернуть Gotenberg самостоятельно в 2026 году: HTML в PDF, тайм-ауты и шрифты
Разверните Gotenberg с правильно настроенными портом, постоянным хранилищем, TLS, аутентификацией и резервным копированием. Устраните проблемы, возникающие, когда в production-запросах используется неправильное multipart-поле.
Неудачное развертывание Gotenberg не всегда приводит к сбою. Сервис может отдавать страницу входа, пока запросы используют неправильное multipart-поле, или конвертация может превышать тайм-ауты proxy. Сначала выполните сквозную проверку: отправьте HTML и ресурсы как multipart-данные, сформируйте PDF, повторите операцию с документом Office и после каждой конвертации проверьте health endpoint.
Эта проверка соответствует заявленному назначению Gotenberg: HTTP-сервису, который конвертирует HTML, Markdown и файлы Office в PDF. Кроме того, она раньше, чем проверка доступности, выявляет отсутствующие зависимости, неверные предположения о proxy и эфемерные данные.
Порты, процессы и внутренние сервисы
Не позволяйте образу Gotenberg случайно определять архитектуру production-среды. Образ запускает процесс на порту 3000, но для хранилища, маршрутизации и внешних зависимостей по-прежнему нужно явно определить жизненный цикл. Локальное требование среды выполнения — запас CPU и памяти для worker-процессов Chromium и LibreOffice. Проверьте этот предел до публикации сервиса и повторно после замены контейнера.
Развертывание готово к углубленному тестированию, когда оно может отправить HTML и ресурсы как multipart-данные, сформировать PDF, повторить операцию с документом Office и после каждой конвертации проверить health endpoint. Отслеживайте транзакцию в логах и контролируйте количество процессов Chromium и LibreOffice, временное дисковое пространство, сложность документов и тайм-ауты proxy. Эти наблюдения показывают, изолирует ли текущая топология нужный компонент.
Сделайте восстановление Gotenberg измеримым
В стандартном образе Gotenberg не предполагается наличие доступного для записи состояния приложения. Не сохраняйте постоянные данные приложения; вместо резервного копирования пустой файловой системы контейнера сохраняйте шрифты, шаблоны и конфигурацию развертывания, включая зафиксированный digest и проверенную конфигурацию маршрутов.
Создайте Gotenberg с нуля на другом хосте и убедитесь, что пользовательские шрифты, шаблоны и флаги команд воспроизводимы, а известные документы отображаются с ожидаемым числом страниц. Если добавляется отдельная база данных, room server или слой аутентификации, назначьте для этого компонента отдельного ответственного за восстановление. В руководстве по переходу от Git к production показано, как воспроизводимый артефакт заменяет резервную копию контейнера.
Зафиксируйте команду пересоздания и тест ожидаемого результата вместе с релизом. План восстановления без сохранения состояния успешен, если позволяет воспроизвести поведение из доверенных входных данных; он не должен зависеть от копирования непрозрачного работающего контейнера.
Сократите полномочия Gotenberg
Ценный актив в Gotenberg — это путь обработки пользовательского ввода. Специфический для приложения риск заключается в разрешении неограниченной публичной конвертации без ограничений на размер и тайм-ауты; в production-среде конечные точки конвертации должны оставаться приватными либо перед приемом недоверенных файлов необходимо применять ограничения размера, частоты запросов и времени ожидания.
В стандартном контейнере нет секрета администратора, поэтому аутентификацию следует реализовать на HTTPS-маршруте, если сервис приватный. Зафиксируйте сборку, избегайте широких монтирований файловой системы и ограничьте количество процессов Chromium и LibreOffice, временное дисковое пространство, сложность документов и тайм-ауты proxy. Используйте известные тестовые входные данные, чтобы после каждого обновления убедиться, что развернутая сборка формирует ожидаемый результат.
Критерии выпуска Gotenberg
Превратите smoke-тест Gotenberg в повторяемую команду релиза или короткий runbook. Его результат должен подтверждать следующее: HTML и ресурсы отправляются как multipart-данные, формируется PDF, операция повторяется с документом Office, а после каждой конвертации проверяется health endpoint. Вместе с результатом сохраняйте версию приложения, digest контейнера, hostname маршрута и идентификатор тестовых данных.
Выполняйте эту же проверку после обычной замены контейнера и после восстановления без постоянных данных приложения; шрифты, шаблоны и конфигурацию развертывания храните отдельно. Восстановление считается успешным, если пользовательские шрифты, шаблоны и флаги команд воспроизводимы, а известные документы отображаются с ожидаемым числом страниц. Сравнивайте время выполнения и потребление ресурсов с учетом количества процессов Chromium и LibreOffice, временного дискового пространства, сложности документов и тайм-аутов proxy; существенное изменение требует расследования, даже если итоговая операция по-прежнему завершается успешно.
Затем выполните безопасный сценарий сбоя: отправьте безвредные входные данные, близкие к ограничению ресурсов или формата, связанному с этой границей: запросы используют неправильное multipart-поле или конвертация превышает тайм-ауты proxy. Убедитесь, что Gotenberg сообщает об ошибке и возвращается к нормальной работе без разрушительных ручных изменений. Сохраните только необходимый фрагмент лога с удаленными чувствительными данными. Эти четыре части проверки охватывают запуск, сохранение данных, восстановление и обработку сбоев.
Сделайте запуск Gotenberg воспроизводимым
Используйте команду, в которой явно указаны все важные параметры. Этот базовый вариант привязывает Gotenberg к loopback-интерфейсу хоста, добавляет известные монтирования данных и передает первую обязательную настройку. Перед публикацией сервиса проверьте локальное требование: запас CPU и памяти для worker-процессов Chromium и LibreOffice.
docker run -d \
--name gotenberg \
--restart unless-stopped \
-p 127.0.0.1:3000:3000 \
gotenberg/gotenberg:8
Замените плавающие теги на протестированную версию или digest. После запуска проверьте docker logs --tail 200 gotenberg и убедитесь, что процесс слушает порт 3000. Затем выполните приемочный сценарий Gotenberg; ответ корневой страницы не доказывает успешность всего сценария: отправьте HTML и ресурсы как multipart-данные, сформируйте PDF, повторите операцию с документом Office и после каждой конвертации проверьте health endpoint.
Не позволяйте успешному ответу proxy скрывать сбой приложения
Выберите окончательный hostname Gotenberg до того, как пользователи сохранят callback-адреса или настройки клиентов, затем предоставьте API конвертации через HTTPS или приватный внутренний домен. Маршрут платформы должен один раз завершать TLS и направлять запросы на приватный порт 3000.
Выполните приемочную транзакцию извне. Если клиент не достигает Gotenberg, воспользуйтесь чек-листом проверки SSL для проверки DNS и сертификата. Если запрос достигает Gotenberg, но использует неправильное multipart-поле или конвертация превышает тайм-ауты proxy, прекратите менять перенаправления proxy и проверьте границу приложения, связанную с конкретным сценарием.
Проверка производительности и обновления
Полезный индикатор состояния Gotenberg — успешное выполнение сценария «отправить HTML и ресурсы как multipart-данные, сформировать PDF, повторить операцию с документом Office и после каждой конвертации проверить health endpoint». Сопоставляйте этот результат с количеством процессов Chromium и LibreOffice, временным дисковым пространством, сложностью документов и тайм-аутами proxy; зеленая корневая страница ничего не говорит о совместимости результата или исчерпании ресурсов.
Перед заменой образа учтите следующий риск: API-маршруты, флаги Chromium и поведение LibreOffice могут измениться между мажорными версиями Gotenberg. Проверьте типовые и граничные входные данные на обеих версиях и сохраняйте старый digest, пока кандидат не пройдет проверку. Если запросы используют неправильное multipart-поле или конвертация превышает тайм-ауты proxy, проверьте формат запроса, поведение клиента и runtime-логи, прежде чем менять настройки маршрута или хранилища.
Как Dockup упрощает работу с Gotenberg
Шаблон Gotenberg с запуском в один клик должен содержать digest образа, порт 3000, параметры проверки состояния, домен и TLS. Поскольку базовый сервис не хранит состояние, Dockup может напрямую пересоздать его на вычислительных ресурсах Dockup или подключенной машине, не выдавая пустой volume за резервную копию.
После запуска откройте API конвертации через HTTPS или приватный внутренний домен. Dockup должен сохранять настройки среды выполнения Gotenberg, пока оператор проверяет локальное требование: запас CPU и памяти для worker-процессов Chromium и LibreOffice. Проверьте следующий результат: HTML и ресурсы отправляются как multipart-данные, формируется PDF, операция повторяется с документом Office, а после каждой конвертации проверяется health endpoint. Любое последующее расширение с хранением состояния должно объявить собственное монтирование, секрет и тест восстановления, не меняя молча смысл базового шаблона.
Часто задаваемые вопросы
Что требуется Gotenberg для production-развертывания?
Направьте контейнер Gotenberg через порт 3000 из одного HTTPS-источника. Локальное требование среды выполнения — запас CPU и памяти для worker-процессов Chromium и LibreOffice. Не объявляйте Gotenberg готовым, пока не сможете отправить HTML и ресурсы как multipart-данные, сформировать PDF, повторить операцию с документом Office и после каждой конвертации проверить health endpoint.
Какие данные Gotenberg нужно включать в резервную копию?
В стандартном образе Gotenberg нет обязательного монтирования данных приложения. Сохраняйте конфигурацию развертывания и отдельно создавайте резервные копии подключенного состояния; восстановление считается успешным, если пользовательские шрифты, шаблоны и флаги команд воспроизводимы, а известные документы отображаются с ожидаемым числом страниц.
Требуется ли Gotenberg HTTPS за reverse proxy?
Используйте HTTPS для публичного источника Gotenberg и оставьте порт 3000 во внутреннем маршруте. Корректно применяйте настройку Gotenberg: открывайте API конвертации через HTTPS или приватный внутренний домен. Для Gotenberg HTTPS защищает учетные данные или пользовательское содержимое при передаче и обеспечивает единообразное поведение клиентов, зависящее от источника.
Как тестировать обновление Gotenberg?
Разверните кандидатную версию образа Gotenberg рядом с текущей и повторите приемочную транзакцию с известными входными данными. Уделите особое внимание тому, что API-маршруты, флаги Chromium и поведение LibreOffice могут измениться между мажорными версиями Gotenberg. В стандартном контейнере нет миграции данных, поэтому сохраняйте предыдущий digest, пока проверки результата и совместимости не будут пройдены.