การผสานการทำงานของ NextPDF Connect

ภาพรวมโดยสังเขป

ผสานการทำงานกับ NextPDF Connect โดยเรียกใช้เป็นเซิร์ฟเวอร์ ไม่ใช่เชื่อมต่อไลบรารีเข้ากับแอปพลิเคชันโฮสต์ เลือกทรานสปอร์ต แล้วกำหนดค่าการตรวจสอบสิทธิ์สำหรับทรานสปอร์ตที่ทำงานบนเครือข่าย เครื่องมือของเอนจินยังคงอยู่หลังเกตยืนยัน

การติดตั้ง

composer require nextpdf/server

ข้อกำหนดของ Composer คือ nextpdf/core: ^3.0 ร่วมกับ php: >=8.4 <9.0 สำหรับการตั้งค่าเสริมของ ext-redis และ nextpdf/premium โปรดดู /connect/install/

ภาพรวมเชิงแนวคิด

แพ็กเกจทำงานเป็นบริการแบบสแตนด์อโลน ไม่ต้องลงทะเบียน service provider, bundle หรือ container module ในเฟรมเวิร์กโฮสต์ จุดผสานการทำงานคือกระบวนการที่คุณเรียกใช้ ทรานสปอร์ตแต่ละชนิดมี entry point ของตนเองและบูตอย่างเป็นอิสระ โปรดดู /connect/boot-and-discovery/

พื้นผิว API

จุดเข้าใช้งาน (entry point)	ทรานสปอร์ต	โปรไฟล์
bin/nextpdf-mcp	MCP ผ่าน stdio	(ไม่มี — ซับโพรเซสโดยตรง)
bin/nextpdf-server	REST ผ่าน RoadRunner HTTP	.rr.yaml
bin/nextpdf-grpc	gRPC ผ่าน RoadRunner gRPC	.rr.grpc.yaml
ทรานสปอร์ตที่ทำงานบนเครือข่ายทั้งสองชนิด	REST + gRPC	.rr.full.yaml

การบูตและการค้นหาอัตโนมัติ

รีจิสทรีจะค้นหา core tier เสมอ จากนั้นจึงเพิ่ม Pro และ Enterprise provider เมื่อคลาสของแต่ละตัวสามารถ resolve ได้ ตามด้วย abstract syntax tree (AST) และ mutation provider ที่มากับแพ็กเกจภายใต้ environment gate allowlist ด้านความปลอดภัย enabled_tools จะกรองทั้งหมด ดังนั้นแคตตาล็อกที่เปิดเผยจึงเป็นของการดีพลอยนี้ โปรดดู /connect/tool-catalog/ และ /connect/boot-and-discovery/

การ binding ของ container

ไม่มี server factory แต่ละตัวจะสร้าง object graph ของตนเองอย่างชัดเจน จุด inject ที่เปิดไว้มีไว้สำหรับรองรับการทดสอบ ไม่ใช่สำหรับเชื่อมต่อแอปพลิเคชัน

การเผยแพร่ค่ากำหนด

เซิร์ฟเวอร์ MCP รองรับไฟล์ YAML แบบเลือกใช้ได้ (--config=PATH ส่วน nextpdf_mcp) และการ override ผ่านตัวแปรสภาพแวดล้อม NEXTPDF_MCP_* เซิร์ฟเวอร์ REST และ gRPC จะอ่านตัวแปรสภาพแวดล้อม NEXTPDF_* สำหรับรายละเอียด โปรดดู /connect/configuration/

ความพร้อมใช้งานของทรานสปอร์ต (MCP / REST / gRPC)

ทรานสปอร์ตทั้งสามชนิดให้บริการจากรีจิสทรีเดียวกัน:

• MCP — ซับโพรเซสภายในเครื่อง JSON-RPC 2.0 ผ่าน stdio ไม่ต้องใช้คีย์ API MCP revision 2025-06-18 โปรดดู /transports/mcp/
• REST — RoadRunner HTTP worker pool สัญญา OpenAPI 3.1 คีย์ API แบบ bearer และเส้นทางที่ควบคุมตามระดับ โปรดดู /transports/rest/
• gRPC — RoadRunner gRPC worker pool บริการ Protobuf nextpdf.connect.v1 RPC แบบ server-streaming การตรวจสอบสิทธิ์แบบ bearer-in-metadata และ mutual TLS ในโปรไฟล์แบบรวม โปรดดู /transports/grpc/

ทรานสปอร์ตจะ “พร้อมใช้งาน” เมื่อ entry point หรือโปรไฟล์ RoadRunner ของทรานสปอร์ตนั้นกำลังทำงานอยู่ ทรานสปอร์ตจะไม่เริ่มทำงานให้กันโดยอัตโนมัติ

ระดับความเสี่ยงแบบ HITL

