Üretim ortamında NextPDF Gotenberg

Bir bakışta

Köprü, tek bir eşzamanlı Hypertext Transfer Protocol (HTTP) gidiş dönüşü gerçekleştirir ve sonucu doğrular. Yeniden deneme, kuyruğa alma, önbelleğe alma veya hız sınırlama yapmaz. Bu davranışları köprüyü saran uygulama katmanına yerleştirin. Bu sayfa, hangi sorumluluğun nereye ait olduğunu ve köprünün neyi garanti ettiğini gösterir; böylece geri kalanını doğru biçimde oluşturabilirsiniz.

Her dönüştürmeyi, işlettiğiniz ancak işlem içinde denetlemediğiniz bir hizmete yapılan uzak çağrı olarak ele alın. Planlamanızı bu hizmetin gecikme süresini ve olası hatalarını hesaba katarak yapın.

Yapılandırma ve gizli anahtarların temin edilmesi

GotenbergConfig, application programming interface (API)‘si için Uniform Resource Locator (URL) değerini ve kimlik doğrulama etkinleştirildiğinde kullanılacak taşıyıcı belirtecini saklar. Belirteç alanı #[\SensitiveParameter] ile işaretlenmiştir; bu nedenle yığın izlemelerinde bu alan gizlenir. Belirteci güvenli biçimde temin etmek yine de sizin sorumluluğunuzdadır.

Belirteci işlem başlangıcında gizli anahtar yönetiçinizden veya enjekte edilen bir ortam değerinden yükleyin. Belirteci sürüm denetimine eklemeyin ve imajla birlikte dağıtılan bir yapılandırma dosyasına koymayın.
Yapılandırmayı her dönüştürme için değil, her istek kapsamı ya da her çalışan için bir kez oluşturun. Yapılandırma değişmezdir ve saklama maliyeti düşüktür.
GotenbergConfig::fromArray(), tasarım gereği hatalı biçimlendirilmiş girdiyi kabul eder ve sessizce varsayılan değerleri yerine koyar. Üretim ortamında, fromArray() çağrısını yapmadan önce kaynak diziyi doğrulayın. Böylece eksik bir URL, daha sonra her dönüştürmede oluşan bir Invalid Gotenberg configuration: apiUrl is empty istisnası olarak değil, önyükleme sırasında bir yapılandırma hatası olarak görünür.

Zaman aşımları

timeout (saniye, varsayılan 30), cURL’a sabitlenmiş taşıma katmanı tarafından uygulanan katı aktarım zaman aşımıdır. LibreOffice üzerinden Office dönüştürme anlık değildir; büyük veya karmaşık belgeler daha uzun sürer. Zaman aşımını, gerçek belgeleriniz için ölçülen dönüştürme gecikmesine dayanarak ve pay bırakacak şekilde ayarlayın. Bu değeri, üst akıştaki herhangi bir ağ geçidi zaman aşımının veya PHP çalışma zamanının max_execution_time değerinin altında tutun. Böylece işlem dışarıdan sonlandırılmak yerine, köprü önce türlenmiş bir istisnayla zaman aşımına uğrar.

Enjekte edilmiş PHP Standard Recommendation 18 (PSR-18) istemci yolunu kullanıyorsanız (responseFactory enjekte edilmemişse veya sabit değeri olmayan salt bir Internet Protocol (IP) URL’si varsa), köprü timeout değerini bu istemciye uygulamaz. Her iki taşıma katmanının da sınırlı kalması için zaman aşımını PSR-18 istemcisinde de yapılandırın.

Yeniden denemeler

Köprü, her çağrıda tam olarak bir istek gönderir ve hiçbir zaman yeniden deneme yapmaz. Yeniden denemeleri çağıran tarafa ekleyin ve bunları güvenli hâle getirin:

Yalnızca taşıma düzeyindeki hataları (nedeni bir PSR-18 istemci istisnası olan bir GotenbergConvertException) ve geçici sunucu hatalarını (HTTP 502, 503, 504) yeniden deneyin. GotenbergConvertException istisnalarının tümünü ayrım gözetmeksizin yeniden denemeyin. Bir 400 sınıfı yanıt genellikle girdinin hatalı olduğu anlamına gelir; bu nedenle aynı işlem tekrar aynı şekilde başarısız olur.
Rastgele gecikme (jitter) içeren sınırlı üstel geri çekilme kullanın. Yük altındaki bir dönüştürme hizmeti 503 döndürdüğünde, üzerine daha fazla yük bindirmek kesintiyi daha da kötüleştirir.
Toplam deneme sayısını ve toplam geçen süreyi sınırlayın. Dönüştürme zaten yavaştır; bu nedenle sınırsız yeniden denemeler kuyruk gecikmesini katlar.
Yeniden doğrulama otomatik olarak çalışır: yeniden denenen her çağrı, URL doğrulamasını ve adres denetimini yeniden yürütür; böylece bir yeniden deneme, server-side request forgery (SSRF) korumasını yanlışlıkla atlayamaz.

Eşzamanlılık ve kapasite

Her dönüştürme, istek tamamlanana kadar Gotenberg tarafında bir bağlantıyı ve bir LibreOffice çalışanını tutar. Köprünün kendisi durumsuzdur ve birden çok çalışandan eşzamanlı kullanılması güvenlidir. Gotenberg hizmeti yine de sınırlı bir dönüştürme kapasitesine sahiptir.

