분산 배포

여러 노드에서 하나의 문서 제공

여러 노드가 동일한 문서를 제공할 때, 문서를 렌더링하는 노드가 반드시 브라우저의 페이지 요청에 응답하는 노드인 것은 아닙니다. 이번 릴리스에서는 이 작업을 두 개의 명확한 절반으로 나눕니다 — 공유 스토리지에 문서의 아티팩트를 게시하는 쓰기 측과, 어떤 노드에서든 이를 제공하는 읽기 측.

현재 애플리케이션에서 UseDoconutWebFarm(...)을 호출하고 있다면, 이 페이지가 그 대체 역할을 합니다. 이번 릴리스에는 UseDoconutWebFarm도, WebFarmOptions도 존재하지 않습니다.

토폴로지는 변경되지 않습니다. 오늘 사용하고 있는 동일한 UNC 경로를 공유 루트로 지정하면 모든 노드는 현재와 같은 방식으로 계속 작동합니다. 변하는 점은 게시가 렌더링의 부수 효과가 아니라 호출하는 작업이 된다는 것입니다.

웹 팜 미들웨어를 대체한 것

이전에는 하나의 미들웨어가 모든 작업을 수행했습니다: 공유 폴더에서 사전 렌더링된 이미지를 제공하고, 다른 노드가 아직 이미지를 쓰고 있는 동안 폴링했습니다. 대기 시간은 눈에 보이지 않는 예산이었으며 — “페이지가 나타날 때까지 최대 3분까지 차단”이라는 식이었습니다.

이제 동일한 작업은 두 번의 호출로 나뉘며, 이를 직접 보고 이해할 수 있습니다:

text
node A            open request
                      -> PublishAsync(...)   writes pages, document info,
                                             search index and metadata
                                             into  RootPath/{token}/
                      -> returns the token

node B            ?token=...&page=7
                      -> UseDoconutCloud<FileShareCloudHandler>
                      -> reads RootPath/{token}/ and serves the page

양쪽 절반이 필요로 하는 공유 구성

게시자는 FileShareConfig을 사용해 기록하고, 읽기 핸들러는 이를 사용해 제공합니다. RootPath 또는 UsePerTokenSubfolders이 서로 다르면 다른 노드는 404 응답을 반환합니다. 구성을 정확히 한 곳에서만 만들고 한 번만 등록하여 양쪽 절반이 동일한 객체를 읽도록 합니다:

csharp
var rootPath = builder.Configuration["Doconut:SharedRoot"]!;   // 예: \\fileserver\doconut
builder.Services.AddSingleton(SharedStore.Config(rootPath, asyncPublish: false));

internal static class SharedStore
{
    public static FileShareConfig Config(string rootPath, bool asyncPublish) => new()
    {
        Location              = CloudLocation.FileShare,
        RootPath              = rootPath,
        UsePerTokenSubfolders = true,
        ReadReadyPollMs       = asyncPublish ? 250 : 0,
    };
}

백그라운드 게시를 활성화할 때는 asyncPublish: true을 전달합니다. (백그라운드 게시 참고).

FileShareConfig은 Doconut.Clouds에 존재하며, AzureConfig, AmazonConfig, GoogleCloudConfig, DropBoxConfig, RedisConfig, CDNConfig, 그리고 FTPConfig와 함께 있습니다. 이전 라이브러리에서는 이들이 Doconut.Configs.Cloud에 있었으며, 클래스 이름은 변경되지 않았습니다.

속성목적
LocationCloudLocation.FileShare (UNC/로컬 공유용)
RootPath모든 노드가 접근할 수 있는 공유 폴더
UsePerTokenSubfolders각 문서의 아티팩트를 자체 {token} 폴더에 보관합니다 (기본값 true)
ReadReadyPollMs백그라운드 게시가 아직 페이지를 쓰고 있을 때 읽기 측이 기다리는 시간; 0 (기본값) 은 한 번만 확인합니다. 동기식으로 게시된 문서에는 영향을 주지 않습니다.

쓰기 측 — 문서 게시

DistributedDocumentPublisher를 주입하고 로컬 세션을 여는 대신 게시합니다. 하나의 호출로 페이지, 문서 정보, 검색 인덱스, 메타데이터 등 전체 아티팩트 세트를 렌더링하고 기록하며, 작업이 완료되면 반환됩니다:

