NextPDF Gotenberg สำหรับการใช้งานจริง

ภาพรวมโดยย่อ

บริดจ์รับส่งข้อมูลแบบซิงโครนัสผ่าน Hypertext Transfer Protocol (HTTP) หนึ่งรอบ แล้วตรวจสอบความถูกต้องของผลลัพธ์ บริดจ์ไม่ลองใหม่ ไม่จัดคิว ไม่แคช และไม่จำกัดอัตรา ให้นำพฤติกรรมเหล่านั้นไปไว้ในแอปพลิเคชันที่อยู่รอบบริดจ์ หน้านี้อธิบายว่าควรวางหน้าที่ใดไว้ที่ใด และบริดจ์รับประกันสิ่งใดบ้าง เพื่อให้คุณสร้างส่วนที่เหลือได้อย่างถูกต้อง

ให้ถือว่าการแปลงทุกครั้งเป็นการเรียกใช้บริการระยะไกลไปยังบริการที่คุณดำเนินการเองแต่ไม่ได้ควบคุมภายในกระบวนการ วางแผนรองรับความหน่วงและความล้มเหลวของบริการนั้น

การจัดเตรียมการกำหนดค่าและ secret

GotenbergConfig จัดเก็บ Uniform Resource Locator (URL) สำหรับ application programming interface (API) และเมื่อเปิดใช้การรับรองตัวตน ก็จะจัดเก็บ bearer token ด้วย ฟิลด์ token ถูกทำเครื่องหมายด้วย #[\SensitiveParameter] ดังนั้น stack trace จะปกปิดค่านั้น คุณยังคงต้องจัดเตรียม token ดังกล่าวอย่างปลอดภัยด้วยตนเอง

• โหลด token จาก secret manager ของคุณหรือจากค่า environment ที่ฉีดเข้ามาเมื่อกระบวนการเริ่มทำงาน อย่า commit token และอย่าใส่ไว้ในไฟล์ config ที่จัดส่งไปพร้อมกับ image
• สร้าง config หนึ่งครั้งต่อขอบเขตคำขอหรือหนึ่งครั้งต่อ worker ไม่ใช่ต่อการแปลงหนึ่งครั้ง config เปลี่ยนแปลงไม่ได้และเก็บไว้ได้โดยมีต้นทุนต่ำ
• GotenbergConfig::fromArray() จงใจยอมรับอินพุตที่มีรูปแบบผิดและแทนที่ด้วยค่าเริ่มต้นโดยไม่แจ้ง ในการใช้งานจริง ให้ตรวจสอบความถูกต้องของ source array ก่อนเรียกใช้ fromArray() หากไม่มี URL ให้แสดงเป็นข้อผิดพลาดของการกำหนดค่าระหว่างบูต แทนที่จะไปปรากฏภายหลังเป็น exception Invalid Gotenberg configuration: apiUrl is empty ต่อการแปลงแต่ละครั้ง

การหมดเวลา

timeout (วินาที ค่าเริ่มต้น 30) คือค่าหมดเวลาการรับส่งข้อมูลแบบเด็ดขาดที่ทรานสปอร์ตซึ่งปักหมุดด้วย cURL ใช้ การแปลงเอกสาร Office ผ่าน LibreOffice ไม่ได้เกิดขึ้นในทันที เอกสารที่มีขนาดใหญ่หรือซับซ้อนจะใช้เวลานานกว่า กำหนดค่าการหมดเวลาจากความหน่วงของการแปลงที่วัดได้จากเอกสารจริงของคุณ โดยเผื่อส่วนต่างไว้ ให้ค่านี้ต่ำกว่าการหมดเวลาของเกตเวย์ต้นทางใดๆ หรือ max_execution_time ของรันไทม์ PHP วิธีนี้จะทำให้บริดจ์หมดเวลาก่อน พร้อม exception ที่ระบุชนิดชัดเจน แทนที่จะปล่อยให้กระบวนการถูกบังคับยุติ

หากคุณใช้เส้นทางไคลเอนต์ PHP Standard Recommendation 18 (PSR-18) ที่ฉีดเข้ามา (โดยไม่ได้ฉีด responseFactory หรือใช้ URL แบบ Internet Protocol (IP) ดิบที่ไม่มีการปักหมุด) บริดจ์จะไม่ใช้ค่า timeout กับไคลเอนต์นั้น ให้กำหนดค่าการหมดเวลาบนไคลเอนต์ PSR-18 ด้วย เพื่อให้ทรานสปอร์ตทั้งสองอยู่ภายในขอบเขตที่จำกัด

การลองใหม่

บริดจ์ส่งคำขอเพียงครั้งเดียวต่อการเรียกหนึ่งครั้งและไม่ลองใหม่ เพิ่มการลองใหม่ที่ฝั่งผู้เรียกใช้ และออกแบบให้ปลอดภัย:

