การกำหนดค่า NextPDF Connect

ภาพรวมโดยย่อ

NextPDF Connect มีจุดกำหนดค่าสองส่วน เซิร์ฟเวอร์ Model Context Protocol (MCP) อ่านไฟล์ YAML และตัวแปร NEXTPDF_MCP_* ส่วนเซิร์ฟเวอร์ REST และ gRPC อ่านตัวแปรสภาพแวดล้อม NEXTPDF_* หลังจากเซิร์ฟเวอร์บูตแล้ว การกำหนดค่าจะเปลี่ยนแปลงไม่ได้

การติดตั้ง

composer require nextpdf/server

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

เซิร์ฟเวอร์ MCP เลือกค่าการกำหนดค่าตามลำดับความสำคัญที่กำหนดไว้แน่นอน โดยใช้แหล่งที่มีลำดับความสำคัญสูงสุด:

1. ตัวแปรสภาพแวดล้อม (NEXTPDF_MCP_*)
2. ส่วน nextpdf_mcp ของไฟล์การกำหนดค่า YAML
3. ค่าเริ่มต้นในตัว

ส่งไฟล์ YAML ด้วย --config=PATH หากละเว้นไว้ เซิร์ฟเวอร์จะใช้เพียงค่าเริ่มต้นและตัวแปรสภาพแวดล้อมเท่านั้น McpConfig ที่ได้เป็นอ็อบเจกต์ค่าแบบ readonly และไม่มีการตั้งค่าใดเปลี่ยนแปลงได้หลังการบูต

เซิร์ฟเวอร์ REST และ gRPC อ่าน HttpConfig จากสภาพแวดล้อมขณะบูต รองรับ NEXTPDF_BIND, NEXTPDF_WORKER_COUNT, NEXTPDF_SESSIONS_ENABLED และ NEXTPDF_CORS_ENABLED ในฐานะการแทนที่ผ่านสภาพแวดล้อม เพดานที่เหลือใช้ค่าเริ่มต้นที่ปลอดภัย

พื้นผิว API

การกำหนดค่า MCP (nextpdf-mcp)

ไฟล์ YAML ส่วน nextpdf_mcp:

nextpdf_mcp:
  enabled_tools: []          # empty/absent = all available tools allowed
  temp_directory: /tmp/nextpdf-mcp
  max_documents: 50
  document_ttl: 1800
  max_file_size_bytes: 104857600
  allow_file_output: true
  compress: true
  risk_level_overrides:
    fill_form: 3             # raise fill_form to ApprovalRequired (see below)

การแทนที่ผ่านสภาพแวดล้อมสำหรับเซิร์ฟเวอร์ MCP:

ตัวแปร	คีย์การกำหนดค่า	ค่าเริ่มต้น
NEXTPDF_MCP_ENABLED_TOOLS	enabled_tools	อนุญาตเครื่องมือที่มีอยู่ทั้งหมด
NEXTPDF_MCP_TEMP_DIR	temp_directory	temp ของระบบ + /nextpdf-mcp
NEXTPDF_MCP_MAX_FILE_SIZE	max_file_size_bytes	104857600 (100 MB)
NEXTPDF_MCP_MAX_DOCUMENTS	max_documents	50
NEXTPDF_MCP_DOCUMENT_TTL	document_ttl	1800 วินาที
NEXTPDF_MCP_TOOL_PARSE_PDF_ENABLED	(ควบคุม parse_pdf)	ไม่ได้ตั้งค่า (ปิดใช้งาน)
NEXTPDF_AST_TOOLS_ENABLED	(ควบคุมเครื่องมือ AST)	เปิดใช้งาน
NEXTPDF_MUTATION_TOOLS_ENABLED	(ควบคุมเครื่องมือ AST mutation)	ไม่ได้ตั้งค่า (ปิดใช้งาน)

การกำหนดค่า REST และ gRPC