csharp
app.MapPost("/api/open", async (string fileName, FileShareConfig shareConfig,
    DistributedDocumentPublisher publisher, CancellationToken ct) =>
{
    var path            = Path.Combine("files", Path.GetFileName(fileName));
    var config          = new PdfConfig { AllowSearch = true };
    var documentOptions = new DocOptions { TimeOut = 60 };
    var publishOptions  = new DistributedDocumentPublishOptions { CleanUpStagingDirectory = true };

    DistributedDocumentPublishResult result = await publisher.PublishAsync(
        path, shareConfig, config, documentOptions, publishOptions, ct);

    return Results.Text(result.Token);
});

DistributedDocumentPublishResult은 Token, ArtifactPath, TotalPages, 그리고 Format을 포함합니다. 토큰은 일반 뷰어 토큰과 동일하게 브라우저로 전달됩니다. 팜 환경에서는 엔드포인트가 서명된 액세스 티켓도 반환합니다 — 노드 간 보안을 참고하세요.

이 단일 호출은 이전의 두 단계 — 문서를 로컬 세션으로 열고, 그 후 ExportToPng(sharedPath)을 사용해 이미지를 공유 폴더에 덤프하던 작업 — 를 대체합니다. ExportToPng와 ExportToCloud은 여기서 대응되는 것이 없습니다.

읽기 측 — 공유에서 제공

클라이언트가 이미 호출하는 동일한 브랜치에 FileShare 핸들러를 마운트하고, 티켓 검증 뒤에 배치합니다:

csharp
var app = builder.Build();

app.UseDoconutResources();
app.MapWhen(
    ctx => ctx.Request.Path.Value?.EndsWith("DocImage.axd", StringComparison.OrdinalIgnoreCase) == true,
    branch =>
    {
        branch.UseDoconutDistributedDocumentSecurity();   // 서명된 티켓 — 아래를 보세요
        branch.UseDoconutCloud<FileShareCloudHandler>(options =>
        {
            options.Location          = CloudLocation.FileShare;
            options.CloudUploadConfig = app.Services.GetRequiredService<FileShareConfig>();
        }, "/");
    });

UseDoconutCloud는 이번 릴리스에서 제네릭입니다: 제공자는 미들웨어 내부에서 전환되는 Location 값이 아니라 타입 인수입니다. 핸들러는 <Provider>CloudHandler — FileShareCloudHandler, AzureCloudHandler, AmazonS3CloudHandler, GoogleCloudHandler, DropBoxCloudHandler, RedisCloudHandler, FTPCloudHandler, 그리고 CDNCloudHandler 로 명명됩니다. 경로 접두사 "/"와 함께, 핸들러는 해당 브랜치에 도달하는 모든 요청에 응답합니다.

CDN 핸들러는 읽기 전용이며 — CDN에 이미 존재하는 것을 제공하고, 업로드는 하지 않습니다.

선택 사항: 백그라운드에서 게시

기본적으로 PublishAsync는 반환하기 전에 전체 문서를 렌더링합니다. 토큰이 생성되는 즉시 반환하고 호스팅된 워커가 동일한 폴더에 렌더링하도록 하려면, 옵트인 큐를 등록하고 asyncPublish: true로 공유 구성을 빌드하십시오:

csharp
builder.Services.AddDoconut(options => { /* … */ });
builder.Services.AddDoconutDistributedAsyncPublish();

이 등록이 없으면 아무 것도 등록되지 않으며, 게시가 이전과 동일하게 동기식으로 유지됩니다.

그런 다음 PublishAsync 대신 EnqueueAsync를 호출합니다. (DistributedDocumentPublishOptions.Async는 두 경로 중 하나를 선택하기 위해 사용자의 코드가 읽을 수 있는 플래그일 뿐이며, 퍼블리셔는 이를 무시합니다.) 큐는 제한됩니다: 포화 상태가 되면 EnqueueAsync가 DistributedPublishQueueFullException를 발생시킵니다. 클라이언트가 대기하지 않고 뒤로 물러날 수 있도록 503와 Retry-After 헤더로 응답하십시오:

csharp
app.MapPost("/api/open", async (string fileName, FileShareConfig shareConfig,
    IDistributedPublishQueue publishQueue, HttpResponse response, CancellationToken ct) =>
{
    var path            = Path.Combine("files", Path.GetFileName(fileName));
    var config          = new PdfConfig { AllowSearch = true };
    var documentOptions = new DocOptions { TimeOut = 60 };
    var publishOptions  = new DistributedDocumentPublishOptions { FirstPagePriority = true };

    try
    {
        var token = await publishQueue.EnqueueAsync(
            path, shareConfig, config, documentOptions, publishOptions, ct);
        return Results.Text(token);
    }
    catch (DistributedPublishQueueFullException)
    {
        response.Headers["Retry-After"] = "5";
        return Results.StatusCode(503);
    }
});

