Üretimde NextPDF Connect

Bir bakışta

Üretime yönelik bir NextPDF Connect dağıtımı çeşitli işletim denetimleri sunar: sağlık ve hazırlık denetimleri, eşzamanlı ve eşzamansız işleme yolları, eşgüçlülük, istemci başına ve İnternet Protokolü (IP) başına hız sınırları ve isteğe bağlı durum bilgili oturumlar. Bunları öngörülebilir davranış sağlayacak şekilde çalıştırmak için bu sayfayı kullanın.

Kurulum

composer require nextpdf/server

Kavramsal genel bakış

Temsili Durum Aktarımı (REST) taşıyıcısı, bir PHP Standartları Önerisi (PSR)-15 ara katman yazılımı işlem hattıdır. Her istek, ara katman yazılımında sırayla şu adımlardan geçer: istek kimliği ataması, gövde boyutu sınırları, Kaynaklar Arası Köken Paylaşımı (CORS), kimlik doğrulama, yetenek yetkilendirme, hız sınırlama, eşgüçlülük ve zaman aşımı. Ardından istek bir işleyiciye ulaşır. gRPC taşıyıcısı, RoadRunner gRPC çalışanının arkasında aynı uygulama hizmetlerini yeniden kullanır.

İşlemenin iki yolu vardır. Eşzamanlı yol, POST /api/v1/render ile işlemleri çalıştırır ve Taşınabilir Belge Biçimi (PDF) dosyasını yanıtta döndürür. Eşzamansız iş yolu POST /api/v1/jobs kullanır. Hemen bir iş kimliği döndürür ve sonucu daha sonra GET /api/v1/jobs/{id}/result adresinden alırsınız. İşler paylaşılan bir SQLite deposunda kalıcı hale getirilir, böylece herhangi bir çalışan durum veya sonuç sorgularını yanıtlayabilir.

API yüzeyi

Sağlık ve hazırlık

Uç nokta	Kimlik doğrulama	Anlamı
`GET /healthz`	yok	Süreç çalışıyor
`GET /readyz`	yok	Sunucu istekleri kabul etmeye hazır

Canlılık denetimi için /healthz uç noktasını, hazırlık denetimi için /readyz uç noktasını bağlayın. Her iki uç nokta da anonimdir, bu nedenle orkestratörlerin kimlik bilgilerine ihtiyacı yoktur.

Eşzamansız işler

Uç nokta	Yöntem	Amaç
`/api/v1/jobs`	`POST`	Bir işleme işi gönderin
`/api/v1/jobs/{id}`	`GET`	İş durumu
`/api/v1/jobs/{id}/result`	`GET`	İş sonucu (PDF)
`/api/v1/jobs/{id}`	`DELETE`	Bir işi iptal edin

Oturumlar (isteğe bağlı)

Eğer NEXTPDF_SESSIONS_ENABLED değeri true ise ve araçlar mevcutsa, oturum uç noktaları durum bilgili bir oluşturma akışı sağlar. Bir oturum oluşturur; sayfalar, metin, görüntüler, tablolar ve Köprü Metni İşaretleme Dili (HTML) ekler; yazı tipini ayarlar ve ardından işlersiniz. Oturumların istemci başına bir üst sınırı ve bir boşta kalma zaman aşımı vardır. Varsayılan olarak kapalıdır.

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

Eşzamansız bir iş gönderin ve sonucu yoklayın:

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

Kod örneği — üretim

Bir eşgüçlülük anahtarı göndererek gönderimi güvenle yeniden denenebilir hale getirin:

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"}]}'

Aynı eşgüçlülük anahtarıyla yeniden gönderilen bir istek, ikinci bir iş oluşturmak yerine özgün sonucu döndürür. Bu, bir iletişim hatasından sonra gönderimi yinelemeyi güvenli hale getirir. Bu davranış, eşgüçlü bir yöntemin sağladığı özellikle örtüşür: aynı isteği yeniden göndermenin amaçlanan etkisi, bir kez göndermekle aynıdır (RFC 9110 §9.2.2). Bu nedenle, istemci yanıtı okumadan bağlantı kesilirse istek otomatik olarak yeniden denenebilir (RFC 9110 §9.2.2).

Uç durumlar ve dikkat edilmesi gerekenler

Hız sınırlamanın çalışanlar genelinde doğru olması için Redis gerekir. İstemci başına ve IP başına sınırlayıcılar, yapılandırılan depoyu kullanır. Bellek içi depo birden fazla çalışanla kullanıldığında her çalışan istekleri bağımsız olarak sayar ve etkin sınır çalışan sayısıyla çarpılır. Çok çalışanlı herhangi bir havuz için Redis deposunu kullanın.
Sınırlandırılan bir istek 429 döndürür. Bir sınır aşıldığında sunucu, hız sınırlama durum semantiğine uygun olarak 429 Too Many Requests ve bir Retry-After başlığı ile yanıt verir (RFC 6585 §4). Retry-After başlığına uyun; hemen yeniden denemeyin.
İş sonuçları sonsuz değildir. İş deposu, NEXTPDF_JOB_GC_MAX_AGE_SECONDS süresinden sonra eski girdileri çöp toplama ile temizler. Sonuçları, süreleri dolmadan önce alın.
Oturumlar bellek tüketir. Bir oturum, devam etmekte olan bir belgeyi tutar. İstemci başına oturum üst sınırı ve boşta kalma zaman aşımı bu maliyeti sınırlar. En kötü duruma göre belleği boyutlandırmadan bunları artırmayın.

Performans

Eşzamanlı yol, tüm işleme boyunca bir çalışanı meşgul tutar. Büyük veya yavaş işlemeler için eşzamansız iş yolunu kullanın. Bu yol çalışanı hemen serbest bırakır ve istemci sonucu yoklar. Çalışan havuzunu, gözlemlenen işleme gecikmesine ve eşzamanlılığa göre boyutlandırın. RoadRunner ölçüm uç noktasını izleyin.

Güvenlik notları

Sağlık denetimleri dışındaki her uç nokta, geçerli bir API anahtarı gerektirir. İstemcinin kademesi, hangi işlemlere ve yük boyutlarına izin verildiğini denetler. İstemciler eşgüçlülük anahtarlarını sağlar. Her anahtarı opak ve tek bir mantıksal işleme özgü olarak ele alın. Bkz. /connect/security-and-operations/.

Uyumluluk

İddia	Kaynak	`reference_id`
Eşgüçlü: yinelenen istekler = tek bir etki	RFC 9110 §9.2.2
Eşgüçlü istekler hata sonrası yeniden denenebilir	RFC 9110 §9.2.2
`429` + `Retry-After` ile hız sınırlama	RFC 6585 §4

Ticari bağlam

Pro ve Enterprise anahtarları, ilgili araçlar kurulu olduğunda kademe başına daha yüksek yük ve zaman aşımı üst sınırlarına sahip olur. Varsayılan bir dağıtım, core kademesi üst sınırlarını kullanır.

Ayrıca bkz.

/connect/deployment/ — çalışan havuzları, Redis, RoadRunner profilleri
/transports/rest/ — tam ara katman yazılımı işlem hattı ve OpenAPI sözleşmesi
/connect/troubleshooting/ — 401/403/413/429/5xx ve depo hatalarının tanılanması
/connect/security-and-operations/ — kimlik doğrulama ve hız sınırı yaklaşımı