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
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 pageDen 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:
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.
| Egenskap | Syfte |
|---|---|
Location | CloudLocation.FileShare för en UNC/lokal delning |
RootPath | Den delade mappen som varje nod kan nå |
UsePerTokenSubfolders | Behåll varje dokuments artefakter i sin egen {token}-mapp (standard true) |
ReadReadyPollMs | Hur 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:
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:
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:
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:
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:
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.
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:
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:
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:
bool CloseDistributedDocument(FileShareConfig fileShareConfig, string token)Skicka samma FileShareConfig som dokumentet publicerades med.
Checklist
- Bygg
FileShareConfigi en hjälpfunktion, registrera den en gång och använd den från båda halvorna. - Peka
RootPathpå en mapp som varje nod kan nå. - Publicera med
PublishAsync(...), ellerEnqueueAsync(...)med bakgrundspublicering. - Servera med
UseDoconutCloud<FileShareCloudHandler>(...)på den gren som klienten anropar. - Vid bakgrundspublicering, slå på
FirstPagePriorityochretryOn409samtidigt, och ge lässidan ett icke‑nollReadReadyPollMs. - 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 inteUnsafeMode = trueensam. - 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?