NextPDF Gotenberg 개요

한눈에 보기

NextPDF Gotenberg은 NextPDF와 외부 Gotenberg 서비스 사이를 잇는 얇은 브리지입니다. NextPDF가 자체적으로 렌더링할 수 없는 Office 문서를 받아 HTTP를 통해 Gotenberg 인스턴스로 전송하고, PDF를 다시 받은 뒤 그 PDF를 애플리케이션에 전달합니다. 그 이후부터는 NextPDF의 나머지 기능 집합이 후처리를 담당합니다.

이 패키지는 작고 명시적입니다. 렌더러를 내장하지 않고, LibreOffice를 실행하지 않으며, 브라우저를 구동하지도 않습니다. 모든 변환은 Gotenberg 엔드포인트로 보내는 단일 multipart HTTP 요청입니다. 해당 엔드포인트는 사용자가 운영하며, 구성을 통해 브리지가 그 엔드포인트를 가리키도록 설정합니다.

.docx, .xlsx, .pptx, .odt, .ods 또는 .odp 원본 파일이 있고 이를 NextPDF 파이프라인 안에서 PDF로 만들고자 할 때 이 브리지를 사용합니다. PDF가 생성된 이후의 모든 작업 — 서명, PDF/A 변환, 워터마킹, 병합 — 은 NextPDF 자체 또는 nextpdf/premium 패키지를 통해 처리됩니다.

브리지가 의존하는 것

브리지에는 PHP 패키지가 아닌 런타임 의존성이 하나 있습니다. 바로 브리지가 HTTPS를 통해 접근할 수 있는 실행 중인 Gotenberg 서비스입니다.

브리지는 Gotenberg를 설치하거나 관리하거나 감독하지 않습니다. Gotenberg는 사용자가 직접 배포하며(업스트림 프로젝트가 컨테이너 이미지를 게시합니다), 그 가용성, 용량, 네트워크 노출은 사용자의 책임입니다.
브리지는 Gotenberg의 LibreOffice 변환 라우트와 통신합니다. 요청 URL은 <apiUrl>/forms/libreoffice/convert 형태로 구성되며, 여기서 <apiUrl>은 사용자가 구성하는 기본 URL입니다. 이 라우트가 브리지의 지원 형식 집합을 결정합니다.
상태 점검 프로브는 HTTP HEAD 요청으로 <apiUrl>/health를 대상으로 하며, 500 미만의 모든 상태를 사용 가능으로 간주합니다.

변환은 사용자가 운영하는 서비스에서 이루어지므로, 브리지의 동작은 실행 중인 Gotenberg 버전에 따라 달라집니다. 브리지는 고정된 multipart 요청 형태를 전송하며, 라우트 경로(/forms/libreoffice/convert)와 상태 점검 경로(/health)만을 Gotenberg 측 계약으로 가정합니다. 배포 기준선은 /integrations/gotenberg/install/을, 서비스 강화는 /integrations/gotenberg/security-and-operations/를 참조하십시오.

지원되는 문서 형식

브리지는 OfficeFormat 타입에 열거된 형식만 정확히 변환합니다. 각 형식은 파일 확장자에서 감지됩니다(대소문자를 구분하지 않으며, 앞에 붙은 점은 허용됩니다). 그런 다음 각 형식은 고정된 MIME 타입과 함께 Gotenberg로 전송됩니다.

형식	확장자	Gotenberg로 전송되는 MIME 타입
Word (OOXML)	`docx`	`application/vnd.openxmlformats-officedocument.wordprocessingml.document`
Excel (OOXML)	`xlsx`	`application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`
PowerPoint (OOXML)	`pptx`	`application/vnd.openxmlformats-officedocument.presentationml.presentation`
OpenDocument Text	`odt`	`application/vnd.oasis.opendocument.text`
OpenDocument Spreadsheet	`ods`	`application/vnd.oasis.opendocument.spreadsheet`
OpenDocument Presentation	`odp`	`application/vnd.oasis.opendocument.presentation`

이 목록이 전부입니다. 이 집합에 속하지 않는 확장자는 네트워크 요청이 이루어지기 전에 ValueError를 발생시키므로, 브리지는 설명할 수 없는 변환을 결코 시도하지 않습니다. 브리지는 “모든 Office 파일”이나 “모든 문서 형식”을 지원한다고 주장하지 않습니다. 위 여섯 가지 형식만 지원하며, 이는 코드가 인식하고 테스트 스위트가 검증하는 형식이 이 여섯 가지뿐이기 때문입니다.

