NextPDF Gotenberg 프로덕션 운영

한눈에 보기

브리지는 검증으로 보호되는 단일 동기 HTTP 왕복 호출입니다. 브리지는 재시도, 큐잉, 캐싱 또는 속도 제한을 수행하지 않습니다. 이러한 동작은 브리지를 둘러싼 애플리케이션의 책임입니다. 이 페이지에서는 각 동작이 어디에 속하는지, 그리고 브리지가 무엇을 보장하는지 보여 주므로 나머지를 올바르게 구축할 수 있습니다.

모든 변환을 직접 운영하되 프로세스 내에서 제어할 수 없는 서비스에 대한 원격 호출로 취급하십시오. 해당 지연 시간과 실패 가능성을 고려하여 설계하십시오.

구성 및 시크릿 가져오기

GotenbergConfig는 API URL을 보유하며, 인증이 활성화된 경우 베어러 토큰도 보유합니다. 토큰 필드는 #[\SensitiveParameter]로 표시되므로 스택 트레이스에서 가려집니다. 다만 토큰의 출처를 관리하는 책임은 여전히 사용자에게 있습니다.

프로세스 시작 시 시크릿 관리자 또는 주입된 환경 값에서 토큰을 가져오십시오. 토큰을 커밋하지 말고, 이미지에 포함되는 구성 파일에 두지 마십시오.
구성은 변환마다 새로 만들지 말고, 요청 범위당 한 번 또는 워커당 한 번 빌드하십시오. 불변 객체이며 보관 비용이 낮습니다.
GotenbergConfig::fromArray()는 설계상 잘못된 형식의 입력도 허용하고 조용히 기본값으로 대체합니다. 프로덕션에서는 fromArray()를 호출하기 전에 소스 배열을 직접 검증하십시오. 이렇게 하면 URL 누락이 이후 변환마다 발생하는 Invalid Gotenberg configuration: apiUrl is empty 예외가 아니라, 부팅 경로에서 구성 오류로 드러납니다.

타임아웃

timeout(초 단위, 기본값 30)은 cURL 고정 전송이 적용하는 하드 전송 타임아웃입니다. LibreOffice를 통한 오피스 변환은 즉각적이지 않으며, 크거나 복잡한 문서는 더 오래 걸립니다. 실제 문서에서 측정한 변환 지연 시간을 기준으로 여유를 두어 타임아웃을 설정하십시오. 상위 게이트웨이나 PHP max_execution_time보다 낮게 유지하십시오. 그래야 브리지가 먼저 타임아웃되어, 종료된 프로세스 대신 타입이 지정된 예외를 받게 됩니다.

주입된 PSR-18 클라이언트 경로에 의존하는 경우(responseFactory를 주입하지 않았거나, 핀이 없는 베어 IP URL인 경우), 브리지는 해당 클라이언트에 timeout 값을 강제하지 않습니다. 두 전송 모두 한계가 적용되도록 PSR-18 클라이언트 자체에도 타임아웃을 구성하십시오.

재시도

브리지는 호출당 정확히 한 번 요청을 수행하며 재시도하지 않습니다. 재시도 로직은 호출자 쪽에 추가하되, 안전하게 만드십시오:

전송 수준 실패(원인이 PSR-18 클라이언트 예외인 GotenbergConvertException)와 멱등성 서버 오류(HTTP 502, 503, 504)에서만 재시도하십시오. 모든 GotenbergConvertException를 무분별하게 재시도하지 마십시오. 400 계열 응답은 대개 입력이 잘못되었음을 의미하며, 재시도해도 동일하게 실패합니다.
지터를 적용한 상한이 있는 지수 백오프를 사용하십시오. 부하를 받는 변환 서비스는 503을 반환할 수 있으며, 반복적으로 요청하면 장애가 더 악화됩니다.
총 시도 횟수와 총 벽시계 시간에 상한을 두십시오. 변환은 이미 느리므로, 한계 없는 재시도는 꼬리 지연 시간을 배가시킵니다.
재검증은 자동으로 이루어집니다. 재시도되는 각 호출은 URL 검증과 주소 재확인을 다시 실행하므로, 재시도가 실수로 SSRF 가드를 우회할 수 없습니다.

동시성 및 용량

각 변환은 요청이 지속되는 동안 Gotenberg 측에서 하나의 연결과 하나의 LibreOffice 워커를 점유합니다. 브리지 자체는 상태가 없으며 여러 워커에서 동시에 사용해도 안전합니다. 그러나 Gotenberg 서비스의 변환 용량은 유한합니다.