Devam etmekte olan dönüştürmelerin sayısını kendi tarafınızda (bir kuyruk, bir semafor veya bir çalışan havuzuyla) Gotenberg’in sürdürebileceği kapasiteyle sınırlayın. Boyutlandırma, bu pakete değil, sizin Gotenberg dağıtımınıza bağlıdır; bakınız /integrations/gotenberg/security-and-operations/.
Girdi boyutu üst sınırı (maxFileSize, varsayılan 50 MiB), köprünün tek yerleşik kaynak sınırıdır. Köprü bu sınırı, istek gönderilmeden önce işlem içinde uygular; böylece aşırı büyük bir dosya hizmet kapasitesini hiçbir zaman tüketmez. Bu sınırı, belgelerinizin gerçekte ihtiyaç duyduğu değere uyacak şekilde düşürün; daha küçük bir üst sınır, daha büyük bir sınıra kıyasla daha ucuz bir hizmet reddi denetimidir.
İşlem içi önbelleğe alma yoktur. Aynı belgeyi tekrar tekrar dönüştürüyorsanız, elde edilen Portable Document Format (PDF) çıktısını girdinin içerik özetiyle anahtarlayarak uygulamanızda önbelleğe alın.

Gözlemlenebilirlik

Her dönüştürme isteğinde bir debug kaydı almak için bir PHP Standard Recommendation 3 (PSR-3) günlükleyicisi enjekte edin. Kayıt; istek URL’sini, dosya adını, algılanan biçimi ve istek içerik uzunluğunu içerir. Dosya içeriklerini veya taşıyıcı belirtecini içermez.

Bu sinyali metriğe dönüştürün: dönüştürmeleri biçime ve sonuca göre sayın ve her convertFile() / convertString() çağrısının çevresinde ölçülen geçen süreyi bir gecikme histogramı olarak kaydedin. Köprü, metrikleri kendisi yaymaz.
Sonuç nesnesi bir renderTimeMs alanı sunar. Entegrasyonunuz bu değeri ölçüp ayarlamadıkça değeri 0.0 olur; köprü bu alanı Gotenberg yanıtından doldurmaz. Bu değere ihtiyacınız varsa çağrının süresini kendiniz ölçün.
İstisnaları türleriyle birlikte günlüğe kaydedin. İstisna türü, neyin başarısız olduğunu gösteren birincil sinyaldir; katalog için bakınız /integrations/gotenberg/troubleshooting/.
Hazır olma veya sağlık uç noktanızdan isAvailable() yöntemini yoklayın, her dönüştürmede değil. Bir HEAD isteğini /health adresine gönderir. Bunu her dönüştürmeden önce çalıştırmak, hiçbir fayda sağlamadan hizmete yönelik istek hızınızı ikiye katlar.

Hata işleme sözleşmesi

Köprü, hataları türlenmiş istisnalar olarak ortaya çıkarır ve hiçbir zaman kısmi ya da doğrulanmamış bir sonuç döndürmez. Aşağıdakileri garanti eder:

Bir 200 dışı durum kodu, Content-Type başlığında application/pdf bulunmaması ya da %PDF ile başlamayan bir gövde, bir GotenbergConvertException oluşturur. Köprü, yalnızca üç denetimin tümü başarılı olduğunda bir sonuç nesnesi döndürür.
Bir PSR-18 istemci hatası (bir ağ hatası veya zaman aşımı dâhil), özgün istisna neden olacak ve istemcinin kodu istisna kodu olacak şekilde bir GotenbergConvertException içinde sarmalanır.
Doğrulama hataları (HTTPS olmayan URL, private/reserved adres, aşırı büyük girdi, güvenli olmayan dosya adı), herhangi bir ağ trafiğinden önce bir RuntimeException oluşturur.
Tanınmayan bir dosya uzantısı, herhangi bir ağ trafiğinden önce bir ValueError oluşturur.

Belirli türleri yakalayın. examples/convert-office-to-pdf.php içindeki örnek program, eksiksiz yakalama sırasını gösterir. /integrations/gotenberg/troubleshooting/ her tetikleyiciyi açıklar.

Son işleme sınırı

Köprü bir PDF üretir ve durur. Yaygın üretim iş hattı şöyledir:

Office belgesini bu köprüyle dönüştürün.
Elde edilen baytları bir NextPDF belgesine yükleyin.
Son işlemeyi uygulayın: sayfa birleştirme, filigran ekleme, Portable Document Format/Archive (PDF/A) dönüştürme ve dijital imzalar.

Üçüncü adım köprüye değil, NextPDF tarafına aittir. nextpdf/premium, imzalama, PDF/A profilleri ve filigran ekleme işlevlerini sağlar. Dönüştürme ile son işlemeyi ayrı aşamalar olarak tutun; böylece bir dönüştürme hatasını imzalama hatasından bağımsız olarak teşhis edebilirsiniz.

Pro sürümünün PDF Advanced Electronic Signatures (PAdES) desteği yalnızca B-B temel düzeyini kapsar. B-T, B-LT veya B-LTA sağlamaz ve bu profiller, bir belgenin bu köprü aracılığıyla dönüştürülmesiyle ima edilmez. Uzun vadeli doğrulama yeteneği, ayrı bir sürüm konusudur ve bu paketin kapsamı dışındadır.

Ayrıca bakınız

/integrations/gotenberg/configuration/ - taşıma katmanı seçim kuralları ve sabitleme modeli.
/integrations/gotenberg/security-and-operations/ - Gotenberg bağımlılığının dağıtılması ve sağlamlaştırılması.
/integrations/gotenberg/troubleshooting/ - istisna kataloğu.
/integrations/gotenberg/integration/ - dönüştürülen PDF’in bir NextPDF iş hattına bağlanması.