Как да хоствате самостоятелно Gotenberg през 2026 г.: HTML към PDF, таймаути и шрифтове

Неуспешното разполагане на Gotenberg невинаги води до срив. Възможно е услугата да показва login страница, докато заявките използват грешното multipart поле, или конверсиите да надхвърлят таймаутите на proxy. Вместо това започнете с цялостна проверка: изпратете HTML и assets като multipart данни, генерирайте PDF, повторете с Office документ и проверявайте health endpoint след всяка конверсия.

Тази проверка съответства на описаното предназначение на Gotenberg: HTTP услуга, която конвертира HTML, Markdown и Office файлове в PDF. Тя също така разкрива липсващи зависимости, грешни предположения за proxy и временни данни по-рано, отколкото може да го направи проверка за uptime.

Портове, процеси и частни услуги

Не позволявайте на Gotenberg image да определи production архитектурата случайно. Image-ът предоставя процес на порт 3000, но lifecycle-ът на storage, routing-а и външните изисквания все още трябва да бъде планиран целенасочено. Локалното изискване за runtime е достатъчен CPU и memory headroom за worker-ите на Chromium и LibreOffice. Тествайте тази граница преди публикуване и отново след подмяна на container.

Разполагането е готово за по-задълбочено тестване, когато може да изпраща HTML и assets като multipart данни, да генерира PDF, да повтори с Office документ и да проверява health endpoint след всяка конверсия. Следете transaction-а в log-овете и наблюдавайте броя процеси на Chromium и LibreOffice, временния disk, сложността на документите и proxy timeout-ите. Тези наблюдения показват дали текущата topology изолира правилния компонент.

Направете възстановяването на Gotenberg измеримо

В стандартния Gotenberg image не се очаква да има записваемо application state. Не съхранявайте durable app data; запазвайте fonts, templates и deployment configuration, включително pinned digest-а и прегледаната route configuration, вместо да архивирате празната filesystem на container-а.

Създайте Gotenberg от нулата на друг host и проверете дали custom fonts, templates и command flags могат да бъдат възпроизведени и дали известни документи се генерират с очаквания брой страници. Ако добавите отделна database, room server или authentication layer, определете за всеки компонент отделен отговорник за възстановяването. Ръководството от Git до production показва как възпроизводим artifact заменя backup на container.

Запишете командата за rebuild и теста с очакван резултат заедно с release-а. Stateless recovery plan-ът работи чрез възпроизвеждане на поведението от надеждни входни данни; той не трябва да зависи от копирането на непрозрачен работещ container.

Ограничете правомощията на Gotenberg

Ценният asset в Gotenberg е code path-ът, който обработва потребителски вход. Специфичният за приложението риск е да се позволят неограничени публични конверсии без контроли за размер и timeout; в production endpoint-ите за конверсия трябва да останат private или преди приемането на непроверени файлове да се наложат ограничения за размер, rate и timeout.

Стандартният container няма administrator secret, затова authentication-ът трябва да бъде поставен на HTTPS route-а, ако услугата е private. Pin-нете build-а, избягвайте широки filesystem mounts и ограничете броя процеси на Chromium и LibreOffice, временния disk, сложността на документите и proxy timeout-ите. Използвайте известни test inputs, за да потвърдите, че обслужваният build генерира очаквания резултат след всяка актуализация.

Gate за release на Gotenberg

Превърнете smoke теста на Gotenberg в повторяема release команда или кратък runbook. Резултатът му трябва да демонстрира следния outcome: изпратете HTML и assets като multipart данни, генерирайте PDF, повторете с Office документ и проверете health endpoint след всяка конверсия. Запишете application version, container digest, route hostname и идентификатора на test data заедно с резултата.

Изпълнете същата проверка след стандартна подмяна на container и след възстановяване без durable app data; съхранявайте fonts, templates и deployment configuration на друго място. Възстановяването е успешно, когато custom fonts, templates и command flags могат да бъдат възпроизведени и известни документи се генерират с очаквания брой страници. Сравнете времето и потреблението, свързани с броя процеси на Chromium и LibreOffice, временния disk, сложността на документите и proxy timeout-ите; значителна промяна заслужава проверка, дори когато крайното действие все още преминава успешно.

След това изпълнете безопасен failure тест: изпратете безвреден input близо до resource или format limit-а, свързан с тази граница: заявките използват грешното multipart поле или конверсиите надхвърлят proxy timeout-ите. Потвърдете, че Gotenberg показва грешката и се връща към нормална работа без destructive ръчни промени. Запазете само необходимия, редактиран откъс от log-а. Този gate от четири части обхваща startup, persistence, recovery и failure handling.

Направете стартирането на Gotenberg възпроизводимо

