Як розгорнути Gotenberg на власному хостингу у 2026 році: HTML у PDF, тайм-аути та шрифти
Розгорніть Gotenberg із правильним портом, надійним сховищем, TLS, автентифікацією та резервними копіями. Дізнайтеся, як усунути проблеми, коли запити використовують неправильне multipart-поле у production.
Невдале розгортання Gotenberg не завжди призводить до аварійного завершення. Сервіс може віддавати сторінку входу, коли запити використовують неправильне multipart-поле, або конвертація перевищує тайм-аути проксі. Натомість спочатку виконайте наскрізну перевірку: надішліть HTML і ресурси як multipart-дані, згенеруйте PDF, повторіть операцію з документом Office і після кожної конвертації перевірте health endpoint.
Ця перевірка відповідає задокументованому призначенню Gotenberg: це HTTP-сервіс, який конвертує HTML, Markdown і файли Office у PDF. Вона також раніше виявляє відсутні залежності, неправильні припущення щодо проксі та ефемерні дані, ніж це може зробити перевірка доступності.
Порти, процеси та приватні сервіси
Не дозволяйте образу Gotenberg випадково визначати production-архітектуру. Образ запускає процес на порту 3000, але для сховища, маршрутизації та зовнішніх вимог усе одно потрібно свідомо визначити життєві цикли. Локальна вимога середовища виконання — запас CPU і пам’яті для воркерів Chromium і LibreOffice. Перевірте цю межу до публікації сервісу та повторно після заміни контейнера.
Розгортання готове до глибшого тестування, коли воно може надсилати HTML і ресурси як multipart-дані, генерувати PDF, повторювати операцію з документом Office і після кожної конвертації перевіряти health endpoint. Відстежуйте транзакцію в логах і контролюйте кількість процесів Chromium і LibreOffice, тимчасовий диск, складність документів і тайм-аути проксі. Ці спостереження покажуть, чи поточна топологія ізолює потрібний компонент.
Зробіть відновлення Gotenberg вимірюваним
У стандартному образі Gotenberg не передбачається записування стану застосунку. Не зберігайте постійні дані застосунку; натомість зберігайте шрифти, шаблони та конфігурацію розгортання, зокрема зафіксований digest і перевірену конфігурацію маршрутів, а не резервну копію порожньої файлової системи контейнера.
Створіть Gotenberg з нуля на іншому хості та перевірте, що користувацькі шрифти, шаблони й прапорці командного рядка можна відтворити, а відомі документи відображаються з очікуваною кількістю сторінок. Якщо додано окрему базу даних, room server або шар автентифікації, призначте для цього компонента окремого відповідального за відновлення. У посібнику від Git-репозиторію до production-розгортання показано, як відтворюваний артефакт замінює резервну копію контейнера.
Додавайте команду перебудови та тест із відомим результатом до релізу. План відновлення без збереження стану успішний, якщо поведінку можна відтворити з надійних вхідних даних; він не має залежати від копіювання непрозорого запущеного контейнера.
Зменште повноваження Gotenberg
Цінний актив у Gotenberg — це кодовий шлях, який обробляє введені користувачем дані. Специфічний для застосунку ризик полягає в тому, що необмежена публічна конвертація дозволяє надсилати файли без контролю розміру й часу очікування; у production кінцеві точки конвертації мають бути приватними або перед прийманням ненадійних файлів слід застосувати обмеження розміру, частоти запитів і часу очікування.
Стандартний контейнер не має секрету адміністратора, тому автентифікацію слід реалізувати на HTTPS-маршруті, якщо сервіс приватний. Зафіксуйте build, уникайте широких монтувань файлової системи та обмежте кількість процесів Chromium і LibreOffice, тимчасовий диск, складність документів і тайм-аути проксі. Використовуйте відомі тестові дані, щоб після кожного оновлення підтверджувати, що запущений build створює очікуваний результат.
Критерії випуску Gotenberg
Перетворіть smoke test Gotenberg на повторювану команду для релізу або короткий runbook. Його результат має підтверджувати такий сценарій: надіслати HTML і ресурси як multipart-дані, згенерувати PDF, повторити операцію з документом Office і після кожної конвертації перевірити health endpoint. Додавайте до результату версію застосунку, digest контейнера, hostname маршруту та ідентифікатор тестових даних.
Виконуйте ту саму перевірку після звичайної заміни контейнера та після відновлення без постійних даних застосунку; зберігайте шрифти, шаблони й конфігурацію розгортання в іншому місці. Відновлення успішне, коли користувацькі шрифти, шаблони й прапорці командного рядка можна відтворити, а відомі документи відображаються з очікуваною кількістю сторінок. Порівнюйте час і споживання ресурсів, пов’язані з кількістю процесів Chromium і LibreOffice, тимчасовим диском, складністю документів і тайм-аутами проксі; суттєва зміна потребує перевірки, навіть якщо підсумкова дія все ще завершується успішно.
Потім виконайте безпечний сценарій відмови: надішліть нешкідливі дані, близькі до обмеження ресурсу або формату, пов’язаного з цією межею: запити використовують неправильне multipart-поле або конвертація перевищує тайм-аути проксі. Переконайтеся, що Gotenberg повідомляє про помилку й повертається до нормальної роботи без ручних руйнівних змін. Збережіть лише необхідний, відредагований фрагмент логу. Ці чотири частини охоплюють запуск, збереження даних, відновлення та обробку відмов.
Зробіть запуск Gotenberg відтворюваним
Використовуйте команду, яка явно задає всі важливі параметри. Цей базовий варіант прив’язує Gotenberg до loopback-інтерфейсу хоста, додає відомі монтування даних і передає перше обов’язкове налаштування. Перед відкриттям доступу перевірте локальну вимогу: запас CPU і пам’яті для воркерів 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.
Не дозволяйте успішній відповіді проксі приховати збій застосунку
Визначте кінцевий hostname Gotenberg до того, як користувачі збережуть callback-и або налаштування клієнта, а потім відкрийте API конвертації через HTTPS або приватний внутрішній домен. Маршрут платформи має один раз завершувати TLS і спрямовувати трафік на приватний порт 3000.
Запускайте приймальну транзакцію ззовні. Якщо клієнт не доходить до Gotenberg, скористайтеся контрольним списком перевірки SSL для перевірки DNS і сертифіката. Якщо запит доходить до Gotenberg, але використовує неправильне multipart-поле або конвертація перевищує тайм-аути проксі, припиніть змінювати перенаправлення проксі та перевірте специфічну для застосунку межу.
Перевірки місткості та оновлення
Корисний індикатор стану Gotenberg — успішне виконання сценарію «надіслати HTML і ресурси як multipart-дані, згенерувати PDF, повторити операцію з документом Office і після кожної конвертації перевірити health endpoint». Поєднуйте цей результат із кількістю процесів Chromium і LibreOffice, станом тимчасового диска, складністю документів і тайм-аутами проксі; зелена коренева сторінка нічого не говорить про сумісність результату чи вичерпання ресурсів.
Перед заміною образу врахуйте такий ризик: маршрути API, прапорці Chromium і поведінка LibreOffice можуть змінюватися між основними версіями Gotenberg. Перевірте типові та граничні вхідні дані в обох версіях і зберігайте старий digest, доки кандидат не пройде перевірку. Якщо запити використовують неправильне multipart-поле або конвертація перевищує тайм-аути проксі, перевірте формат запиту, поведінку клієнта й runtime-логи, перш ніж змінювати налаштування маршруту або сховища.
Як Dockup спрощує роботу з Gotenberg
Шаблон Gotenberg для запуску в один клік має містити digest образу, порт 3000, час очікування health check, домен і TLS. Оскільки базовий сервіс не зберігає стан, Dockup може безпосередньо відтворити його на обчислювальних ресурсах Dockup або під’єднаній машині, не видаючи порожній volume за резервну копію.
Після запуску відкрийте API конвертації через HTTPS або приватний внутрішній домен. Dockup має зберігати налаштування середовища виконання Gotenberg, поки оператор перевіряє локальну вимогу: запас CPU і пам’яті для воркерів Chromium і LibreOffice. Перевірте цей результат: надішліть HTML і ресурси як multipart-дані, згенеруйте PDF, повторіть операцію з документом Office і після кожної конвертації перевірте health endpoint. Будь-яке подальше розширення зі збереженням стану має окремо визначати власне монтування, секрет і тест відновлення, а не непомітно змінювати призначення базового шаблону.
Поширені запитання
Що потрібно Gotenberg для production-розгортання?
Спрямуйте контейнер Gotenberg на порту 3000 через один HTTPS origin. Локальна вимога середовища виконання — запас CPU і пам’яті для воркерів Chromium і LibreOffice. Не вважайте Gotenberg готовим, доки не зможете надіслати HTML і ресурси як multipart-дані, згенерувати PDF, повторити операцію з документом Office і після кожної конвертації перевірити health endpoint.
Які дані Gotenberg потрібно включати до резервної копії?
Стандартний образ Gotenberg не має обов’язкового монтування даних застосунку. Зберігайте його конфігурацію розгортання, а під’єднаний стан резервуйте окремо; відновлення пройдено, коли користувацькі шрифти, шаблони й прапорці командного рядка можна відтворити, а відомі документи відображаються з очікуваною кількістю сторінок.
Чи потрібен Gotenberg HTTPS за reverse proxy?
Використовуйте HTTPS для публічного origin Gotenberg, а порт 3000 залишайте у внутрішньому маршруті. Правильно застосуйте налаштування Gotenberg: відкрийте API конвертації через HTTPS або приватний внутрішній домен. Для Gotenberg HTTPS захищає облікові дані або вміст користувачів під час передавання та забезпечує узгоджену поведінку клієнта, чутливу до origin.
Як тестувати оновлення Gotenberg?
Розгорніть кандидат-образ Gotenberg поруч із поточним і повторіть приймальну транзакцію з відомими вхідними даними. Будьте особливо уважні, оскільки маршрути API, прапорці Chromium і поведінка LibreOffice можуть змінюватися між основними версіями Gotenberg. Стандартний контейнер не має міграції даних, тому зберігайте попередній digest, доки перевірки результату й сумісності не буде пройдено.