ตัวแปร	ค่าเริ่มต้น	ผล
NEXTPDF_BIND	0.0.0.0:8080	ที่อยู่สำหรับรับฟังของ REST
NEXTPDF_WORKER_COUNT	4	จำนวน worker ของ RoadRunner PHP
NEXTPDF_SESSIONS_ENABLED	false	เปิดใช้งานเอนด์พอยต์เซสชันแบบ stateful
NEXTPDF_CORS_ENABLED	false	เปิดใช้งานส่วนหัวการตอบกลับ CORS
NEXTPDF_API_KEYS	ไม่ได้ตั้งค่า	นิยามคีย์ API แบบ inline
NEXTPDF_API_KEYS_FILE	ไม่ได้ตั้งค่า	พาธไปยังไฟล์คีย์ API
NEXTPDF_JOB_STORE_PATH	temp ของระบบ	พาธไปยังที่จัดเก็บงาน SQLite
NEXTPDF_REDIS_HOST	ไม่ได้ตั้งค่า	เปิดใช้งานที่จัดเก็บแบบ Redis เมื่อตั้งค่าไว้

เซิร์ฟเวอร์ REST จะใช้ Redis เมื่อตั้งค่า NEXTPDF_REDIS_HOST และโหลด ext-redis แล้ว:

ตัวแปร	ค่าเริ่มต้น
NEXTPDF_REDIS_PORT	6379
NEXTPDF_REDIS_PASSWORD	ว่าง
NEXTPDF_REDIS_DATABASE	0
NEXTPDF_REDIS_PREFIX	nextpdf:
NEXTPDF_REDIS_CONNECT_TIMEOUT	2.0 วินาที
NEXTPDF_REDIS_READ_TIMEOUT	2.0 วินาที

ตัวอย่างโค้ด — เริ่มต้นอย่างรวดเร็ว

เรียกใช้เซิร์ฟเวอร์ MCP ด้วยไฟล์การกำหนดค่าที่ระบุอย่างชัดเจน:

./vendor/bin/nextpdf-mcp --config=/etc/nextpdf/nextpdf-mcp.yaml

ตัวอย่างโค้ด — การใช้งานจริง

จำกัดแคตตาล็อก MCP ด้วย allowlist ที่ระบุอย่างชัดเจน และยกระดับความเสี่ยงของเครื่องมือ:

/etc/nextpdf/nextpdf-mcp.yaml

nextpdf_mcp:
  enabled_tools:
    - create_pdf
    - add_text
    - output_pdf
    - diagnostic.doctor
  temp_directory: /var/lib/nextpdf/tmp
  max_file_size_bytes: 26214400
  risk_level_overrides:
    add_text: 2          # upgrade add_text from caution to review

เมื่อ enabled_tools มีค่า นโยบายความปลอดภัยจะรับเฉพาะชื่อเครื่องมือที่อยู่ในรายการเท่านั้น รีจิสทรีจะตัดเครื่องมืออื่นทั้งหมดออกอย่างเงียบๆ รายการที่ว่างหรือไม่มีอยู่จะรับเครื่องมือที่มีอยู่ทั้งหมด

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

• เครื่องมือสำคัญสองรายการไม่สามารถลดระดับลงได้ output_pdf และ sign_pdf ถูกออกแบบให้ต้องผ่านการอนุมัติ: รายการ risk_level_overrides ที่ลดระดับเครื่องมือใดเครื่องมือหนึ่งให้ต่ำกว่า ApprovalRequired จะโยน InvalidArgumentException ขณะโหลด และเซิร์ฟเวอร์จะปฏิเสธการบูต สามารถยกระดับ หรือ ลดระดับความเสี่ยงของเครื่องมืออื่นทุกตัวได้ ดังนั้นควรตรวจสอบการลดระดับใดๆ เทียบกับแบบจำลองภัยคุกคามของตนเอง ดู /connect/hitl-risk-tiers/

• enabled_tools กรองออก ไม่ได้เพิ่มเข้ามา การระบุชื่อเครื่องมือ Pro ขณะที่ไม่มี nextpdf/premium จะไม่ทำให้เครื่องมือนั้นปรากฏขึ้น allowlist จะถูกตัดให้เหลือเฉพาะเครื่องมือที่รีจิสทรีค้นพบจริง

