A Gotenberg saját üzemeltetése 2026-ban: HTML–PDF konvertálás, időkorlátok és betűkészletek

Egy hibás Gotenberg-telepítés nem mindig áll le. Előfordulhat, hogy bejelentkezési oldalt szolgál ki, miközben a kérések hibás multipart mezőt használnak, vagy a konvertálások túllépik a proxyk időkorlátait. Ehelyett kezdd teljes körű ellenőrzéssel: küldj HTML-t és asseteket multipart adatként, állíts elő egy PDF-et, ismételd meg a műveletet egy Office-dokumentummal, majd minden konvertálás után ellenőrizd a health endpointot.

Ez az ellenőrzés megfelel a Gotenberg dokumentált céljának: HTTP-szolgáltatás, amely HTML-, Markdown- és Office-fájlokat PDF-fé konvertál. A hiányzó függőségeket, a hibás proxyfeltételezéseket és az ideiglenes adatokat is hamarabb felfedi, mint egy uptime-ellenőrzés.

Portok, folyamatok és privát szolgáltatások

Ne hagyd, hogy a Gotenberg image véletlenül meghatározza az éles architektúrát. Az image egy 3000-es porton futó folyamatot biztosít; a tárolásnak, az útválasztásnak és a külső követelményeknek azonban továbbra is tudatosan kialakított életciklusra van szükségük. A helyi futtatási követelmény a Chromium- és LibreOffice-workerek számára biztosított CPU- és memóriatartalék. A publikálás előtt, majd minden konténercsere után ismét ellenőrizd ezt a határt.

A telepítés akkor áll készen az alaposabb tesztelésre, amikor képes HTML-t és asseteket multipart adatként fogadni, PDF-et előállítani, egy Office-dokumentummal megismételni a műveletet, majd minden konvertálás után ellenőrizni a health endpointot. Kövesd a tranzakciót a logokban, és figyeld a Chromium- és LibreOffice-folyamatok számát, az ideiglenes lemezhasználatot, a dokumentum összetettségét és a proxyk időkorlátait. Ezek a megfigyelések megmutatják, hogy a jelenlegi topológia a megfelelő komponenst választja-e le.

Tedd mérhetővé a Gotenberg helyreállítását

A standard Gotenberg image-en belül nem várható írható alkalmazásállapot. Ne őrizz tartós alkalmazásadatokat; az üres konténerfájlrendszer mentése helyett a betűkészleteket, sablonokat és a telepítési konfigurációt — beleértve a rögzített digestet és az ellenőrzött route-konfigurációt is — tartsd meg.

Hozd létre a Gotenberget a semmiből egy másik hoston, majd ellenőrizd, hogy az egyéni betűkészletek, sablonok és parancssori kapcsolók reprodukálhatók-e, illetve hogy az ismert dokumentumok a várt oldalszámmal jelennek-e meg. Ha külön adatbázist, room servert vagy hitelesítési réteget adsz hozzá, annak a komponensnek külön, egyértelmű helyreállítási felelőst adj. A Gitből éles környezetbe vezető útmutató bemutatja, hogyan váltja ki egy reprodukálható artifact a konténermentést.

A build paranccsal együtt rögzítsd az újraépítési parancsot és az ismert kimenetet ellenőrző tesztet. Egy állapotmentes helyreállítási terv akkor működik, ha megbízható bemenetekből reprodukálja a működést; nem szabad egy átláthatatlan, futó konténer másolására támaszkodnia.

Csökkentsd a Gotenberg jogosultságait

A Gotenberg értékes eleme a felhasználói bemenetet kezelő kódútvonal. Az alkalmazásspecifikus kockázat az, hogy korlátozás nélkül engedélyezed a nyilvános konvertálásokat méret- és időkorlátok nélkül; éles környezetben a konvertálási végpontokat tartsd privátan, vagy a nem megbízható fájlok engedélyezése előtt alkalmazz méret-, sebesség- és időkorlátokat.

A standard konténer nem tartalmaz adminisztrátori titkot, ezért a hitelesítést a privát szolgáltatás HTTPS-route-ján kell megvalósítani. Rögzítsd a buildet, kerüld a széles körű fájlrendszer-csatolásokat, és korlátozd a Chromium- és LibreOffice-folyamatok számát, az ideiglenes lemezhasználatot, a dokumentumok összetettségét és a proxyk időkorlátait. Ismert tesztbemenettel ellenőrizd, hogy a kiszolgált build minden frissítés után a várt kimenetet állítja elő.

