NextPDF Connect trong môi trường production

Tổng quan nhanh

Một triển khai NextPDF Connect trong môi trường production cung cấp các cơ chế vận hành: health probe và readiness probe, đường dẫn kết xuất đồng bộ và bất đồng bộ, idempotency, giới hạn tốc độ theo từng client và theo từng địa chỉ Internet Protocol (IP), cùng các phiên làm việc có trạng thái tùy chọn. Hãy dùng trang này để vận hành các cơ chế đó với hành vi có thể dự đoán được.

Cài đặt

composer require nextpdf/server

Tổng quan khái niệm

Phương thức truyền tải Representational State Transfer (REST) là một pipeline middleware theo PHP Standards Recommendation (PSR)-15. Mỗi yêu cầu đi qua middleware theo thứ tự: gán request-id, giới hạn kích thước body, Cross-Origin Resource Sharing (CORS), xác thực, ủy quyền theo năng lực, giới hạn tốc độ, idempotency và thời gian chờ. Sau đó, yêu cầu đi tới một handler. Phương thức truyền tải gRPC tái sử dụng cùng các dịch vụ ứng dụng đó ở phía sau worker gRPC của RoadRunner.

Việc kết xuất có hai đường dẫn. Lệnh đồng bộ POST /api/v1/render chạy các thao tác và trả về tệp Portable Document Format (PDF) ngay trong phản hồi. Tác vụ bất đồng bộ dùng POST /api/v1/jobs. Nó trả về ngay lập tức cùng một job id; sau đó bạn lấy kết quả từ GET /api/v1/jobs/{id}/result. Các tác vụ được lưu trong một kho SQLite dùng chung, nên bất kỳ worker nào cũng có thể phản hồi truy vấn về trạng thái hoặc kết quả.

Bề mặt API

Health và readiness

Endpoint	Xác thực	Ý nghĩa
GET /healthz	không	Tiến trình đang chạy
GET /readyz	không	Máy chủ đã sẵn sàng nhận yêu cầu

Hãy gắn /healthz vào một liveness probe và /readyz vào một readiness probe. Cả hai endpoint đều cho phép truy cập ẩn danh, nên các orchestrator không cần thông tin xác thực.

Tác vụ async

Endpoint	Phương thức	Mục đích
/api/v1/jobs	POST	Gửi một tác vụ kết xuất
/api/v1/jobs/{id}	GET	Trạng thái tác vụ
/api/v1/jobs/{id}/result	GET	Kết quả tác vụ (tệp PDF)
/api/v1/jobs/{id}	DELETE	Hủy một tác vụ

Phiên làm việc (chọn bật)

Khi NEXTPDF_SESSIONS_ENABLED là true và các công cụ tương ứng có sẵn, các endpoint phiên làm việc cung cấp một luồng dựng tài liệu có trạng thái. Bạn tạo một phiên làm việc, thêm trang, văn bản, hình ảnh, bảng và HyperText Markup Language (HTML), thiết lập phông chữ, rồi kết xuất. Mỗi phiên làm việc chịu giới hạn theo từng client và có thời gian chờ khi không hoạt động. Chúng được tắt theo mặc định.

Mẫu code — bắt đầu nhanh

Gửi một tác vụ async và poll để lấy kết quả:

JOB=$(curl -sS -X POST http://localhost:8080/api/v1/jobs \
  -H "Authorization: Bearer $NEXTPDF_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"operations":[{"type":"add_text","text":"async render"}]}' \
  | python3 -c 'import sys,json;print(json.load(sys.stdin)["id"])')

curl -sS "http://localhost:8080/api/v1/jobs/$JOB/result" \
  -H "Authorization: Bearer $NEXTPDF_KEY" --output out.pdf

Mẫu code — production

Để việc gửi yêu cầu an toàn khi thử lại, hãy gửi kèm một khóa idempotency:

curl -sS -X POST http://localhost:8080/api/v1/jobs \
  -H "Authorization: Bearer $NEXTPDF_KEY" \
  -H 'Idempotency-Key: 7b1c2d3e-…' \
  -H 'Content-Type: application/json' \
  -d '{"operations":[{"type":"add_text","text":"safe retry"}]}'

Một yêu cầu được gửi lại với cùng khóa idempotency sẽ trả về kết quả ban đầu thay vì tạo ra một tác vụ thứ hai. Nhờ đó, việc gửi yêu cầu có thể được lặp lại an toàn sau một lỗi giao tiếp. Hành vi này phù hợp với đặc tính của phương thức idempotent: gửi lại cùng một yêu cầu có hiệu ứng mong muốn giống như chỉ gửi một lần (RFC 9110 §9.2.2). Do đó, yêu cầu có thể được thử lại tự động nếu kết nối bị ngắt trước khi client đọc được phản hồi (RFC 9110 §9.2.2).

Trường hợp đặc biệt và lưu ý

• Giới hạn tốc độ cần Redis để chính xác trên nhiều worker. Các bộ giới hạn theo từng client và theo từng IP dùng kho được cấu hình. Khi dùng kho trong bộ nhớ với nhiều hơn một worker, mỗi worker đếm yêu cầu độc lập, và giới hạn thực tế bị nhân lên theo số lượng worker. Hãy dùng kho Redis cho bất kỳ pool nhiều worker nào.

• Một yêu cầu bị giới hạn tốc độ sẽ trả về 429. Khi vượt quá một giới hạn, máy chủ phản hồi bằng 429 Too Many Requests và một header Retry-After, theo ngữ nghĩa của trạng thái giới hạn tốc độ (RFC 6585 §4). Hãy tôn trọng Retry-After; đừng thử lại ngay lập tức.

• Kết quả tác vụ không tồn tại mãi mãi. Kho tác vụ dọn các mục cũ sau NEXTPDF_JOB_GC_MAX_AGE_SECONDS. Hãy lấy kết quả trước khi chúng hết hạn.

• Phiên làm việc tốn bộ nhớ. Một phiên làm việc giữ một tài liệu đang dựng dở. Giới hạn phiên làm việc theo từng client và thời gian chờ khi không hoạt động đặt trần cho chi phí này. Đừng nâng chúng lên mà không tính toán bộ nhớ cho trường hợp xấu nhất.

Hiệu năng

Đường dẫn đồng bộ giữ một worker trong suốt quá trình kết xuất. Với các lần kết xuất lớn hoặc chậm, hãy dùng đường dẫn tác vụ async. Nó giải phóng worker ngay lập tức, và client poll để lấy kết quả. Hãy định cỡ pool worker dựa trên độ trễ kết xuất và mức đồng thời quan sát được. Hãy theo dõi endpoint số liệu của RoadRunner.

Lưu ý bảo mật

Mọi endpoint ngoại trừ các health probe đều yêu cầu một khóa application programming interface (API) hợp lệ. Bậc của client kiểm soát những thao tác và kích thước payload nào được phép. Client cung cấp các khóa idempotency. Hãy xem mỗi khóa là không thể diễn giải và duy nhất cho một thao tác logic. Xem /connect/security-and-operations/.

Tính tuân thủ

Tuyên bố	Nguồn	reference_id
Idempotent: các yêu cầu lặp lại = một hiệu ứng	RFC 9110 §9.2.2
Yêu cầu idempotent có thể thử lại sau lỗi	RFC 9110 §9.2.2
429 + Retry-After cho giới hạn tốc độ	RFC 6585 §4

Bối cảnh thương mại

Các khóa Pro và Enterprise nhận được trần payload và thời gian chờ cao hơn theo từng bậc khi những công cụ đó được cài đặt. Một bản triển khai mặc định dùng trần của bậc core.

Xem thêm

• /connect/deployment/ — pool worker, Redis, hồ sơ RoadRunner
• /transports/rest/ — toàn bộ pipeline middleware và hợp đồng OpenAPI
• /connect/troubleshooting/ — chẩn đoán 401/403/413/429/5xx và lỗi kho
• /connect/security-and-operations/ — tư thế bảo mật cho xác thực và giới hạn tốc độ