진행 중인 변환 수를 사용자 측에서(큐, 세마포어 또는 워커 풀로) Gotenberg가 지속할 수 있는 용량 이내로 제한하십시오. 용량 산정은 이 패키지가 아니라 사용자의 Gotenberg 배포 속성입니다 — /integrations/gotenberg/security-and-operations/을 참조하십시오.
입력 크기 상한(maxFileSize, 기본값 50 MiB)은 브리지의 유일한 내장 리소스 한계입니다. 이 한계는 요청이 전송되기 전에 프로세스 내에서 적용되므로, 크기를 초과한 파일은 서비스 용량을 절대 소비하지 않습니다. 문서에 실제로 필요한 만큼으로 낮추십시오. 작은 상한은 큰 상한보다 비용이 낮은 서비스 거부 제어입니다.
프로세스 내 캐싱은 없습니다. 동일한 문서가 반복해서 변환되는 경우, 입력 콘텐츠 해시를 키로 삼아 결과 PDF를 애플리케이션에 캐시하십시오.

관찰 가능성

변환 요청마다 debug 항목을 얻으려면 PSR-3 로거를 주입하십시오. 이 항목에는 요청 URL, 파일 이름, 감지된 형식, 요청 콘텐츠 길이가 포함됩니다. 파일 콘텐츠나 베어러 토큰은 포함되지 않습니다.

이 신호를 메트릭으로 승격하십시오: 형식과 결과별로 변환 수를 집계하고, 각 convertFile() / convertString() 호출 주변의 벽시계 시간을 지연 시간 히스토그램으로 기록하십시오. 브리지는 자체적으로 메트릭을 방출하지 않습니다.
결과 객체는 renderTimeMs 필드를 노출하며, 사용자의 통합이 이를 측정해 설정하지 않는 한 0.0입니다. 브리지는 이를 Gotenberg 응답에서 채우지 않습니다. 그 수치가 필요하면 호출 시간을 직접 측정하십시오.
예외를 해당 타입과 함께 로깅하십시오. 예외 타입은 무엇이 실패했는지 알려 주는 기본 신호이며, 카탈로그는 /integrations/gotenberg/troubleshooting/에 있습니다.
isAvailable()는 모든 변환마다 실행하지 말고, 준비성 또는 상태 점검 엔드포인트에서 프로빙하십시오. 이는 /health에 대한 HEAD 요청입니다. 변환마다 이를 실행하면 아무 이점 없이 서비스에 대한 요청 비율이 두 배가 됩니다.

실패 처리 계약

브리지는 실패를 타입이 지정된 예외로 드러내며, 부분적이거나 검증되지 않은 결과를 절대 반환하지 않습니다. 관련 보장은 다음과 같습니다:

200이 아닌 상태, application/pdf이 없는 Content-Type 또는 %PDF로 시작하지 않는 본문은 각각 GotenbergConvertException를 발생시킵니다. 결과 객체는 세 가지 검사가 모두 통과한 경우에만 반환됩니다.
PSR-18 클라이언트 실패(네트워크 실패 또는 타임아웃 포함)는 원본 예외를 원인으로 삼고, 클라이언트의 코드를 예외 코드로 사용해 GotenbergConvertException로 래핑됩니다.
검증 실패(HTTPS가 아닌 URL, private/reserved 주소, 크기를 초과한 입력, 안전하지 않은 파일 이름)는 어떠한 네트워크 트래픽도 발생하기 전에 RuntimeException을 발생시킵니다.
인식되지 않는 파일 확장자는 어떠한 네트워크 트래픽도 발생하기 전에 ValueError를 발생시킵니다.

특정 타입을 캐치하십시오. examples/convert-office-to-pdf.php의 예제 프로그램은 전체 캐치 순서를 보여 줍니다. /integrations/gotenberg/troubleshooting/는 각 트리거를 설명합니다.

후처리 경계

브리지는 PDF를 생성하고 거기서 멈춥니다. 일반적인 프로덕션 파이프라인은 다음과 같습니다:

이 브리지로 오피스 문서를 변환합니다.
결과 바이트를 NextPDF 문서로 로드합니다.
후처리를 적용합니다 — 페이지 조립, 워터마킹, PDF/A 변환, 디지털 서명.

3 단계는 브리지가 아니라 NextPDF의 책임입니다. 서명, PDF/A 프로파일, 워터마킹은 nextpdf/premium에서 제공합니다. 변환과 후처리를 별도의 단계로 유지하여, 변환 실패와 서명 실패를 독립적으로 진단할 수 있도록 하십시오.

Pro 에디션의 PAdES 지원은 B-B 베이스라인으로 한정됩니다. 이는 B-T, B-LT 또는 B-LTA를 제공하지 않으며, 이 브리지를 통해 문서를 변환한다고 해서 해당 프로파일이 암시되지 않습니다. 장기 검증 기능은 별개의 에디션 사안이며 이 패키지의 범위를 벗어납니다.

참고 항목

/integrations/gotenberg/configuration/ — 전송 선택 규칙 및 핀 모델.
/integrations/gotenberg/security-and-operations/ — Gotenberg 의존성 배포 및 하드닝.
/integrations/gotenberg/troubleshooting/ — 예외 카탈로그.
/integrations/gotenberg/integration/ — 변환된 PDF를 NextPDF 파이프라인에 연결하기.