NextPDF Connect dağıtımı

Bir bakışta

REST ve gRPC aktarımları RoadRunner çalışan havuzlarında çalışır. Paket üç RoadRunner profili içerir: yalnızca HTTP, yalnızca gRPC ve birleşik bir profil. MCP aktarımı doğrudan bir alt süreç olarak çalışır ve gözetmen gerektirmez.

Kurulum

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

Kavramsal genel bakış

RoadRunner bir süreç gözetmenidir. Çalışan havuzunu yönetir, bellek baskısı oluştuğunda çalışanları yeniden başlatır ve her isteği uygun çalışana yönlendirir. PHP paketi çalışan giriş noktalarını sağlar: HTTP için bin/nextpdf-server ve gRPC için bin/nextpdf-grpc. RoadRunner, bu giriş noktalarını ilgili havuzlarla sarmalar. Her çalışan aynı anda yalnızca bir isteği işler.

MCP aktarımı farklı şekilde çalışır. bin/nextpdf-mcp tek bir PHP sürecidir. stdio üzerinden JSON-RPC ile iletişim kurar ve istemci onu doğrudan başlatır.

API yüzeyi

RoadRunner profilleri

Profil	Aktarımlar	Komut
`.rr.yaml`	yalnızca REST	`rr serve -c .rr.yaml`
`.rr.grpc.yaml`	yalnızca gRPC	`rr serve -c .rr.grpc.yaml`
`.rr.full.yaml`	REST + gRPC	`rr serve -c .rr.full.yaml`

HTTP profili, REST dinleyicisini 0.0.0.0:8080 adresine bağlar. :2114 üzerinde bir durum uç noktası ve :2112 üzerinde ölçümleri sunar. Çalışan havuzunu, varsayılanı dört olan NEXTPDF_WORKER_COUNT değerine göre boyutlandırır. Paketle gelen profillerde gözetmen, her çalışanı 256 MB ile sınırlar.

Birleşik profil, gRPC çalışan havuzunu tcp://0.0.0.0:9090 üzerine ekler. Bu havuzu, varsayılanı iki olan NEXTPDF_GRPC_WORKER_COUNT değerine göre boyutlandırır. Ayrıca gRPC karşılıklı TLS’yi yapılandırır.

Kod örneği — hızlı başlangıç

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

Kod örneği — üretim

Üretim konteynerini birleşik profil, dosya tabanlı anahtarlar ve Redis destekli paylaşımlı depolarla çalıştırın:

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

Uç durumlar ve dikkat edilmesi gerekenler

Bellek içi depolar çalışanlar arasında paylaşılmaz. Redis olmadan her çalışan kendi hız sınırlaması, idempotency ve belge depolarını tutar. Birden çok çalışana sahip bir havuzda bellek içi depolar tutarsız hız sınırlamasına yol açar ve belgelerin çalışanlar arasında kaybolmasına neden olabilir. Tek çalışandan büyük her havuz için NEXTPDF_REDIS_HOST değerini ayarlayın ve ext-redis kurun. Redis bağlantısı başarısız olursa sunucu otomatik olarak bellek içi depolara geri döner. Redis sağlığını varsaymayın; doğrulayın.
İş deposu, WAL modunda SQLite’dır. Eşzamansız işler, tüm HTTP ve gRPC çalışanlarının paylaştığı tek bir SQLite dosyasında saklanır. Bu dosyayı tüm çalışanların yazabileceği bir birime yerleştirin. Bir çalışan kapandığında, devam eden işlerini mümkün olduğunca başarısız olarak işaretler, böylece bu işler sahipsiz kalmaz.
bin/nextpdf-prune bir bakım giriş noktasıdır. vendor/bin/ içinde değil, depoyla birlikte gelir. Depo budama görevleri için doğrudan çağırın. Bir sunucu aktarımı değildir.
Görüntünün PHP sürümünde ext-redis bulunmayabilir. Paketle gelen Dockerfile, ext-redis uzantısını mümkün olduğunda der. Temel PHP için uyumlu bir sürüm yoksa uzantı olmadan devam eder. Redis destekli depolara güvenmeden önce uzantının çalıştırılan görüntüde mevcut olduğunu doğrulayın.

Performans

Mevcut CPU ve belleğe göre NEXTPDF_WORKER_COUNT değerini ayarlayın. Her çalışan, gözetmenin bellek tavanıyla sınırlanan bir PHP sürecidir. Yoğun işlem gerektiren iş yükleri için çekirdek başına bir çalışanla başlayın, ardından ölçüm uç noktasından gelen verilere göre ince ayar yapın. gRPC havuzunu bağımsız olarak boyutlandırın. gRPC istemcileri genellikle daha az sayıda olur ve daha uzun ömürlüdür; bu nedenle bu havuz tipik olarak HTTP havuzundan daha küçüktür.

Güvenlik notları

gRPC karşılıklı TLS

Birleşik profil, gRPC aktarımını karşılıklı TLS için yapılandırır: sunucu bir sertifika sunar, ardından bir istemci sertifikası ister ve doğrular. Sunucu anahtarını, sunucu sertifikasını ve istemci CA’sını görüntüye gömmek yerine dağıtım sırları olarak sağlayın. Bunları bant dışında oluşturun ve döndürün; gRPC aktarımını güvenilmeyen bir ağda düz metin dinleyiciyle çalıştırmayın.

REST TLS sonlandırma

REST profili, düz metin bir HTTP dinleyicisi bağlar. TLS’yi bunun önünde bir ters proxy, yük dengeleyici veya hizmet ağı ile sonlandırın ve dinleyiciyi yalnızca dahili ağa bağlayın. İstemci kimliğini Authorization başlığı aracılığıyla değiştirmeden iletin; sunucu kendi anahtar doğrulamasını gerçekleştirir. Dinleyici tek başına güvenli aktarım sağlamaz; güvenli aktarımı bu dağıtım yapılandırması sağlar.

Sırlar

API anahtarlarını, bir sır dosyasına işaret eden NEXTPDF_API_KEYS_FILE ile bağlayın; satır içi NEXTPDF_API_KEYS değişkenini kullanmayın. Dosya tabanlı depo değişiklik olduğunda anında yeniden yüklenir, bu nedenle döndürme için yeniden başlatma gerekmez. Anahtarları veya TLS özel materyalini asla görüntüye gömmeyin. Bkz. /connect/security-and-operations/.

Uygunluk

Dağıtım mekaniği, normatif protokol iddiasında bulunmaz. Kimlik doğrulama ve aktarım güvenliği alıntıları /connect/security-and-operations/ sayfasına sabitlenmiştir.

Ticari bağlam

Ek Pro ve Enterprise araçlarını aynı çalışanların içinde kaydetmek için nextpdf/premium paketini görüntüye kurun. Ayrı bir süreç veya bağlantı noktası söz konusu değildir. Görüntü derleme zamanında paketleme sınırını siz belirlersiniz.

Ayrıca bkz.

/connect/configuration/ — çalışan sayısı, Redis ve katman tavanları
/connect/security-and-operations/ — TLS, karşılıklı TLS, sırlar, tehdit modeli
/transports/rest/ · /transports/grpc/ — her aktarım için çalışma zamanı ayrıntıları
/connect/production-usage/ — sağlık yoklamaları, ölçeklendirme ve gözlemlenebilirlik
/connect/troubleshooting/ — çalışan, depo ve kimlik doğrulama hatalarını teşhis etme