Gotenberg API를 활용한 HTML to PDF 변환 - n8n 워크플로우

자동 문서 생성을 위한 안정적인 자체 호스팅 솔루션이 필요한 개발자.
기존 n8n 환경에 통합되는 개인 정보 보호가 중요하고 대용량 PDF 변환 도구가 필요한 사용자.
복잡한 바이너리 파일 처리 및 외부 API 통합을 시연하는 고급 n8n 템플릿을 찾는 기술 사용자.
n8n 설정을 위해 Docker를 사용하고 다른 컨테이너화된 서비스를 활용하려는 모든 사용자.

동적 HTML 콘텐츠에서 고품질 PDF 문서를 생성하는 것은 자동화에서 흔히 발생하는 과제입니다. 많은 온라인 서비스가 존재하지만, 개인 정보 보호 문제나 확장성 문제를 야기하는 경우가 많습니다. 이 특화된 n8n 워크플로 템플릿은 n8n 인스턴스와 안전하게 나란히 실행되는 자체 호스팅 Gotenberg 서비스와 직접 통합하여 이 문제를 해결합니다.

이 자동화는 전문 보고서, 송장 또는 복잡한 문서를 생성하기 위한 안전하고 고도로 사용자 지정 가능한 방법을 제공합니다. 이 워크플로는 초기 n8n 트리거를 통해 HTML 데이터와 원하는 출력 파일 이름을 수신하고, 내부적으로 파일 준비를 처리한 다음, Gotenberg에 요청을 보내 효율적이고 안전한 PDF 생성을 보장합니다. 이 n8n 자동화를 마스터한다는 것은 문서 파이프라인에 대한 완전한 제어권을 확보하는 것을 의미하며, 이는 전문 시스템에 매우 중요한 기능입니다.

이 n8n 워크플로는 수동으로 실행되거나 외부 웹훅 또는 트리거에 의해 호출될 때 시작되며, HTML 콘텐츠와 원하는 파일 이름을 예상합니다.

1. 입력 트리거: 워크플로는 Create PDF from HTML n8n 트리거 노드에서 시작됩니다. 이 노드는 변환할 html 콘텐츠와 결과 PDF의 이름인 file_name이라는 두 가지 필수 입력 필드를 받도록 구성됩니다.


2. 파일 준비: 흐름은 Create index.html n8n 노드로 이동하며, 여기서는 내부 convertToFile 함수를 사용합니다. 이 노드는 수신된 html 문자열을 index.html이라는 바이너리 파일로 변환합니다. 이는 Gotenberg API에 HTML을 올바르게 패키징하기 위해 필요한 단계입니다.


3. Gotenberg API 호출: 가장 중요한 단계는 Convert to PDF with Gotenberg n8n 노드(HTTP 요청 n8n 노드)에서 발생합니다. 이 노드는 Gotenberg 서비스(기본값: http://gotenberg:3000/forms/chromium/convert/html)로 POST 요청을 수행합니다. 이전 단계에서 준비된 바이너리 파일을 multipart-form-data 인코딩을 사용하여 전송합니다.


4. 메타데이터 사용자 지정: 중요하게도, 이 n8n 노드는 요청 본문 내에서 사용자 지정 메타데이터(예: 작성자, 제목, 생성 날짜 및 키워드)도 전달합니다. 또한 n8n 트리거에 정의된 초기 입력을 기반으로 최종 출력 파일 이름을 동적 표현식을 사용하여 설정합니다.


5. 출력: Gotenberg는 생성된 PDF 문서를 바이너리 출력으로 반환하며, 이후 n8n 노드를 사용하여 저장하거나, 클라우드 스토리지에 업로드하거나, 이메일에 첨부할 수 있습니다.

이 n8n 워크플로 템플릿을 성공적으로 배포하려면 다음 단계를 따르세요.

1. n8n 워크플로 가져오기: 제공된 JSON 데이터를 복사하여 n8n 환경에서 '새로 만들기' -> 'JSON에서 가져오기' 기능을 사용하여 붙여넣습니다.


2. 선행 조건: Gotenberg 설정: 이 워크플로는 실행 중인 Gotenberg 서비스가 필요합니다. 가장 쉬운 방법은 n8n과 Gotenberg가 동일한 Docker 네트워크에서 실행되도록 하는 것입니다. 일반적인 Docker 구성은 다음과 같습니다.

gotenberg:
        image: gotenberg/gotenberg:8
        restart: always

1. API URL 구성: Convert to PDF with Gotenberg n8n 노드에서 URL을 확인하세요. Gotenberg 서비스가 표준 Docker 네트워크 외부 또는 다른 포트에서 호스팅되는 경우, url 매개변수를 http://gotenberg:3000/forms/chromium/convert/html에서 특정 엔드포인트로 업데이트해야 합니다.


2. 메타데이터 사용자 지정: 필요에 맞게 Author 및 Title과 같은 PDF 메타데이터를 조정하려면 Convert to PDF with Gotenberg n8n 노드의 '본문 매개변수'를 검토하세요.


3. 테스트: Create PDF from HTML n8n 트리거를 수동으로 실행하여 PDF가 올바르게 생성되었는지 확인합니다.

Create PDF from HTML (워크플로 실행 트리거)
기능: 워크플로의 시작점(n8n 트리거) 역할을 하며 실행을 위한 샘플 데이터를 제공합니다.
주요 구성: 입력 데이터는 html 콘텐츠와 원하는 출력인 file_name으로 정의됩니다.

Create index.html (파일로 변환)
기능: 입력 HTML 문자열을 저장 가능한 바이너리 파일(index.html)로 변환합니다. Gotenberg는 입력을 파일 형태로 전송해야 하므로, 이 n8n 노드는 준비 작업에 필수적입니다.
주요 구성: operation: toText, sourceProperty: html, fileName: index.html.

Convert to PDF with Gotenberg (HTTP 요청)
기능: 준비된 바이너리 HTML 파일을 자체 호스팅 Gotenberg 서비스로 전송하여 PDF 문서로 변환합니다. 이것이 전체 n8n 워크플로의 핵심 작업입니다.
주요 구성:
URL: http://gotenberg:3000/forms/chromium/convert/html (원격 서비스를 사용하는 경우 조정해야 함).
콘텐츠 유형: multipart-form-data.
본문 매개변수: 바이너리 데이터 입력 및 사용자 지정을 위한 광범위한 JSON 형식의 PDF 메타데이터를 포함합니다.
* 헤더: 초기 n8n 트리거 입력에 따라 최종 PDF 이름을 설정하기 위해 동적 표현식을 사용하여 Gotenberg-Output-Filename 헤더를 사용합니다.