Jak hostować Gotenberg samodzielnie w 2026 roku: HTML do PDF, timeouty i fonty

Nieudane wdrożenie Gotenberg nie zawsze kończy się awarią. Usługa może wyświetlać stronę logowania, gdy żądania używają nieprawidłowego pola multipart, albo konwersje mogą przekraczać timeouty proxy. Zamiast tego zacznij od testu end-to-end: wyślij HTML i assety jako dane multipart, wygeneruj PDF, powtórz test z dokumentem Office i po każdej konwersji sprawdź endpoint health.

Ten test odpowiada katalogowemu przeznaczeniu Gotenberg: jest to usługa HTTP, która konwertuje HTML, Markdown i pliki Office do PDF. Ujawnia też brakujące zależności, błędne założenia dotyczące proxy oraz efemeryczne dane wcześniej niż test dostępności.

Porty, procesy i prywatne usługi

Nie pozwól, aby obraz Gotenberg przypadkowo narzucił architekturę produkcyjną. Obraz udostępnia proces na porcie 3000, ale storage, routing i wymagania zewnętrzne nadal wymagają przemyślanych cykli życia. Lokalne wymaganie runtime’u to zapas CPU i pamięci dla workerów Chromium i LibreOffice. Przetestuj tę granicę przed publikacją oraz ponownie po wymianie kontenera.

Wdrożenie jest gotowe do dokładniejszych testów, gdy może wysłać HTML i assety jako dane multipart, wygenerować PDF, powtórzyć test z dokumentem Office i po każdej konwersji sprawdzić endpoint health. Śledź transakcję w logach i obserwuj liczbę procesów Chromium i LibreOffice, dysk tymczasowy, złożoność dokumentów oraz timeouty proxy. Te obserwacje pokażą, czy obecna topologia izoluje właściwy komponent.

Spraw, aby odzyskiwanie Gotenberg było mierzalne

W standardowym obrazie Gotenberg nie zakłada się zapisywalnego stanu aplikacji. Nie zachowuj trwałych danych aplikacji; przechowuj fonty, szablony i konfigurację wdrożenia, w tym przypięty digest i zweryfikowaną konfigurację routingu, zamiast wykonywać backup pustego systemu plików kontenera.

Utwórz Gotenberg od zera na innym hoście i sprawdź, czy własne fonty, szablony i flagi poleceń można odtworzyć oraz czy znane dokumenty są renderowane z oczekiwaną liczbą stron. Jeśli zostanie dodana osobna baza danych, serwer room lub warstwa uwierzytelniania, przypisz temu komponentowi odrębnego właściciela procesu odtwarzania. Przewodnik od repozytorium Git do produkcji pokazuje, jak odtwarzalny artefakt zastępuje backup kontenera.

Dołącz do release’u polecenie odbudowy i test oczekiwanego wyniku. Plan odzyskiwania bez stanu odnosi sukces, gdy odtwarza działanie na podstawie zaufanych danych wejściowych; nie powinien zależeć od kopiowania nieprzejrzystego, działającego kontenera.

Ogranicz uprawnienia Gotenberg

Najcenniejszym zasobem w Gotenberg jest ścieżka kodu obsługująca dane wejściowe użytkownika. Ryzyko charakterystyczne dla tej aplikacji polega na umożliwieniu nieograniczonych publicznych konwersji bez kontroli rozmiaru i timeoutów; na produkcji endpointy konwersji powinny pozostać prywatne albo przed przyjęciem niezaufanych plików należy wymusić limity rozmiaru, rate i timeoutów.

Standardowy kontener nie ma sekretu administratora, dlatego uwierzytelnianie należy skonfigurować na trasie HTTPS, jeśli usługa jest prywatna. Przypnij build, unikaj szerokich mountów systemu plików i ogranicz liczbę procesów Chromium i LibreOffice, dysk tymczasowy, złożoność dokumentów oraz timeouty proxy. Użyj znanych danych testowych, aby po każdej aktualizacji potwierdzić, że udostępniony build generuje oczekiwany wynik.

