NextPDF Gotenberg trong môi trường production

Tổng quan nhanh

Bridge thực hiện một vòng request đồng bộ qua Hypertext Transfer Protocol (HTTP) và xác thực kết quả. Nó không thử lại, không xếp hàng, không lưu cache và không giới hạn tốc độ. Hãy đặt những hành vi đó trong ứng dụng bao quanh bridge. Trang này làm rõ phần nào thuộc về đâu, và bridge bảo đảm những gì, để bạn có thể xây dựng phần còn lại đúng cách.

Hãy coi mỗi lần chuyển đổi là một lệnh gọi từ xa tới một dịch vụ mà bạn vận hành nhưng không kiểm soát ngay trong tiến trình. Hãy dự liệu độ trễ và các trường hợp lỗi của dịch vụ đó.

Lấy cấu hình và secret từ nguồn an toàn

GotenbergConfig lưu Uniform Resource Locator (URL) của application programming interface (API) và, khi bật xác thực, một bearer token. Trường token được đánh dấu #[\SensitiveParameter], nên stack trace sẽ che giá trị này. Bạn vẫn chịu trách nhiệm lấy nó từ nguồn an toàn.

Nạp token từ trình quản lý secret của bạn hoặc từ một giá trị môi trường được đưa vào khi tiến trình khởi động. Đừng commit nó, và đừng đặt nó trong một tệp cấu hình được đóng gói cùng image.
Tạo cấu hình một lần cho mỗi phạm vi request hoặc một lần cho mỗi worker, thay vì cho từng lần chuyển đổi. Cấu hình là bất biến và giữ lại không tốn kém.
GotenbergConfig::fromArray() theo thiết kế sẽ chấp nhận đầu vào không hợp lệ và âm thầm thay bằng các giá trị mặc định. Trong môi trường production, hãy xác thực mảng nguồn trước khi bạn gọi fromArray(). Khi đó, một URL bị thiếu sẽ lộ ra dưới dạng lỗi cấu hình lúc khởi động, thay vì chỉ xuất hiện muộn hơn dưới dạng ngoại lệ Invalid Gotenberg configuration: apiUrl is empty ở từng lần chuyển đổi.

Timeout

timeout (tính bằng giây, mặc định 30) là giới hạn thời gian truyền cứng do transport gắn với cURL áp dụng. Việc chuyển đổi Office qua LibreOffice không diễn ra tức thì; tài liệu lớn hoặc phức tạp sẽ mất nhiều thời gian hơn. Hãy đặt timeout dựa trên độ trễ chuyển đổi đo được với tài liệu thực tế của bạn, kèm theo một khoảng dự phòng. Hãy giữ nó thấp hơn mọi timeout của gateway phía trên hoặc max_execution_time của runtime PHP. Như vậy bridge sẽ hết thời gian chờ trước, với một ngoại lệ có kiểu rõ ràng thay vì một tiến trình bị buộc dừng.

Nếu bạn dùng nhánh client PHP Standard Recommendation 18 (PSR-18) được đưa vào (không đưa vào responseFactory, hoặc một URL Internet Protocol (IP) trần không có pin), bridge sẽ không áp dụng giá trị timeout cho client đó. Hãy cấu hình timeout cả trên client PSR-18, để cả hai transport đều có giới hạn.

Thử lại

Bridge gửi đúng một request cho mỗi lệnh gọi và không bao giờ thử lại. Hãy thêm cơ chế thử lại ở phía gọi, và bảo đảm cơ chế đó an toàn:

Chỉ thử lại với các lỗi ở tầng transport (một GotenbergConvertException có nguyên nhân là ngoại lệ từ client PSR-18) và các lỗi máy chủ idempotent (HTTP 502, 503, 504). Đừng thử lại mọi GotenbergConvertException một cách bừa bãi. Phản hồi thuộc nhóm 400 thường có nghĩa là đầu vào sai, nên thử lại y như cũ cũng sẽ lỗi y như cũ.
Hãy dùng exponential backoff có giới hạn kèm jitter. Khi một dịch vụ chuyển đổi đang quá tải trả về 503, việc dồn dập gửi yêu cầu sẽ khiến sự cố tệ hơn.
Hãy giới hạn tổng số lần thử và tổng thời gian thực. Việc chuyển đổi vốn đã chậm, nên thử lại không giới hạn sẽ khuếch đại độ trễ phần đuôi.
Việc xác thực lại chạy tự động: mỗi lệnh gọi được thử lại sẽ chạy lại quá trình xác thực URL và kiểm tra lại địa chỉ, nên một lần thử lại không thể vô tình vượt qua cơ chế bảo vệ chống server-side request forgery (SSRF).

Tính đồng thời và năng lực xử lý

Mỗi lần chuyển đổi giữ một kết nối và một worker LibreOffice ở phía Gotenberg cho đến khi request hoàn tất. Bản thân bridge là stateless và an toàn khi dùng từ nhiều worker cùng lúc. Dịch vụ Gotenberg vẫn có năng lực chuyển đổi hữu hạn.

