NextPDF Connect 설치

한눈에 보기

Composer로 nextpdf/server를 설치합니다. 그런 다음 세 가지 전송 진입점 중 하나를 실행합니다. 코어 설치에는 PHP 8.4와 NextPDF 엔진만 필요합니다. Redis와 Premium은 선택 사항입니다.

설치

composer require nextpdf/server

이 명령은 nextpdf/core: ^3.0도 함께 설치합니다. 이 패키지는 php: >=8.4 <9.0을 선언하므로 Composer는 PHP 8.3 이하나 PHP 9에서는 설치를 거부합니다.

개념 개요

이 패키지는 library 유형의 Composer 패키지입니다. 설치하면 vendor/bin/에 네 개의 콘솔 진입점이 추가됩니다.

vendor/bin/nextpdf-mcp — MCP stdio 서버입니다.
vendor/bin/nextpdf-server — RoadRunner HTTP 워커 기반 REST 서버입니다.
vendor/bin/nextpdf-grpc — RoadRunner gRPC 워커 기반 gRPC 서버입니다.
vendor/bin/generate-skills — 도구 카탈로그를 에이전트 스킬로 내보냅니다.

다섯 번째 스크립트인 bin/nextpdf-prune은 유지 관리 작업용으로 저장소에 함께 제공됩니다. 이 스크립트는 vendor/bin/을 거치지 않고 직접 실행합니다.

서비스 프로바이더, 번들, 프레임워크 등록은 전혀 필요하지 않습니다. 서버는 독립형 프로세스로 실행됩니다. 호스트 애플리케이션에 연결하는 라이브러리가 아닙니다.

API 표면

Composer는 패키지의 런타임 종속성도 함께 설치합니다. 이 전이 종속성에는 HTTP 및 gRPC 스택이 포함됩니다.

league/route 및 nyholm/psr7 — REST 라우팅과 PSR-7 메시지입니다.
spiral/roadrunner-http 및 spiral/roadrunner-grpc — REST 및 gRPC 전송을 위한 RoadRunner 워커 런타임입니다.
psr/http-server-middleware 및 psr/http-server-handler — REST 파이프라인이 구현하는 PSR-15 미들웨어 계약입니다.
symfony/yaml — 구성 파일 구문 분석에 사용됩니다.
ramsey/uuid — 요청 및 리소스 식별자입니다.

이 패키지들을 직접 설치할 필요는 없습니다. Composer가 nextpdf/server에서 대신 해결해 줍니다.

코드 예제 — 빠른 시작

설치를 확인하려면 서버를 시작하지 않고 도구 카탈로그를 나열합니다.

./vendor/bin/generate-skills --dry-run --list-tools

이 명령은 레지스트리를 부팅하고 계층 감지를 실행한 뒤, 이 설치에서 노출하는 도구를 출력합니다. 이 목록은 어떤 선택적 패키지가 있는지를 반영합니다. /connect/tool-catalog/를 참조하세요.

코드 예제 — 프로덕션

프로덕션 설치는 종속성을 고정하고 개발 도구는 제외합니다.

composer require nextpdf/server --no-dev
composer install --no-dev --optimize-autoloader --classmap-authoritative

REST 및 gRPC 전송에서는 RoadRunner 바이너리도 함께 설치합니다. RoadRunner는 워커 풀을 관리하는 프로세스 관리자입니다. PHP 패키지는 관리자가 아니라 워커를 제공합니다.

./vendor/bin/rr get-binary

예외 상황과 주의 사항

선택적 Redis. ext-redis 확장은 require가 아니라 suggest입니다. 이 확장이 없으면 REST 서버는 인메모리 속도 제한, 멱등성, 문서 저장소를 사용합니다. 이러한 인메모리 저장소는 단일 워커에는 적합하지만 다중 워커 풀에서는 워커 간에 공유되지 않습니다. 다중 워커 배포에서는 ext-redis를 설치하고 Redis 환경 변수를 설정합니다. /connect/configuration/를 참조하세요.
선택적 Premium. nextpdf/premium은 suggest입니다. 서버와 함께 설치하면 레지스트리의 계층 감지 프로브가 해당 프로바이더 클래스를 찾습니다. 그 결과 프로브가 추가 Pro 및 Enterprise 도구를 등록합니다. 이 패키지가 없으면 코어 카탈로그만 제공됩니다. 이는 런타임 토글이 아니라 composer require 시점에 정해지는 패키징 결정입니다.
MCP 서버에는 RoadRunner가 필요하지 않습니다. nextpdf-mcp는 stdio를 통해 JSON-RPC로 통신하는 일반 PHP 프로세스입니다. RoadRunner는 REST 및 gRPC 전송에만 필요합니다.

성능

설치 시간의 대부분은 Composer 종속성 해결에 쓰입니다. 프로덕션 이미지에서는 콜드 부팅 자동 로드 시간을 낮게 유지하기 위해 --prefer-dist와 권위 있는 클래스맵을 사용합니다. 서버 자체의 부팅 비용은 레지스트리 스캔과 계층 감지에서 발생합니다. 이 페이지의 performance_budget은 해당 부팅 비용을 제한합니다.

보안 참고 사항

공식 Packagist 패키지인 nextpdf/server만 설치하세요. 배포된 도구 카탈로그를 재현할 수 있도록 composer.json에서 버전을 고정하고 composer.lock을 커밋하세요. 네트워크 전송은 상태 확인 외의 엔드포인트를 제공하기 전에 API 키를 요구합니다. /connect/security-and-operations/를 참조하세요.

적합성

이 페이지는 설치 메커니즘만 설명합니다. 프로토콜 및 보안 적합성 관련 인용은 /transports/mcp/, /transports/rest/, /transports/grpc/, /connect/security-and-operations/에 고정되어 있습니다.

상업적 맥락

코어 설치만으로도 온전히 작동합니다. 세 가지 전송 모두에서 문서 생성, 검사, 진단을 처리합니다. nextpdf/premium을 추가하면 전송 또는 인증 모델을 변경하지 않고도 카탈로그가 확장됩니다.