Bramka wydania Gotenberg

Przekształć smoke test Gotenberg w powtarzalne polecenie release’u albo krótką runbook. Jego wynik musi potwierdzać następujący rezultat: wyślij HTML i assety jako dane multipart, wygeneruj PDF, powtórz test z dokumentem Office i po każdej konwersji sprawdź endpoint health. Dołącz do wyniku wersję aplikacji, digest kontenera, hostname trasy i identyfikator danych testowych.

Uruchom ten sam test po rutynowej wymianie kontenera oraz po odtworzeniu bez trwałych danych aplikacji; fonty, szablony i konfigurację wdrożenia przechowuj w innym miejscu. Odtwarzanie zakończyło się powodzeniem, gdy własne fonty, szablony i flagi poleceń można odtworzyć, a znane dokumenty są renderowane z oczekiwaną liczbą stron. Porównaj czas działania i zużycie związane z liczbą procesów Chromium i LibreOffice, dyskiem tymczasowym, złożonością dokumentów i timeoutami proxy; duża zmiana wymaga analizy, nawet jeśli końcowa akcja nadal się powiedzie.

Następnie przeprowadź bezpieczną awarię: wyślij nieszkodliwe dane wejściowe w pobliżu limitu zasobów lub formatu związanego z tą granicą: żądania używają nieprawidłowego pola multipart albo konwersje przekraczają timeouty proxy. Potwierdź, że Gotenberg zgłasza problem i wraca do normalnego działania bez destrukcyjnych ręcznych zmian. Zachowaj tylko niezbędny, zredagowany fragment logu. Ta czteroczęściowa bramka obejmuje uruchamianie, trwałość, odzyskiwanie i obsługę awarii.

Spraw, aby uruchamianie Gotenberg było odtwarzalne

Użyj polecenia, które ujawnia każdą istotną decyzję. Ta konfiguracja bazowa wiąże Gotenberg z loopbackiem hosta, dodaje znane mounty danych i przekazuje pierwsze wymagane ustawienie. Potwierdź lokalne wymaganie przed udostępnieniem usługi: zapas CPU i pamięci dla workerów Chromium i LibreOffice.

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

Zastąp zmienne tagi przetestowaną wersją albo digestem. Po uruchomieniu sprawdź docker logs --tail 200 gotenberg i potwierdź, że proces nasłuchuje na porcie 3000. Następnie wykonaj akcję akceptacyjną Gotenberg; odpowiedź strony głównej nie dowodzi, że cały scenariusz działa: wyślij HTML i assety jako dane multipart, wygeneruj PDF, powtórz test z dokumentem Office i po każdej konwersji sprawdź endpoint health.

Nie pozwól, aby poprawne działanie proxy maskowało awarię aplikacji

Wybierz docelowy hostname Gotenberg, zanim użytkownicy zapiszą callbacki lub ustawienia klienta, a następnie udostępnij API konwersji przez HTTPS albo prywatną domenę wewnętrzną. Trasa platformy powinna kończyć TLS raz i kierować ruch na prywatny port 3000.

Wykonaj transakcję akceptacyjną z zewnątrz. Jeśli klient nigdy nie dociera do Gotenberg, użyj checklisty walidacji SSL, aby sprawdzić DNS i certyfikat. Jeśli żądanie dociera do Gotenberg, ale używa nieprawidłowego pola multipart albo konwersje przekraczają timeouty proxy, przestań zmieniać przekierowania proxy i sprawdź granicę właściwą dla aplikacji.

Sprawdzanie wydajności i aktualizacji

