Tích hợp NextPDF Connect

Tổng quan nhanh

Tích hợp NextPDF Connect bằng cách chạy nó như một máy chủ. Bạn không nhúng thư viện vào ứng dụng chủ. Chọn một transport, rồi cấu hình xác thực cho mọi transport nối mạng. Các công cụ của engine vẫn được đặt sau cổng xác nhận.

Cài đặt

composer require nextpdf/server

Các ràng buộc Composer là nextpdf/core: ^3.0 với php: >=8.4 <9.0. Để thiết lập các tùy chọn ext-redis và nextpdf/premium, xem /connect/install/.

Tổng quan khái niệm

Gói này chạy như một dịch vụ độc lập. Bạn không đăng ký service provider, bundle hay container module nào trong framework chủ. Điểm tích hợp chính là tiến trình mà bạn chạy. Mỗi transport có entry point riêng và khởi động độc lập. Xem /connect/boot-and-discovery/.

Bề mặt API

Entry point	Transport	Profile
`bin/nextpdf-mcp`	MCP qua stdio	(không có — subprocess trực tiếp)
`bin/nextpdf-server`	REST qua RoadRunner HTTP	`.rr.yaml`
`bin/nextpdf-grpc`	gRPC qua RoadRunner gRPC	`.rr.grpc.yaml`
cả hai transport nối mạng	REST + gRPC	`.rr.full.yaml`

Khởi động và tự động khám phá

Registry luôn khám phá tầng core. Sau đó, registry thêm các provider Pro và Enterprise khi các lớp của chúng được phân giải, rồi đến các provider abstract syntax tree (AST) và mutation được đóng gói kèm, dưới các cổng kiểm soát theo môi trường. Danh sách cho phép bảo mật enabled_tools lọc toàn bộ các mục đó, nên danh mục được phơi bày là danh mục của chính lần triển khai này. Xem /connect/tool-catalog/ và /connect/boot-and-discovery/.

Container binding

Không có. Mỗi server factory tự dựng đồ thị đối tượng của nó một cách tường minh. Các điểm tiêm phụ thuộc chỉ phục vụ kiểm thử, không dùng để gắn kết ứng dụng.

Cấu hình publish

Máy chủ MCP chấp nhận một tệp YAML tùy chọn (--config=PATH, phần nextpdf_mcp) cùng các giá trị ghi đè qua biến môi trường NEXTPDF_MCP_*. Các máy chủ REST và gRPC đọc các biến môi trường NEXTPDF_*. Để biết chi tiết, xem /connect/configuration/.

Tính khả dụng của transport (MCP / REST / gRPC)

Cả ba transport đều phục vụ cùng một registry:

MCP — subprocess cục bộ, JSON-RPC 2.0 qua stdio, không cần API key, bản sửa đổi MCP 2025-06-18. Xem /transports/mcp/.
REST — pool worker RoadRunner HTTP, hợp đồng OpenAPI 3.1, API key dạng bearer, các route được kiểm soát theo tầng. Xem /transports/rest/.
gRPC — pool worker RoadRunner gRPC, dịch vụ Protobuf nextpdf.connect.v1, RPC server-streaming, xác thực bearer trong metadata, mutual TLS trong profile kết hợp. Xem /transports/grpc/.

Một transport được coi là “khả dụng” khi entry point hoặc profile RoadRunner của nó đang chạy. Các transport không tự động khởi động lẫn nhau.

Tầng rủi ro HITL

Mỗi công cụ khai báo một trong bốn mức rủi ro: safe, caution, review, approval_required. Các công cụ ở mức approval_required không chạy trong lần gọi đầu tiên. Cổng xác nhận phát ra một challenge token dùng một lần mà con người phải phê duyệt. Một giá trị ghi đè cấu hình chỉ có thể nâng mức rủi ro của một công cụ, không bao giờ hạ mức một công cụ approval_required. Mô hình này được áp dụng nhất quán trên mọi transport vận hành các công cụ. Xem /connect/hitl-risk-tiers/.

Gói JSON của cổng xác nhận

Bước kiểm tra của cổng trả về một trong hai dạng JSON. Cho phép:

{ "allowed": true }

Thử thách:

{
  "allowed": false,
  "challenge": "<human-readable text naming the operation, its description, an overwrite warning when applicable, and the re-invocation instruction>",
  "token": "confirm_<nonce>"
}

Token được gắn với tên công cụ, một nonce ngẫu nhiên và TTL 300 giây, chứ không gắn với các đối số. Để tiếp tục, bên gọi gọi lại đúng công cụ đó với đối số _confirmation_token được đặt thành token đã phát ra. Thử thách chỉ là văn bản hướng dẫn thuần túy kèm theo token; nó không phải là một gói được ký bằng mật mã. Xem /connect/hitl-risk-tiers/.

Kiểm tra nhanh dịch vụ

./vendor/bin/generate-skills --dry-run --list-tools

Lệnh này khởi động registry và cơ chế phát hiện tầng, rồi in ra các công cụ được phơi bày mà không phục vụ lưu lượng nào. Dùng lệnh này để xác nhận rằng phần tích hợp đã được gắn kết và để kiểm tra bản cài đặt này tạo ra danh mục nào.

Trường hợp đặc biệt và điểm cần lưu ý

Không có hook framework. Đừng tìm một service provider hay bundle. Tiến trình đang chạy chính là phần tích hợp.
Thiếu một tầng không phải là lỗi. Bản cài đặt chỉ có core vẫn khởi động được và phục vụ danh mục core của nó.
Các transport nối mạng cần một key. Chỉ /healthz và /readyz (REST) cùng các RPC health (gRPC) mới cho phép ẩn danh.

Hiệu năng

Chi phí khởi động đến từ việc quét registry và phát hiện tầng, một lần cho mỗi tiến trình. Chi phí cho mỗi yêu cầu là thao tác của engine. Định cỡ các pool worker RoadRunner dựa trên độ trễ kết xuất quan sát được. Xem /connect/production-usage/.

Ghi chú bảo mật

Các transport nối mạng xác thực bằng một bearer key npk_live_ được kiểm tra trong thời gian hằng số; cổng xác nhận bắt buộc phải có xác nhận của con người cho các thao tác phá hủy, bất kể transport nào. Hãy kết thúc TLS ở lớp phía trước REST, và dùng mutual TLS cho gRPC trên các mạng không tin cậy. Xem /connect/security-and-operations/.

Tuân thủ

Các trích dẫn về giao thức và bảo mật được ghim tại /transports/mcp/, /transports/rest/, /transports/grpc/ và /connect/security-and-operations/.

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

Cài đặt nextpdf/premium cùng với máy chủ để đăng ký thêm các công cụ Pro và Enterprise vào cùng một máy chủ đang chạy. Không cần tiến trình riêng nào.

Xem thêm

/connect/overview/ — kiến trúc
/connect/quickstart/ — lượt trao đổi đầu tiên có thể chạy được
/transports/mcp/ · /transports/rest/ · /transports/grpc/ — tài liệu tham khảo cho từng transport
/connect/hitl-risk-tiers/ — chi tiết về cổng xác nhận
/connect/tool-catalog/ — danh mục phụ thuộc vào runtime
/connect/security-and-operations/ — xác thực và mô hình mối đe dọa