Distribuzioni distribuite
Servi un documento da più nodi
Quando più nodi servono gli stessi documenti, il nodo che rende un documento non è necessariamente il nodo che risponde alle richieste di pagina del browser. Questa release divide quel compito in due metà esplicite — un lato di scrittura che pubblica gli artefatti di un documento nello storage condiviso, e un lato di lettura che li serve da qualsiasi nodo.
Se la tua applicazione chiama attualmente UseDoconutWebFarm(...), questa pagina è la tua sostituzione. Né UseDoconutWebFarm né WebFarmOptions esistono in questa release.
La tua topologia non cambia. Punta la radice condivisa allo stesso percorso UNC che usi oggi e ogni nodo continuerà a funzionare come fa ora. Ciò che cambia è che la pubblicazione è un'operazione che chiami, invece di un effetto collaterale del rendering.
Cosa ha sostituito il middleware web-farm
In precedenza un unico middleware faceva tutto: serviva immagini pre‑renderizzate da una cartella condivisa e interrogava mentre un altro nodo le stava ancora scrivendo. L'attesa era un budget cieco — "blocca fino a tre minuti sperando che la pagina appaia".
Ora lo stesso compito è costituito da due chiamate che puoi vedere e analizzare:
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 pageLa configurazione condivisa di cui entrambe le metà hanno bisogno
Il publisher scrive con un FileShareConfig e il gestore di lettura serve con uno. Se RootPath o UsePerTokenSubfolders differiscono tra loro, l'altro nodo risponde 404. Costruisci la configurazione in un unico posto e registrala una sola volta, così entrambe le metà leggono lo stesso oggetto:
var rootPath = builder.Configuration["Doconut:SharedRoot"]!; // es. \\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,
};
}Passa asyncPublish: true quando attivi la pubblicazione in background.
FileShareConfig vive in Doconut.Clouds, insieme a AzureConfig, AmazonConfig, GoogleCloudConfig, DropBoxConfig, RedisConfig, CDNConfig, e FTPConfig. Nella libreria precedente questi erano in Doconut.Configs.Cloud; i nomi delle classi non sono cambiati.
| Proprietà | Scopo |
|---|---|
Location | CloudLocation.FileShare per una condivisione UNC/local |
RootPath | La cartella condivisa a cui ogni nodo può accedere |
UsePerTokenSubfolders | Mantieni gli artefatti di ogni documento nella propria cartella {token} (predefinita true) |
ReadReadyPollMs | Quanto tempo il lato di lettura attende una pagina che una pubblicazione in background sta ancora scrivendo; 0 (il valore predefinito) controlla una volta. Non ha effetto sui documenti pubblicati in modo sincrono |
Lato di scrittura — pubblica il documento
Inietta DistributedDocumentPublisher e pubblica invece di aprire una sessione locale. Una chiamata rende e scrive l'intero set di artefatti — pagine, informazioni del documento, indice di ricerca e metadati — e ritorna quando ha terminato:
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 trasporta Token, ArtifactPath, TotalPages e Format. Il token va al browser esattamente come fa un normale token di visualizzatore. In un farm, l'endpoint restituisce anche un ticket di accesso firmato — vedi Sicurezza tra nodi.
Questa singola chiamata sostituisce la coppia precedente — aprire il documento in una sessione locale e poi scaricare le immagini sulla condivisione con ExportToPng(sharedPath). ExportToPng e ExportToCloud non hanno un equivalente qui.
Lato di lettura — servire dalla condivisione
Monta il gestore FileShare sullo stesso ramo che il client chiama già, dietro il controllo del ticket:
var app = builder.Build();
app.UseDoconutResources();
app.MapWhen(
ctx => ctx.Request.Path.Value?.EndsWith("DocImage.axd", StringComparison.OrdinalIgnoreCase) == true,
branch =>
{
branch.UseDoconutDistributedDocumentSecurity(); // biglietti firmati — vedi sotto
branch.UseDoconutCloud<FileShareCloudHandler>(options =>
{
options.Location = CloudLocation.FileShare;
options.CloudUploadConfig = app.Services.GetRequiredService<FileShareConfig>();
}, "/");
});UseDoconutCloud è generico in questa versione: il provider è l'argomento di tipo piuttosto che un valore Location selezionato all'interno del middleware. I gestori sono denominati <Provider>CloudHandler — FileShareCloudHandler, AzureCloudHandler, AmazonS3CloudHandler, GoogleCloudHandler, DropBoxCloudHandler, RedisCloudHandler, FTPCloudHandler e CDNCloudHandler. Con il prefisso di percorso "/", il gestore risponde a ogni richiesta che raggiunge il suo ramo.
Il gestore CDN è sola lettura — serve ciò che è già sul CDN; non effettua upload.
Opzionale: pubblicare in background
Per impostazione predefinita PublishAsync rende l'intero documento prima di restituire. Per restituire non appena il token è generato e consentire a un worker ospitato di renderizzare nella stessa cartella, registra la coda di opt-in e costruisci la configurazione condivisa con asyncPublish: true:
builder.Services.AddDoconut(options => { /* … */ });
builder.Services.AddDoconutDistributedAsyncPublish();Senza questa registrazione nulla viene registrato e la pubblicazione rimane sincrona, esattamente come prima.
Quindi chiama EnqueueAsync invece di PublishAsync. (DistributedDocumentPublishOptions.Async è solo un flag che il tuo codice può leggere per scegliere tra i due percorsi; il publisher lo ignora.) La coda è limitata: quando è saturata, EnqueueAsync lancia DistributedPublishQueueFullException. Rispondi con un 503 e un'intestazione Retry-After in modo che i client si ritirino anziché bloccarsi:
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);
}
});Pagine non ancora scritte: HTTP 202
Con la pubblicazione in background, una richiesta di pagina può arrivare prima che il worker abbia scritto quella pagina. Il lato di lettura attende fino a ReadReadyPollMs e poi risponde HTTP 202 Accepted invece di bloccare la richiesta.
FirstPagePriority = true accorcia l'attesa per la prima visualizzazione: la pagina 1 viene scritta nella cartella del documento per prima, così il documento si apre mentre le pagine successive sono ancora in fase di rendering. Si applica solo alla pubblicazione in background nelle cartelle per token (UsePerTokenSubfolders = true); il PublishAsync sincrono lo ignora, perché il suo chiamante attende comunque l'intero documento.
Ciò sposta l'attesa sul client, dove è limitata e visibile. Abilita il retry sul widget:
const objViewer = $('#div_ctlDoc').docViewer({
BasePath: '/',
ResPath: 'doconut-res/images',
retryOn409: true // tentativi 202 (e legacy 409) risposte di prontezza
});Un client che non effettua retry mostra tasselli rotti per le pagine ancora in rendering. Il budget di retry e i suoi valori predefiniti (retryInitialDelayMs, retryBackoffFactor, retryMaxDelayMs, retryMaxAttempts, retryMaxTotalMs) sono documentati in ViewerConfig.
Questa coppia — pubblicazione in background con FirstPagePriority, più il polling lato lettura — è ciò che sostituisce le precedenti impostazioni PageWaitTimeSeconds e StartWaitFromPage. Nessuna delle due esiste più.
Sicurezza tra i nodi
I token legati alla sessione presumono che il nodo di servizio abbia visto la richiesta iniziale. In un farm non lo ha fatto, quindi il controllo per sessione rifiuterebbe richieste legittime; un farm quindi imposta UnsafeMode = true.
UnsafeMode = true non è il modello di sicurezza — è la rimozione di uno che non è più applicabile. Sostituirlo con ticket di accesso firmati, che ogni nodo può verificare in modo indipendente. Quattro componenti lavorano insieme.
1. Registra la sicurezza dei ticket su ogni nodo. I ticket sono protetti con ASP.NET Core Data Protection, quindi ogni nodo deve usare lo stesso anello di chiavi e nome dell'applicazione; un nodo con chiavi diverse non può leggere un ticket emesso da un altro nodo.
using Microsoft.AspNetCore.DataProtection;
builder.Services.AddDataProtection()
.PersistKeysToFileSystem(new DirectoryInfo(@"\\fileserver\doconut-keys")) // condiviso da ogni nodo
.SetApplicationName("doconut-farm");
builder.Services.AddDoconut(options => options.UnsafeMode = true);
builder.Services.AddDoconutDistributedDocumentSecurity(options =>
{
options.TicketLifetimeMinutes = 60; // predefinito
});2. Verifica i ticket sul lato di lettura. UseDoconutDistributedDocumentSecurity() va sul ramo di lettura prima di UseDoconutCloud, come nel campione lato lettura.
3. Emissione di un ticket quando il documento è aperto. Il ticket indica il token, il browser (tramite un cookie che il lato di lettura confronta) e l'utente autenticato, se presente:
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);
// Associa il ticket a questo browser tramite il cookie che il lato di lettura verifica.
var cookieName = security.Value.BrowserCookieName; // "doconut-client" per impostazione predefinita
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. Passa entrambi al widget. Il visualizzatore invia il ticket come access con ogni richiesta:
const resp = await fetch('/api/open?fileName=Sample.pdf', { method: 'POST' });
const { token, access } = await resp.json();
objViewer.View(token, access);Il lato di lettura rifiuta una richiesta il cui ticket è mancante, non valido, emesso per un altro token, scaduto, legato a un altro cookie del browser, o emesso per un altro utente autenticato. Risponde 403 — con l'immagine di errore UnauthorizedMessage per le richieste di pagina e miniatura, altrimenti come testo semplice. Testare con un browser reale o un client che conserva i cookie.
Non riportare mai UnsafeMode = true in un'implementazione a nodo singolo, e non considerarlo mai una scorciatoia per un controllo di sessione fallito su un nodo — lì la correzione corretta è AddSession() / UseSession(). Vedi Sessioni e Sicurezza.
Chiusura di un documento pubblicato
CloseDocument(token) sull'Viewer iniettato elimina una sessione locale. Per rimuovere gli artefatti pubblicati di un documento dalla condivisione, il pubblicatore espone:
bool CloseDistributedDocument(FileShareConfig fileShareConfig, string token)Passa lo stesso FileShareConfig con cui è stato pubblicato il documento.
Mapping impostazione per impostazione
| Precedente | Ora |
|---|---|
UseDoconutWebFarm(new WebFarmOptions { … }) | PublishAsync(...) sul lato di scrittura più UseDoconutCloud<FileShareCloudHandler>(...) sul lato di lettura |
WebFarmOptions.Path | FileShareConfig.RootPath |
PageWaitTimeSeconds / StartWaitFromPage | Pubblicazione in background con DistributedDocumentPublishOptions.FirstPagePriority, più FileShareConfig.ReadReadyPollMs |
viewer.OpenDocument(...) then viewer.ExportToPng(share) | una chiamata PublishAsync(...) |
viewer.ExportToCloud(cloudConfig) | PublishAsync(...) con la configurazione del provider |
UseDoconutCloud(new CloudOptions { Location = … }) | UseDoconutCloud<THandler>(options => …, pathPrefix) |
DocOptions.IsWebfarm / WebfarmPath | Ancora presente, scritto IsWebFarm / WebFarmPath — non necessario nel percorso di pubblicazione |
Doconut.Configs.Cloud | Doconut.Clouds |
Checklist
- Costruisci il
FileShareConfigin un unico helper, registralo una sola volta e usalo da entrambe le metà. - Punta
RootPathsulla condivisione che usi già. - Pubblica con
PublishAsync(...); elimina qualsiasi chiamataExportToPng/ExportToCloud. - Servi con
UseDoconutCloud<FileShareCloudHandler>(...)sul ramo che il client chiama. - Con la pubblicazione in background, attiva
FirstPagePriorityeretryOn409insieme, e fornisci al lato di lettura unReadReadyPollMsnon zero. - Sostituisci il controllo per sessione con ticket di accesso firmati — un anello di chiavi Data Protection su ogni nodo,
UseDoconutDistributedDocumentSecurity()sul ramo di lettura, un ticket dall'endpoint aperto — e non distribuireUnsafeMode = trueda solo. - Verifica aprendo un documento su un nodo e richiedendo una pagina tardiva da un altro.
Questa pagina è stata utile?