Khắc phục sự cố NextPDF Connect

Tổng quan nhanh

Hầu hết lỗi thuộc một trong năm dạng: quá trình bắt tay JavaScript Object Notation Remote Procedure Call (JSON-RPC) bị sai định dạng, thiếu khóa application programming interface (API), công cụ chưa được cài đặt trong gói này, thử thách xác nhận chưa được phản hồi, hoặc store không được các worker dùng chung. Mỗi dạng đều có dấu hiệu riêng.

Cài đặt

composer require nextpdf/server

Tổng quan khái niệm

Lớp truyền tải Model Context Protocol (MCP) trả về các đối tượng lỗi JSON-RPC 2.0 với mã chuẩn. Lớp truyền tải Representational State Transfer (REST) trả về tài liệu problem-details theo Request for Comments (RFC) 7807. Mỗi tài liệu có một URL type để xác định tình trạng tương ứng. Với vấn đề môi trường, hãy bắt đầu bằng các công cụ chẩn đoán (diagnostic.doctor, diagnostic.capabilities). Các công cụ này luôn có trong catalog lõi.

Bề mặt API

Mã lỗi JSON-RPC của MCP

Mã	Tên	Nguyên nhân
`-32700`	Lỗi phân tích cú pháp	Dòng không phải là JSON hợp lệ
`-32600`	Yêu cầu không hợp lệ	Không phải thông điệp JSON-RPC 2.0 (thiếu `jsonrpc`/`method`)
`-32601`	Không tìm thấy phương thức	Phương thức khác với `initialize`, `tools/list`, `tools/call`
`-32602`	Tham số không hợp lệ	Thiếu `params.name` trên `tools/call`
`-32603`	Lỗi nội bộ	Công cụ phát sinh lỗi khi thực thi

Khi một công cụ thất bại có kiểm soát, nó sẽ không dùng các mã này. Thay vào đó, công cụ trả về phản hồi JSON-RPC thành công, trong kết quả có isError: true và kèm lời giải thích bằng văn bản, chẳng hạn công cụ không xác định, bị tắt theo chính sách hoặc đối số không hợp lệ.

Các loại problem-details của REST

HTTP	`type` slug	Nguyên nhân
`401`	`unauthorized`	Khóa API bị thiếu/không hợp lệ/bị tắt/hết hạn
`403`	`capability-denied`	Gói của khóa không có quyền dùng thao tác này
`413`	`payload-too-large` / `tier-payload-exceeded`	Phần thân vượt quá giới hạn toàn cục hoặc giới hạn của gói
`422`	`validation-failed`	Phần thân yêu cầu không vượt qua kiểm tra schema
`429`	`ip-rate-exceeded` / `client-rate-exceeded`	Đã vượt giới hạn tốc độ
`404`	`not-found`	Route không xác định hoặc id của job/session
`504`	(hết thời gian chờ yêu cầu)	Thao tác vượt quá thời gian chờ của gói

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

Chạy kiểm tra tình trạng môi trường. Lệnh này không cần tài liệu hay xác nhận:

./vendor/bin/nextpdf-mcp <<'EOF'
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"diag","version":"1.0.0"}}}
{"jsonrpc":"2.0","method":"notifications/initialized"}
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"diagnostic.doctor","arguments":{}}}
EOF

Mẫu mã — môi trường sản xuất

Trước khi gỡ lỗi “công cụ bị thiếu”, hãy xác nhận bản triển khai này cung cấp những công cụ nào:

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

hoặc với REST server đang chạy:

curl -sS http://localhost:8080/api/v1/capabilities \
  -H "Authorization: Bearer $NEXTPDF_KEY"

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

