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 stránky v prohlížeči. Doconut rozděluje tuto úlohu na dvě explicitní poloviny — zápisová část, která publikuje artefakty dokumentu do sdíleného úložiště, a čtecí část, která je obsluhuje z libovolného uzlu.
Jeden uzel nepotřebuje nic z toho: běžná cesta OpenDocumentAsync udržuje 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ž mohou požadavky na stránku 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 potřebují obě poloviny
Publikátor zapisuje pomocí FileShareConfig a čtecí obsluha 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 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í část čeká na stránku, kterou publikování na pozadí stále zapisuje; 0 (výchozí) kontroluje jednou. Nemá žádný vliv na dokumenty publikované synchronně |
Zápisová část — 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, 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ý ticket — viz Zabezpečení napříč uzly.
Čtecí strana — obsluhovat ze sdíleného úložiště
Namontujte handler FileShare na větev, kterou klient volá — /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 typový argument. 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ý dorazí k jeho větvi.
CDN handler je pouze pro čtení — poskytuje to, co je již na CDN; nenahrává.
Volitelné: publikovat na pozadí
Ve výchozím nastavení PublishAsync vykreslí celý dokument před tím, než se vrátí. Pro okamžité vrácení po vytvoření tokenu a umožnění hostovanému workeru renderovat do stejné složky, zaregistrujte volitelnou frontu 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.
Poté 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 zaplněná, EnqueueAsync vyhodí DistributedPublishQueueFullException. Odpovězte na to pomocí 503 a hlavičky Retry-After, aby klienti odložili požadavky 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 dorazit dříve, než worker stránku zapíše. Čtecí strana čeká až 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 se dokument otevře, zatímco pozdější stránky se stále renderují. Platí pouze pro publikování na pozadí do složek podle 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: 'doconut',
ResPath: 'doconut-res/images',
retryOn409: true // opakování 202 (a starší 409) odpovědi připravenosti
});Klient, který neopakovaně požaduje, zobrazuje poškozené dlaždice pro stránky, které se ještě 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 oprávněné požadavky; farmu proto nastavuje UnsafeMode = true.
UnsafeMode = true není bezpečnostní model — je to odstranění modelu, který již neplatí.
Nahraďte jej podepsanými přístupovými lístky, které může každý uzel ověřit nezávisle. Č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ý okruh 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, jako v ukázce čtecí strany.
3. Vydávejte lístek při otevření dokumentu.
Lístek uvádí 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 přes 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 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 svázán s jiným cookie prohlížeče nebo byl vydán jinému přihlášenému uživateli. Odpoví kódem 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á cookies.
Nikdy nepřenášejte UnsafeMode = true zpět do nasazení s jedním uzlem a nikdy jej nepovažujte za 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 ukončuje lokální relaci. Pro odstranění publikovaných artefaktů dokumentu ze sdíleného úložiště publisher poskytuje:
bool CloseDistributedDocument(FileShareConfig fileShareConfig, string token)Předávejte stejný FileShareConfig, se kterým byl dokument publikován.
Kontrolní seznam
- Vytvořte
FileShareConfigv jednom pomocníku, 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
FirstPagePriorityaretryOn409současně a dejte čtecí straně nenulovéReadReadyPollMs. - Nahraďte kontrolu na úrovni relace podepsanými přístupovými lístky — jedním klíčovým prstencem Data Protection na každém uzlu,
UseDoconutDistributedDocumentSecurity()na čtecí větvi, lístkem 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á?