Deployment NextPDF Connect

Sekilas pandang

Transport REST dan gRPC berjalan di dalam pool worker RoadRunner. Paket ini menyertakan tiga profil RoadRunner: HTTP saja, gRPC saja, dan profil gabungan. Transport MCP berjalan sebagai subproses biasa dan tidak memerlukan supervisor.

Pemasangan

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

Gambaran konseptual

RoadRunner adalah supervisor proses. RoadRunner mengelola pool worker, memulai ulang worker saat tekanan memori tinggi, dan merutekan setiap permintaan ke worker yang tersedia. Paket PHP menyediakan titik masuk worker: bin/nextpdf-server untuk HTTP, dan bin/nextpdf-grpc untuk gRPC. RoadRunner menjalankan titik masuk tersebut di dalam pool. Setiap worker menangani satu permintaan dalam satu waktu.

Transport MCP bekerja secara berbeda. bin/nextpdf-mcp adalah satu proses PHP tunggal. Proses ini berkomunikasi dengan JSON-RPC melalui stdio, dan klien menjalankannya secara langsung.

Permukaan API

Profil RoadRunner

Profil	Transport	Perintah
`.rr.yaml`	REST saja	`rr serve -c .rr.yaml`
`.rr.grpc.yaml`	gRPC saja	`rr serve -c .rr.grpc.yaml`
`.rr.full.yaml`	REST + gRPC	`rr serve -c .rr.full.yaml`

Profil HTTP mengikat listener REST ke 0.0.0.0:8080. Profil ini mengekspos endpoint status di :2114 dan metrik di :2112. Profil ini menentukan ukuran pool worker dari NEXTPDF_WORKER_COUNT, dengan nilai standar empat. Pada profil bawaan, supervisor membatasi setiap worker hingga 256 MB.

Profil gabungan menambahkan pool worker gRPC pada tcp://0.0.0.0:9090. Profil ini menentukan ukuran pool tersebut dari NEXTPDF_GRPC_WORKER_COUNT, dengan nilai standar dua. Profil ini juga mengonfigurasi mutual TLS gRPC.

Contoh kode — Mulai cepat

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

Contoh kode — Produksi

Jalankan kontainer produksi dengan profil gabungan, kunci berbasis berkas, dan store bersama berbasis 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

Kasus tepi dan jebakan

Store in-memory tidak dibagikan lintas worker. Tanpa Redis, setiap worker menyimpan store rate-limit, idempotensi, dan dokumennya sendiri. Dalam pool multi-worker, store in-memory menghasilkan pembatasan laju yang tidak konsisten dan dapat membuat dokumen tidak tersedia lintas worker. Untuk pool apa pun yang lebih besar dari satu worker, atur NEXTPDF_REDIS_HOST dan pasang ext-redis. Server secara otomatis beralih ke store in-memory jika koneksi Redis gagal. Verifikasi kesehatan Redis; jangan berasumsi.
Store job menggunakan SQLite dalam mode WAL. Job asinkron disimpan secara persisten dalam satu berkas SQLite yang dibagikan oleh semua worker HTTP dan gRPC. Tempatkan berkas tersebut pada volume yang dapat ditulisi oleh semua worker. Saat worker dimatikan, worker menandai job yang masih berjalan sebagai gagal secara best-effort, sehingga job tersebut tidak tertinggal sebagai job yatim.
bin/nextpdf-prune adalah titik masuk pemeliharaan. Titik masuk ini disertakan dalam repositori, bukan di vendor/bin/. Panggil secara langsung untuk tugas pemangkasan store. Ini bukan transport server.
Versi PHP pada image mungkin tidak memiliki ext-redis. Dockerfile bawaan membangun ext-redis secara best-effort. Proses berlanjut tanpa ekstensi tersebut jika tidak ada rilis yang kompatibel untuk PHP dasar. Pastikan ekstensi tersebut ada di image yang sedang berjalan sebelum Anda mengandalkan store berbasis Redis.

Performa

Atur NEXTPDF_WORKER_COUNT sesuai CPU dan memori yang tersedia. Setiap worker adalah proses PHP yang dibatasi oleh batas atas memori supervisor. Untuk beban kerja rendering yang berat, mulailah dengan satu worker per core, lalu sesuaikan berdasarkan endpoint metrik. Tentukan ukuran pool gRPC secara terpisah. Pool ini biasanya lebih kecil daripada pool HTTP, karena klien gRPC umumnya lebih sedikit dan koneksinya bertahan lebih lama.

Catatan keamanan

Mutual TLS gRPC

Profil gabungan mengonfigurasi transport gRPC untuk mutual Transport Layer Security (TLS): server menyediakan sertifikat, lalu mewajibkan dan memverifikasi sertifikat klien. Sediakan kunci server, sertifikat server, dan CA klien sebagai secret deployment, bukan ditanamkan ke dalam image. Buat dan rotasikan secara out-of-band; jangan jalankan transport gRPC dengan listener plaintext pada jaringan yang tidak tepercaya.

Terminasi TLS REST

Profil REST mengikat listener HTTP plaintext. Terminasikan TLS di depannya dengan reverse proxy, load balancer, atau service mesh, dan ikat listener hanya ke jaringan internal. Teruskan identitas klien melalui header Authorization tanpa perubahan; server melakukan validasi kuncinya sendiri. Listener itu sendiri tidak menyediakan transport yang aman; konfigurasi deployment inilah yang menyediakannya.

Secret

Sediakan API key melalui NEXTPDF_API_KEYS_FILE yang menunjuk ke berkas secret alih-alih menggunakan variabel inline NEXTPDF_API_KEYS. Store berbasis berkas melakukan hot-reload saat terjadi perubahan, sehingga rotasi tidak memerlukan restart. Jangan pernah menanam kunci atau materi privat TLS ke dalam image. Lihat /connect/security-and-operations/.

Konformitas

Mekanisme deployment tidak membuat klaim protokol normatif. Sitasi autentikasi dan keamanan transport dicantumkan di /connect/security-and-operations/.

Konteks komersial

Pasang nextpdf/premium ke dalam image untuk mendaftarkan alat Pro dan Enterprise tambahan di dalam worker yang sama. Tidak ada proses atau port terpisah yang terlibat. Batas pengemasan ditetapkan pada saat build image.

Lihat juga

/connect/configuration/ — jumlah worker, Redis, dan batas atas tier
/connect/security-and-operations/ — TLS, mutual TLS, secret, model ancaman
/transports/rest/ · /transports/grpc/ — detail runtime per transport
/connect/production-usage/ — health probe, penskalaan, dan observabilitas
/connect/troubleshooting/ — mendiagnosis kegagalan worker, store, dan autentikasi