Distribuerade distributioner
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 skrivdel som publicerar ett dokuments artefakter till delat lagringsutrymme, och en lässida som serverar dem från vilken nod som helst.
En enskild nod behöver inte någon av detta: den vanliga OpenDocumentAsync-vägen håller dokumentet i 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/local share |
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 (standardvärdet) kontrollerar en gång. Det har ingen effekt på dokument som publiceras synkront |
Skrivdel — 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 visartoken gör. I en farm returnerar slutpunkten 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 typargument. Handlarna 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; 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 i samma mapp, registrera den frivilliga kön och bygg den delade konfigurationen med asyncPublish: true:
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 drar sig 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
Med bakgrundspublicering kan en sidbegäran anländer 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 // omförsök 202 (och äldre 409) beredskapsrespons
});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 Visningskonfiguration.
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.
Byt ut den mot 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.
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; // standardvärdet
});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:
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);
// Koppla ticketen till den här webbläsaren via kakan 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 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 403 — med UnauthorizedMessage felbild för sid- och miniatyrförfrågningar, som ren 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.
Checklista
- 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. - Med bakgrundspublicering, slå på
FirstPagePriorityochretryOn409samtidigt, och ge lässidan ett icke‑nollReadReadyPollMs. - 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 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?