분산 배포

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

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

단일 노드에서는 이 모든 것이 필요하지 않습니다: 일반 OpenDocumentAsync 경로는 문서를 해당 노드의 메모리에 보관하고 브라우저 세션에 바인딩합니다 (참조 세션 및 보안). 페이지 요청이 열림을 한 번도 보지 못한 노드에 도달할 수 있을 때 이 페이지를 사용하십시오.

두 절반이 맞춰지는 방식

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 와 함께 있습니다.

속성목적
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 를 포함합니다. 토큰은 일반 뷰어 토큰과 동일하게 브라우저로 전달됩니다. 팜 환경에서는 엔드포인트가 서명된 액세스 티켓도 반환합니다 — 참조 노드 간 보안.

읽기 측 — 공유에서 제공

클라이언트가 호출하는 브랜치에 FileShare 핸들러를 마운트합니다 — /doconut, BasePath: 'doconut'와 일치하도록 — 티켓 검증 뒤에서:

csharp
var app = builder.Build();

app.UseDoconutResources();
app.Map("/doconut", branch =>
{
    branch.UseDoconutDistributedDocumentSecurity();   // 서명된 티켓 — 아래를 참조
    branch.UseDoconutCloud<FileShareCloudHandler>(options =>
    {
        options.Location          = CloudLocation.FileShare;
        options.CloudUploadConfig = app.Services.GetRequiredService<FileShareConfig>();
    }, "/");
});

UseDoconutCloud는 제공자를 타입 인자로 받습니다. 핸들러 이름은 <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이 문서 폴더에 먼저 작성되므로 이후 페이지가 아직 렌더링 중일 때도 문서가 열립니다. 이는 토큰별 폴더에 대한 백그라운드 게시(UsePerTokenSubfolders = true)에만 적용되며, 동기식 PublishAsync는 무시합니다. 왜냐하면 호출자는 어쨌든 전체 문서를 기다리기 때문입니다.

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

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

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

노드 간 보안

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

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

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

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);

    // 읽기 측에서 확인하는 쿠키를 통해 티켓을 이 브라우저에 바인딩합니다.
    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()입니다. 세션 및 보안을 참조하십시오.

게시된 문서 닫기

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

text
bool CloseDistributedDocument(FileShareConfig fileShareConfig, string token)

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

체크리스트

  1. 하나의 헬퍼에서 FileShareConfig을 구축하고, 한 번 등록한 뒤 양쪽 절반에서 사용합니다.
  2. RootPath를 모든 노드가 접근할 수 있는 폴더에 지정합니다.
  3. PublishAsync(...)를 사용해 게시하거나, 백그라운드 게시와 함께 EnqueueAsync(...)를 사용합니다.
  4. 클라이언트가 호출하는 브랜치에서 UseDoconutCloud<FileShareCloudHandler>(...)로 서비스를 제공합니다.
  5. 백그라운드 게시를 사용할 경우, FirstPagePriority와 retryOn409를 함께 켜고, 읽기 측에 0이 아닌 ReadReadyPollMs를 제공합니다.
  6. 세션당 검사를 서명된 접근 티켓으로 교체합니다 — 모든 노드에 하나의 Data Protection 키 링, 읽기 브랜치에 UseDoconutDistributedDocumentSecurity(), 열린 엔드포인트에서 발급된 티켓 — 그리고 UnsafeMode = true만 단독으로 배포하지 않습니다.
  7. 한 노드에서 문서를 열고 다른 노드에서 늦은 페이지를 요청하여 확인합니다.

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