Distribuované nasazení
Obsluhujte jeden dokument z několika uzlů
Když několik uzlů obsluhuje stejné dokumenty, uzel, který vykresluje dokument, není nutně uzel, který odpovídá na požadavky prohlížeče na stránku. Toto vydání rozděluje tuto úlohu na dvě explicitní poloviny — zapisovací část, která publikuje artefakty dokumentu do sdíleného úložiště, a čtecí část, která je obsluhuje z libovolného uzlu.
Pokud vaše aplikace v současnosti volá UseDoconutWebFarm(...), tato stránka je jeho náhradou. Ani UseDoconutWebFarm, ani WebFarmOptions v tomto vydání neexistují.
Vaše topologie se nemění. Nastavte sdílený kořen na stejnou UNC cestu, kterou používáte dnes, a každý uzel bude nadále fungovat tak, jak funguje nyní. Co se mění, je to, že publikování je operace, kterou voláte, místo vedlejšího efektu vykreslování.
Co nahradilo middleware web-farm
Dříve jedno middleware dělalo vše: obsluhovalo předrenderované obrázky ze sdílené složky a pollovalo, zatímco jiný uzel je ještě zapisoval. Čekání bylo slepý rozpočet — „blokovat až tři minuty v naději, že se stránka objeví“.
Nyní je stejná úloha dvěma voláními, která můžete vidět a rozumně pochopit:
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 oba díly potřebují
Publikátor zapisuje pomocí FileShareConfig a čtecí handler obsluhuje 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 oba díly č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ředávejte 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. V předchozí knihovně byly tyto v Doconut.Configs.Cloud; názvy tříd se nezměnily.
| 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í část čeká na stránku, kterou pozadí stále zapisuje; 0 (výchozí) kontroluje jednou. Nemá žádný vliv na dokumenty publikované synchronně |
Zapisovací část — publikovat dokument
Injektujte DistributedDocumentPublisher a publikujte místo otevírání lokální relace. Jedno volání vykreslí a zapíše kompletní sadu artefaktů — stránky, informace o dokumentu, vyhledávací index a metadata — a vrátí se, až 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ý tiket — viz Zabezpečení napříč uzly.
Toto jediné volání nahrazuje předchozí dvojici — otevření dokumentu do lokální relace a následné uložení obrázků na sdílení pomocí ExportToPng(sharedPath). ExportToPng a ExportToCloud zde nemají ekvivalent.
Čtecí strana — obsluhovat ze sdílení
Namontujte obslužný program FileShare na stejnou větev, kterou klient již volá, za kontrolou lístku:
var app = builder.Build();
app.UseDoconutResources();
app.MapWhen(
ctx => ctx.Request.Path.Value?.EndsWith("DocImage.axd", StringComparison.OrdinalIgnoreCase) == true,
branch =>
{
branch.UseDoconutDistributedDocumentSecurity(); // podepsané tikety — viz níže
branch.UseDoconutCloud<FileShareCloudHandler>(options =>
{
options.Location = CloudLocation.FileShare;
options.CloudUploadConfig = app.Services.GetRequiredService<FileShareConfig>();
}, "/");
});UseDoconutCloud je v tomto vydání generický: poskytovatel je typový argument místo hodnoty Location, která se přepíná uvnitř middleware. Obslužné programy jsou pojmenovány <Provider>CloudHandler — FileShareCloudHandler, AzureCloudHandler, AmazonS3CloudHandler, GoogleCloudHandler, DropBoxCloudHandler, RedisCloudHandler, FTPCloudHandler a CDNCloudHandler. S předponou cesty "/" obslužný program odpovídá na každý požadavek, který dorazí do jeho větve.
Obslužný program CDN je pouze pro čtení — poskytuje to, co je již na CDN; nenahrává.
Volitelné: publikovat na pozadí
Ve výchozím nastavení PublishAsync vykresluje celý dokument před tím, než se vrátí. Pro okamžité vrácení, jakmile je token vytvořen, a nechat hostovaného pracovníka vykreslovat do stejné složky, zaregistrujte frontu s opt‑in a sestavte sdílenou konfiguraci pomocí asyncPublish: true:
builder.Services.AddDoconut(options => { /* … */ });
builder.Services.AddDoconutDistributedAsyncPublish();Bez této registrace není nic registrováno a publikování zůstává synchronní, přesně jako dříve.
Poté zavolejte EnqueueAsync místo PublishAsync. (DistributedDocumentPublishOptions.Async je jen 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 zaplněná, EnqueueAsync vyhodí DistributedPublishQueueFullException. Odpovězte na to pomocí 503 a hlavičky Retry-After, aby klienti odradili místo zablokování:
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ž pracovník stránku zapíše. Čtecí strana čeká až do ReadReadyPollMs a poté odpoví 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 dokument se otevře, zatímco pozdější stránky se stále vykreslují. Platí pouze 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é. Povolit opakování na widgetu:
const objViewer = $('#div_ctlDoc').docViewer({
BasePath: '/',
ResPath: 'doconut-res/images',
retryOn409: true // opakování 202 (a starší 409) odpovědi připravenosti
});Klient, který neopakování provádí, zobrazuje poškozené dlaždice pro stránky, které se stále vykreslují. Rozpočet pro opakování a jeho výchozí hodnoty (retryInitialDelayMs, retryBackoffFactor, retryMaxDelayMs, retryMaxAttempts, retryMaxTotalMs) jsou zdokumentovány v ViewerConfig.
Tento pár — publikování na pozadí s FirstPagePriority, plus čtecí poll — nahrazuje předchozí nastavení PageWaitTimeSeconds a StartWaitFromPage. Žádné z nich již neexistuje.
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; farmu proto nastavuje UnsafeMode = true.
UnsafeMode = true není bezpečnostní model — jde o odstranění modelu, který již neplatí.
Nahraďte jej podepsanými přístupovými lístky, které může každý uzel ověřit samostatně. Čtyři součásti spolupracují.
1. Zaregistrujte zabezpečení lístků 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ěřte lístky na čtecí straně.
UseDoconutDistributedDocumentSecurity() se umisťuje na čtecí větev před UseDoconutCloud, jak je uvedeno v ukázka čtecí strany.
3. Vydávejte lístek při otevření dokumentu.
Lístek uvádí token, prohlížeč (prostřednictvím souboru cookie, který č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);
// Svázat ticket s tímto prohlížečem prostřednictvím cookie, kterou kontroluje čtecí část
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 widgetu.
Prohlížeč posílá lístek jako access u každého požadavku:
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 jiný soubor 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ánku a miniaturu, jinak jako prostý text. Otestujte pomocí skutečného prohlížeče nebo klienta, který uchovává soubory cookie.
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 vloženém Viewer ruší lokální relaci. Pro odebrání publikovaných artefaktů dokumentu ze sdíleného úložiště poskytovatel zveřejňuje:
bool CloseDistributedDocument(FileShareConfig fileShareConfig, string token)Předávejte stejný FileShareConfig, se kterým byl dokument publikován.
Mapování nastavení po nastavení
| Předchozí | Nyní |
|---|---|
UseDoconutWebFarm(new WebFarmOptions { … }) | PublishAsync(...) na zápisové straně plus UseDoconutCloud<FileShareCloudHandler>(...) na čtecí straně |
WebFarmOptions.Path | FileShareConfig.RootPath |
PageWaitTimeSeconds / StartWaitFromPage | Publikování na pozadí s DistributedDocumentPublishOptions.FirstPagePriority, a FileShareConfig.ReadReadyPollMs |
viewer.OpenDocument(...) then viewer.ExportToPng(share) | jeden PublishAsync(...) volání |
viewer.ExportToCloud(cloudConfig) | PublishAsync(...) s konfigurací poskytovatele |
UseDoconutCloud(new CloudOptions { Location = … }) | UseDoconutCloud<THandler>(options => …, pathPrefix) |
DocOptions.IsWebfarm / WebfarmPath | Stále přítomno, napsáno IsWebFarm / WebFarmPath — není potřeba na cestě publikování |
Doconut.Configs.Cloud | Doconut.Clouds |
Kontrolní seznam
- Vytvořte
FileShareConfigv jednom pomocníku, zaregistrujte jej jednou a použijte ho z obou polovin. - Nasmerujte
RootPathna sdílení, které již používáte. - Publikujte pomocí
PublishAsync(...); odstraňte všechny voláníExportToPng/ExportToCloud. - Obsluhujte pomocí
UseDoconutCloud<FileShareCloudHandler>(...)na větvi, kterou klient volá. - Při publikování na pozadí zapněte
FirstPagePriorityaretryOn409společně a dejte čtecí straně nenulovýReadReadyPollMs. - Nahraďte kontrolu na relaci podepsanými přístupovými tikety — jeden klíčový kruh Data Protection na každém uzlu,
UseDoconutDistributedDocumentSecurity()na čtecí větvi, tiket 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.
Byla tato stránka užitečná?