Chạy chẩn đoán môi trường bằng NextPDF Connect

Tổng quan nhanh

Xác nhận rằng máy chủ NextPDF Connect đang hoạt động ổn định và có các năng lực mà quy trình của bạn cần trước khi chạy công việc thực tế. Hãy dùng cách này làm bước đầu tiên trong mọi pipeline tác tử. Các công cụ này được xác minh dựa trên registry công cụ của máy chủ: diagnostic.doctor, diagnostic.capabilities và diagnostic.verify. Registry hiển thị chúng theo tên giao thức dạng chấm, đồng thời có thêm một công cụ liên quan là diagnostic.inspect. Tất cả đều là công cụ Core.

Cài đặt

composer require nextpdf/server

Cấu hình một transport. Bạn chỉ cần đến veraPDF cho bước kiểm tra tuân thủ tùy chọn. Kiểm tra cấu trúc không cần công cụ bên ngoài.

Tổng quan khái niệm

diagnostic.doctor trả về báo cáo tình trạng cơ bản: phiên bản PHP, các extension đã được nạp, phiên bản máy chủ, tier hiện hoạt và mọi cảnh báo. Hãy coi status là cổng kiểm soát. Tiếp tục khi gặp ok, đọc warnings khi gặp warning, và dừng lại khi gặp error.
diagnostic.capabilities liệt kê các năng lực đã đăng ký, cùng tier và trạng thái runtime của chúng (available, unavailable, degraded). Số năng lực phụ thuộc vào runtime và tier, vì vậy đừng cố định một tổng số. Hãy kiểm tra từng năng lực mà quy trình của bạn cần.
diagnostic.verify kiểm tra tính toàn vẹn cấu trúc: phần header PDF, dấu EOF và bảng cross-reference. Mục tiêu là cấu trúc tài liệu được tiếp cận qua page tree (ISO 32000-2 §7.5). Khi có compliance_flavour, công cụ này cũng gọi veraPDF.

Kết quả chẩn đoán là một phản hồi bình thường trên mọi transport (PHP Standard Recommendation 18, PSR-18 §p2).

Bề mặt API

Công cụ	Vai trò	Mức rủi ro
`diagnostic.doctor`	Báo cáo tình trạng môi trường	An toàn
`diagnostic.capabilities`	Danh mục năng lực kèm trạng thái	An toàn
`diagnostic.verify`	Kiểm tra cấu trúc / tuân thủ	An toàn
`create_pdf`, `add_text`, `output_pdf`	Kiểm tra nhanh một tài liệu	như mô tả ở nơi khác

Những tên này là tên giao thức của registry. Tool catalog là danh mục chính thức. Tier đã cài đặt quyết định những công cụ và năng lực nào tồn tại, vì vậy đừng bao giờ giả định một số lượng công cụ hay năng lực cố định.

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

diagnostic.doctor (không có đối số) → đọc status.
diagnostic.capabilities (không có đối số) → xác nhận mỗi năng lực cần dùng đều ở trạng thái available.
create_pdf rồi add_text → một tài liệu kiểm tra nhanh tối thiểu.
diagnostic.verify với document_id → kiểm tra cấu trúc.
Tùy chọn diagnostic.verify với compliance_flavour: "4" → veraPDF.
output_pdf (base64) → hủy phiên kiểm tra nhanh.

Mẫu mã — Production

Điều khiển pipeline dựa trên diagnostic.doctorstatus. Ánh xạ từng phụ thuộc của quy trình tới một capability id cụ thể, rồi xác nhận trạng thái available trước khi chạy các bước phụ thuộc. Hãy coi degraded là một rủi ro về chất lượng cần kiểm tra chọn mẫu. Luôn chạy biến thể cấu trúc của diagnostic.verify. Chỉ chạy biến thể tuân thủ khi tính phù hợp là quan trọng. Nếu không có veraPDF, công cụ trả về một kết quả không tìm thấy rõ ràng thay vì một lỗi máy chủ.

Trường hợp biên & điểm cần lưu ý

Không có veraPDF. Lệnh gọi kiểm tra tuân thủ trả về một kết quả không tìm thấy rõ ràng. Việc kiểm tra cấu trúc vẫn hoạt động. Nếu bạn cần kiểm tra tuân thủ, hãy cài đặt veraPDF và đưa nó vào PATH của tiến trình máy chủ.
veraPDF quá thời gian. Tài liệu lớn có thể vượt quá giới hạn thời gian kiểm tra. Hãy giảm kích thước tài liệu hoặc tăng giới hạn thời gian trong cấu hình máy chủ.
Năng lực degraded. Một phụ thuộc chỉ khả dụng một phần, vì vậy chất lượng đầu ra có thể giảm. Hãy kiểm tra log máy chủ để biết phương án dự phòng đang được sử dụng.
Doctor trả về error. Một yêu cầu thiết yếu chưa được đáp ứng. Đừng tiếp tục.

Hiệu năng

Kiểm tra cấu trúc rất nhanh. Luồng tuân thủ khởi chạy veraPDF và chịu giới hạn thời gian kiểm tra. Ngân sách rộng là để tính đến tiến trình con đó.

Lưu ý bảo mật

Kết quả chẩn đoán tiết lộ chi tiết môi trường: phiên bản PHP, các extension và tier. Hãy coi nó chỉ dành cho người vận hành và đừng hiển thị cho bên gọi không đáng tin cậy.

Tính phù hợp

Tuyên bố	Đặc tả	Điều khoản	reference_id
Kết quả chẩn đoán là phản hồi transport bình thường.	PSR-18	§p2
Kiểm tra tính toàn vẹn cấu trúc nhắm tới cấu trúc được neo vào page tree.	ISO 32000-2	§7.5

Biến thể tuân thủ chạy veraPDF và báo cáo kết luận của nó. NextPDF không tự khẳng định tính phù hợp. Trình kiểm định là bên quyết định.

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

Không áp dụng — tất cả các công cụ chẩn đoán đều là Core.

Mức khả dụng theo transport

Transport	Khả dụng	Ghi chú
MCP (stdio)	Có	Kết quả chẩn đoán được trả về dưới dạng kết quả công cụ.
REST	Có	Các health endpoint ánh xạ tới những công cụ này.
gRPC	Có	Unary; kết quả mang cùng các trường status.

Mức rủi ro HITL

Cả ba công cụ chẩn đoán đều An toàn: chỉ đọc, không có tác dụng phụ. Chúng không bao giờ kích hoạt cổng xác nhận. output_pdf được dùng để kiểm tra nhanh ở chế độ base64 (Review, không có cổng).

Vỏ bọc JSON của cổng xác nhận

Chẩn đoán không bao giờ bị chặn tại cổng.

{ "allowed": true }