성능 튜닝

렌더링 및 메모리 최적화

Doconut의 리소스 프로필은 세 가지 요소가 지배합니다: 렌더 DPI, 캐시되는 내용, 그리고 세션 지속 시간. 이 가이드는 영향력 순서대로 레버를 설명합니다.

해상도 — 가장 큰 레버

ImageResolution (25–300 DPI)는 렌더링 시간과 이미지 크기에 모두 영향을 줍니다. 대부분의 포맷은 기본값이 200 DPI이며, 이미지와 PSD는 기본값이 100 DPI입니다.

csharp
// A document list preview doesn't need print quality
var token = await viewer.OpenDocumentAsync(path, new PdfConfig { ImageResolution = 100 });

DPI를 절반으로 줄이면 페이지당 픽셀 수가 대략 1/4이 되므로 렌더링이 빨라지고 전송량이 줄어들며 캐시 메모리도 감소합니다. 확대에 많이 의존하는 사용 사례(CAD, 엔지니어링 도면)에는 250–300 DPI를 유지하세요.

이미지가 많이 포함된 PDF의 경우, PdfConfig는 더 세밀한 조정을 제공합니다: CompressImages + CompressQuality, ResizeImages + ResizeResolution, 그리고 CompressFast. 일반 이미지의 경우 ImageConfig.MaxImagePixelSize(기본값 3000px)가 출력 크기를 제한합니다.

페이지 캐싱 — 메모리 vs. 재렌더링

BaseConfig.CachePages(기본값 true)는 세션 기간 동안 모든 렌더된 페이지를 메모리에 보관합니다. 이는 인터랙티브 뷰잉에 적합한 기본값이며, 사용자는 앞뒤로 스크롤합니다. 다음 경우에 비활성화하세요:

  • 문서가 매우 크고 한 번만 앞에서 뒤까지 보는 경우,
  • 다수의 동시 세션이 캐시된 페이지를 곱셈적으로 늘릴 경우,
  • RAM을 차지하기보다 뷰당 CPU 사용을 선호하는 경우.
csharp
var token = await viewer.OpenDocumentAsync(path, new PdfConfig { CachePages = false });

클라이언트에서는 ViewerConfig.CacheEnabled = true가 브라우저 메모리에 다가오는 페이지 이미지의 작은 이동 윈도우를 미리 로드합니다. 이는 뷰당 프리패치 캐시이며, 지속적인 localStorage가 아닙니다.

세션 — 눈에 보이지 않는 메모리

열린 모든 세션은 파싱된 문서 모델과 (CachePages가 켜져 있다면) 렌더된 페이지를 보관하며, 슬라이딩 TimeOut(기본값 60분)이 마지막 요청 이후 경과할 때까지 유지됩니다. 이 상황을 제어하는 두 가지 습관은 다음과 같습니다:

  • 작업이 끝난 문서를 닫으세요. viewer.CloseDocument(token)은 대기 창을 기다리지 않고 엔진을 즉시 해제합니다.
  • 타임아웃을 적절히 설정하세요. 사용자가 2분 정도 살펴보는 미리보기는 1시간 세션이 필요하지 않습니다:
csharp
var token = await viewer.OpenDocumentAsync(path, new DocOptions { TimeOut = 10 });

트레이드오프를 기억하세요: 만료된 후 위젯은 Document session not found. Please re-open document. 라는 메시지를 표시합니다 — 실제 읽기 세션에 맞는 타임아웃을 선택하세요.

포맷별 스위치

  • Excel: MemoryOptimizationPreference는 기본적으로 켜져 있으며 매우 큰 워크북을 렌더링할 때 메모리 사용량을 줄입니다 — 켜둔 상태를 유지하거나 메모리를 약간의 속도 향상과 교환하려면 false로 설정하세요; SheetNames / PrintArea는 중요한 부분만 렌더링하도록 제한합니다.
  • Redirect 모드에는 초기 비용이 있습니다: DefaultRender = false는 열 때 전체 문서를 PDF로 변환합니다. 이는 네이티브 텍스트 기반 검색을 가능하게 하지만, 500페이지 문서에서는 열기 호출 시 변환이 발생합니다 — 무조건 활성화하지 마세요.
  • Linux/Docker에서 Word/PPT: 폰트가 없으면 느린 폰트 대체 탐색과 잘못된 메트릭이 발생합니다; FontFolders를 폰트가 들어 있는 디렉터리로 지정하세요.
  • Linux/macOS에서 프레젠테이션: PPT/PPTX/PPS/POT/ODP 파일을 열 수 있지만 현재 프레젠테이션 엔진으로 렌더링하려면 네이티브 libgdiplus와 런타임 스위치 System.Drawing.EnableUnixSupport=true가 필요합니다. 다른 포맷군은 일반적인 크로스플랫폼 렌더링 경로를 사용합니다.

클라이언트 측 전략

  • LargeDoc = true — 매우 큰 문서에 대한 지연 로드 전략; 사용자가 페이지에 접근할 때 로드됩니다.
  • AutoLoad = false(기본값) — 실제로 View(token)을 호출할 때까지 렌더링하지 않습니다.
  • ShowThumbs = false — 단일 페이지 또는 임베디드 미리보기에서 썸네일 생성/요청을 건너뜁니다.
  • FixedZoom를 활성화하면 자유형 줌 변화를 방지합니다; C# ViewerConfig를 매핑할 때 작은 화면에 맞게 FixedZoomPercentMobile(C# 기본값 75)를 조정하세요.

요청당이 아니라 한 번만 시작

Encoding.RegisterProvider(CodePagesEncodingProvider.Instance)는 Program.cs에 위치해야 합니다 — 요청당 인코딩을 등록하는 것은 불필요한 작업이며, 이를 완전히 놓치면 레거시 코드 페이지 문서가 깨집니다.

튜닝 체크리스트

  1. 사용자 경험(UX)이 허용하는 가장 낮은 ImageResolution을 설정하세요.
  2. 인터랙티브 뷰잉에는 CachePages를 켜두고, 일회성 또는 고동시성 시나리오에서는 끄세요.
  3. 세션을 명시적으로 닫고, 사용이 급증하는 경우 TimeOut을 짧게 설정하세요.
  4. 큰 문서의 경우 클라이언트에서 LargeDoc와 기본값인 AutoLoad = false를 사용하세요.
  5. DefaultRender = false는 텍스트가 포함된 PDF 투영이 필요할 때만 사용하세요.

이 페이지가 도움이 되었나요?