• ลองใหม่เฉพาะความล้มเหลวระดับทรานสปอร์ต (GotenbergConvertException ที่มีสาเหตุมาจาก client exception ของ PSR-18) และข้อผิดพลาดของเซิร์ฟเวอร์ที่เป็น idempotent (HTTP 502, 503, 504) อย่าลองใหม่กับทุก GotenbergConvertException โดยไม่แยกกรณี การตอบกลับในกลุ่ม 400 มักหมายความว่าอินพุตไม่ถูกต้อง ดังนั้นการลองใหม่ด้วยคำขอเดิมก็จะล้มเหลวในแบบเดียวกัน
• ใช้ exponential backoff ที่มีขอบเขตจำกัดพร้อม jitter เมื่อบริการแปลงที่รับภาระสูงตอบกลับ 503 การส่งคำขอถี่ขึ้นจะยิ่งทำให้การหยุดทำงานแย่ลง
• จำกัดจำนวนครั้งทั้งหมดและเวลาตามจริงทั้งหมด การแปลงนั้นช้าอยู่แล้ว ดังนั้นการลองใหม่ที่ไม่มีขอบเขตจะเพิ่ม tail latency เป็นทวีคูณ
• การตรวจสอบความถูกต้องจะทำซ้ำโดยอัตโนมัติ การเรียกที่ลองใหม่แต่ละครั้งจะรันการตรวจสอบความถูกต้องของ URL และการตรวจสอบที่อยู่ซ้ำ ดังนั้นการลองใหม่จึงไม่สามารถข้ามตัวป้องกัน server-side request forgery (SSRF) โดยบังเอิญได้

การทำงานพร้อมกันและความจุ

การแปลงแต่ละครั้งจะใช้การเชื่อมต่อหนึ่งรายการและ LibreOffice worker หนึ่งตัวบนฝั่ง Gotenberg จนกว่าคำขอจะเสร็จสิ้น ตัวบริดจ์เองไม่มีสถานะ และใช้งานพร้อมกันจาก worker หลายตัวได้อย่างปลอดภัย บริการ Gotenberg ยังคงมีความจุในการแปลงที่จำกัด

• จำกัดจำนวนการแปลงที่กำลังดำเนินอยู่ในฝั่งของคุณ (ด้วยคิว เซมาฟอร์ หรือ worker pool) ให้อยู่ในความจุที่ Gotenberg สามารถรองรับได้ การกำหนดขนาดขึ้นอยู่กับการปรับใช้ Gotenberg ของคุณ ไม่ใช่แพ็กเกจนี้ ดู /integrations/gotenberg/security-and-operations/.
• ขีดจำกัดขนาดอินพุต (maxFileSize ค่าเริ่มต้น 50 MiB) เป็นขีดจำกัดทรัพยากรในตัวเพียงรายการเดียวของบริดจ์ บริดจ์บังคับใช้ขีดจำกัดนี้ภายในกระบวนการก่อนที่จะส่งคำขอ ดังนั้นไฟล์ที่เกินขนาดจะไม่ใช้ความจุของบริการเลย ลดค่านี้ให้ตรงกับความต้องการจริงของเอกสารของคุณ ขีดจำกัดที่เล็กกว่าเป็นการควบคุม denial-of-service ที่มีต้นทุนต่ำกว่าขีดจำกัดที่ใหญ่กว่า
• ไม่มีการแคชภายในกระบวนการ หากคุณแปลงเอกสารเดียวกันซ้ำๆ ให้แคช Portable Document Format (PDF) ที่ได้ไว้ในแอปพลิเคชันของคุณ โดยใช้ content hash ของอินพุตเป็นคีย์

การสังเกตการณ์

ฉีด logger ของ PHP Standard Recommendation 3 (PSR-3) เพื่อให้ได้รายการบันทึก debug หนึ่งรายการสำหรับคำขอแปลงแต่ละครั้ง รายการนี้มี URL ของคำขอ ชื่อไฟล์ รูปแบบที่ตรวจพบ และความยาวของเนื้อหาคำขอ รายการนี้ไม่มีเนื้อหาไฟล์หรือ bearer token

• เปลี่ยนสัญญาณนี้เป็นเมตริก: นับจำนวนการแปลงตามรูปแบบและผลลัพธ์ และบันทึกเวลาตามจริงของการเรียก convertFile() / convertString() แต่ละครั้งเป็น latency histogram บริดจ์ไม่ได้ส่งออกเมตริกด้วยตัวเอง
• ออบเจ็กต์ผลลัพธ์เปิดเผยฟิลด์ renderTimeMs ค่านี้เป็น 0.0 เว้นแต่การผสานรวมของคุณจะวัดและกำหนดค่านี้ บริดจ์ไม่ได้เติมค่านี้จากการตอบกลับของ Gotenberg จับเวลาการเรียกด้วยตัวคุณเองหากคุณต้องการค่าดังกล่าว
• บันทึก exception ควบคู่กับชนิดของ exception นั้น ชนิดของ exception เป็นสัญญาณหลักที่บอกว่าสิ่งใดล้มเหลว ดูแคตตาล็อกได้ที่ /integrations/gotenberg/troubleshooting/
• ตรวจสอบ isAvailable() จาก readiness หรือ health endpoint ของคุณ ไม่ใช่ทุกครั้งที่แปลง โดยจะส่ง HEAD ไปยัง /health การเรียกก่อนการแปลงแต่ละครั้งจะเพิ่มอัตราคำขอไปยังบริการเป็นสองเท่าโดยไม่มีประโยชน์เพิ่ม