Hãy giới hạn số lần chuyển đổi đang chạy ở phía bạn (bằng một hàng đợi, một semaphore hoặc một worker pool) cho khớp với năng lực mà Gotenberg có thể duy trì. Việc tính toán quy mô phụ thuộc vào bản triển khai Gotenberg của bạn, không phụ thuộc vào gói này; xem /integrations/gotenberg/security-and-operations/.
Giới hạn kích thước đầu vào (maxFileSize, mặc định 50 MiB) là giới hạn tài nguyên tích hợp sẵn duy nhất của bridge. Bridge thực thi giới hạn này ngay trong tiến trình trước khi request được gửi đi, nên một tệp quá lớn sẽ không bao giờ tiêu tốn năng lực của dịch vụ. Hãy hạ nó xuống cho khớp với nhu cầu thực tế của tài liệu; một giới hạn nhỏ hơn là biện pháp chống denial-of-service ít tốn kém hơn so với một giới hạn lớn hơn.
Không có cơ chế lưu cache trong tiến trình. Nếu bạn chuyển đổi cùng một tài liệu nhiều lần, hãy lưu cache Portable Document Format (PDF) thu được trong ứng dụng của bạn, với khóa dựa trên content hash của đầu vào.

Khả năng quan sát

Hãy đưa vào một logger PHP Standard Recommendation 3 (PSR-3) để nhận một bản ghi debug cho mỗi request chuyển đổi. Bản ghi chứa URL của request, tên tệp, định dạng được phát hiện và độ dài nội dung của request. Bản ghi không chứa nội dung tệp hay bearer token.

Hãy biến tín hiệu đó thành một số liệu: đếm số lần chuyển đổi theo định dạng và kết quả, và ghi lại thời gian thực quanh mỗi lệnh gọi convertFile() / convertString() dưới dạng một histogram độ trễ. Bản thân bridge không phát ra số liệu.
Đối tượng kết quả cung cấp một trường renderTimeMs. Giá trị này bằng 0.0 trừ khi tích hợp của bạn đo và đặt nó; bridge không điền giá trị này từ phản hồi của Gotenberg. Hãy tự đo thời gian lệnh gọi nếu bạn cần giá trị này.
Hãy ghi log các ngoại lệ kèm theo kiểu của chúng. Kiểu ngoại lệ là tín hiệu chính cho biết điều gì đã thất bại; xem /integrations/gotenberg/troubleshooting/ để biết danh mục.
Hãy thăm dò isAvailable() từ endpoint readiness hoặc health của bạn, chứ không phải ở mỗi lần chuyển đổi. Nó gửi một HEAD tới /health. Chạy nó trước mỗi lần chuyển đổi sẽ làm tăng gấp đôi tốc độ gửi request tới dịch vụ mà không mang lại lợi ích gì.

Hợp đồng xử lý lỗi

Bridge báo lỗi dưới dạng các ngoại lệ có kiểu rõ ràng và không bao giờ trả về một kết quả không hoàn chỉnh hay chưa được xác thực. Nó bảo đảm những điều sau:

Một trạng thái khác 200, một Content-Type không phải application/pdf, hoặc một phần thân không bắt đầu bằng %PDF sẽ làm phát sinh một GotenbergConvertException. Bridge chỉ trả về một đối tượng kết quả khi cả ba kiểm tra đều vượt qua.
Một lỗi của client PSR-18 (bao gồm lỗi mạng hoặc timeout) được bọc thành một GotenbergConvertException, với ngoại lệ gốc làm nguyên nhân và mã của client làm mã ngoại lệ.
Các lỗi xác thực (URL không phải HTTPS, địa chỉ private/reserved, đầu vào quá lớn, tên tệp không an toàn) sẽ làm phát sinh RuntimeException trước khi có bất kỳ lưu lượng mạng nào.
Một phần mở rộng tệp không được nhận diện sẽ làm phát sinh ValueError trước khi có bất kỳ lưu lượng mạng nào.

Hãy bắt từng kiểu cụ thể. Chương trình ví dụ trong examples/convert-office-to-pdf.php cho thấy đầy đủ thứ tự bắt ngoại lệ. /integrations/gotenberg/troubleshooting/ giải thích từng nguyên nhân kích hoạt.

Ranh giới hậu xử lý

Bridge tạo ra một PDF rồi dừng lại. Một pipeline production thường gặp là:

Chuyển đổi tài liệu Office bằng bridge này.
Nạp các byte thu được vào một tài liệu NextPDF.
Áp dụng hậu xử lý: ghép trang, thêm hình mờ, chuyển đổi Portable Document Format/Archive (PDF/A) và chữ ký số.

Bước 3 thuộc về NextPDF, không phải bridge. nextpdf/premium cung cấp ký, các profile PDF/A và thêm hình mờ. Hãy giữ chuyển đổi và hậu xử lý ở các giai đoạn tách biệt, để bạn có thể chẩn đoán lỗi chuyển đổi độc lập với lỗi ký.

Hỗ trợ PDF Advanced Electronic Signatures (PAdES) của phiên bản Pro chỉ ở mức baseline B-B. Nó không cung cấp B-T, B-LT hay B-LTA, và những profile đó không được ngầm cung cấp khi chuyển đổi một tài liệu qua bridge này. Khả năng xác thực dài hạn là vấn đề thuộc về phiên bản riêng và nằm ngoài phạm vi của gói này.

Xem thêm

/integrations/gotenberg/configuration/ - các quy tắc chọn transport và mô hình pin.
/integrations/gotenberg/security-and-operations/ - triển khai và tăng cường bảo mật cho phụ thuộc Gotenberg.
/integrations/gotenberg/troubleshooting/ - danh mục ngoại lệ.
/integrations/gotenberg/integration/ - kết nối PDF đã chuyển đổi với một pipeline NextPDF.