Distribuované nasazení

Poskytněte jeden dokument z několika uzlů

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

Jeden uzel to nepotřebuje: běžná cesta OpenDocumentAsync uchovává 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ž požadavky na stránku mohou 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 obě poloviny potřebují

Publikátor zapisuje pomocí FileShareConfig a čtecí obsluha poskytuje 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í strana čeká na stránku, kterou pozadí stále zapisuje; 0 (výchozí) kontroluje jednou. Nemá žádný vliv na dokumenty publikované synchronně

Write side — 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, index vyhledávání a metadata — a vrátí se, když 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ý lístek — viz Zabezpečení napříč uzly.

Čtecí strana — poskytovat ze sdíleného

Namontujte handler FileShare na větev, kterou volá klient — /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 argument typu. 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ý dosáhne jeho větve.

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

Volitelné: publikovat na pozadí

Ve výchozím nastavení PublishAsync vykresluje celý dokument před tím, než se vrátí. Aby se vrátil okamžitě po vytvoření tokenu a umožnil hostovanému workeru renderovat do stejné složky, zaregistrujte frontu s opt‑in 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.

Pak 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 nasycena, EnqueueAsync vyhodí DistributedPublishQueueFullException. Odpovězte na to pomocí 503 a hlavičky Retry-After, aby klienti spíše ustoupili než se zasekli:

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 přijít dříve, než worker tuto stránku zapíše. Čtecí strana čeká až do ReadReadyPollMs a poté odpovídá 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í to jen pro publikování na pozadí do složek po 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é. Povolte opakování na widgetu:

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

Klient, který neopakování neprovádí, zobrazuje poškozené dlaždice pro stránky, které se stále 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 legitimní požadavky; farma proto nastaví UnsafeMode = true.

UnsafeMode = true není bezpečnostní model — je to odstranění modelu, který již neplatí.

1. Zaregistrujte zabezpečení lístku 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ý kruh 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ěřujte lístky na čtecí straně. UseDoconutDistributedDocumentSecurity() se umisťuje na čtecí větev před UseDoconutCloud, jako v ukázce čtení.

3. Vydávejte lístek při otevření dokumentu. Lístek pojmenovává 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 prostřednictvím 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 do widgetu. Prohlížeč posílá lístek jako access s každým požadavkem:

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 vázán na jinou cookie prohlížeče nebo byl vydán jinému přihlášenému uživateli. Odpoví 403 — s chybovým obrázkem UnauthorizedMessage pro požadavky na stránky a miniatury, 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 nepoužívejte jako 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 uvolňuje lokální relaci. Pro odstranění publikovaných artefaktů dokumentu ze sdíleného úložiště, vydavatel poskytuje:

text
bool CloseDistributedDocument(FileShareConfig fileShareConfig, string token)

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

Checklist

  1. Vytvořte FileShareConfig v jednom pomocném modulu, 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 společně a nastavte pro čtecí stranu nenulovou hodnotu ReadReadyPollMs.
  6. Nahraďte kontrolu na úrovni relace podepsanými přístupovými tokeny — jedním klíčovým prstencem Data Protection na každém uzlu, UseDoconutDistributedDocumentSecurity() na čtecí větvi, tokenem 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 uzlu.

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