• สภาพแวดล้อมมีลำดับความสำคัญเหนือ YAML สำหรับเซิร์ฟเวอร์ MCP ตัวแปร NEXTPDF_MCP_* จะแทนที่คีย์เดียวกันในไฟล์ YAML เซิร์ฟเวอร์ REST และ gRPC ไม่อ่านไฟล์ YAML ของ MCP เลย

• parse_pdf ต้องเลือกเปิดใช้ เซิร์ฟเวอร์จะลงทะเบียนเครื่องมือ parse_pdf เฉพาะเมื่อ NEXTPDF_MCP_TOOL_PARSE_PDF_ENABLED เป็น true หรือ 1 เครื่องมือนี้ไม่มีอยู่โดยค่าเริ่มต้น แม้ในแคตตาล็อก core

ประสิทธิภาพ

การกำหนดค่าจะถูกแยกวิเคราะห์เพียงครั้งเดียวขณะบูต การตั้งค่า max_documents และ document_ttl จำกัดขอบเขตของที่จัดเก็บเอกสารในหน่วยความจำ การลดค่าเหล่านี้จะลดหน่วยความจำสูงสุด แต่ทำให้อายุของเอกสารสั้นลง จำนวน worker และเพดาน payload ต่อระดับเป็นตัวควบคุมสำหรับการปรับแต่งการใช้งานจริง ซึ่งอธิบายไว้ใน /connect/deployment/

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

• ถือว่า enabled_tools เป็นการควบคุมแบบปฏิเสธโดยค่าเริ่มต้นสำหรับการใช้งานตามหลักสิทธิ์น้อยที่สุด: ระบุเฉพาะเครื่องมือที่การผสานรวมหนึ่งๆ ต้องใช้
• ห้ามเก็บคีย์ API ไว้ในไฟล์ YAML เด็ดขาด ใช้ NEXTPDF_API_KEYS_FILE กับไฟล์ที่เมานต์เป็น secret ของ Docker หรือ Kubernetes เซิร์ฟเวอร์ต้องใช้ที่จัดเก็บไฟล์ที่โหลดใหม่ได้ขณะทำงาน ดังนั้นจึงหมุนเวียนคีย์ได้โดยไม่ต้องรีสตาร์ท ดู /connect/security-and-operations/
• ค่า temp_directory คือไดเรกทอรีฐานที่บังคับใช้สำหรับการส่งออกไฟล์ เซิร์ฟเวอร์จะแปลงพาธการส่งออกให้เป็นรูปแบบมาตรฐานและปฏิเสธสิ่งใดก็ตามที่หลังจากแปลงแล้วออกไปนอกไดเรกทอรีนั้น

ความสอดคล้อง

หน้านี้อธิบายกลไกการกำหนดค่า ส่วนการอ้างอิงความสอดคล้องด้านการรับรองตัวตนและความปลอดภัยของการขนส่งถูกตรึงไว้ใน /connect/security-and-operations/

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

เพดาน payload และไทม์เอาต์ต่อระดับ (corePayloadLimit, proPayloadLimit, enterprisePayloadLimit และไทม์เอาต์ที่ตรงกัน) ใช้กับการขนส่ง REST ตามระดับของคีย์ API ที่ผ่านการรับรองตัวตน เพดานเหล่านี้จะมีผลเฉพาะเมื่อมีการติดตั้งเครื่องมือ Pro หรือ Enterprise และคีย์มีสิทธิ์ใช้เครื่องมือเหล่านั้น

ดูเพิ่มเติม

• /connect/install/ — การติดตั้งและแพ็กเกจเสริม
• /connect/boot-and-discovery/ — การกำหนดค่าถูกป้อนเข้าสู่ลำดับการบูตอย่างไร
• /connect/hitl-risk-tiers/ — แบบจำลองความเสี่ยงและการแทนที่แบบยกระดับเท่านั้น
• /connect/security-and-operations/ — การกำหนดค่าคีย์ API และความปลอดภัยของการขนส่ง
• /connect/deployment/ — จำนวน worker, Redis และเพดานต่อระดับในการใช้งานจริง