NextPDF Connect 배포

한눈에 보기

REST 및 gRPC 전송은 RoadRunner 워커 풀 안에서 실행됩니다. 이 패키지는 HTTP 전용, gRPC 전용, 결합형의 세 가지 RoadRunner 프로필을 제공합니다. MCP 전송은 일반 하위 프로세스로 실행되며 수퍼바이저가 필요하지 않습니다.

설치

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

개념 개요

RoadRunner는 프로세스 수퍼바이저입니다. RoadRunner는 워커 풀을 관리하고, 메모리 사용량이 커지면 워커를 재시작하며, 각 요청을 유휴 워커로 라우팅합니다. PHP 패키지는 워커 진입점을 제공합니다. HTTP에는 bin/nextpdf-server, gRPC에는 bin/nextpdf-grpc를 사용합니다. RoadRunner는 해당 진입점을 실행하는 풀을 제공합니다. 각 워커는 한 번에 요청 하나를 처리합니다.

MCP 전송은 다르게 동작합니다. bin/nextpdf-mcp는 단일 PHP 프로세스입니다. 이 프로세스는 stdio를 통해 JSON-RPC로 통신하며, 클라이언트가 직접 실행합니다.

API 표면

RoadRunner 프로필

프로필	전송	명령
.rr.yaml	REST 전용	rr serve -c .rr.yaml
.rr.grpc.yaml	gRPC 전용	rr serve -c .rr.grpc.yaml
.rr.full.yaml	REST + gRPC	rr serve -c .rr.full.yaml

HTTP 프로필은 REST 리스너를 0.0.0.0:8080에 바인딩합니다. 또한 :2114에서 상태 엔드포인트를, :2112에서 메트릭을 노출합니다. 워커 풀 크기는 NEXTPDF_WORKER_COUNT에서 결정되며, 기본값은 4입니다. 제공되는 프로필에서 수퍼바이저는 워커당 메모리를 256 MB로 제한합니다.

결합 프로필은 tcp://0.0.0.0:9090에 gRPC 워커 풀을 추가하며, 풀 크기는 NEXTPDF_GRPC_WORKER_COUNT에서 결정되고 기본값은 2입니다. 또한 gRPC 상호 TLS도 구성합니다.

코드 샘플 — 빠른 시작

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

코드 샘플 — 프로덕션

결합 프로필, 파일 기반 키, Redis 기반 공유 저장소를 사용하여 프로덕션 컨테이너를 실행합니다.

docker/docker-compose.yml (production shape)

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

예외 사례 및 주의 사항

• 인메모리 저장소는 워커 간에 공유되지 않습니다. Redis가 없으면 각 워커는 자체 속도 제한, 멱등성, 문서 저장소를 유지합니다. 워커가 여러 개인 풀에서 인메모리 저장소를 사용하면 속도 제한이 일관되지 않고 워커 간에 문서가 유실됩니다. 워커가 둘 이상인 풀에서는 NEXTPDF_REDIS_HOST를 설정하고 ext-redis를 설치해야 합니다. Redis 연결이 실패하면 서버는 인메모리로 자동 폴백합니다. Redis 상태를 확인해야 합니다. 정상이라고 가정해서는 안 됩니다.

• 작업 저장소는 WAL 모드의 SQLite입니다. 비동기 작업은 모든 HTTP 및 gRPC 워커가 공유하는 단일 SQLite 파일에 저장됩니다. 해당 파일은 모든 워커가 쓰기 가능한 볼륨에 두어야 합니다. 워커가 종료될 때 아직 실행 중인 작업은 최선의 노력으로 실패 처리되므로, 해당 작업이 고아 상태로 남지 않습니다.

• bin/nextpdf-prune는 유지 관리 진입점입니다. 이 도구는 vendor/bin/이 아니라 저장소에 포함되어 제공됩니다. 저장소 정리 작업에서는 이 도구를 직접 호출해야 합니다. 이 도구는 서버 전송이 아닙니다.

• 이미지의 PHP 버전에 ext-redis가 없을 수 있습니다. 제공되는 Dockerfile은 ext-redis를 최선의 노력으로 빌드합니다. 기반 PHP에 호환되는 릴리스가 없으면 해당 확장 없이 계속 진행합니다. Redis 기반 저장소에 의존하기 전에 실행 중인 이미지에 해당 확장이 있는지 확인해야 합니다.

성능

사용 가능한 CPU와 메모리에 맞게 NEXTPDF_WORKER_COUNT를 설정해야 합니다. 각 워커는 수퍼바이저의 메모리 상한으로 제한되는 PHP 프로세스입니다. 렌더링 부하가 큰 워크로드에서는 코어당 워커 하나로 시작한 다음 메트릭 엔드포인트를 기준으로 조정합니다. gRPC 풀 크기는 별도로 설정합니다. gRPC 클라이언트는 일반적으로 수가 적고 수명이 길기 때문에, 이 풀은 보통 HTTP 풀보다 작습니다.

보안 참고 사항

gRPC 상호 TLS

결합 프로필은 gRPC 전송을 상호 TLS로 구성합니다. 서버는 인증서를 제시하고 클라이언트 인증서를 요구해 검증합니다. 서버 키, 서버 인증서, 클라이언트 CA는 이미지에 포함하지 않고 배포 시크릿으로 제공합니다. 이러한 항목은 대역 외에서 생성하고 교체해야 합니다. 신뢰할 수 없는 네트워크에서 gRPC 전송을 평문 리스너로 실행해서는 안 됩니다.

REST TLS 종료

REST 프로필은 평문 HTTP 리스너를 바인딩합니다. 그 앞단에서 — 리버스 프록시, 로드 밸런서, 또는 서비스 메시로 — TLS를 종료하고, 리스너를 내부 네트워크에만 바인딩해야 합니다. 클라이언트 ID는 Authorization 헤더를 통해 변경 없이 전달해야 합니다. 서버가 자체적으로 키 검증을 수행합니다. 리스너 자체는 보안 전송을 제공하지 않습니다. 보안 전송은 이 배포 구성이 제공합니다.

시크릿

API 키는 시크릿 파일을 가리키는 NEXTPDF_API_KEYS_FILE로 마운트하고, 인라인 NEXTPDF_API_KEYS 변수는 사용하지 않아야 합니다. 파일 기반 저장소는 변경 시 핫 리로드되므로 교체할 때 재시작할 필요가 없습니다. 키나 TLS 비밀 자료를 이미지에 절대 포함해서는 안 됩니다. /connect/security-and-operations/. 참조

적합성

배포 메커니즘은 규범적 프로토콜 주장을 포함하지 않습니다. 인증 및 전송 보안에 대한 인용은 /connect/security-and-operations/.에 고정되어 있습니다.

상업적 컨텍스트

이미지에 nextpdf/premium을 설치하면 추가 Pro 및 Enterprise 도구가 같은 워커 안에 등록됩니다. 별도의 프로세스나 포트는 사용되지 않습니다. 패키징 경계는 이미지 빌드 시점에 설정됩니다.

함께 보기

• /connect/configuration/ — 워커 수, Redis, 티어 상한
• /connect/security-and-operations/ — TLS, 상호 TLS, 시크릿, 위협 모델
• /transports/rest/ · /transports/grpc/ — 전송별 런타임 세부 정보
• /connect/production-usage/ — 상태 프로브, 확장, 가관측성
• /connect/troubleshooting/ — 워커, 저장소, 인증 실패 진단