“Công cụ không xác định” đối với công cụ Pro/Enterprise. Gói chứa công cụ này chưa được cài đặt. Registry kiểm tra các lớp provider và bỏ qua các gói vắng mặt mà không cảnh báo. Đây là hành vi dự kiến, không phải lỗi. Hãy cài đặt nextpdf/premium cùng với server hoặc dùng công cụ lõi. Thông báo lỗi có kèm đường dẫn cài đặt.
Một công cụ tôi đã cấu hình trong enabled_tools lại không xuất hiện. Danh sách cho phép sẽ được giao với các công cụ tìm thấy. Danh sách này không thể thêm công cụ mà registry không tìm thấy. Hãy kiểm tra việc cài đặt gói và mọi điều kiện bật qua môi trường. Ví dụ, parse_pdf chỉ được bật khi được đăng ký qua NEXTPDF_MCP_TOOL_PARSE_PDF_ENABLED.
tools/call trả về văn bản yêu cầu một token. Đây là thử thách xác nhận, không phải lỗi. Hãy gọi lại công cụ trong vòng 300 giây và đặt _confirmation_token thành token đã cấp. Xem /connect/hitl-risk-tiers/.
Dòng thông báo không tạo ra kết quả nào. Đó là hành vi đúng. Một thông điệp JSON-RPC không có id là thông báo, nên handler không trả về gì. Hãy gửi các yêu cầu có id để nhận phản hồi.
Một id yêu cầu bị lặp trả về phản hồi cũ. Handler khử trùng lặp theo id yêu cầu trong bộ đệm 64 mục. Hãy dùng id mới cho mỗi yêu cầu logic.
Giới hạn tốc độ hoạt động bất thường giữa các worker. Store trong bộ nhớ là riêng cho từng worker. Để dùng chung bộ đếm, hãy đặt NEXTPDF_REDIS_HOST và cài đặt ext-redis. Xem /connect/deployment/.
Tài liệu biến mất giữa các yêu cầu. Store tài liệu trong bộ nhớ là riêng của từng worker và bị giới hạn bởi thời gian sống (document_ttl, mặc định 1800 s). Để duy trì tài liệu giữa các worker, hãy dùng store dựa trên Redis, dùng các endpoint phiên, hoặc giữ toàn bộ tập thao tác trong một lần kết xuất đồng bộ.
Server chuyển về dùng bộ nhớ dù đã cấu hình Redis. REST server tự động dùng phương án dự phòng nếu kết nối Redis thất bại khi khởi động. Hãy kiểm tra khả năng truy cập Redis và xác nhận ext-redis có mặt trong image đang chạy. Đừng cho rằng Redis đang được dùng mà không xác minh.
Server từ chối khởi động kèm lỗi cấu hình. Một mục risk_level_overrides đã cố hạ cấp công cụ ApprovalRequired. Loader từ chối việc này theo thiết kế. Hãy bỏ phần hạ cấp; các override chỉ có thể nâng mức rủi ro.

Hiệu năng

Nếu kết xuất chậm dưới tải nặng, hãy xác nhận worker pool không bị quá tải. Hãy kiểm tra endpoint số liệu của RoadRunner. Sau đó chuyển các lần kết xuất dài sang luồng tác vụ bất đồng bộ để chúng không chiếm giữ worker. Xem /connect/production-usage/.

Lưu ý về bảo mật

Đừng lách qua một 401 bằng cách mở lớp truyền tải MCP không xác thực ra mạng; điều đó loại bỏ hoàn toàn việc xác thực. Thay vào đó, hãy sửa khóa API. Đừng tăng độ chi tiết của log để xem các đối số của công cụ trong môi trường dùng chung; nội dung đối số có thể nhạy cảm. Xem /connect/security-and-operations/.

Tuân thủ

Trang này cung cấp hướng dẫn vận hành. Các trích dẫn về giao thức và bảo mật được ghim tại /transports/mcp/, /transports/rest/, và /connect/security-and-operations/.

Xem thêm

/connect/tool-catalog/ — catalog lõi gồm những gì và vì sao số lượng thay đổi
/connect/hitl-risk-tiers/ — chi tiết về các thử thách xác nhận
/connect/deployment/ — Redis, worker pool và cách dùng chung store
/connect/security-and-operations/ — lỗi xác thực và trạng thái bảo mật