Distribuované nasazení
Poskytněte jeden dokument z několika uzlů
Když několik uzlů poskytuje stejné dokumenty, uzel, který vykresluje dokument, není nutně uzel, který odpovídá na požadavky prohlížeče na stránku. Doconut rozděluje tuto úlohu na dvě explicitní poloviny — write side, která publikuje artefakty dokumentu do sdíleného úložiště, a read side, která je poskytuje z libovolného uzlu.
Jeden uzel to nepotřebuje: běžná cesta OpenDocumentAsync uchovává dokument v paměti toho uzlu a váže jej k relaci prohlížeče (viz Relace a zabezpečení). Použijte tuto stránku, když požadavky na stránku mohou dopadnout na uzel, který otevření nikdy neviděl.
Jak se dvě poloviny doplňují
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 pageSdílená konfigurace, kterou obě poloviny potřebují
Publikátor zapisuje pomocí FileShareConfig a čtecí obsluha poskytuje 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 obě poloviny četly stejný objekt:
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ředejte 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.
| Vlastnost | Účel |
|---|---|
Location | CloudLocation.FileShare pro UNC/místní sdílení |
RootPath | Sdílená složka, ke které má přístup každý uzel |
UsePerTokenSubfolders | Uchovávejte artefakty každého dokumentu ve své vlastní složce {token} (výchozí true) |
ReadReadyPollMs | Jak dlouho čtecí strana čeká na stránku, kterou pozadí stále zapisuje; 0 (výchozí) kontroluje jednou. Nemá žádný vliv na dokumenty publikované synchronně |
Write side — publikovat dokument
Vložte DistributedDocumentPublisher a publikujte místo otevření lokální relace. Jeden volání vykreslí a zapíše kompletní sadu artefaktů — stránky, informace o dokumentu, index vyhledávání a metadata — a vrátí se, když je hotovo:
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ý lístek — viz Zabezpečení napříč uzly.
Čtecí strana — poskytovat ze sdíleného
Namontujte handler FileShare na větev, kterou volá klient — /doconut, odpovídající BasePath: 'doconut' — za kontrolou ticketu:
var app = builder.Build();
app.UseDoconutResources();
app.Map("/doconut", branch =>
{
branch.UseDoconutDistributedDocumentSecurity(); // podepsané tikety — viz níže
branch.UseDoconutCloud<FileShareCloudHandler>(options =>
{
options.Location = CloudLocation.FileShare;
options.CloudUploadConfig = app.Services.GetRequiredService<FileShareConfig>();
}, "/");
});UseDoconutCloud přijímá poskytovatele jako argument typu. Handlery jsou pojmenovány <Provider>CloudHandler — FileShareCloudHandler, AzureCloudHandler, AmazonS3CloudHandler, GoogleCloudHandler, DropBoxCloudHandler, RedisCloudHandler, FTPCloudHandler a CDNCloudHandler. S předponou cesty "/" handler odpovídá na každý požadavek, který dosáhne jeho větve.
CDN handler je pouze pro čtení — poskytuje to, co je již na CDN; neprovádí nahrávání.
Volitelné: publikovat na pozadí
Ve výchozím nastavení PublishAsync vykresluje celý dokument před tím, než se vrátí. Aby se vrátil okamžitě po vytvoření tokenu a umožnil hostovanému workeru renderovat do stejné složky, zaregistrujte frontu s opt‑in a vytvořte sdílenou konfiguraci pomocí asyncPublish: true:
builder.Services.AddDoconut(options => { /* … */ });
builder.Services.AddDoconutDistributedAsyncPublish();Bez této registrace se nic nezaregistruje a publikování zůstává synchronní, přesně jako dříve.
Pak zavolejte EnqueueAsync místo PublishAsync. (DistributedDocumentPublishOptions.Async je pouze 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 nasycena, EnqueueAsync vyhodí DistributedPublishQueueFullException. Odpovězte na to pomocí 503 a hlavičky Retry-After, aby klienti spíše ustoupili než se zasekli:
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ž worker tuto stránku zapíše. Čtecí strana čeká až do ReadReadyPollMs a poté odpovídá 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 se dokument otevře, zatímco pozdější stránky se stále renderují. Platí to jen 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é. Povolte opakování na widgetu:
const objViewer = $('#div_ctlDoc').docViewer({
BasePath: 'doconut',
ResPath: 'doconut-res/images',
retryOn409: true // opakování 202 (a legacy 409) odpovědi připravenosti
});Klient, který neopakování neprovádí, zobrazuje poškozené dlaždice pro stránky, které se stále renderují. Rozpočet pro opakování a jeho výchozí hodnoty (retryInitialDelayMs, retryBackoffFactor, retryMaxDelayMs, retryMaxAttempts, retryMaxTotalMs) jsou zdokumentovány v ViewerConfig.
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; farma proto nastaví UnsafeMode = true.
UnsafeMode = true není bezpečnostní model — je to odstranění modelu, který již neplatí.
1. Zaregistrujte zabezpečení lístku 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.
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ěřujte lístky na čtecí straně. UseDoconutDistributedDocumentSecurity() se umisťuje na čtecí větev před UseDoconutCloud, jako v ukázce čtení.
3. Vydávejte lístek při otevření dokumentu. Lístek pojmenovává token, prohlížeč (prostřednictvím cookie, kterou čtecí strana porovnává) a přihlášeného uživatele, pokud existuje:
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);
// Propojte tiket s tímto prohlížečem prostřednictvím cookie, kterou kontroluje čtecí strana.
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 do widgetu. Prohlížeč posílá lístek jako access s každým požadavkem:
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 jinou 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ánky a miniatury, jinak jako prostý text. Otestujte pomocí skutečného prohlížeče nebo klienta, který uchovává cookies.
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 injektovaném Viewer uvolňuje lokální relaci. Pro odstranění publikovaných artefaktů dokumentu ze sdíleného úložiště, vydavatel poskytuje:
bool CloseDistributedDocument(FileShareConfig fileShareConfig, string token)Předávejte stejný FileShareConfig, se kterým byl dokument publikován.
Checklist
- Vytvořte
FileShareConfigv jednom pomocném modulu, zaregistrujte jej jednou a použijte jej z obou částí. - Nasmerujte
RootPathna složku, ke které má přístup každý uzel. - Publikujte pomocí
PublishAsync(...), neboEnqueueAsync(...)s publikováním na pozadí. - Obsluhujte pomocí
UseDoconutCloud<FileShareCloudHandler>(...)na větvi, kterou klient volá. - Při publikování na pozadí zapněte
FirstPagePriorityaretryOn409společně a nastavte pro čtecí stranu nenulovou hodnotuReadReadyPollMs. - Nahraďte kontrolu na úrovni relace podepsanými přístupovými tokeny — jedním klíčovým prstencem Data Protection na každém uzlu,
UseDoconutDistributedDocumentSecurity()na čtecí větvi, tokenem z otevřeného koncového bodu — a nezasílejteUnsafeMode = truesamostatně. - Ověřte otevřením dokumentu na jednom uzlu a požádáním o pozdější stránku z jiného uzlu.
Byla tato stránka užitečná?