การปรับใช้ NextPDF Connect

ภาพรวมโดยสรุป

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

การติดตั้ง

composer require nextpdf/server
./vendor/bin/rr get-binary

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

RoadRunner ทำหน้าที่เป็นซูเปอร์ไวเซอร์ของโพรเซส โดยเป็นเจ้าของเวิร์กเกอร์พูล รีสตาร์ตเวิร์กเกอร์เมื่อหน่วยความจำใกล้ถึงขีดจำกัด และกำหนดเส้นทางคำขอแต่ละรายการไปยังเวิร์กเกอร์ที่ว่างอยู่ แพ็กเกจ PHP จัดเตรียมจุดเริ่มต้นของเวิร์กเกอร์ไว้ ได้แก่ bin/nextpdf-server สำหรับ HTTP และ bin/nextpdf-grpc สำหรับ gRPC RoadRunner ครอบจุดเริ่มต้นเหล่านั้นด้วยพูล เวิร์กเกอร์แต่ละตัวจัดการคำขอได้ครั้งละหนึ่งรายการ

ทรานสปอร์ต MCP ทำงานต่างออกไป bin/nextpdf-mcp เป็นโพรเซส PHP เพียงโพรเซสเดียวที่สื่อสารด้วย JSON-RPC ผ่าน stdio และไคลเอนต์จะเริ่มต้นโพรเซสนี้โดยตรง

ขอบเขตของ API

โปรไฟล์ของ RoadRunner

โปรไฟล์	ทรานสปอร์ต	คำสั่ง
.rr.yaml	REST อย่างเดียว	rr serve -c .rr.yaml
.rr.grpc.yaml	gRPC อย่างเดียว	rr serve -c .rr.grpc.yaml
.rr.full.yaml	REST + gRPC	rr serve -c .rr.full.yaml

โปรไฟล์ HTTP ผูกลิสเทนเนอร์ REST กับ 0.0.0.0:8080 โปรไฟล์นี้เปิดเอนด์พอยต์สถานะที่ :2114 และเมตริกที่ :2112 และกำหนดขนาดของเวิร์กเกอร์พูลจาก NEXTPDF_WORKER_COUNT ซึ่งมีค่าเริ่มต้นเป็นสี่ ในโปรไฟล์ที่จัดส่งมา ซูเปอร์ไวเซอร์จะจำกัดเวิร์กเกอร์แต่ละตัวไว้ที่ 256 MB

โปรไฟล์แบบรวมเพิ่มเวิร์กเกอร์พูล gRPC ที่ tcp://0.0.0.0:9090 และกำหนดขนาดของพูลดังกล่าวจาก NEXTPDF_GRPC_WORKER_COUNT ซึ่งมีค่าเริ่มต้นเป็นสอง โปรไฟล์นี้ยังกำหนดค่า gRPC mutual TLS ไว้ด้วย

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

export NEXTPDF_API_KEYS_FILE=/run/secrets/api-keys
./vendor/bin/rr serve -c .rr.full.yaml

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

รันคอนเทนเนอร์สำหรับโปรดักชันด้วยโปรไฟล์แบบรวม คีย์แบบอิงไฟล์ และที่จัดเก็บข้อมูลร่วมที่มี Redis เป็นแบ็กเอนด์:

docker/docker-compose.yml (production shape)

services:
  nextpdf-connect:
    image: ghcr.io/nextpdf-labs/server:latest
    command: ["rr", "serve", "-c", "/app/.rr.full.yaml"]
    ports:
      - "8080:8080"   # REST
      - "9090:9090"   # gRPC
    environment:
      - NEXTPDF_API_KEYS_FILE=/run/secrets/api-keys
      - NEXTPDF_WORKER_COUNT=8
      - NEXTPDF_GRPC_WORKER_COUNT=4
      - NEXTPDF_REDIS_HOST=redis
    secrets:
      - api-keys
    depends_on:
      redis:
        condition: service_healthy
    restart: unless-stopped
  redis:
    image: redis:8

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

• ที่จัดเก็บข้อมูลแบบอินเมโมรีไม่ใช้ร่วมกันระหว่างเวิร์กเกอร์ หากไม่มี Redis เวิร์กเกอร์แต่ละตัวจะมีที่จัดเก็บข้อมูลของ rate-limit idempotency และเอกสารเป็นของตนเอง ในพูลที่มีเวิร์กเกอร์หลายตัว ที่จัดเก็บข้อมูลแบบอินเมโมรีจะทำให้การจำกัดอัตราไม่สอดคล้องกันและอาจทำให้เอกสารสูญหายระหว่างเวิร์กเกอร์ สำหรับพูลใดๆ ที่ใหญ่กว่าหนึ่งเวิร์กเกอร์ ให้กำหนดค่า NEXTPDF_REDIS_HOST และติดตั้ง ext-redis หากการเชื่อมต่อ Redis ล้มเหลว เซิร์ฟเวอร์จะกลับไปใช้ที่จัดเก็บข้อมูลแบบอินเมโมรีโดยอัตโนมัติ ให้ตรวจสอบความพร้อมของ Redis อย่าสันนิษฐานเอาเอง

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

• bin/nextpdf-prune เป็นจุดเริ่มต้นสำหรับงานบำรุงรักษา เครื่องมือนี้มาพร้อมรีโพซิทอรี ไม่ได้อยู่ใน vendor/bin/ ให้เรียกใช้โดยตรงสำหรับงานตัดข้อมูลในที่จัดเก็บ เครื่องมือนี้ไม่ใช่ทรานสปอร์ตของเซิร์ฟเวอร์