아직 작성되지 않은 페이지: HTTP 202

백그라운드 게시를 사용하면, 워커가 페이지를 작성하기 전에 페이지 요청이 도착할 수 있습니다. 읽기 측은 최대 ReadReadyPollMs까지 대기한 뒤, 요청을 차단하는 대신 HTTP 202 Accepted를 응답합니다.

FirstPagePriority = true은 첫 번째 뷰에 대한 대기 시간을 줄입니다: 페이지 1이 문서 폴더에 먼저 작성되므로, 이후 페이지가 아직 렌더링 중일 때도 문서가 열립니다. 이는 per-token 폴더에 대한 백그라운드 게시(UsePerTokenSubfolders = true)에만 적용됩니다; 동기식 PublishAsync는 이를 무시합니다, 왜냐하면 호출자는 전체 문서를 기다리기 때문입니다.

이렇게 하면 대기가 클라이언트 쪽으로 이동하며, 제한되고 가시적입니다. 위젯에서 재시도를 활성화하십시오:

javascript
const objViewer = $('#div_ctlDoc').docViewer({
    BasePath:   '/',
    ResPath:    'doconut-res/images',
    retryOn409: true      // 재시도 202 (및 레거시 409) 준비 응답
});

재시도를 하지 않는 클라이언트는 아직 렌더링 중인 페이지에 대해 깨진 타일을 표시합니다. 재시도 예산 및 기본값(retryInitialDelayMs, retryBackoffFactor, retryMaxDelayMs, retryMaxAttempts, retryMaxTotalMs)은 뷰어 구성에서 문서화되어 있습니다.

이 쌍 — FirstPagePriority와 함께하는 백그라운드 게시, 그리고 읽기 측 폴링 — 은 이전 PageWaitTimeSeconds와 StartWaitFromPage 설정을 대체합니다. 이제는 더 이상 존재하지 않습니다.

노드 간 보안

세션에 바인딩된 토큰은 제공 노드가 최초 요청을 보았다고 가정합니다. 팜에서는 그렇지 않으므로 세션당 검사가 정상 요청을 거부하게 됩니다; 따라서 팜은 UnsafeMode = true을 설정합니다.

UnsafeMode = true은 보안 모델이 아니라 더 이상 적용되지 않는 모델을 제거하는 것입니다. 이를 서명된 액세스 티켓으로 교체하십시오. 각 노드가 독립적으로 검증할 수 있습니다. 네 가지 요소가 함께 작동합니다.

1. 모든 노드에서 티켓 보안을 등록합니다. 티켓은 ASP.NET Core Data Protection으로 보호되므로 모든 노드는 동일한 키 링과 애플리케이션 이름을 사용해야 합니다; 다른 키를 가진 노드는 다른 노드가 발행한 티켓을 읽을 수 없습니다.

csharp
using Microsoft.AspNetCore.DataProtection;

builder.Services.AddDataProtection()
    .PersistKeysToFileSystem(new DirectoryInfo(@"\\fileserver\doconut-keys"))   // 모든 노드에서 공유됨
    .SetApplicationName("doconut-farm");

builder.Services.AddDoconut(options => options.UnsafeMode = true);
builder.Services.AddDoconutDistributedDocumentSecurity(options =>
{
    options.TicketLifetimeMinutes = 60;   // 기본값
});

2. 읽기 측에서 티켓을 확인합니다. UseDoconutDistributedDocumentSecurity()은 UseDoconutCloud 전에 읽기 브랜치에 적용되며, 읽기 측 샘플과 같습니다.

3. 문서가 열릴 때 티켓을 발행합니다. 티켓은 토큰, 브라우저(읽기 측이 비교하는 쿠키를 통해) 및 (있는 경우) 로그인한 사용자를 명시합니다:

csharp
using System.Security.Claims;
using Microsoft.Extensions.Options;

