Triển khai NextPDF Connect

Tổng quan nhanh

Các transport REST và gRPC chạy trong các nhóm worker RoadRunner. Gói này có sẵn ba cấu hình RoadRunner: chỉ HTTP, chỉ gRPC và một cấu hình kết hợp. Transport MCP chạy như một tiến trình con thông thường và không cần supervisor.

Cài đặt

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

Tổng quan khái niệm

RoadRunner là bộ giám sát tiến trình. Nó quản lý nhóm worker, khởi động lại worker khi áp lực bộ nhớ tăng, và định tuyến từng yêu cầu đến một worker khả dụng. Gói PHP cung cấp điểm khởi đầu cho worker: bin/nextpdf-server cho HTTP và bin/nextpdf-grpc cho gRPC. RoadRunner bao bọc điểm khởi đầu đó trong một nhóm. Mỗi worker xử lý một yêu cầu tại một thời điểm.

Transport MCP hoạt động theo cách khác. bin/nextpdf-mcp là một tiến trình PHP đơn lẻ. Nó giao tiếp bằng JSON-RPC qua stdio, và client trực tiếp khởi chạy tiến trình này.

Bề mặt API

Các cấu hình RoadRunner

Cấu hình	Transport	Lệnh
`.rr.yaml`	Chỉ REST	`rr serve -c .rr.yaml`
`.rr.grpc.yaml`	Chỉ gRPC	`rr serve -c .rr.grpc.yaml`
`.rr.full.yaml`	REST + gRPC	`rr serve -c .rr.full.yaml`

Cấu hình HTTP gắn listener REST vào 0.0.0.0:8080. Nó cung cấp endpoint trạng thái trên :2114 và số liệu trên :2112. Kích thước nhóm worker được lấy từ NEXTPDF_WORKER_COUNT, với giá trị mặc định là bốn. Trong các cấu hình được cung cấp sẵn, supervisor giới hạn mỗi worker ở mức 256 MB.

Cấu hình kết hợp bổ sung nhóm worker gRPC trên tcp://0.0.0.0:9090. Kích thước của nhóm đó được lấy từ NEXTPDF_GRPC_WORKER_COUNT, với giá trị mặc định là hai. Cấu hình này cũng thiết lập gRPC mutual TLS.

Mã ví dụ — bắt đầu nhanh

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

Mã ví dụ — môi trường production

Chạy một container production bằng cấu hình kết hợp, khóa dựa trên tệp và kho lưu trữ dùng chung dựa trên Redis:

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

Trường hợp đặc biệt và những điểm cần lưu ý

Các kho lưu trữ trong bộ nhớ không được chia sẻ giữa các worker. Khi không có Redis, mỗi worker tự giữ kho giới hạn tốc độ, kho idempotency và kho tài liệu riêng. Trong một nhóm nhiều worker, các kho lưu trữ trong bộ nhớ khiến giới hạn tốc độ không nhất quán và có thể làm thất lạc tài liệu giữa các worker. Với bất kỳ nhóm nào có nhiều hơn một worker, hãy đặt NEXTPDF_REDIS_HOST và cài đặt ext-redis. Máy chủ tự động chuyển về dùng các kho lưu trữ trong bộ nhớ nếu kết nối Redis thất bại. Hãy kiểm tra tình trạng hoạt động của Redis; đừng cho rằng nó vẫn ổn.
Kho lưu trữ job là SQLite ở chế độ WAL. Các job bất đồng bộ được lưu vào một tệp SQLite dùng chung cho tất cả các worker HTTP và gRPC. Hãy đặt tệp đó trên một volume mà tất cả các worker đều có thể ghi vào. Khi một worker dừng, nó đánh dấu các job vẫn đang chạy của mình là thất bại theo cơ chế nỗ lực tối đa, để những job đó không bị bỏ rơi.
bin/nextpdf-prune là một điểm khởi đầu để bảo trì. Nó được cung cấp trong repository, không phải trong vendor/bin/. Hãy gọi trực tiếp điểm khởi đầu này cho các tác vụ dọn dẹp kho lưu trữ. Nó không phải là một transport của máy chủ.
Phiên bản PHP trong image có thể không có ext-redis. Dockerfile được cung cấp sẵn sẽ build ext-redis theo cơ chế nỗ lực tối đa. Nó vẫn tiếp tục mà không có extension đó nếu không có bản phát hành tương thích với PHP nền. Hãy xác nhận rằng extension đó có mặt trong image đang chạy trước khi bạn dựa vào các kho lưu trữ dựa trên Redis.