• เวอร์ชัน PHP ของอิมเมจอาจไม่มี ext-redis Dockerfile ที่จัดส่งมาให้จะบิลด์ ext-redis แบบ best-effort หากไม่มีรีลีสที่เข้ากันได้กับ PHP เวอร์ชันพื้นฐาน กระบวนการจะดำเนินต่อโดยไม่มีส่วนขยายดังกล่าว ให้ตรวจสอบว่าส่วนขยายนี้มีอยู่ในอิมเมจที่กำลังทำงานก่อนพึ่งพาที่จัดเก็บข้อมูลที่มี Redis เป็นแบ็กเอนด์

ประสิทธิภาพ

ให้กำหนดค่า NEXTPDF_WORKER_COUNT ให้เหมาะกับ CPU และหน่วยความจำที่มีอยู่ เวิร์กเกอร์แต่ละตัวเป็นโพรเซส PHP ที่ถูกจำกัดด้วยเพดานหน่วยความจำของซูเปอร์ไวเซอร์ สำหรับเวิร์กโหลดที่เรนเดอร์หนัก ให้เริ่มต้นด้วยหนึ่งเวิร์กเกอร์ต่อหนึ่งคอร์ แล้วจึงปรับแต่งโดยอ้างอิงเอนด์พอยต์เมตริก ให้กำหนดขนาดพูล gRPC แยกต่างหาก โดยทั่วไปพูลนี้จะเล็กกว่าพูล HTTP เนื่องจากไคลเอนต์ gRPC มักมีจำนวนน้อยกว่าและคงการเชื่อมต่อไว้นานกว่า

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

gRPC mutual TLS แบบสองทาง

โปรไฟล์แบบรวมกำหนดค่าทรานสปอร์ต gRPC ให้ใช้ Transport Layer Security (TLS) แบบสองทาง โดยเซิร์ฟเวอร์จะแสดงใบรับรอง จากนั้นจึงกำหนดให้ต้องมีใบรับรองของไคลเอนต์และตรวจสอบใบรับรองนั้น ให้จัดเตรียมคีย์ของเซิร์ฟเวอร์ ใบรับรองของเซิร์ฟเวอร์ และ CA ของไคลเอนต์เป็นความลับสำหรับการปรับใช้งาน อย่าฝังสิ่งเหล่านี้ไว้ในอิมเมจ ให้สร้างและหมุนเวียนผ่านช่องทางแยกต่างหาก อย่ารันทรานสปอร์ต gRPC ด้วยลิสเทนเนอร์เพลนเท็กซ์บนเครือข่ายที่ไม่น่าเชื่อถือ

การยุติ TLS ของ REST

โปรไฟล์ REST ผูกลิสเทนเนอร์ HTTP แบบเพลนเท็กซ์ ให้ยุติ TLS ไว้ด้านหน้าด้วยรีเวิร์สพร็อกซี โหลดบาลานเซอร์ หรือเซอร์วิสเมช และผูกลิสเทนเนอร์ไว้กับเครือข่ายภายในเท่านั้น ให้ส่งต่ออัตลักษณ์ของไคลเอนต์ผ่านเฮดเดอร์ Authorization โดยไม่แก้ไข เซิร์ฟเวอร์จะตรวจสอบคีย์ด้วยตนเอง ความปลอดภัยของการรับส่งข้อมูลจึงมาจากการกำหนดค่าการปรับใช้งาน ไม่ได้มาจากลิสเทนเนอร์โดยตรง

ความลับ

ให้เมาต์คีย์ API โดยใช้ NEXTPDF_API_KEYS_FILE ที่ชี้ไปยังไฟล์ความลับ แทนการใช้ตัวแปรแบบอินไลน์ NEXTPDF_API_KEYS ที่จัดเก็บคีย์แบบอิงไฟล์จะรีโหลดทันทีเมื่อมีการเปลี่ยนแปลง ดังนั้นการหมุนเวียนจึงไม่ต้องรีสตาร์ต อย่าฝังคีย์หรือข้อมูลลับส่วนตัวของ TLS ไว้ในอิมเมจเด็ดขาด ดู /connect/security-and-operations/

การปฏิบัติตามมาตรฐาน

กลไกการปรับใช้งานไม่ได้ระบุข้อกล่าวอ้างเชิงกำหนดเกี่ยวกับโปรโตคอลใดๆ การอ้างอิงด้านการพิสูจน์ตัวตนและความปลอดภัยของทรานสปอร์ตระบุไว้ที่ /connect/security-and-operations/

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

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

ดูเพิ่มเติม

• /connect/configuration/ — จำนวนเวิร์กเกอร์ การตั้งค่า Redis และเพดานของแต่ละระดับ
• /connect/security-and-operations/ — TLS, mutual TLS, ความลับ และแบบจำลองภัยคุกคาม
• /transports/rest/ · /transports/grpc/ — รายละเอียดรันไทม์ของแต่ละทรานสปอร์ต
• /connect/production-usage/ — โพรบตรวจสอบความพร้อม การปรับขนาด และการสังเกตการณ์
• /connect/troubleshooting/ — การวินิจฉัยความล้มเหลวของเวิร์กเกอร์ ที่จัดเก็บข้อมูล และการพิสูจน์ตัวตน