Използвайте команда, която показва всеки важен избор. Тази baseline конфигурация свързва Gotenberg към loopback интерфейса на host-а, добавя известните data mounts и подава първата необходима настройка. Потвърдете локалното изискване преди експониране: достатъчен CPU и memory headroom за worker-ите на Chromium и LibreOffice.

docker run -d \
  --name gotenberg \
  --restart unless-stopped \
  -p 127.0.0.1:3000:3000 \
  gotenberg/gotenberg:8

Заменете floating tags с тествана версия или digest. След стартирането проверете docker logs --tail 200 gotenberg и потвърдете, че процесът слуша на порт 3000. След това изпълнете acceptance action-а на Gotenberg; отговор от root page не може да докаже, че целият сценарий работи успешно: изпратете HTML и assets като multipart данни, генерирайте PDF, повторете с Office документ и проверете health endpoint след всяка конверсия.

Не позволявайте на успешния proxy да прикрива грешка в приложението

Изберете крайния hostname на Gotenberg, преди потребителите да запазят callbacks или client settings, след което предоставете conversion API чрез HTTPS или private internal domain. Platform route-ът трябва да прекратява TLS веднъж и да насочва към private порт 3000.

Изпълнете acceptance transaction-а externally. Ако client-ът изобщо не достига до Gotenberg, използвайте чеклиста за проверка на SSL за DNS и certificate проверки. Ако заявката достига до Gotenberg, но използва грешното multipart поле или конверсиите надхвърлят proxy timeout-ите, спрете да променяте proxy redirects и проверете application-specific границата.

Проверки за капацитет и upgrade

Полезният service indicator за Gotenberg е успешното изпълнение на „изпратете HTML и assets като multipart данни, генерирайте PDF, повторете с Office документ и проверете health endpoint след всяка конверсия“. Съчетайте този резултат с броя процеси на Chromium и LibreOffice, временния disk, сложността на документите и proxy timeout-ите; зелена root page не казва нищо за съвместимостта на output-а или изчерпването на ресурсите.

Преди да замените image-а, отчетете следния риск: API routes, Chromium flags и поведението на LibreOffice може да се променят между major версиите на Gotenberg. Тествайте representative и boundary inputs и с двете версии и запазете стария digest, докато candidate-ът не премине проверките. Ако заявките използват грешното multipart поле или конверсиите надхвърлят proxy timeout-ите, проверете request format-а, client behavior-а и runtime log-овете, преди да променяте настройките за route или storage.

Как Dockup спестява работа с Gotenberg

One-click template за Gotenberg трябва да задава image digest-а, порт 3000, health timing-а, domain-а и TLS. Тъй като базовата услуга е stateless, Dockup може да я пресъздаде директно върху Dockup compute или свързана машина, без да представя празен volume като backup.

След стартирането предоставете conversion API чрез HTTPS или private internal domain. Dockup трябва да запази runtime settings на Gotenberg, докато операторът потвърди това локално изискване: достатъчен CPU и memory headroom за worker-ите на Chromium и LibreOffice. Проверете следния outcome: изпратете HTML и assets като multipart данни, генерирайте PDF, повторете с Office документ и проверете health endpoint след всяка конверсия. Всяко последващо stateful разширение трябва да декларира собствен mount, secret и restore test, вместо тихомълком да променя смисъла на базовия template.

Често задавани въпроси

Какво е необходимо на Gotenberg за production deployment?

Насочете Gotenberg container-а на порт 3000 през един HTTPS origin. Локалното изискване за runtime е достатъчен CPU и memory headroom за worker-ите на Chromium и LibreOffice. Не обявявайте Gotenberg за готов, докато не можете да изпратите HTML и assets като multipart данни, да генерирате PDF, да повторите с Office документ и да проверите health endpoint след всяка конверсия.

Кои данни на Gotenberg трябва да бъдат включени в backup?

Стандартният Gotenberg image няма задължителен application-data mount. Запазете deployment configuration-а му и архивирайте свързаното state отделно; recovery-ят е успешен, когато custom fonts, templates и command flags могат да бъдат възпроизведени и известни документи се генерират с очаквания брой страници.

Изисква ли Gotenberg HTTPS зад reverse proxy?

Използвайте HTTPS за публичния Gotenberg origin и запазете порт 3000 във вътрешния route. Приложете настройката на Gotenberg правилно: предоставете conversion API чрез HTTPS или private internal domain. При Gotenberg HTTPS защитава credentials или потребителско съдържание при пренос и поддържа последователно поведение на client-а, зависещо от origin-а.

Как трябва да се тества upgrade на Gotenberg?

Разположете candidate Gotenberg image-а до текущия и повторете acceptance transaction-а с известен input. Обърнете особено внимание, тъй като API routes, Chromium flags и поведението на LibreOffice може да се променят между major версиите на Gotenberg. Стандартният container няма data migration, затова запазете предишния digest, докато проверките за output и compatibility не преминат успешно.