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 prohlížeče na stránku. Toto vydání rozděluje tuto úlohu na dvě explicitní poloviny — zapisovací část, která publikuje artefakty dokumentu do sdíleného úložiště, a čtecí část, která je obsluhuje z libovolného uzlu.

Pokud vaše aplikace v současnosti volá UseDoconutWebFarm(...), tato stránka je jeho náhradou. Ani UseDoconutWebFarm, ani WebFarmOptions v tomto vydání neexistují.

Vaše topologie se nemění. Nastavte sdílený kořen na stejnou UNC cestu, kterou používáte dnes, a každý uzel bude nadále fungovat tak, jak funguje nyní. Co se mění, je to, že publikování je operace, kterou voláte, místo vedlejšího efektu vykreslování.

Co nahradilo middleware web-farm

Dříve jedno middleware dělalo vše: obsluhovalo předrenderované obrázky ze sdílené složky a pollovalo, zatímco jiný uzel je ještě zapisoval. Čekání bylo slepý rozpočet — „blokovat až tři minuty v naději, že se stránka objeví“.

Nyní je stejná úloha dvěma voláními, která můžete vidět a rozumně pochopit:

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 oba díly potřebují

Publikátor zapisuje pomocí FileShareConfig a čtecí handler 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 oba díly č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ředávejte 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. V předchozí knihovně byly tyto v Doconut.Configs.Cloud; názvy tříd se nezměnily.

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 pozadí stále zapisuje; 0 (výchozí) kontroluje jednou. Nemá žádný vliv na dokumenty publikované synchronně

Zapisovací část — publikovat dokument

Injektujte DistributedDocumentPublisher a publikujte místo otevírání lokální relace. Jedno 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ý tiket — viz Zabezpečení napříč uzly.

Toto jediné volání nahrazuje předchozí dvojici — otevření dokumentu do lokální relace a následné uložení obrázků na sdílení pomocí ExportToPng(sharedPath). ExportToPng a ExportToCloud zde nemají ekvivalent.

Čtecí strana — obsluhovat ze sdílení

Namontujte obslužný program FileShare na stejnou větev, kterou klient již volá, za kontrolou lístku:

csharp
var app = builder.Build();

app.UseDoconutResources();
app.MapWhen(
    ctx => ctx.Request.Path.Value?.EndsWith("DocImage.axd", StringComparison.OrdinalIgnoreCase) == true,
    branch =>
    {
        branch.UseDoconutDistributedDocumentSecurity();   // podepsané tikety — viz níže
        branch.UseDoconutCloud<FileShareCloudHandler>(options =>
        {
            options.Location          = CloudLocation.FileShare;
            options.CloudUploadConfig = app.Services.GetRequiredService<FileShareConfig>();
        }, "/");
    });

UseDoconutCloud je v tomto vydání generický: poskytovatel je typový argument místo hodnoty Location, která se přepíná uvnitř middleware. Obslužné programy jsou pojmenovány <Provider>CloudHandler — FileShareCloudHandler, AzureCloudHandler, AmazonS3CloudHandler, GoogleCloudHandler, DropBoxCloudHandler, RedisCloudHandler, FTPCloudHandler a CDNCloudHandler. S předponou cesty "/" obslužný program odpovídá na každý požadavek, který dorazí do jeho větve.

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

Volitelné: publikovat na pozadí

Ve výchozím nastavení PublishAsync vykresluje celý dokument před tím, než se vrátí. Pro okamžité vrácení, jakmile je token vytvořen, a nechat hostovaného pracovníka vykreslovat do stejné složky, zaregistrujte frontu s opt‑in a sestavte sdílenou konfiguraci pomocí asyncPublish: true:

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

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

Poté zavolejte EnqueueAsync místo PublishAsync. (DistributedDocumentPublishOptions.Async je jen 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 odradili 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 přijít dříve, než pracovník stránku zapíše. Čtecí strana čeká až do 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 dokument se otevře, zatímco pozdější stránky se stále vykreslují. Platí pouze 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é. Povolit opakování na widgetu:

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

Klient, který neopakování provádí, zobrazuje poškozené dlaždice pro stránky, které se stále vykreslují. Rozpočet pro opakování a jeho výchozí hodnoty (retryInitialDelayMs, retryBackoffFactor, retryMaxDelayMs, retryMaxAttempts, retryMaxTotalMs) jsou zdokumentovány v ViewerConfig.

Tento pár — publikování na pozadí s FirstPagePriority, plus čtecí poll — nahrazuje předchozí nastavení PageWaitTimeSeconds a StartWaitFromPage. Žádné z nich již neexistuje.

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; farmu proto nastavuje UnsafeMode = true.

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

Nahraďte jej podepsanými přístupovými lístky, které může každý uzel ověřit samostatně. Č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ý 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ěřte lístky na čtecí straně.
UseDoconutDistributedDocumentSecurity() se umisťuje na čtecí větev před UseDoconutCloud, jak je uvedeno v ukázka čtecí strany.

3. Vydávejte lístek při otevření dokumentu.
Lístek uvádí token, prohlížeč (prostřednictvím souboru cookie, který č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);

    // Svázat ticket s tímto prohlížečem prostřednictvím cookie, kterou kontroluje čtecí část
    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 vázán na jiný soubor 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ánku a miniaturu, jinak jako prostý text. Otestujte pomocí skutečného prohlížeče nebo klienta, který uchovává soubory cookie.

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 vloženém Viewer ruší lokální relaci. Pro odebrání publikovaných artefaktů dokumentu ze sdíleného úložiště poskytovatel zveřejňuje:

text
bool CloseDistributedDocument(FileShareConfig fileShareConfig, string token)

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

Mapování nastavení po nastavení

PředchozíNyní
UseDoconutWebFarm(new WebFarmOptions { … })PublishAsync(...) na zápisové straně plus UseDoconutCloud<FileShareCloudHandler>(...) na čtecí straně
WebFarmOptions.PathFileShareConfig.RootPath
PageWaitTimeSeconds / StartWaitFromPagePublikování na pozadí s DistributedDocumentPublishOptions.FirstPagePriority, a FileShareConfig.ReadReadyPollMs
viewer.OpenDocument(...) then viewer.ExportToPng(share)jeden PublishAsync(...) volání
viewer.ExportToCloud(cloudConfig)PublishAsync(...) s konfigurací poskytovatele
UseDoconutCloud(new CloudOptions { Location = … })UseDoconutCloud<THandler>(options => …, pathPrefix)
DocOptions.IsWebfarm / WebfarmPathStále přítomno, napsáno IsWebFarm / WebFarmPath — není potřeba na cestě publikování
Doconut.Configs.CloudDoconut.Clouds

Kontrolní seznam

  1. Vytvořte FileShareConfig v jednom pomocníku, zaregistrujte jej jednou a použijte ho z obou polovin.
  2. Nasmerujte RootPath na sdílení, které již používáte.
  3. Publikujte pomocí PublishAsync(...); odstraňte všechny volání ExportToPng / ExportToCloud.
  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 dejte čtecí straně nenulový ReadReadyPollMs.
  6. Nahraďte kontrolu na relaci podepsanými přístupovými tikety — jeden klíčový kruh Data Protection na každém uzlu, UseDoconutDistributedDocumentSecurity() na čtecí větvi, tiket 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á?