프로덕션 환경에서의 NextPDF Connect

한눈에 보기

프로덕션 NextPDF Connect 배포에서는 여러 운영 인터페이스를 제공합니다. 상태 및 준비 상태 프로브, 동기 및 비동기 렌더링 경로, 멱등성 제어, 클라이언트별 및 IP별 속도 제한, 선택적 상태 저장 세션이 이에 해당합니다. 이 페이지에서는 이러한 인터페이스를 운영하는 방법을 설명합니다.

설치

composer require nextpdf/server

개념 개요

REST 전송 계층은 PSR-15 미들웨어 파이프라인입니다. 각 요청은 요청 ID 할당, 본문 크기 제한, CORS, 인증, 기능 권한 부여, 속도 제한, 멱등성, 타임아웃 순서로 미들웨어를 통과한 뒤 핸들러에 도달합니다. gRPC 전송 계층은 RoadRunner gRPC 워커 뒤에서 동일한 애플리케이션 서비스를 재사용합니다.

렌더링에는 두 가지 방식이 있습니다. 동기 POST /api/v1/render 요청은 작업을 실행하고 응답으로 PDF를 반환합니다. 비동기 작업은 POST /api/v1/jobs를 사용합니다. 이 요청은 작업 ID와 함께 즉시 반환되며, 이후 GET /api/v1/jobs/{id}/result에서 결과를 가져옵니다. 작업은 공유 SQLite 저장소에 유지되므로 어떤 워커든 상태 또는 결과 조회를 처리할 수 있습니다.

API 인터페이스

상태 및 준비 상태

엔드포인트	인증	의미
GET /healthz	없음	프로세스가 살아 있음
GET /readyz	없음	서버가 요청을 받을 준비가 되어 있음

각각 /healthz를 활성 상태(liveness) 프로브에 연결하고 /readyz를 준비 상태(readiness) 프로브에 연결하세요. 두 엔드포인트 모두 익명으로 호출할 수 있으므로 오케스트레이터에 자격 증명이 필요하지 않습니다.

비동기 작업

엔드포인트	메서드	용도
/api/v1/jobs	POST	렌더링 작업 제출
/api/v1/jobs/{id}	GET	작업 상태 조회
/api/v1/jobs/{id}/result	GET	작업 결과(PDF) 가져오기
/api/v1/jobs/{id}	DELETE	작업 취소

세션(옵트인)

환경 변수 NEXTPDF_SESSIONS_ENABLED가 true이고 도구를 사용할 수 있으면, 세션 엔드포인트가 상태 저장 빌드를 제공합니다. 세션을 만들고 페이지, 텍스트, 이미지, 표, HTML을 추가하고 글꼴을 설정한 다음 렌더링합니다. 세션에는 클라이언트별 상한과 유휴 타임아웃이 있습니다. 세션은 기본적으로 비활성화되어 있습니다.

코드 예제 — 빠른 시작

비동기 작업을 제출하고 결과를 폴링합니다.

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

코드 예제 — 프로덕션

멱등성 키를 전송해 제출을 안전하게 재시도할 수 있게 하세요.

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

동일한 멱등성 키로 재전송된 요청은 두 번째 작업을 생성하는 대신 원래 결과를 반환합니다. 이를 통해 통신 실패 후에도 제출을 안전하게 반복할 수 있습니다. 이러한 안전성은 멱등 메서드의 속성에서 나옵니다. 요청을 반복해도 한 번 전송한 것과 동일한 의도된 효과가 발생하므로(RFC 9110 §9.2.2), 응답을 읽기 전에 연결이 끊어지면 요청을 자동으로 재시도할 수 있습니다(RFC 9110 §9.2.2).

엣지 케이스 및 주의사항

• 속도 제한이 여러 워커에서 정확하게 작동하려면 Redis가 필요합니다. 클라이언트별 및 IP별 제한기는 구성된 저장소를 사용합니다. 인메모리 저장소를 사용하면서 워커가 두 개 이상이면 각 워커가 독립적으로 카운트하므로 실질적인 제한값이 워커 수만큼 곱해집니다. 멀티 워커 풀에서는 Redis 저장소를 사용하세요.

• 스로틀링된 요청은 429를 반환합니다. 제한을 초과하면 서버는 속도 제한 상태 의미 체계에 따라 429 Too Many Requests와 Retry-After 헤더로 응답합니다(RFC 6585 §4). 즉시 재시도하지 말고 Retry-After를 준수하세요.

• 작업 결과는 무한히 유지되지 않습니다. 작업 저장소는 NEXTPDF_JOB_GC_MAX_AGE_SECONDS 이후 오래된 항목을 가비지 컬렉션합니다. 결과가 만료되기 전에 가져오세요.

• 세션은 메모리를 소비합니다. 세션은 진행 중인 문서를 보유합니다. 클라이언트별 세션 상한과 유휴 타임아웃으로 이 비용을 제한합니다. 최악의 경우를 기준으로 메모리 용량을 산정하지 않았다면 이 값을 높이지 마세요.

성능

동기 경로는 렌더링이 완료될 때까지 워커를 점유합니다. 크거나 느린 렌더링에는 비동기 작업 경로를 사용하세요. 이 경로는 워커를 즉시 해제하고 클라이언트가 결과를 폴링하도록 합니다. 관측된 렌더링 지연 시간과 동시성에 맞춰 워커 풀 크기를 산정하세요. RoadRunner 메트릭 엔드포인트를 모니터링하세요.

보안 참고사항

상태 프로브를 제외한 모든 엔드포인트에는 유효한 API 키가 필요합니다. 클라이언트 등급에 따라 허용되는 작업과 페이로드 크기가 제한됩니다. 멱등성 키는 클라이언트가 제공합니다. 멱등성 키를 불투명한 값으로 취급하고 논리적 작업마다 고유하게 지정하세요. 자세한 내용은 /connect/security-and-operations/ 항목을 참조하세요.

규격 준수

주장	출처	reference_id
멱등성: 반복된 요청 = 하나의 효과	RFC 9110 §9.2.2
멱등성 요청은 실패 후 재시도 가능	RFC 9110 §9.2.2
429 + Retry-After 속도 제한에 사용	RFC 6585 §4

상업적 맥락

해당 도구가 설치되어 있으면 Pro 및 Enterprise 키에는 등급별로 더 높은 페이로드 및 타임아웃 상한이 적용됩니다. 기본 배포에는 core 등급 상한이 적용됩니다.

참고 항목

• /connect/deployment/ — 워커 풀, Redis, RoadRunner 프로필
• /transports/rest/ — 전체 미들웨어 파이프라인 및 OpenAPI 계약
• /connect/troubleshooting/ — 401/403/413/429/5xx 및 저장소 오류 진단
• /connect/security-and-operations/ — 인증 및 속도 제한 정책