Khởi động và khám phá trong NextPDF Connect

Tổng quan nhanh

Mỗi transport có điểm vào và trình tự khởi động riêng. Các transport dùng chung registry, cấu hình và gate về mặt khái niệm. Chúng chạy như những tiến trình độc lập, nên việc khởi động một transport không khởi động các transport còn lại.

Cài đặt

composer require nextpdf/server

Tổng quan khái niệm

Trình tự khởi động MCP

McpServer::create() thiết lập máy chủ Model Context Protocol (MCP) theo một thứ tự cố định. Trước tiên, nó nạp cấu hình, xây dựng chính sách bảo mật từ cấu hình đó, dựng tool registry và chạy quá trình khám phá tier. Tiếp đó, nó dựng kho tài liệu trong bộ nhớ dựa trên thời gian sống (TTL) và dung lượng đã cấu hình, tạo transport stdio, rồi lắp ráp trình xử lý giao thức JSON-RPC cùng gate xác nhận và trình ghi nhật ký kiểm toán. Sau đó, máy chủ đi vào vòng lặp đọc-xử lý-ghi và chạy cho đến khi luồng đầu vào chuẩn đi đến cuối tệp.

Trình tự khởi động REST

HttpServer::create() đọc HttpConfig từ môi trường và áp dụng các tùy chọn ghi đè từ giao diện dòng lệnh (CLI). Sau đó, nó phân giải kho khóa API theo thứ tự ưu tiên sau: kho tệp có hot reload trước, rồi đến tệp tĩnh, sau cùng là môi trường. Tiếp theo, nó phân giải các kho rate-limit và idempotency. Các kho này dùng Redis khi Redis đã được cấu hình và có thể truy cập; nếu không, chúng chuyển sang lưu trữ trong bộ nhớ. Từ đó, máy chủ mở kho công việc SQLite dùng chung, dựng các dịch vụ ứng dụng và xây dựng bảng route. Vì bảng route được xây dựng từ các tier được phát hiện, nó phản ánh các gói đã cài đặt. Sau đó, RoadRunner điều khiển vòng lặp yêu cầu của worker.

Trình tự khởi động gRPC

GrpcServer::create() phân giải cùng kho khóa, dựng cùng các dịch vụ ứng dụng và đăng ký dịch vụ nextpdf.connect.v1 với worker gRPC của Spiral. Khi thành phần phụ thuộc engine không khả dụng, máy chủ gRPC vẫn khởi động và phục vụ các truy vấn về tình trạng và năng lực. Ở trạng thái đó, tiến trình không từ chối khởi động; thay vào đó, các lệnh gọi thủ tục từ xa (RPC) có payload sẽ thất bại một cách gọn gàng.

Khám phá tool

Bước khám phá là quá trình đăng ký mặc định của registry. Tier core được đăng ký trước. Các provider Pro và Enterprise được đăng ký tiếp theo nếu class của chúng phân giải được qua class_exists(). Sau đó, các provider Abstract Syntax Tree (AST) và mutation đi kèm đăng ký dưới tier Pro, tùy theo gate môi trường của chúng. Mọi lần đăng ký đều được lọc qua allowlist bảo mật enabled_tools, và phản hồi initialize của MCP báo cáo số lượng nhận được theo từng tier. Xem /connect/tool-catalog/.

Khám phá transport

Không có một thiết lập cấu hình duy nhất nào để “bật các transport.” Mỗi transport là một điểm vào riêng. REST và gRPC mỗi transport có một profile RoadRunner riêng. Một bản triển khai chọn transport dựa trên profile đang chạy: .rr.yaml cho REST, .rr.grpc.yaml cho gRPC, hoặc .rr.full.yaml cho cả hai. Các transport chạy như những tiến trình độc lập. Việc thiếu client MCP không bao giờ chặn máy chủ REST, và việc thiếu client REST không bao giờ chặn MCP. Xem /connect/deployment/.

Thứ tự phân giải cấu hình

Máy chủ MCP phân giải cấu hình theo thứ tự ưu tiên sau: môi trường (NEXTPDF_MCP_*) có ưu tiên cao hơn phần nextpdf_mcp trong tệp YAML, và phần này có ưu tiên cao hơn các giá trị mặc định tích hợp sẵn. Các máy chủ REST và gRPC đọc HttpConfig từ các biến môi trường NEXTPDF_*, với các giá trị mặc định an toàn. Chúng không đọc tệp YAML của MCP. Xem /connect/configuration/.

Liên kết container

Không cần đăng ký dependency-injection container hay service provider nào. Mỗi factory create() dựng đồ thị đối tượng của riêng nó một cách tường minh và xác định. Có hai điểm cho phép inject — transport và worker factory — và cả hai đều dành cho kiểm thử, không phải để kết nối ứng dụng.

Mẫu mã — bắt đầu nhanh

Kiểm tra kết quả khám phá mà không cần phục vụ lưu lượng:

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

Mẫu mã — môi trường production

Khởi động các transport kết hợp dưới một supervisor:

export NEXTPDF_API_KEYS_FILE=/run/secrets/api-keys
./vendor/bin/rr serve -c .rr.full.yaml

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

• Việc thiếu một tier không làm khởi động thất bại. Quá trình khám phá tier âm thầm bỏ qua một gói Pro hoặc Enterprise vắng mặt. Máy chủ khởi động với catalog core.

• Một tùy chọn ghi đè làm hạ cấp sẽ khiến khởi động thất bại. Một mục risk_level_overrides làm suy yếu một tool approval_required sẽ ném lỗi trong khi nạp cấu hình; máy chủ từ chối khởi động. Điều này là có chủ ý.

• Lỗi Redis khiến hệ thống giảm cấp chứ không gây sập. Nếu Redis đã được cấu hình nhưng không thể truy cập khi khởi động, máy chủ REST chuyển sang dùng các kho trong bộ nhớ. Hãy kiểm tra tình trạng của Redis thay vì giả định rằng Redis đang được sử dụng.

Hiệu năng

Chi phí khởi động đến từ việc phân tích cú pháp cấu hình, quét registry và phát hiện các tier. performance_budget của trang giới hạn chi phí này. Chi phí này chỉ phát sinh một lần cho mỗi lần khởi chạy tiến trình, không phải cho mỗi yêu cầu.

Ghi chú bảo mật

Chính sách bảo mật được xây dựng trước registry, nên allowlist enabled_tools ràng buộc quá trình khám phá ngay từ lần đăng ký đầu tiên. Khóa API không bao giờ được đọc từ tệp YAML của MCP; các transport mạng phân giải khóa từ một tệp secret hoặc từ môi trường. Xem /connect/security-and-operations/.

Tuân thủ

Trang này mô tả cơ chế khởi động. 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

Việc phát hiện tier khi khởi động là điểm duy nhất mà nextpdf/premium đóng góp các tool Pro và Enterprise vào catalog, khi nextpdf/premium được cài đặt cùng với máy chủ.

Xem thêm

• /connect/tool-catalog/ — những gì quá trình khám phá đăng ký và vì sao số lượng thay đổi
• /connect/configuration/ — thứ tự phân giải chi tiết
• /connect/deployment/ — chọn transport thông qua các profile RoadRunner
• /transports/mcp/ · /transports/rest/ · /transports/grpc/ — chi tiết theo từng transport