สัญญาการจัดการความล้มเหลว

บริดจ์แสดงความล้มเหลวผ่าน exception ที่มีชนิดชัดเจน และไม่เคยคืนผลลัพธ์ที่ไม่สมบูรณ์หรือยังไม่ผ่านการตรวจสอบความถูกต้อง บริดจ์รับประกันสิ่งต่อไปนี้:

• สถานะที่ไม่ใช่ 200 Content-Type ที่ไม่มี application/pdf หรือเนื้อหาที่ไม่ได้ขึ้นต้นด้วย %PDF จะทำให้เกิด GotenbergConvertException บริดจ์จะคืนออบเจ็กต์ผลลัพธ์ก็ต่อเมื่อการตรวจสอบทั้งสามรายการผ่านเท่านั้น
• ความล้มเหลวของไคลเอนต์ PSR-18 (รวมถึงความล้มเหลวของเครือข่ายหรือการหมดเวลา) จะถูกห่อหุ้มเป็น GotenbergConvertException โดยมี exception เดิมเป็นสาเหตุ และใช้รหัสของไคลเอนต์เป็นรหัส exception
• ความล้มเหลวของการตรวจสอบความถูกต้อง (URL ที่ไม่ใช่ HTTPS ที่อยู่ private/reserved อินพุตที่มีขนาดเกิน ชื่อไฟล์ที่ไม่ปลอดภัย) จะทำให้เกิด RuntimeException ก่อนที่จะมีการรับส่งข้อมูลเครือข่ายใดๆ
• ส่วนขยายไฟล์ที่ไม่รู้จักจะทำให้เกิด ValueError ก่อนที่จะมีการรับส่งข้อมูลเครือข่ายใดๆ

ให้จับชนิดที่เฉพาะเจาะจง โปรแกรมตัวอย่างใน examples/convert-office-to-pdf.php แสดงลำดับการ catch แบบครบถ้วน /integrations/gotenberg/troubleshooting/ อธิบายแต่ละทริกเกอร์

ขอบเขตการประมวลผลภายหลัง

บริดจ์สร้าง PDF แล้วหยุด ไปป์ไลน์การใช้งานจริงที่พบบ่อยมีดังนี้:

1. แปลงเอกสาร Office ด้วยบริดจ์นี้
2. โหลดไบต์ผลลัพธ์เข้าสู่เอกสาร NextPDF
3. ใช้การประมวลผลภายหลัง: การประกอบหน้า การใส่ลายน้ำ การแปลง Portable Document Format/Archive (PDF/A) และลายเซ็นดิจิทัล

ขั้นตอนที่ 3 เป็นหน้าที่ของ NextPDF ไม่ใช่ของบริดจ์ nextpdf/premium ให้บริการการลงนาม โปรไฟล์ PDF/A และการใส่ลายน้ำ แยกการแปลงและการประมวลผลภายหลังเป็นคนละขั้นตอน เพื่อให้คุณวินิจฉัยความล้มเหลวของการแปลงได้แยกจากความล้มเหลวของการลงนาม

รุ่น Pro รองรับ PDF Advanced Electronic Signatures (PAdES) เฉพาะเบสไลน์ B-B เท่านั้น ไม่รองรับ B-T, B-LT หรือ B-LTA และ โปรไฟล์เหล่านั้นไม่ได้เกิดขึ้นโดยปริยายจากการแปลงเอกสารผ่าน บริดจ์นี้ ความสามารถในการตรวจสอบความถูกต้องระยะยาวเป็นเรื่องของรุ่นแยกต่างหาก และอยู่นอกขอบเขตของแพ็กเกจนี้

ดูเพิ่มเติม

• /integrations/gotenberg/configuration/ - กฎการเลือกทรานสปอร์ตและโมเดลการปักหมุด
• /integrations/gotenberg/security-and-operations/ - การปรับใช้และการเพิ่มความปลอดภัยให้กับการพึ่งพา Gotenberg
• /integrations/gotenberg/troubleshooting/ - แคตตาล็อก exception
• /integrations/gotenberg/integration/ - การเชื่อม PDF ที่แปลงแล้วเข้ากับไปป์ไลน์ NextPDF