릴리즈 3.3.2602 이상
기능설명
Export API 서버는 에디터에서 사용된 이미지를 다운로드한 뒤, 문서를 HWPX, DOCX 등 다양한 포맷으로 변환하여 파일을 반환하는 역할을 합니다.
실행환경
Export API Docker 이미지는 담당 영업사원을 통해 요청해 주시기 바랍니다.
본 Export API 실행 모듈은 Docker 컨테이너 환경에서 실행됩니다.
Docker가 설치 및 실행 가능한 Linux 운영체제에서 사용 가능합니다.
다음은 검증된 환경 예시입니다.
Ubuntu 18.04 이상
CentOS 7 이상 / RHEL 7 이상
Debian 9 이상
Fedora 30 이상
운영 환경에서는 Linux (x86_64 / amd64) 서버에서의 실행을 권장합니다.
해당 환경에서는 아키텍처 에뮬레이션 없이 네이티브로 실행되어 성능 및 안정성이 가장 우수합니다.
컨테이너 내부 실행 환경은 node:18-slim 이미지를 기반으로 하며,
호스트 운영체제에 따른 실행 모듈의 동작 차이는 없습니다.
macOS(Apple Silicon) 및 Windows 환경에서도 Docker Desktop을 통해 실행이 가능하나,
해당 환경에서는 아키텍처 에뮬레이션이 사용될 수 있으므로 개발 및 테스트 용도로만 사용하는 것을 권장합니다.
실행 방법
## Installation # Load Docker image: docker load -i export_api.tar # Docker run docker run -d --name export-api \ -p 9090:9090 \ -e REMOTE_SOURCE_PROXY_DOMAINS=example.com,.internal.local \ -e REMOTE_SOURCE_PROXY_TARGET=http://10.0.0.5:8080/remote/ \ export-api:latest
환경 변수
| 옵션명 | 설명 | 기본값 | 필수 여부 | 예시 |
|---|---|---|---|---|
| PORT | 서버가 리스닝하는 포트 번호 | 9090 | 선택 | PORT=9090 |
EXPORTER_PATH | Exporter 실행 파일 경로 | ./Exporter_exe | 선택 | |
WORK_ROOT | 임시 작업 디렉터리 | ./workspaces | 선택 | |
EXPORTER_TIMEOUT | 변환 타임아웃(ms) | 120000 | 선택 | |
| REMOTE_SOURCE_PROXY_DOMAINS | 원격 이미지 프록시를 적용할 도메인 목록 (쉼표로 구분) | 없음 | 선택 | example.com,.internal.local |
| REMOTE_SOURCE_PROXY_TARGET | 내부망에서 접근 가능한 프록시 대상 베이스 URL | 없음 | 선택 | http://10.0.0.5:8080/remote/ |
- 직접 다운로드 장애 상황
- 사내망 차단, 인증 필요, IP/지역 제한, HTTP↔HTTPS 정책 등으로 서버(또는 Docker 컨테이너)가 외부 이미지를 바로 받지 못하면, 해당 이미지는 엑박(깨진 이미지)으로 표시됩니다. - 프록시 설정으로 우회
REMOTE_SOURCE_PROXY_DOMAINS: 프록시를 적용할 도메인 목록을 콤마로 지정합니다. 예: .example.com,cdn.partner.com.
REMOTE_SOURCE_PROXY_TARGET: 실제 이미지를 대신 내려받을 프록시 서버 주소를 지정합니다. 예: http://proxy.internal/....
위 두 변수를 세팅하면, 지정된 도메인의 이미지는 프록시를 경유하여 다운로드를 시도합니다. - 그럼에도 실패할 경우
프록시 자체 인증 실패, 프록시 서버 오류, 추가 권한 요구 등이 있으면 여전히 이미지를 얻지 못할 수 있으며, 이 경우 최종 결과에서는 해당 이미지가 엑박(깨진 이미지)으로 표시됩니다. - 임시 파일 보관 정책
변환 과정에서 내려받은 이미지, 생성된 .word.pb, 출력 파일 등 모든 리소스는 작업 완료 후 즉시 삭제됩니다.
API
| Endpoint | Method | 설명 |
|---|---|---|
| /exportFile | POST | 사이냅 에디터에서 직렬화한 문서(serializedData)와 이미지 리소스를 받아 특정 포맷(docx, hwpx 등)의 문서로 변환하여 반환. application/json 또는 multipart/form-data 지원 |
| /info | GET | 배포된 서버 정보(프로덕트 이름, 버전, Exporter 버전 등)를 조회 |
| /health | GET | 서버 정상 기동 여부 확인(헬스 체크) |
/exportFile 요청 필드 (multipart/form-data)
사이냅 에디터 클라이언트의 실제 호출 /exportFile은 아래 필드들로 전송됩니다.
| 필드명 | 타입 | 필수 | 설명 |
|---|---|---|---|
payload | string(JSON) | 예 | 문서 메타데이터. filename, exportType, responseType, mediaManifest 포함 |
serializedData | file/blob | 예 | 직렬화된 문서 바이너리. 클라이언트에서는 보통 document.bin 이름으로 전송 |
media | file[] | 아니오 | 인라인 이미지 Blob 배열. payload.mediaManifest의 비원격 항목 순서와 동일해야 함 |
그 외 추가 필드 | form field | 아니오 | 클라이언트 설정(editor.export.param) 또는 이벤트에서 병합된 사용자 정의 파라미터 |
payload JSON 구조
{
"filename": "document",
"exportType": "hwpx",
"responseType": "json",
"mediaManifest": [
{
"path": "image/image1.png",
"filename": "image1.png",
"isRemote": false,
"sourceUrl": null,
"contentType": "image/png"
},
{
"path": "https://example.com/logo.png",
"filename": "logo.png",
"isRemote": true,
"sourceUrl": "https://example.com/logo.png",
"contentType": "image/png"
}
]
}
payload 필드 설명
| 필드명 | 타입 | 필수 | 설명 |
|---|---|---|---|
filename | string | 아니오 | 출력 파일명(확장자 제외). 서버에서 미지정 시 document 사용 |
exportType | string | 아니오 | 변환 포맷. 예: docx, hwpx, hwp |
mediaManifest | Array<object> | 아니오 | 문서에 포함된 이미지 목록 |
mediaManifest 항목 설명
| 필드명 | 타입 | 필수 | 설명 |
|---|---|---|---|
path | string | 아니오 | 원본 경로 또는 식별자 |
filename | string | 아니오 | 파일명 후보. 서버가 저장 파일명 생성 시 참고 |
isRemote | boolean | 아니오 | true면 서버가 sourceUrl로 직접 다운로드 |
sourceUrl | string | null | 조건부 | isRemote=true일 때 사용할 원격 이미지 URL |
contentType | string | null | 아니오 | MIME 타입 힌트. 예: image/png |
처리 규칙
serializedData는 반드시 multipart 파일 필드로 전송해야 합니다.
mediaManifest에서 isRemote: true이고 sourceUrl이 있으면 서버가 해당 URL에서 이미지를 다운로드합니다.
isRemote가 아니면 서버는 media 파일 배열에서 순서대로 이미지를 매칭합니다.
따라서 media 업로드 순서는 mediaManifest의 비원격 항목 순서와 일치해야 합니다.