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. Doconut delar upp den uppgiften i två tydliga halvor — en skrivsida som publicerar ett dokuments artefakter till delad lagring, och en lässida som serverar dem från vilken nod som helst.

En enskild nod behöver inte någon av detta: den normala OpenDocumentAsync‑vägen behåller dokumentet i den nodens minne och binder det till webbläsarsessionen (se Sessioner & Säkerhet). Använd den här sidan när sidförfrågningar kan hamna på en nod som aldrig har sett öppningen.

Hur de två halvorna passar ihop

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 mellan dem, 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.

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

Skrivsida — 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 viewer‑token gör. I en farm returnerar endpointen också en signerad åtkomstbiljett — se Säkerhet över noder.

Läs‑sidan — servera från delningen

Montera FileShare‑hanteraren på den gren som klienten anropar — /doconut, matchande BasePath: 'doconut' — bakom biljettkontrollen:

csharp
var app = builder.Build();

app.UseDoconutResources();
app.Map("/doconut", branch =>
{
    branch.UseDoconutDistributedDocumentSecurity();   // Signerade biljetter — se nedan
    branch.UseDoconutCloud<FileShareCloudHandler>(options =>
    {
        options.Location          = CloudLocation.FileShare;
        options.CloudUploadConfig = app.Services.GetRequiredService<FileShareConfig>();
    }, "/");
});

UseDoconutCloud tar leverantören som sitt typargument. Hanterare 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 skrivskyddad — 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 returneras. För att returnera så snart token har skapats och låta en hostad worker rendera i samma mapp, registrera den valfria kön och bygg den delade konfigurationen med asyncPublish: true:

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

Utan denna registrering blir inget registrerat 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 tillbaka 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

Vid 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:   'doconut',
    ResPath:    'doconut-res/images',
    retryOn409: true      // återförsök 202 (och legacy 409) beredskaps-svar
});

En klient som inte försöker igen 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.

Säkerhet över noder

Sessionsbundna token antar att den serverande noden såg öppningsbegäran. I en farm gör den det inte, så per-session‑kontrollen 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 arbetar 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 läs‑sidexemplet.

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 ticketen 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ässidan avvisar en begäran vars biljett saknas, är ogiltig, utfärdad för ett annat token, har gått ut, är bunden till en annan webbläsarcookie, eller utfärdad till en annan inloggad användare. Den svarar 403 — med UnauthorizedMessage felbild 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 avslutar 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.

Checklist

  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å en mapp som varje nod kan nå.
  3. Publicera med PublishAsync(...), eller EnqueueAsync(...) med bakgrundspublicering.
  4. Servera med UseDoconutCloud<FileShareCloudHandler>(...) på den gren som klienten anropar.
  5. Vid bakgrundspublicering, slå på FirstPagePriority och retryOn409 samtidigt, och ge lässidan ett icke‑noll ReadReadyPollMs.
  6. Ersätt per‑sessionskontrollen med signerade åtkomstbiljetter — en Data Protection-nyckelring på varje nod, UseDoconutDistributedDocumentSecurity() på läsgrenen, en biljett från den öppna slutpunkten — och skicka inte 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?