app.MapPost("/api/open", async (string fileName, HttpContext http, FileShareConfig shareConfig,
    DistributedDocumentPublisher publisher, IDocumentAccessTicketProtector protector,
    IOptions<DistributedDocumentSecurityOptions> security, CancellationToken ct) =>
{
    var path   = Path.Combine("files", Path.GetFileName(fileName));
    var result = await publisher.PublishAsync(path, shareConfig, ct: ct);

    // 읽기 측에서 확인하는 쿠키를 통해 ticket을 이 browser에 바인딩합니다.
    var cookieName = security.Value.BrowserCookieName;   // "doconut-client" 기본값으로
    if (!http.Request.Cookies.TryGetValue(cookieName, out var browserId) || string.IsNullOrEmpty(browserId))
    {
        browserId = Guid.NewGuid().ToString("N");
        http.Response.Cookies.Append(cookieName, browserId, new CookieOptions
        {
            HttpOnly = true,
            Secure   = http.Request.IsHttps,
            SameSite = SameSiteMode.Lax
        });
    }

    var access = protector.Protect(new DocumentAccessTicket
    {
        Token      = result.Token,
        BrowserId  = browserId,
        UserId     = http.User.FindFirstValue(ClaimTypes.NameIdentifier) ?? "",
        ExpiresUtc = DateTimeOffset.UtcNow.AddMinutes(security.Value.TicketLifetimeMinutes),
        Nonce      = Guid.NewGuid().ToString("N")
    });

    return Results.Json(new { token = result.Token, access });
});

4. 두 값을 위젯에 전달합니다. 뷰어는 모든 요청에 티켓을 access으로 보냅니다:

javascript
const resp = await fetch('/api/open?fileName=Sample.pdf', { method: 'POST' });
const { token, access } = await resp.json();
objViewer.View(token, access);

읽기 측은 티켓이 없거나, 유효하지 않거나, 다른 토큰용으로 발행되었거나, 만료되었거나, 다른 브라우저 쿠키에 바인딩되었거나, 다른 로그인 사용자에게 발행된 요청을 거부합니다. 응답은 403이며, 페이지 및 썸네일 요청에 대해서는 UnauthorizedMessage 오류 이미지를, 그 외에는 일반 텍스트로 반환합니다. 쿠키를 유지하는 실제 브라우저 또는 클라이언트로 테스트하십시오.

절대로 UnsafeMode = true을 단일 노드 배포로 다시 가져가지 말고, 하나의 노드에서 세션 검사가 실패했을 때의 우회책으로도 사용하지 마십시오 — 그 경우 올바른 해결책은 AddSession() / UseSession()입니다. 세션 및 보안을 참조하십시오.

게시된 문서 닫기

CloseDocument(token)은 주입된 Viewer에서 로컬 세션을 해제합니다. 공유에서 문서의 게시된 아티팩트를 제거하려면, 퍼블리셔가 다음을 노출합니다:

text
bool CloseDistributedDocument(FileShareConfig fileShareConfig, string token)

문서를 게시할 때 사용한 동일한 FileShareConfig을 전달하십시오.

설정별 매핑

이전현재
UseDoconutWebFarm(new WebFarmOptions { … })쓰기 측면에서 PublishAsync(...)와 읽기 측면에서 UseDoconutCloud<FileShareCloudHandler>(...)
WebFarmOptions.PathFileShareConfig.RootPath
PageWaitTimeSeconds / StartWaitFromPageDistributedDocumentPublishOptions.FirstPagePriority와 함께 백그라운드 퍼블리싱, 그리고 FileShareConfig.ReadReadyPollMs
viewer.OpenDocument(...) then viewer.ExportToPng(share)하나의 PublishAsync(...) 호출
viewer.ExportToCloud(cloudConfig)PublishAsync(...)와 제공자 구성
UseDoconutCloud(new CloudOptions { Location = … })UseDoconutCloud<THandler>(options => …, pathPrefix)
DocOptions.IsWebfarm / WebfarmPath여전히 존재하지만, IsWebFarm / WebFarmPath 로 표기됩니다 — 퍼블리시 경로에서는 필요하지 않음
Doconut.Configs.CloudDoconut.Clouds

체크리스트

  1. 하나의 헬퍼에서 FileShareConfig를 구축하고, 한 번 등록한 뒤 양쪽 절반에서 사용합니다.
  2. RootPath를 이미 사용 중인 공유에 지정합니다.
  3. PublishAsync(...)로 퍼블리시하고; 모든 ExportToPng / ExportToCloud 호출을 삭제합니다.
  4. 클라이언트가 호출하는 브랜치에서 UseDoconutCloud<FileShareCloudHandler>(...)로 제공합니다.
  5. 백그라운드 퍼블리싱 시, FirstPagePriority와 retryOn409를 동시에 켜고, 읽기 측면에 0이 아닌 ReadReadyPollMs를 부여합니다.
  6. 세션당 검사를 서명된 액세스 티켓으로 교체합니다 — 모든 노드에 하나의 Data Protection 키 링, 읽기 브랜치에 UseDoconutDistributedDocumentSecurity(), 오픈 엔드포인트에서 티켓 — 그리고 UnsafeMode = true만 단독으로 배포하지 않습니다.
  7. 한 노드에서 문서를 열고 다른 노드에서 늦은 페이지를 요청하여 확인합니다.

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