A Gotenberg kiadási ellenőrzőpontja

Alakítsd át a Gotenberg smoke tesztjét reprodukálható kiadási paranccsá vagy rövid runbookká. A kimenetének ezt az eredményt kell bizonyítania: HTML és assetek küldése multipart adatként, PDF előállítása, a művelet megismétlése egy Office-dokumentummal, majd a health endpoint ellenőrzése minden konvertálás után. Az eredménnyel együtt rögzítsd az alkalmazás verzióját, a konténer digestjét, a route hosztnevét és a tesztadatok azonosítóját.

Futtasd le ugyanezt az ellenőrzést egy szokásos konténercsere után, valamint tartós alkalmazásadatok visszaállítása nélkül; a betűkészleteket, sablonokat és a telepítési konfigurációt máshol őrizd meg. A visszaállítás akkor sikeres, ha az egyéni betűkészletek, sablonok és parancssori kapcsolók reprodukálhatók, az ismert dokumentumok pedig a várt oldalszámmal jelennek meg. Hasonlítsd össze a Chromium- és LibreOffice-folyamatok számához, az ideiglenes lemezhasználathoz, a dokumentum összetettségéhez és a proxyk időkorlátaihoz kapcsolódó időzítést és erőforrás-felhasználást; a jelentős eltérés akkor is vizsgálatra érdemes, ha a végső művelet továbbra is sikeres.

Ezután hajts végre egy biztonságos hibatesztet: küldj ártalmatlan bemenetet a következő határhoz kapcsolódó erőforrás- vagy formátumkorlát közelében: a kérések hibás multipart mezőt használnak, vagy a konvertálások túllépik a proxyk időkorlátait. Ellenőrizd, hogy a Gotenberg jelzi-e a hibát, majd destruktív kézi módosítások nélkül visszatér-e a normál működéshez. Csak a szükséges, kitakart logrészletet őrizd meg. Ez a négy részből álló ellenőrzőpont az indítást, a perzisztenciát, a helyreállítást és a hibakezelést fedi le.

Tedd reprodukálhatóvá a Gotenberg indítását

Olyan parancsot használj, amely minden fontos választást láthatóvá tesz. Ez az alapkonfiguráció a Gotenberget a host loopback interfészére köti, hozzáadja az ismert adatcsatolásokat, és megadja az első szükséges beállítást. Kitettség előtt erősítsd meg a helyi követelményt: a Chromium- és LibreOffice-workerek számára biztosított CPU- és memóriatartalék.

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

A változó tageket cseréld tesztelt verzióra vagy digeszt­re. Indítás után tekintsd meg a docker logs --tail 200 gotenberg kimenetét, és erősítsd meg, hogy a folyamat a 3000-es porton figyel. Ezután hajtsd végre a Gotenberg elfogadási műveletét; a gyökéroldal válasza önmagában nem bizonyítja a teljes forgatókönyv sikerét: küldj HTML-t és asseteket multipart adatként, állíts elő egy PDF-et, ismételd meg a műveletet egy Office-dokumentummal, majd minden konvertálás után ellenőrizd a health endpointot.

Ne hagyd, hogy a proxy sikere elfedje az alkalmazás hibáját

Még azelőtt válaszd ki a végleges Gotenberg-hosztnevet, hogy a felhasználók elmentenék a callbackeket vagy a kliensbeállításokat, majd tedd elérhetővé a konvertálási API-t HTTPS-en vagy privát belső domainen keresztül. A platform route-ja egyszer terminálja a TLS-t, majd a privát 3000-es portra továbbít.

Az elfogadási tranzakciót kívülről futtasd. Ha a kliens egyáltalán nem éri el a Gotenberget, használd az SSL-ellenőrzőlistát a DNS- és tanúsítvány-ellenőrzésekhez. Ha a kérés eléri a Gotenberget, de hibás multipart mezőt használ, vagy a konvertálások túllépik a proxyk időkorlátait, ne módosítsd tovább a proxyátirányításokat, hanem az alkalmazásspecifikus határt vizsgáld meg.

Kapacitás- és frissítési ellenőrzések

