Distribuerade utrullningar

Servera ett dokument från flera noder

När flera noder serverar samma dokument är noden som renderar ett dokument inte nödvändigtvis den nod som svarar på webbläsarens sidförfrågningar. Denna version delar upp den uppgiften i två tydliga halvor — en write side som publicerar ett dokuments artefakter till delat lagringsutrymme, och en read side som serverar dem från vilken nod som helst.

Om din applikation för närvarande anropar UseDoconutWebFarm(...), är den här sidan din ersättning. Varken UseDoconutWebFarm eller WebFarmOptions finns i denna version.

Din topologi förändras inte. Peka den delade roten på samma UNC‑sökväg som du använder idag så fortsätter varje nod att fungera som den gör nu. Det som förändras är att publicering är en operation du anropar, istället för en bieffekt av rendering.

Vad ersatte web-farm-mellanprogramvaran

Tidigare gjorde ett mellanprogram allt: det serverade förrenderade bilder från en delad mapp och polled medan en annan nod fortfarande skrev dem. Väntan var en blind budget — "blockera i upp till tre minuter i hopp om att sidan visas".

Nu är samma uppgift två anrop som du kan se och resonera om:

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

Den delade konfigurationen som båda halvorna behöver

Publiceraren skriver med en FileShareConfig och läshanteraren serverar med en. Om RootPath eller UsePerTokenSubfolders skiljer sig åt, svarar den andra noden med 404. Bygg konfigurationen på exakt ett ställe och registrera den en gång, så att båda halvorna läser samma objekt:

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

Skicka asyncPublish: true när du aktiverar bakgrundspublicering.

FileShareConfig finns i Doconut.Clouds, tillsammans med AzureConfig, AmazonConfig, GoogleCloudConfig, DropBoxConfig, RedisConfig, CDNConfig och FTPConfig. I det tidigare biblioteket var dessa i Doconut.Configs.Cloud; klassnamnen ändrades inte.

EgenskapSyfte
LocationCloudLocation.FileShare för en UNC/lokal delning
RootPathDen delade mappen som varje nod kan nå
UsePerTokenSubfoldersBehåll varje dokuments artefakter i sin egen {token}-mapp (standard true)
ReadReadyPollMsHur länge lässidan väntar på en sida som en bakgrundspublicering fortfarande skriver; 0 (standard) kontrollerar en gång. Det har ingen effekt på dokument som publiceras synkront

Skrivrdel — publicera dokumentet

Injicera DistributedDocumentPublisher och publicera istället för att öppna en lokal session. Ett anrop renderar och skriver hela artefaktuppsättningen — sidor, dokumentinformation, sökindex och metadata — och återvänder när det är klart:

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 bär Token, ArtifactPath, TotalPages och Format. Tokenet går till webbläsaren exakt som ett normalt visartoken gör. I en farm returnerar slutpunkten också en signerad åtkomstbiljett — se Säkerhet över noder.

Detta enda anrop ersätter det tidigare paret — att öppna dokumentet i en lokal session och sedan dumpa bilder till delningen med ExportToPng(sharedPath). ExportToPng och ExportToCloud har ingen motsvarighet här.

Läs‑sidan — servera från delningen

Montera FileShare‑hanteraren på samma gren som klienten redan anropar, bakom biljettkontrollen:

csharp
var app = builder.Build();

app.UseDoconutResources();
app.MapWhen(
    ctx => ctx.Request.Path.Value?.EndsWith("DocImage.axd", StringComparison.OrdinalIgnoreCase) == true,
    branch =>
    {
        branch.UseDoconutDistributedDocumentSecurity();   // signerade biljetter — se nedan
        branch.UseDoconutCloud<FileShareCloudHandler>(options =>
        {
            options.Location          = CloudLocation.FileShare;
            options.CloudUploadConfig = app.Services.GetRequiredService<FileShareConfig>();
        }, "/");
    });

UseDoconutCloud är generisk i den här releasen: leverantören är typargumentet snarare än ett Location‑värde som växlas på inne i middleware. Handlers heter <Provider>CloudHandler — FileShareCloudHandler, AzureCloudHandler, AmazonS3CloudHandler, GoogleCloudHandler, DropBoxCloudHandler, RedisCloudHandler, FTPCloudHandler och CDNCloudHandler. Med sökvägsprefixet "/" svarar hanteraren på varje begäran som når dess gren.

CDN‑hanteraren är read-only — den serverar det som redan finns på CDN:n; den laddar inte upp.

Valfritt: publicera i bakgrunden

Som standard renderar PublishAsync hela dokumentet innan det returnerar. För att returnera så snart token har skapats och låta en hostad worker rendera in i samma mapp, registrera den frivilliga kön och bygg den delade konfigurationen med asyncPublish: true:

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

Utan denna registrering registreras inget och publicering förblir synkron, exakt som tidigare.

Anropa sedan EnqueueAsync istället för PublishAsync. (DistributedDocumentPublishOptions.Async är bara en flagga som din egen kod kan läsa för att välja mellan de två vägarna; publiceraren ignorerar den.) Kün är begränsad: när den är mättad kastar EnqueueAsync DistributedPublishQueueFullException. Svara med en 503 och ett Retry-After‑huvud så att klienterna backar istället för att fastna:

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

Sidor som ännu inte skrivits: HTTP 202

Med bakgrundspublicering kan en sidbegäran komma innan workern har skrivit den sidan. Läs‑sidan väntar upp till ReadReadyPollMs och svarar sedan med HTTP 202 Accepted istället för att blockera begäran.

FirstPagePriority = true förkortar väntan för den första vyn: sida 1 skrivs först in i dokumentets mapp, så dokumentet öppnas medan senare sidor fortfarande renderas. Det gäller endast bakgrundspublicering i per‑token‑mappar (UsePerTokenSubfolders = true); den synkrona PublishAsync ignorerar det, eftersom dess anropar väntar på hela dokumentet ändå.