Przydatnym wskaźnikiem działania Gotenberg jest pomyślne wykonanie operacji „wyślij HTML i assety jako dane multipart, wygeneruj PDF, powtórz test z dokumentem Office i po każdej konwersji sprawdź endpoint health”. Połącz ten wynik z liczbą procesów Chromium i LibreOffice, dyskiem tymczasowym, złożonością dokumentów i timeoutami proxy; zielona strona główna nic nie mówi o zgodności generowanych plików ani wyczerpaniu zasobów.

Przed wymianą obrazu uwzględnij następujące ryzyko: trasy API, flagi Chromium i działanie LibreOffice mogą zmieniać się między głównymi wersjami Gotenberg. Przetestuj reprezentatywne dane wejściowe oraz przypadki graniczne w obu wersjach i zachowaj stary digest do czasu przejścia testów przez kandydata. Jeśli żądania używają nieprawidłowego pola multipart albo konwersje przekraczają timeouty proxy, sprawdź format żądania, działanie klienta i logi runtime’u, zanim zmienisz ustawienia trasy lub storage’u.

Gdzie Dockup ogranicza nakład pracy związany z Gotenberg

Jednoklikowy template Gotenberg powinien definiować digest obrazu, port 3000, czas oczekiwania health check, domenę i TLS. Ponieważ usługa bazowa jest bezstanowa, Dockup może odtworzyć ją bezpośrednio na compute Dockup albo na podłączonej maszynie, bez udawania, że pusty volume jest backupem.

Po uruchomieniu udostępnij API konwersji przez HTTPS albo prywatną domenę wewnętrzną. Dockup powinien zachować ustawienia runtime’u Gotenberg, a operator potwierdzić następujące lokalne wymaganie: zapas CPU i pamięci dla workerów Chromium i LibreOffice. Zweryfikuj ten rezultat: wyślij HTML i assety jako dane multipart, wygeneruj PDF, powtórz test z dokumentem Office i po każdej konwersji sprawdź endpoint health. Każde późniejsze rozszerzenie stanowe musi deklarować własny mount, sekret i test odtwarzania, zamiast po cichu zmieniać znaczenie bazowego template’u.

Najczęściej zadawane pytania

Czego Gotenberg potrzebuje w środowisku produkcyjnym?

Skieruj kontener Gotenberg na port 3000 przez jedno źródło HTTPS. Lokalne wymaganie runtime’u to zapas CPU i pamięci dla workerów Chromium i LibreOffice. Nie uznawaj Gotenberg za gotowy, dopóki nie możesz wysłać HTML i assetów jako danych multipart, wygenerować PDF, powtórzyć testu z dokumentem Office i po każdej konwersji sprawdzić endpoint health.

Które dane Gotenberg powinny znaleźć się w backupie?

Standardowy obraz Gotenberg nie ma wymaganego mountu danych aplikacji. Zachowaj jego konfigurację wdrożenia i wykonuj backup podłączonego stanu osobno; odzyskiwanie kończy się powodzeniem, gdy własne fonty, szablony i flagi poleceń można odtworzyć, a znane dokumenty są renderowane z oczekiwaną liczbą stron.

Czy Gotenberg wymaga HTTPS za reverse proxy?

Użyj HTTPS dla publicznego źródła Gotenberg i pozostaw port 3000 na trasie wewnętrznej. Zastosuj ustawienie Gotenberg poprawnie: udostępnij API konwersji przez HTTPS albo prywatną domenę wewnętrzną. W przypadku Gotenberg HTTPS chroni dane uwierzytelniające i treści użytkowników podczas transmisji oraz zapewnia spójne działanie klienta zależne od originu.

Jak testować aktualizację Gotenberg?

Wdróż kandydujący obraz Gotenberg obok obecnego i powtórz transakcję akceptacyjną ze znanymi danymi wejściowymi. Zwróć szczególną uwagę na to, że trasy API, flagi Chromium i działanie LibreOffice mogą zmieniać się między głównymi wersjami Gotenberg. Standardowy kontener nie ma migracji danych, dlatego zachowaj poprzedni digest do czasu przejścia testów wyniku i zgodności.