เครื่องมือทุกตัวประกาศระดับความเสี่ยงหนึ่งในสี่ระดับ: safe, caution, review, approval_required เครื่องมือที่ระดับ approval_required จะไม่ทำงานในการเรียกครั้งแรก เกตยืนยันจะออก challenge token แบบใช้ครั้งเดียวที่มนุษย์ต้องอนุญาต การ override ค่ากำหนดทำได้เพียงเพิ่มความเสี่ยงของเครื่องมือเท่านั้น ไม่สามารถลดระดับเครื่องมือที่เป็น approval_required ได้ โมเดลนี้ใช้เหมือนกันกับทรานสปอร์ตทุกชนิดที่ขับเคลื่อนเครื่องมือ โปรดดู /connect/hitl-risk-tiers/

JSON envelope ของเกตยืนยัน

การตรวจสอบเกตจะคืนค่าโครงสร้าง JSON อย่างใดอย่างหนึ่งในสองแบบ อนุญาต:

{ "allowed": true }

คำท้าทาย (Challenge):

{
  "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 ผูกกับชื่อเครื่องมือ nonce แบบสุ่ม และ TTL 300 วินาที ไม่ได้ผูกกับอาร์กิวเมนต์ หากต้องการดำเนินการต่อ ผู้เรียกจะเรียกเครื่องมือเดิมอีกครั้งโดยตั้งค่าอาร์กิวเมนต์ _confirmation_token เป็น token ที่ออกให้ challenge เป็นข้อความคำสั่งธรรมดารวมกับ token ไม่ใช่ envelope ที่ลงนามด้วยวิธีการเข้ารหัสลับ โปรดดู /connect/hitl-risk-tiers/

การทดสอบเบื้องต้นของบริการ

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

คำสั่งนี้จะบูตรีจิสทรีและตรวจหาระดับ จากนั้นพิมพ์เครื่องมือที่เปิดเผยโดยไม่ให้บริการทราฟฟิก ใช้คำสั่งนี้เพื่อยืนยันว่าการผสานการทำงานเชื่อมต่อแล้ว และตรวจสอบว่าการติดตั้งนี้สร้างแคตตาล็อกใด

กรณีขอบและข้อควรระวัง

• ไม่มี framework hook อย่ามองหา service provider หรือ bundle กระบวนการที่กำลังทำงานอยู่คือการผสานการทำงาน
• การไม่มีระดับใดระดับหนึ่งไม่ใช่ข้อผิดพลาด การติดตั้งแบบ core เพียงอย่างเดียวจะบูตและให้บริการแคตตาล็อก core ของตน
• ทรานสปอร์ตที่ทำงานบนเครือข่ายต้องใช้คีย์ มีเพียง /healthz และ /readyz (REST) และ health RPC (gRPC) เท่านั้นที่เป็นแบบไม่ระบุตัวตน

ประสิทธิภาพ

ต้นทุนของการบูตคือการสแกนรีจิสทรีและการตรวจหาระดับ ซึ่งทำหนึ่งครั้งต่อกระบวนการ ต้นทุนต่อคำขอคือการดำเนินการของเอนจิน กำหนดขนาด worker pool ของ RoadRunner ตามเวลาแฝงของการเรนเดอร์ที่สังเกตได้ โปรดดู /connect/production-usage/

หมายเหตุด้านความปลอดภัย

ทรานสปอร์ตที่ทำงานบนเครือข่ายตรวจสอบสิทธิ์ด้วยคีย์แบบ bearer ที่ขึ้นต้นด้วย npk_live_ ซึ่งตรวจสอบในเวลาคงที่ เกตบังคับให้มนุษย์ยืนยันสำหรับการดำเนินการที่ก่อให้เกิดความเสียหายโดยไม่ขึ้นอยู่กับทรานสปอร์ต ยุติ TLS ที่ด้านหน้าของ REST และใช้ mutual TLS สำหรับ gRPC บนเครือข่ายที่ไม่น่าเชื่อถือ โปรดดู /connect/security-and-operations/

ความสอดคล้องตามข้อกำหนด

การอ้างอิงด้านโพรโทคอลและความปลอดภัยถูกตรึงไว้ที่ /transports/mcp/, /transports/rest/, /transports/grpc/ และ /connect/security-and-operations/

บริบทเชิงพาณิชย์

ติดตั้ง nextpdf/premium ควบคู่กับเซิร์ฟเวอร์เพื่อลงทะเบียนเครื่องมือ Pro และ Enterprise เพิ่มเติมในเซิร์ฟเวอร์เดียวกันที่กำลังทำงานอยู่ ไม่มีกระบวนการแยกต่างหากเข้ามาเกี่ยวข้อง

ดูเพิ่มเติม

• /connect/overview/ — สถาปัตยกรรม
• /connect/quickstart/ — การแลกเปลี่ยนที่รันได้ครั้งแรก
• /transports/mcp/ · /transports/rest/ · /transports/grpc/ — เอกสารอ้างอิงแยกตามทรานสปอร์ต
• /connect/hitl-risk-tiers/ — รายละเอียดของเกตยืนยัน
• /connect/tool-catalog/ — แคตตาล็อกที่ขึ้นอยู่กับรันไทม์
• /connect/security-and-operations/ — การตรวจสอบสิทธิ์และแบบจำลองภัยคุกคาม