레거시 바이너리 형식(.doc, .xls, .ppt), 서식 있는 텍스트(.rtf), 일반 텍스트, CSV, 이미지 형식은 브리지의 인식 집합에 포함되지 않습니다. Gotenberg 자체의 LibreOffice 라우트는 더 넓은 범위의 입력을 받아들일 수 있습니다. 브리지는 의도적으로 자신을 열거된 집합으로 제한해 형식 감지, MIME 타입, 결과 메타데이터가 항상 일관되고 검증 가능하도록 합니다.

변환이 흐르는 방식

변환은 하나의 선형 흐름으로 진행됩니다. 어떤 바이트도 프로세스 밖으로 나가기 전에 모든 단계에서 검증을 수행합니다.

구성을 확인합니다. 비어 있는 API URL은 변환 예외와 함께 즉시 실패합니다.
API URL을 검증합니다. HTTPS가 필수이며, 호스트를 해석하고 필터링하여 사설 또는 예약된 주소를 가리킬 수 없게 합니다. 해석된 주소 집합은 이후 고정을 위해 캡처됩니다.
입력을 읽고(파일 변환의 경우 경로 순회를 차단하기 위해 먼저 경로를 정규화합니다), 그 확장자를 OfficeFormat에 매핑합니다.
바이트 길이를 구성된 최대값과 대조하여 확인하고, 파일 이름에서 경로 순회 시퀀스, 슬래시, 널 바이트, 제어 문자를 선별합니다.
검증과 연결 사이의 간격을 좁히기 위해 요청 직전에 주소 집합을 다시 확인합니다.
multipart/form-data 본문을 구성하여 LibreOffice 라우트로 POST하며, 베어러 토큰이 구성되어 있으면 함께 전송합니다.
응답을 파싱합니다. 상태는 200이어야 하고, Content-Type에는 application/pdf가 포함되어야 하며, 본문은 %PDF 시그니처로 시작해야 합니다. 이 조건을 모두 만족해야 결과가 반환됩니다.

1~7 단계에서 발생하는 모든 실패는 부분적이거나 검증되지 않은 결과를 반환하는 대신 타입이 지정된 예외를 발생시킵니다. 정확한 예외와 그 트리거는 /integrations/gotenberg/troubleshooting/.에 정리되어 있습니다.

반환되는 결과

변환이 성공하면 결과 객체가 반환됩니다. 이 객체는 원시 PDF 바이트, 변환된 원본 형식, 선택적인 렌더링 시간 측정값을 담고 있으며, 유효성 검사(%PDF로 시작하는 비어 있지 않은 본문)와 바이트 크기 접근자도 함께 노출합니다. 이 바이트는 일반적인 PDF 스트림이므로 디스크에 기록하거나, 클라이언트로 스트리밍하거나, 추가 처리를 위해 NextPDF 문서로 전달할 수 있습니다.

브리지가 멈추는 지점

브리지는 변환하고 검증합니다. 다음은 수행하지 않습니다.

출력물을 서명, 암호화, 선형화하거나 PDF/A로 변환하지 않습니다. 이는 NextPDF 코어 또는 nextpdf/premium이 처리하는 후처리 관심사입니다.
실패한 요청을 재시도하거나, 작업을 큐에 넣거나, 결과를 캐싱하지 않습니다. 이는 애플리케이션 수준의 관심사입니다. /integrations/gotenberg/production-usage/은 이를 브리지 주변에 추가할 위치를 보여줍니다.
Gotenberg 서비스 수명 주기를 관리하지 않습니다. 배포와 운영은 /integrations/gotenberg/security-and-operations/.에서 다룹니다.

에디션과 후처리

OSS 코어는 변환된 PDF를 있는 그대로 기록할 수 있습니다. 변환된 문서에 서명하거나, PDF/A 보관 프로파일을 생성하거나, 워터마크를 적용해야 하는 경우, nextpdf/premium 패키지가 이러한 기능을 추가로 제공합니다. 브리지 자체는 에디션 중립적입니다. PDF를 생성할 뿐입니다. 그 PDF로 무엇을 하느냐에 따라 상용 에디션이 필요한지가 결정됩니다.

Pro 에디션에서 사용할 수 있는 PAdES 기준선은 B-B뿐입니다. 장기 검증 프로파일(B-T, B-LT, B-LTA)은 Pro 에디션에 포함되지 않으며 이 브리지에서 제공되지 않습니다. 이 패키지가 존재한다고 해서 타임스탬프 또는 LTV 기능을 제공한다고 추론하지 마십시오.