การใช้งาน NextPDF Connect ในระบบจริง

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

การดีพลอย NextPDF Connect สำหรับระบบจริงมีกลไกควบคุมการทำงานหลายอย่าง ได้แก่ โพรบตรวจสอบสถานะและความพร้อม เส้นทางการเรนเดอร์แบบซิงโครนัสและอะซิงโครนัส idempotency การจำกัดอัตราต่อไคลเอนต์และต่อ Internet Protocol (IP) และเซสชันแบบมีสถานะที่เลือกเปิดใช้ได้ ใช้หน้านี้เป็นแนวทางเพื่อให้กลไกเหล่านี้ทำงานด้วยพฤติกรรมที่คาดการณ์ได้

การติดตั้ง

composer require nextpdf/server

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

ทรานสปอร์ต Representational State Transfer (REST) ทำงานเป็นไปป์ไลน์มิดเดิลแวร์ตามมาตรฐาน PHP Standards Recommendation (PSR)-15 แต่ละคำขอจะผ่านมิดเดิลแวร์ตามลำดับ ได้แก่ การกำหนด request-id การจำกัดขนาดเนื้อหา (body-size) Cross-Origin Resource Sharing (CORS) การยืนยันตัวตน การอนุญาตตามความสามารถ (capability authorization) การจำกัดอัตรา idempotency และไทม์เอาต์ จากนั้นคำขอจึงไปถึงตัวจัดการ (handler) ทรานสปอร์ต gRPC นำบริการแอปพลิเคชันชุดเดียวกันมาใช้เบื้องหลังเวิร์กเกอร์ gRPC ของ RoadRunner

การเรนเดอร์มีสองเส้นทาง คำขอแบบ ซิงโครนัส POST /api/v1/render จะประมวลผลการดำเนินการต่างๆ และส่งไฟล์ Portable Document Format (PDF) กลับในการตอบสนอง งานแบบ อะซิงโครนัส ใช้ POST /api/v1/jobs คำขอนี้จะตอบกลับทันทีพร้อม job id และสามารถดึงผลลัพธ์ได้ภายหลังจาก GET /api/v1/jobs/{id}/result งานจะถูกเก็บไว้ในที่เก็บข้อมูล SQLite ที่ใช้ร่วมกัน ดังนั้นเวิร์กเกอร์ใดก็ตามจึงตอบคำขอสอบถามสถานะหรือผลลัพธ์ได้

ขอบเขตของ API

สถานะและความพร้อม

เอนด์พอยต์	การยืนยันตัวตน	ความหมาย
GET /healthz	ไม่มี	โปรเซสกำลังทำงานอยู่
GET /readyz	ไม่มี	เซิร์ฟเวอร์พร้อมรับคำขอแล้ว

เชื่อมต่อ /healthz เข้ากับโพรบตรวจสอบการทำงาน (liveness) และ /readyz เข้ากับโพรบตรวจสอบความพร้อม (readiness) เอนด์พอยต์ทั้งสองไม่ต้องระบุตัวตน ดังนั้นออร์เคสเตรเตอร์จึงไม่จำเป็นต้องใช้ข้อมูลรับรอง

งานแบบอะซิงโครนัส

เอนด์พอยต์	เมท็อด	วัตถุประสงค์
/api/v1/jobs	POST	ส่งงานเรนเดอร์
/api/v1/jobs/{id}	GET	สถานะของงาน
/api/v1/jobs/{id}/result	GET	ผลลัพธ์ของงาน (ไฟล์ PDF)
/api/v1/jobs/{id}	DELETE	ยกเลิกงาน

เซสชัน (เลือกเปิดใช้งาน)

เมื่อ NEXTPDF_SESSIONS_ENABLED เป็น true และมีเครื่องมือพร้อมใช้งาน เอนด์พอยต์เซสชันจะมอบกระบวนการสร้างเอกสารแบบมีสถานะ สามารถสร้างเซสชัน เพิ่มหน้า ข้อความ รูปภาพ ตาราง และ HyperText Markup Language (HTML) กำหนดฟอนต์ แล้วจึงเรนเดอร์ เซสชันมีขีดจำกัดต่อไคลเอนต์และไทม์เอาต์เมื่อไม่มีการใช้งาน (idle) เซสชันถูกปิดไว้ตามค่าเริ่มต้น

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

ส่งงานแบบอะซิงโครนัสแล้วตรวจสอบซ้ำ (poll) เพื่อรับผลลัพธ์:

JOB=$(curl -sS -X POST http://localhost:8080/api/v1/jobs \
  -H "Authorization: Bearer $NEXTPDF_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"operations":[{"type":"add_text","text":"async render"}]}' \
  | python3 -c 'import sys,json;print(json.load(sys.stdin)["id"])')

curl -sS "http://localhost:8080/api/v1/jobs/$JOB/result" \
  -H "Authorization: Bearer $NEXTPDF_KEY" --output out.pdf

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

ทำให้การส่งคำขอรองรับการลองใหม่อย่างปลอดภัยโดยส่งคีย์ idempotency:

curl -sS -X POST http://localhost:8080/api/v1/jobs \
  -H "Authorization: Bearer $NEXTPDF_KEY" \
  -H 'Idempotency-Key: 7b1c2d3e-…' \
  -H 'Content-Type: application/json' \
  -d '{"operations":[{"type":"add_text","text":"safe retry"}]}'

คำขอที่ส่งซ้ำด้วยคีย์ idempotency เดียวกันจะคืนผลลัพธ์เดิมแทนที่จะสร้างงานชิ้นที่สอง พฤติกรรมนี้ทำให้ส่งคำขอซ้ำหลังจากการสื่อสารล้มเหลวได้อย่างปลอดภัย และสอดคล้องกับคุณสมบัติของเมท็อดแบบ idempotent คือการส่งคำขอเดียวกันอีกครั้งจะให้ผลตามเจตนาเดียวกับการส่งเพียงครั้งเดียว (RFC 9110 §9.2.2) คำขอจึงสามารถถูกลองใหม่โดยอัตโนมัติได้หากการเชื่อมต่อหลุดก่อนที่ไคลเอนต์จะอ่านการตอบสนอง (RFC 9110 §9.2.2)

กรณีพิเศษและข้อควรระวัง

• การจำกัดอัตราต้องใช้ Redis เพื่อให้ถูกต้องในทุกเวิร์กเกอร์ ตัวจำกัดต่อไคลเอนต์และต่อ IP ใช้ที่เก็บข้อมูลที่กำหนดค่าไว้ เมื่อใช้ที่เก็บข้อมูล in-memory และมีเวิร์กเกอร์มากกว่าหนึ่งตัว เวิร์กเกอร์แต่ละตัวจะนับคำขอแยกกัน และขีดจำกัดที่มีผลจริงจะถูกคูณด้วยจำนวนเวิร์กเกอร์ ใช้ที่เก็บข้อมูล Redis สำหรับพูลที่มีหลายเวิร์กเกอร์ทุกกรณี

• คำขอที่ถูกจำกัด (throttled) จะคืนค่า 429 เมื่อเกินขีดจำกัด เซิร์ฟเวอร์จะตอบกลับด้วย 429 Too Many Requests และเฮดเดอร์ Retry-After ตามความหมายของสถานะการจำกัดอัตรา (RFC 6585 §4) ให้ปฏิบัติตาม Retry-After อย่าลองใหม่ทันที

• ผลลัพธ์ของงานไม่ได้ถูกเก็บไว้ตลอดไป ที่เก็บข้อมูลงานจะลบรายการเก่าออก (garbage-collect) หลังจาก NEXTPDF_JOB_GC_MAX_AGE_SECONDS ดึงผลลัพธ์ก่อนหมดอายุ

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

ประสิทธิภาพ

เส้นทางแบบซิงโครนัสจะใช้เวิร์กเกอร์ค้างไว้ตลอดการเรนเดอร์ทั้งหมด สำหรับการเรนเดอร์ที่มีขนาดใหญ่หรือช้า ให้ใช้เส้นทางงานแบบอะซิงโครนัส เส้นทางนี้จะปล่อยเวิร์กเกอร์ทันที และไคลเอนต์จะตรวจสอบซ้ำ (poll) เพื่อรับผลลัพธ์ กำหนดขนาดพูลเวิร์กเกอร์ตามค่าหน่วงเวลา (latency) ของการเรนเดอร์และระดับการทำงานพร้อมกัน (concurrency) ที่สังเกตได้ เฝ้าติดตามเอนด์พอยต์เมตริกของ RoadRunner

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

เอนด์พอยต์ทั้งหมด ยกเว้นโพรบตรวจสอบสถานะ ต้องใช้คีย์ application programming interface (API) ที่ถูกต้อง ระดับ (tier) ของไคลเอนต์ควบคุมว่าการดำเนินการและขนาดเพย์โหลดใดได้รับอนุญาต ไคลเอนต์เป็นฝ่ายส่งคีย์ idempotency ให้ถือว่าคีย์แต่ละตัวเป็นค่าทึบ (opaque) และไม่ซ้ำกันสำหรับการดำเนินการเชิงตรรกะหนึ่งรายการ ดู /connect/security-and-operations/

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

ข้อกล่าวอ้าง	แหล่งอ้างอิง	reference_id
Idempotent: คำขอที่ส่งซ้ำให้ผลเทียบเท่าการส่งครั้งเดียว	RFC 9110 §9.2.2
คำขอแบบ idempotent สามารถลองใหม่ได้หลังเกิดความล้มเหลว	RFC 9110 §9.2.2
429 + Retry-After สำหรับการจำกัดอัตรา	RFC 6585 §4

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

คีย์ Pro และ Enterprise จะได้รับขีดจำกัดสูงสุดของขนาดเพย์โหลดและไทม์เอาต์ต่อระดับที่สูงขึ้นเมื่อมีการติดตั้งเครื่องมือเหล่านั้น การดีพลอยตามค่าเริ่มต้นจะใช้ขีดจำกัดของระดับ core

ดูเพิ่มเติม

• /connect/deployment/ — พูลเวิร์กเกอร์ Redis และโปรไฟล์ RoadRunner
• /transports/rest/ — ไปป์ไลน์มิดเดิลแวร์ทั้งหมดและสัญญา OpenAPI
• /connect/troubleshooting/ — การวินิจฉัย 401/403/413/429/5xx และความล้มเหลวของที่เก็บข้อมูล
• /connect/security-and-operations/ — การยืนยันตัวตนและแนวทางการจำกัดอัตรา