Distribuované nasazení

Obsluhujte jeden dokument z několika uzlů

Když několik uzlů obsluhuje stejné dokumenty, uzel, který vykresluje dokument, není nutně uzel, který odpovídá na požadavky stránky v prohlížeči. Doconut rozděluje tuto úlohu na dvě explicitní poloviny — zápisová část, která publikuje artefakty dokumentu do sdíleného úložiště, a čtecí část, která je obsluhuje z libovolného uzlu.

Jeden uzel nepotřebuje nic z toho: běžná cesta OpenDocumentAsync udržuje dokument v paměti toho uzlu a váže jej k relaci prohlížeče (viz Relace a zabezpečení). Použijte tuto stránku, když mohou požadavky na stránku dopadnout na uzel, který otevření nikdy neviděl.

Jak se dvě poloviny doplňují

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

Sdílená konfigurace, kterou potřebují obě poloviny

Publikátor zapisuje pomocí FileShareConfig a čtecí obsluha obsluhuje pomocí jednoho. Pokud se RootPath nebo UsePerTokenSubfolders mezi nimi liší, druhý uzel odpoví 404. Vytvořte konfiguraci na jednom místě a zaregistrujte ji jednou, aby obě poloviny četly stejný objekt:

csharp
var rootPath = builder.Configuration["Doconut:SharedRoot"]!;   // např. \\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,
    };
}

Předejte asyncPublish: true, když zapnete publikování na pozadí.

FileShareConfig se nachází v Doconut.Clouds, spolu s AzureConfig, AmazonConfig, GoogleCloudConfig, DropBoxConfig, RedisConfig, CDNConfig a FTPConfig.

VlastnostÚčel
LocationCloudLocation.FileShare pro UNC/místní sdílení
RootPathSdílená složka, ke které má přístup každý uzel
UsePerTokenSubfoldersUchovávejte artefakty každého dokumentu ve své vlastní složce {token} (výchozí true)
ReadReadyPollMsJak dlouho čtecí část čeká na stránku, kterou publikování na pozadí stále zapisuje; 0 (výchozí) kontroluje jednou. Nemá žádný vliv na dokumenty publikované synchronně

Zápisová část — publikovat dokument

Vložte DistributedDocumentPublisher a publikujte místo otevření lokální relace. Jeden volání vykreslí a zapíše kompletní sadu artefaktů — stránky, informace o dokumentu, vyhledávací index a metadata — a vrátí se, až je hotovo:

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 nese Token, ArtifactPath, TotalPages a Format. Token jde do prohlížeče přesně jako běžný token prohlížeče. Ve farmě endpoint také vrací podepsaný přístupový ticket — viz Zabezpečení napříč uzly.

Čtecí strana — obsluhovat ze sdíleného úložiště

Namontujte handler FileShare na větev, kterou klient volá — /doconut, odpovídající BasePath: 'doconut' — za kontrolou ticketu:

csharp
var app = builder.Build();

app.UseDoconutResources();
app.Map("/doconut", branch =>
{
    branch.UseDoconutDistributedDocumentSecurity();   // podepsané tikety — viz níže
    branch.UseDoconutCloud<FileShareCloudHandler>(options =>
    {
        options.Location          = CloudLocation.FileShare;
        options.CloudUploadConfig = app.Services.GetRequiredService<FileShareConfig>();
    }, "/");
});

UseDoconutCloud přijímá poskytovatele jako typový argument. Handlery jsou pojmenovány <Provider>CloudHandler — FileShareCloudHandler, AzureCloudHandler, AmazonS3CloudHandler, GoogleCloudHandler, DropBoxCloudHandler, RedisCloudHandler, FTPCloudHandler a CDNCloudHandler. S předponou cesty "/" handler odpovídá na každý požadavek, který dorazí k jeho větvi.

CDN handler je pouze pro čtení — poskytuje to, co je již na CDN; nenahrává.

Volitelné: publikovat na pozadí

Ve výchozím nastavení PublishAsync vykreslí celý dokument před tím, než se vrátí. Pro okamžité vrácení po vytvoření tokenu a umožnění hostovanému workeru renderovat do stejné složky, zaregistrujte volitelnou frontu a vytvořte sdílenou konfiguraci pomocí asyncPublish: true:

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

Bez této registrace se nic nezaregistruje a publikování zůstává synchronní, přesně jako dříve.

Poté zavolejte EnqueueAsync místo PublishAsync. (DistributedDocumentPublishOptions.Async je pouze příznak, který může váš vlastní kód přečíst pro výběr mezi dvěma cestami; vydavatel jej ignoruje.) Fronta je omezená: když je zaplněná, EnqueueAsync vyhodí DistributedPublishQueueFullException. Odpovězte na to pomocí 503 a hlavičky Retry-After, aby klienti odložili požadavky místo zablokování:

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

Stránky, které ještě nejsou zapsány: HTTP 202

Při publikování na pozadí může požadavek na stránku dorazit dříve, než worker stránku zapíše. Čtecí strana čeká až ReadReadyPollMs a poté odpoví HTTP 202 Accepted místo blokování požadavku.