Det flyttar väntan till klienten, där den är begränsad och synlig. Aktivera återförsök på widgeten:

javascript
const objViewer = $('#div_ctlDoc').docViewer({
    BasePath:   '/',
    ResPath:    'doconut-res/images',
    retryOn409: true      // omförsök 202 (och legacy 409) readiness-svar
});

En klient som inte återförsöker visar trasiga rutor för sidor som fortfarande renderas. Återförsöksbudgeten och dess standardvärden (retryInitialDelayMs, retryBackoffFactor, retryMaxDelayMs, retryMaxAttempts, retryMaxTotalMs) är dokumenterade i ViewerConfig.

Detta par — bakgrundspublicering med FirstPagePriority, plus lässidans poll — är det som ersätter de tidigare inställningarna PageWaitTimeSeconds och StartWaitFromPage. Ingen av dem finns längre.

Säkerhet över noder

Sessionsbundna token antar att den serverande noden såg öppningsbegäran. I en farm gjorde den det inte, så per-sessionkontrollen skulle avvisa legitima begäranden; en farm sätter därför UnsafeMode = true.

UnsafeMode = true är inte säkerhetsmodellen — det är borttagandet av en som inte längre gäller. Ersätt den med signerade åtkomstbiljetter, som varje nod kan verifiera oberoende. Fyra delar fungerar tillsammans.

1. Registrera biljett‑säkerhet på varje nod. Biljetter skyddas med ASP.NET Core Data Protection, så varje nod måste använda samma nyckelring och applikationsnamn; en nod med olika nycklar kan inte läsa en biljett som en annan nod utfärdat.

csharp
using Microsoft.AspNetCore.DataProtection;

builder.Services.AddDataProtection()
    .PersistKeysToFileSystem(new DirectoryInfo(@"\\fileserver\doconut-keys"))   // delad av varje nod
    .SetApplicationName("doconut-farm");

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

2. Kontrollera biljetter på lässidan. UseDoconutDistributedDocumentSecurity() placeras på läsgrenen före UseDoconutCloud, som i exemplet för lässidan.

3. Utfärda en biljett när dokumentet öppnas. Biljetten namnger token, webbläsaren (genom en cookie som lässidan jämför), och den inloggade användaren, om någon:

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

    // Bind ticket till den här webbläsaren via den cookie som lässidan kontrollerar.
    var cookieName = security.Value.BrowserCookieName;   // "doconut-client" som standard
    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. Skicka båda till widgeten. Visaren skickar biljetten som access med varje begäran:

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

Läsidan avvisar en begäran vars biljett saknas, är ogiltig, utfärdad för en annan token, har gått ut, är bunden till en annan webbläsarcookie, eller utfärdad till en annan inloggad användare. Den svarar med 403 — med felbilden UnauthorizedMessage för sid- och miniatyrförfrågningar, som vanlig text annars. Testa med en riktig webbläsare eller en klient som behåller cookies.

Ta aldrig med UnsafeMode = true tillbaka till en en‑nod‑distribution, och behandla det aldrig som en genväg för en misslyckad sessionskontroll på en nod — där är den korrekta lösningen AddSession() / UseSession(). Se Sessioner & Säkerhet.

Stänga ett publicerat dokument

CloseDocument(token) på den injicerade Viewer avyttrar en lokal session. För att ta bort ett dokuments publicerade artefakter från delningen, exponerar publiceraren:

text
bool CloseDistributedDocument(FileShareConfig fileShareConfig, string token)

Skicka samma FileShareConfig som dokumentet publicerades med.

Mappning inställning för inställning

FöregåendeNu
UseDoconutWebFarm(new WebFarmOptions { … })PublishAsync(...) på skrivsidan plus UseDoconutCloud<FileShareCloudHandler>(...) på lässidan
WebFarmOptions.PathFileShareConfig.RootPath
PageWaitTimeSeconds / StartWaitFromPageBakgrundspublicering med DistributedDocumentPublishOptions.FirstPagePriority, plus FileShareConfig.ReadReadyPollMs
viewer.OpenDocument(...) sedan viewer.ExportToPng(share)ett PublishAsync(...) anrop
viewer.ExportToCloud(cloudConfig)PublishAsync(...) med leverantörens konfiguration
UseDoconutCloud(new CloudOptions { Location = … })UseDoconutCloud<THandler>(options => …, pathPrefix)
DocOptions.IsWebfarm / WebfarmPathFortfarande närvarande, stavat IsWebFarm / WebFarmPath — inte behövs på publiceringsvägen
Doconut.Configs.CloudDoconut.Clouds

Checklista

  1. Bygg FileShareConfig i en hjälpfunktion, registrera den en gång och använd den från båda halvorna.
  2. Peka RootPath på den delning du redan använder.
  3. Publicera med PublishAsync(...); ta bort alla ExportToPng / ExportToCloud anrop.
  4. Servera med UseDoconutCloud<FileShareCloudHandler>(...) på den gren som klienten anropar.
  5. Vid bakgrundspublicering, slå på FirstPagePriority och retryOn409 tillsammans, och ge lässidan ett icke‑noll ReadReadyPollMs.
  6. Ersätt per‑session‑kontrollen med signerade åtkomstbiljetter — ett Data Protection‑nyckelring på varje nod, UseDoconutDistributedDocumentSecurity() på läsgrenen, en biljett från den öppna slutpunkten — och skicka inte med UnsafeMode = true ensam.
  7. Verifiera genom att öppna ett dokument på en nod och begära en sen sida från en annan.

Var den här sidan hjälpsam?