A Gotenberg hasznos szolgáltatásjelzője a következő művelet sikeres végrehajtása: „HTML és assetek küldése multipart adatként, PDF előállítása, a művelet megismétlése egy Office-dokumentummal, majd a health endpoint ellenőrzése minden konvertálás után”. Ezt az eredményt egészítsd ki a Chromium- és LibreOffice-folyamatok számával, az ideiglenes lemezhasználattal, a dokumentum összetettségével és a proxyk időkorlátaival; egy zöld gyökéroldal semmit nem mond a kimenet kompatibilitásáról vagy az erőforrások kimerüléséről.

Az image cseréje előtt számolj ezzel a kockázattal: az API-route-ok, a Chromium-kapcsolók és a LibreOffice működése jelentősen változhat a Gotenberg főverziói között. Reprezentatív és határérték-közeli bemeneteket tesztelj mindkét verzióval, és tartsd meg a régi digestet, amíg az új jelölt sikeresen át nem megy a teszteken. Ha a kérések hibás multipart mezőt használnak, vagy a konvertálások túllépik a proxyk időkorlátait, az útvonal- vagy tárolási beállítások módosítása előtt vizsgáld meg a kérés formátumát, a kliens működését és a futtatási logokat.

Hogyan csökkenti a Dockup a Gotenberggel kapcsolatos munkát?

Egy egykattintásos Gotenberg-sablonnak tartalmaznia kell az image digestjét, a 3000-es portot, a health-ellenőrzés időzítését, a domaint és a TLS-t. Mivel az alapszolgáltatás állapotmentes, a Dockup közvetlenül újra létrehozhatja a Dockup compute-on vagy egy csatolt gépen anélkül, hogy egy üres volume-ot biztonsági mentésnek tekintene.

Indítás után tedd elérhetővé a konvertálási API-t HTTPS-en vagy privát belső domainen keresztül. A Dockupnak meg kell őriznie a Gotenberg futtatási beállításait, miközben az üzemeltető ellenőrzi ezt a helyi követelményt: a Chromium- és LibreOffice-workerek számára biztosított CPU- és memóriatartalék. Ellenőrizd a következő eredményt: HTML és assetek küldése multipart adatként, PDF előállítása, a művelet megismétlése egy Office-dokumentummal, majd a health endpoint ellenőrzése minden konvertálás után. Minden későbbi állapotkezelő bővítménynek külön kell deklarálnia a saját mountját, secretjét és restore-tesztjét, nem pedig csendben megváltoztatnia az alapsablon jelentését.

Gyakran ismételt kérdések

Mire van szüksége a Gotenbergnek éles környezetben?

A Gotenberg konténerét a 3000-es porton keresztül, egyetlen HTTPS-origin mögött route-old. A helyi futtatási követelmény a Chromium- és LibreOffice-workerek számára biztosított CPU- és memóriatartalék. Ne tekintsd késznek a Gotenberget addig, amíg nem tudsz HTML-t és asseteket multipart adatként küldeni, PDF-et előállítani, a műveletet egy Office-dokumentummal megismételni, majd minden konvertálás után ellenőrizni a health endpointot.

Milyen Gotenberg-adatokat kell biztonsági mentésbe tenni?

A standard Gotenberg image nem igényel alkalmazásadatokat tartalmazó mountot. Őrizd meg a telepítési konfigurációját, a kapcsolódó állapotot pedig külön mentsd; a helyreállítás akkor sikeres, ha az egyéni betűkészletek, sablonok és parancssori kapcsolók reprodukálhatók, az ismert dokumentumok pedig a várt oldalszámmal jelennek meg.

Szüksége van a Gotenbergnek HTTPS-re reverse proxy mögött?

A nyilvános Gotenberg-originhez használj HTTPS-t, a belső route-on pedig tartsd meg a 3000-es portot. Helyesen alkalmazd a Gotenberg beállítását: tedd elérhetővé a konvertálási API-t HTTPS-en vagy privát belső domainen keresztül. A Gotenberg esetében a HTTPS védi a hitelesítő adatokat és a felhasználói tartalmakat az átvitel során, valamint konzisztenssé teszi az origintől függő kliensviselkedést.

Hogyan kell tesztelni egy Gotenberg-frissítést?

Telepítsd a Gotenberg jelölt image-ét a jelenlegi mellé, majd ismételd meg az elfogadási tranzakciót ismert bemenettel. Különösen figyelj arra, hogy az API-route-ok, a Chromium-kapcsolók és a LibreOffice működése jelentősen változhat a Gotenberg főverziói között. A standard konténerben nincs adat-migráció, ezért tartsd meg az előző digestet, amíg a kimeneti és kompatibilitási ellenőrzések sikeresen le nem futnak.