분산 서버 구성에서 Doconut 사용하기

PDF, Office 파일, CAD 도면, 이미지 등을 ASP.NET Core 노드 클러스터에서 제공해야 할 때, Doconut의 분산 모드는 모든 노드가 공유 위치에서 동일한 페이지 아티팩트를 읽을 수 있게 해줍니다. 결과적으로 로드 밸런서 뒤에서 스티키 세션 없이 작동하는 수평 확장 가능한 보안 뷰어를 얻을 수 있습니다.

분산 모드가 중요한 이유

• 확장성 – 각 노드는 UNC 또는 클라우드 공유에 페이지를 게시할 수 있으며, 다른 노드는 즉시 이를 제공할 수 있습니다.
• 보안 – 아티팩트는 공유 폴더에 암호화되어 저장되며, 뷰어는 ASP.NET 세션 토큰을 사용해 모든 요청을 검증합니다.
• Office 의존성 없음 – Converter 플러그인은 서버 측에서 실행되어 Word, Excel, PowerPoint, CAD, 이미지 등을 PDF 또는 이미지로 변환하며 Microsoft Office를 설치할 필요가 없습니다.

이러한 특성 덕분에 엔터프라이즈 DMS, CRM, e‑learning 포털은 .NET 백엔드 내부에서 문서 처리를 유지하면서 수십 개의 컨테이너로 확장할 수 있습니다.

분산 모드를 위한 공유 스토리지

분산 모드에서 Doconut은 페이지 아티팩트(PDF 페이지, 이미지 타일 등)가 모든 노드가 접근 가능한 스토리지 위치에 기록되기를 기대합니다—네트워크 공유, Azure Blob 컨테이너, S3 버킷, 혹은 Progressive Cloud Publishing 기능이 지원하는 기타 공유 스토리지일 수 있습니다. 뷰어는 문서별 보안 토큰에 맞는 아티팩트 폴더를 자동으로 찾으므로, 선택한 스토리지에 대한 읽기‑쓰기 권한만 동일하게 설정하면 추가 코드가 필요하지 않습니다.

팁: 모든 인스턴스 구성에 동일한 UNC 경로(예: \\fileserver\doconut) 또는 클라우드 URL을 사용하고 폴더 권한을 일관되게 유지하세요. 기본적으로 UsePerTokenSubfolders 동작이 활성화되어 각 문서의 페이지를 격리합니다.

Doconut 및 세션 미들웨어 등록

Doconut은 문서별 보안을 위해 ASP.NET Core 세션 상태에 의존합니다. 최소 API 프로젝트를 사용할 때만 분산 캐시가 필요하고, MVC나 Razor Pages는 이미 이를 포함합니다.

builder.Services.AddDoconut(options =>
{
    options.LicensePath = "Doconut.Viewer.lic";
});

builder.Services.AddDistributedMemoryCache(); // 세션에 캐시가 필요합니다
builder.Services.AddSession();                 // Doconut는 세션에 대해 검증합니다

app.UseSession();               // UseDoconut() 이전에 실행되어야 합니다
app.UseDoconutResources();      // 정적 뷰어 자산을 등록합니다
app.Map("/doconut", branch => branch.UseDoconut());

사용자 정의 경로 (선택 사항)

다른 라우트가 /doconut와 충돌한다면, 경로를 한 번만 변경하고 클라이언트 BasePath와 동기화하세요:

builder.Services.AddDoconut(options =>
{
    options.MiddlewarePath = "/docs-engine";
    options.ResourcesPath  = "/docs-assets";
});
app.UseDoconutResources();
app.Map("/docs-engine", branch => branch.UseDoconut());

MiddlewarePath 또는 ResourcesPath 앞에 슬래시를 추가하지 마세요; 뷰어가 자동으로 슬래시를 삽입합니다.

전체 예시: 최소‑API 구현

아래는 공유 스토리지 요구사항, 세션 처리, Doconut 등록을 모두 결합한 간결하고 프로덕션 준비된 설정 예시입니다.

var builder = WebApplication.CreateBuilder(args);

// 1️⃣ 핵심 Doconut 등록
builder.Services.AddDoconut(options =>
{
    options.LicensePath = Path.Combine(
        AppContext.BaseDirectory, "wwwroot", "Doconut.Viewer.lic");
    options.MiddlewarePath = "/doconut";
    options.ResourcesPath  = "/doconut-res";
});

// 2️⃣ 세션 및 캐시 (보안을 위해 필요)
builder.Services.AddDistributedMemoryCache();
builder.Services.AddSession();

var app = builder.Build();

app.UseRouting();
app.UseSession();
app.UseDoconutResources();                     // 정적 뷰어 번들
app.Map("/doconut", branch => branch.UseDoconut());

app.Run();

이 바이너리를 Docker 컨테이너나 Windows 서비스 여러 개에 배포하고 로드 밸런서 뒤에 두세요. 각 인스턴스가 페이지 아티팩트를 위한 공유 스토리지 위치에 접근할 수만 있다면, 뷰어는 어느 노드에서든 페이지를 가져오며 업로드/변환 작업도 노드 간 이동을 견딜 수 있습니다.

로드 밸런서 뒤에 배포하기

1. 동일한 기본 URL을 노출 (예: 모든 노드에서).
2. 스티키 세션 비활성화 – Doconut의 분산 모드가 세션 어피니티 필요성을 없앱니다.
3. 헬스 모니터링이 애플리케이션의 기본 엔드포인트(예: /health)를 확인하도록 설정해, 로드 밸런서가 살아있는 노드에만 트래픽을 라우팅하도록 합니다.
4. 공유 폴더 성장 모니터링 – 기본 TTL은 30분이며 스토리지를 제한하지만, 컴플라이언스 요구에 따라 조정할 수 있습니다.

이 단계들을 따르면 문서 중심 .NET 애플리케이션이 수천 명의 동시 뷰어를 지원하고, 모든 페이지를 휴식 상태에서도 암호화하며, 각 서버에 Office를 설치하는 오버헤드를 피할 수 있습니다.

시도해 보고 싶나요? Doconut의 무료 체험을 받아 몇 개의 컨테이너를 띄우고 공유 UNC 경로를 지정한 뒤, 뷰어가 스티키 세션 쿠키 없이 어떻게 확장되는지 확인해 보세요.