Distribuzioni Distribuite
Fornisce un documento da più nodi
Quando più nodi servono gli stessi documenti, il nodo che rende un documento non è necessariamente quello che risponde alle richieste di pagina del browser. Doconut divide questo compito in due metà esplicite — un write side che pubblica gli artefatti di un documento nello storage condiviso, e un read side che li serve da qualsiasi nodo.
Un singolo nodo non ha bisogno di nulla di tutto ciò: il normale percorso OpenDocumentAsync mantiene il documento nella memoria di quel nodo e lo associa alla sessione del browser (vedi Sessioni e Sicurezza). Usa questa pagina quando le richieste di pagina possono arrivare su un nodo che non ha mai visto l'apertura.
Come si incastrano le due metà
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
L'editore scrive con un FileShareConfig e il gestore di lettura serve con uno. Se RootPath o UsePerTokenSubfolders differiscono, l'altro nodo restituisce 404. Crea la configurazione in un unico luogo e registrala una sola volta, così entrambe le metà leggono lo stesso oggetto:
var rootPath = builder.Configuration["Doconut:SharedRoot"]!; // ad 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 si trova in Doconut.Clouds, insieme a AzureConfig, AmazonConfig, GoogleCloudConfig, DropBoxConfig, RedisConfig, CDNConfig e FTPConfig.
| 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 sua propria cartella {token} (predefinita true) |
ReadReadyPollMs | Quanto tempo il read side 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
Inject 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 viene inviato 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 i nodi.
Lato di lettura — servire dalla condivisione
Monta il gestore FileShare sul ramo che il client chiama — /doconut, corrispondente a BasePath: 'doconut' — dietro il controllo del ticket:
var app = builder.Build();
app.UseDoconutResources();
app.Map("/doconut", branch =>
{
branch.UseDoconutDistributedDocumentSecurity(); // biglietti firmati — vedi sotto
branch.UseDoconutCloud<FileShareCloudHandler>(options =>
{
options.Location = CloudLocation.FileShare;
options.CloudUploadConfig = app.Services.GetRequiredService<FileShareConfig>();
}, "/");
});UseDoconutCloud prende il provider come argomento di tipo. I gestori sono nominati <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.
Facoltativo: 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 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.
Chiama quindi EnqueueAsync invece di PublishAsync. (DistributedDocumentPublishOptions.Async è solo un flag che il tuo codice può leggere per scegliere tra i due percorsi; il pubblicatore 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 abbrevia 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.
Questo sposta l'attesa sul client, dove è limitata e visibile. Abilita il retry sul widget:
const objViewer = $('#div_ctlDoc').docViewer({
BasePath: 'doconut',
ResPath: 'doconut-res/images',
retryOn409: true // tentativi 202 (e legacy 409) risposte di readiness
});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 ConfigurazioneViewer.
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. Registrare la sicurezza dei ticket su ogni nodo. I ticket sono protetti con ASP.NET Core Data Protection, quindi ogni nodo deve utilizzare 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. Verificare i ticket sul lato 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 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. Passare 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 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, l'editore espone:
bool CloseDistributedDocument(FileShareConfig fileShareConfig, string token)Passare lo stesso FileShareConfig con cui è stato pubblicato il documento.
Lista di controllo
- Costruisci il
FileShareConfigin un unico helper, registralo una sola volta e usalo da entrambe le metà. - Punta
RootPathsu una cartella raggiungibile da tutti i nodi. - Pubblica con
PublishAsync(...), oppureEnqueueAsync(...)con pubblicazione in background. - Servi con
UseDoconutCloud<FileShareCloudHandler>(...)sul ramo chiamato dal client. - Con la pubblicazione in background, attiva
FirstPagePriorityeretryOn409insieme, e assegna al lato di lettura unReadReadyPollMsdiverso da 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?