Hiệu năng

Hãy đặt NEXTPDF_WORKER_COUNT dựa trên CPU và bộ nhớ khả dụng. Mỗi worker là một tiến trình PHP bị giới hạn bởi mức trần bộ nhớ của supervisor. Với các khối lượng công việc nặng về kết xuất, hãy bắt đầu với một worker cho mỗi lõi, rồi tinh chỉnh dựa trên endpoint số liệu. Hãy đặt kích thước nhóm gRPC một cách độc lập. Nhóm này thường nhỏ hơn nhóm HTTP, vì số lượng client gRPC thường ít hơn và thời gian tồn tại lâu hơn.

Ghi chú bảo mật

gRPC mutual TLS

Cấu hình kết hợp thiết lập transport gRPC dùng Transport Layer Security (TLS) hai chiều: máy chủ xuất trình một chứng chỉ, sau đó yêu cầu và xác minh chứng chỉ của client. Hãy cung cấp khóa máy chủ, chứng chỉ máy chủ và CA của client dưới dạng secret triển khai, không nhúng sẵn vào image. Hãy tạo và xoay vòng chúng qua kênh riêng; đừng chạy transport gRPC với listener dạng văn bản thuần trên một mạng không đáng tin cậy.

Kết thúc TLS cho REST

Cấu hình REST gắn listener HTTP dạng văn bản thuần. Hãy kết thúc TLS ở phía trước nó bằng một reverse proxy, bộ cân bằng tải hoặc service mesh, và chỉ gắn listener vào mạng nội bộ. Hãy chuyển tiếp danh tính của client qua header Authorization mà không sửa đổi; máy chủ tự xác thực khóa của mình. Bản thân listener không cung cấp transport an toàn; chính cấu hình triển khai mới đảm nhiệm việc đó.

Secret

Hãy gắn các khóa API bằng NEXTPDF_API_KEYS_FILE trỏ đến một tệp secret thay vì dùng biến nội tuyến NEXTPDF_API_KEYS. Kho lưu trữ dựa trên tệp hỗ trợ tải lại nóng khi có thay đổi, nên việc xoay vòng không cần khởi động lại. Đừng bao giờ nhúng sẵn khóa hoặc tài liệu khóa riêng TLS vào image. Xem /connect/security-and-operations/.

Tuân thủ

Cơ chế triển khai không đưa ra tuyên bố mang tính quy chuẩn nào về giao thức. Các trích dẫn về xác thực và bảo mật transport được ghim trong /connect/security-and-operations/.

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

Hãy cài đặt nextpdf/premium vào image để đăng ký các công cụ Pro và Enterprise bổ sung trong chính các worker đó. Không có tiến trình hay cổng riêng nào được thêm vào. Ranh giới đóng gói được thiết lập tại thời điểm build image.

Xem thêm

/connect/configuration/ — số lượng worker, Redis và mức trần theo bậc
/connect/security-and-operations/ — TLS, mutual TLS, secret, mô hình mối đe dọa
/transports/rest/ · /transports/grpc/ — chi tiết runtime cho từng transport
/connect/production-usage/ — kiểm tra tình trạng, mở rộng quy mô và khả năng quan sát
/connect/troubleshooting/ — chẩn đoán các lỗi của worker, kho lưu trữ và xác thực