FirstPagePriority = true zkracuje čekání na první zobrazení: stránka 1 je nejprve zapsána do složky dokumentu, takže se dokument otevře, zatímco pozdější stránky se stále renderují. Platí pouze pro publikování na pozadí do složek podle tokenu (UsePerTokenSubfolders = true); synchronní PublishAsync to ignoruje, protože jeho volající čeká na celý dokument.

Tím se čekání přesune na klienta, kde je omezené a viditelné. Povolit opakování na widgetu:

javascript
const objViewer = $('#div_ctlDoc').docViewer({
    BasePath:   'doconut',
    ResPath:    'doconut-res/images',
    retryOn409: true      // opakování 202 (a starší 409) odpovědi připravenosti
});

Klient, který neopakovaně požaduje, zobrazuje poškozené dlaždice pro stránky, které se ještě renderují. Rozpočet pro opakování a jeho výchozí hodnoty (retryInitialDelayMs, retryBackoffFactor, retryMaxDelayMs, retryMaxAttempts, retryMaxTotalMs) jsou zdokumentovány v ViewerConfig.

Zabezpečení napříč uzly

Tokeny vázané na relaci předpokládají, že obsluhující uzel viděl počáteční požadavek. Ve farmě tomu tak není, takže kontrola na úrovni relace by odmítla oprávněné požadavky; farmu proto nastavuje UnsafeMode = true.

UnsafeMode = true není bezpečnostní model — je to odstranění modelu, který již neplatí.
Nahraďte jej podepsanými přístupovými lístky, které může každý uzel ověřit nezávisle. Čtyři součásti spolupracují.

1. Zaregistrujte zabezpečení lístků na každém uzlu.
Lístky jsou chráněny pomocí ASP.NET Core Data Protection, takže každý uzel musí používat stejný klíčový okruh a název aplikace; uzel s odlišnými klíči nemůže přečíst lístek vydaný jiným uzlem.

csharp
using Microsoft.AspNetCore.DataProtection;

builder.Services.AddDataProtection()
    .PersistKeysToFileSystem(new DirectoryInfo(@"\\fileserver\doconut-keys"))   // sdíleno každým uzlem
    .SetApplicationName("doconut-farm");

builder.Services.AddDoconut(options => options.UnsafeMode = true);
builder.Services.AddDoconutDistributedDocumentSecurity(options =>
{
    options.TicketLifetimeMinutes = 60;   // výchozí
});

2. Ověřte lístky na čtecí straně.
UseDoconutDistributedDocumentSecurity() se umisťuje na čtecí větev před UseDoconutCloud, jako v ukázce čtecí strany.

3. Vydávejte lístek při otevření dokumentu.
Lístek uvádí token, prohlížeč (prostřednictvím cookie, kterou čtecí strana porovnává) a přihlášeného uživatele, pokud existuje:

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

    // Propojte tiket s tímto prohlížečem přes cookie, kterou kontroluje čtecí strana
    var cookieName = security.Value.BrowserCookieName;   // "doconut-client" ve výchozím nastavení
    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. Předávejte oba widgetu.
Prohlížeč posílá lístek jako access u každého požadavku:

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

Čtecí strana odmítne požadavek, jehož lístek chybí, je neplatný, byl vydán pro jiný token, vypršel, je svázán s jiným cookie prohlížeče nebo byl vydán jinému přihlášenému uživateli. Odpoví kódem 403 — s chybovým obrázkem UnauthorizedMessage pro požadavky na stránku a miniaturu, jinak jako prostý text. Otestujte pomocí skutečného prohlížeče nebo klienta, který uchovává cookies.

Nikdy nepřenášejte UnsafeMode = true zpět do nasazení s jedním uzlem a nikdy jej nepovažujte za zkratku pro selhávající kontrolu relace na jednom uzlu — správná oprava je AddSession() / UseSession(). Viz Relace a zabezpečení.

Uzavření publikovaného dokumentu

CloseDocument(token) na injektovaném Viewer ukončuje lokální relaci. Pro odstranění publikovaných artefaktů dokumentu ze sdíleného úložiště publisher poskytuje:

text
bool CloseDistributedDocument(FileShareConfig fileShareConfig, string token)

Předávejte stejný FileShareConfig, se kterým byl dokument publikován.

Kontrolní seznam

  1. Vytvořte FileShareConfig v jednom pomocníku, zaregistrujte jej jednou a použijte jej z obou částí.
  2. Nasmerujte RootPath na složku, ke které má přístup každý uzel.
  3. Publikujte pomocí PublishAsync(...), nebo EnqueueAsync(...) s publikováním na pozadí.
  4. Obsluhujte pomocí UseDoconutCloud<FileShareCloudHandler>(...) na větvi, kterou klient volá.
  5. Při publikování na pozadí zapněte FirstPagePriority a retryOn409 současně a dejte čtecí straně nenulové ReadReadyPollMs.
  6. Nahraďte kontrolu na úrovni relace podepsanými přístupovými lístky — jedním klíčovým prstencem Data Protection na každém uzlu, UseDoconutDistributedDocumentSecurity() na čtecí větvi, lístkem z otevřeného koncového bodu — a nezasílejte UnsafeMode = true samostatně.
  7. Ověřte otevřením dokumentu na jednom uzlu a požádáním o pozdější stránku z jiného.

Byla tato stránka užitečná?