Gotenbergin self-hosting vuonna 2026: HTML–PDF-muunnos, aikakatkaisut ja fontit
Ota Gotenberg käyttöön oikealla portilla, kestävällä tallennustilalla, TLS:llä, todennuksella ja varmuuskopioilla. Selvitä tuotannossa tilanteet, joissa pyynnöt käyttävät väärää multipart-kenttää.
Epäonnistunut Gotenberg-asennus ei aina kaadu. Se saattaa näyttää kirjautumissivun, jos pyynnöt käyttävät väärää multipart-kenttää, tai muunnokset voivat ylittää proxyn aikakatkaisut. Aloita sen sijaan päästä päähän tehtävällä tarkistuksella: lähetä HTML ja resurssit multipart-datana, muodosta PDF, toista sama Office-dokumentilla ja tarkista health endpoint jokaisen muunnoksen jälkeen.
Tarkistus vastaa Gotenbergin dokumentoitua käyttötarkoitusta: kyseessä on HTTP-palvelu, joka muuntaa HTML-, Markdown- ja Office-tiedostoja PDF-muotoon. Se paljastaa puuttuvat riippuvuudet, virheelliset proxy-oletukset ja ephemeral-datan aikaisemmin kuin pelkkä uptime-tarkistus.
Portit, prosessit ja yksityiset palvelut
Älä anna Gotenberg-imagen määrittää tuotantoarkkitehtuuria vahingossa. Image tarjoaa prosessin portissa 3000, mutta tallennustila, reititys ja ulkoiset riippuvuudet tarvitsevat edelleen harkitut elinkaaret. Paikallinen runtime-vaatimus on riittävä CPU- ja muistikapasiteetti Chromium- ja LibreOffice-työntekijöille. Testaa tämä raja ennen julkaisua ja uudelleen jokaisen containerin vaihdon jälkeen.
Asennus on valmis perusteellisempaan testaukseen, kun se pystyy lähettämään HTML:n ja resurssit multipart-datana, muodostamaan PDF:n, toistamaan saman Office-dokumentilla ja tarkistamaan health endpointin jokaisen muunnoksen jälkeen. Seuraa tapahtumaa lokeista ja tarkkaile Chromium- ja LibreOffice-prosessien määrää, väliaikaista levytilaa, dokumentin monimutkaisuutta ja proxyn aikakatkaisuja. Näiden havaintojen avulla selviää, eristääkö nykyinen topologia oikean komponentin.
Tee Gotenbergin palautumisesta mitattavaa
Standardi Gotenberg-image ei odota kirjoitettavaa sovellustilaa. Älä säilytä pysyvää sovellusdataa; säilytä sen sijaan fontit, templatet ja deployment-konfiguraatio, mukaan lukien lukittu digest ja tarkistettu route-konfiguraatio, äläkä varmuuskopioi tyhjää container-tiedostojärjestelmää.
Luo Gotenberg tyhjästä toisella hostilla ja varmista, että mukautetut fontit, templatet ja command flagit voidaan toisintaa ja että tunnetut dokumentit renderöityvät odotetulla sivumäärällä. Jos mukaan lisätään erillinen tietokanta, room server tai autentikointikerros, määritä kyseiselle komponentille oma selkeä palautuksesta vastaava taho. Gitistä tuotantoon -opas näyttää, miten toisinnettava artefakti korvaa container-varmuuskopion.
Tallenna rebuild-komento ja tunnetun tuloksen testi julkaisun yhteyteen. Stateless-palautussuunnitelma onnistuu, kun toiminta voidaan toisintaa luotetuista syötteistä; sen ei pidä riippua käynnissä olevan opaque-containerin kopioimisesta.
Rajaa Gotenbergin käyttöoikeudet
Gotenbergin arvokkain kohde on käyttäjän syötettä käsittelevä koodipolku. Sen sovelluskohtainen riski on rajoittamattomien julkisten muunnosten salliminen ilman koko- ja aikakatkaisurajoja; tuotannossa muunnospäätepisteet tulisi pitää yksityisinä tai niissä tulee enforceerata koko-, rate- ja timeout-rajoitukset ennen epäluotettavien tiedostojen sallimista.
Standardicontainerissa ei ole ylläpitäjän secretia, joten autentikointi kuuluu HTTPS-reitille, jos palvelu on yksityinen. Lukitse build, vältä laajoja filesystem-mountteja ja rajoita Chromium- ja LibreOffice-prosessien määrää, väliaikaista levytilaa, dokumentin monimutkaisuutta ja proxyn aikakatkaisuja. Varmista tunnetulla testisyötteellä, että tarjottu build tuottaa odotetun tuloksen jokaisen päivityksen jälkeen.
Gotenbergin julkaisuvaiheen tarkistus
Muunna Gotenbergin smoke-testi toistettavaksi release-komennoksi tai lyhyeksi runbookiksi. Sen tuloksen on osoitettava seuraava lopputulos: lähetä HTML ja resurssit multipart-datana, muodosta PDF, toista sama Office-dokumentilla ja tarkista health endpoint jokaisen muunnoksen jälkeen. Tallenna tuloksen yhteyteen sovelluksen versio, container digest, route-hostname ja testidatan tunniste.
Suorita sama tarkistus tavallisen container-vaihdon jälkeen ja sen jälkeen, kun pysyvää sovellusdataa ei ole palautettu; säilytä fontit, templatet ja deployment-konfiguraatio muualla. Palautus on onnistunut, kun mukautetut fontit, templatet ja command flagit voidaan toisintaa ja tunnetut dokumentit renderöityvät odotetulla sivumäärällä. Vertaa Chromium- ja LibreOffice-prosessien määrään, väliaikaiseen levytilaan, dokumentin monimutkaisuuteen ja proxyn aikakatkaisuihin liittyvää ajoitusta ja kulutusta; suuri muutos kannattaa tutkia, vaikka lopullinen toiminto edelleen onnistuisi.
Tee sen jälkeen turvallinen vikatesti: lähetä harmiton syöte lähelle tähän rajaan liittyvää resurssi- tai formaattirajaa: pyynnöt käyttävät väärää multipart-kenttää tai muunnokset ylittävät proxyn aikakatkaisut. Varmista, että Gotenberg tuo vian näkyviin ja palautuu normaalitilaan ilman tuhoisia manuaalisia muokkauksia. Säilytä vain tarpeellinen, anonymisoitu lokikatkelma. Tämä neliosainen tarkistus kattaa käynnistyksen, pysyvyyden, palautumisen ja vikatilanteiden käsittelyn.
Tee Gotenbergin käynnistyksestä toistettava
Käytä komentoa, joka tuo kaikki tärkeät valinnat näkyviin. Tämä baseline sitoo Gotenbergin hostin loopback-osoitteeseen, lisää tunnetut data-mountit ja toimittaa ensimmäisen vaaditun asetuksen. Varmista paikallinen vaatimus ennen ulkoista näkyvyyttä: riittävä CPU- ja muistikapasiteetti Chromium- ja LibreOffice-työntekijöille.
docker run -d \
--name gotenberg \
--restart unless-stopped \
-p 127.0.0.1:3000:3000 \
gotenberg/gotenberg:8
Korvaa floating tagit testatulla versiolla tai digestillä. Käynnistyksen jälkeen tarkista docker logs --tail 200 gotenberg ja varmista, että prosessi kuuntelee portissa 3000. Suorita sen jälkeen Gotenbergin hyväksymistesti; juurisivun vastaus ei todista koko skenaarion onnistumista: lähetä HTML ja resurssit multipart-datana, muodosta PDF, toista sama Office-dokumentilla ja tarkista health endpoint jokaisen muunnoksen jälkeen.
Estä proxyn onnistumista peittämästä sovelluksen virhettä
Valitse lopullinen Gotenberg-hostname ennen kuin käyttäjät tallentavat callback-osoitteita tai client-asetuksia, ja julkaise muunnos-API HTTPS:n tai yksityisen sisäisen domainin kautta. Platform route -reitin tulee päättää TLS kerran ja ohjata liikenne yksityiseen porttiin 3000.
Suorita hyväksymistapahtuma ulkoisesti. Jos client ei koskaan saavuta Gotenbergiä, käytä SSL-varmistuksen tarkistuslistaa DNS- ja sertifikaattitarkistuksiin. Jos pyyntö saavuttaa Gotenbergin, mutta pyynnöt käyttävät väärää multipart-kenttää tai muunnokset ylittävät proxyn aikakatkaisut, lopeta proxyn redirectien muuttaminen ja tutki sen sijaan sovelluskohtaista rajapintaa.
Kapasiteetti- ja päivitystarkistukset
Gotenbergin hyödyllinen palveluindikaattori on seuraavan toiminnon onnistuminen: ”lähetä HTML ja resurssit multipart-datana, muodosta PDF, toista sama Office-dokumentilla ja tarkista health endpoint jokaisen muunnoksen jälkeen”. Yhdistä tulos Chromium- ja LibreOffice-prosessien määrään, väliaikaiseen levytilaan, dokumentin monimutkaisuuteen ja proxyn aikakatkaisuihin; vihreä juurisivu ei kerro mitään tulosteen yhteensopivuudesta tai resurssien loppumisesta.
Ennen imagen vaihtamista huomioi seuraava riski: API-reitit, Chromium-liput ja LibreOfficen toiminta voivat muuttua Gotenbergin major-versioiden välillä. Testaa tyypilliset ja rajatapauksen syötteet molempia versioita vasten ja säilytä vanha digest, kunnes ehdokasversio läpäisee testit. Jos pyynnöt käyttävät väärää multipart-kenttää tai muunnokset ylittävät proxyn aikakatkaisut, tarkista request-formaatti, clientin toiminta ja runtime-lokit ennen route- tai storage-asetusten muuttamista.
Miten Dockup vähentää Gotenbergiin liittyvää työtä
Yhden napsautuksen Gotenberg-templateen tulisi määrittää image digest, portti 3000, health-tarkistuksen ajoitus, domain ja TLS. Koska peruspalvelu on stateless, Dockup voi luoda sen suoraan Dockup-computeen tai liitetylle koneelle teeskentelemättä, että tyhjä volume olisi varmuuskopio.
Käynnistyksen jälkeen avaa muunnos-API HTTPS:n tai yksityisen sisäisen domainin kautta. Dockupin tulisi säilyttää Gotenbergin runtime-asetukset samalla, kun operaattori varmistaa paikallisen vaatimuksen: riittävä CPU- ja muistikapasiteetti Chromium- ja LibreOffice-työntekijöille. Varmista seuraava lopputulos: lähetä HTML ja resurssit multipart-datana, muodosta PDF, toista sama Office-dokumentilla ja tarkista health endpoint jokaisen muunnoksen jälkeen. Kaikkien myöhempien stateful-laajennusten on määritettävä oma mount, secret ja palautustesti sen sijaan, että ne muuttaisivat perustemplaten merkitystä huomaamatta.
Usein kysytyt kysymykset
Mitä Gotenberg tarvitsee tuotantokäyttöön?
Reititä Gotenberg-container portista 3000 yhden HTTPS-originin kautta. Paikallinen runtime-vaatimus on riittävä CPU- ja muistikapasiteetti Chromium- ja LibreOffice-työntekijöille. Älä merkitse Gotenbergiä valmiiksi, ennen kuin pystyt lähettämään HTML:n ja resurssit multipart-datana, muodostamaan PDF:n, toistamaan saman Office-dokumentilla ja tarkistamaan health endpointin jokaisen muunnoksen jälkeen.
Mitkä Gotenbergin tiedot kuuluvat varmuuskopioon?
Standardi Gotenberg-image ei tarvitse sovellusdatalle varattua mountia. Säilytä sen deployment-konfiguraatio ja varmuuskopioi yhdistetty tila erikseen; palautus läpäisee testin, kun mukautetut fontit, templatet ja command flagit voidaan toisintaa ja tunnetut dokumentit renderöityvät odotetulla sivumäärällä.
Edellyttääkö Gotenberg HTTPS:ää reverse proxyn takana?
Käytä julkisessa Gotenberg-originissa HTTPS:ää ja pidä portti 3000 sisäisellä reitillä. Käytä Gotenberg-asetusta oikein: avaa muunnos-API HTTPS:n tai yksityisen sisäisen domainin kautta. Gotenbergin tapauksessa HTTPS suojaa tunnistetietoja tai käyttäjän sisältöä siirron aikana ja pitää originista riippuvan client-toiminnan yhdenmukaisena.
Miten Gotenberg-päivitys pitäisi testata?
Ota uusi Gotenberg-image käyttöön nykyisen rinnalle ja toista hyväksymistapahtuma tunnetulla syötteellä. Kiinnitä erityistä huomiota siihen, että API-reitit, Chromium-liput ja LibreOfficen toiminta voivat muuttua Gotenbergin major-versioiden välillä. Standardicontainerissa ei ole datamigraatiota, joten säilytä edellinen digest, kunnes tulos- ja yhteensopivuustarkistukset on läpäisty.