Distribuzioni distribuite
Fornisci un documento da diversi nodi
Quando più nodi forniscono 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 lato di scrittura che pubblica gli artefatti di un documento nello storage condiviso, e un lato di lettura che li serve da qualsiasi nodo.
Un singolo nodo non ha bisogno di tutto ciò: il percorso normale 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
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.
| 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 | Per 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.
Lato di lettura — servire dalla condivisione
Montare 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 suo 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 è read-only — 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 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 retrocedano invece di 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 prontezza
});Un client che non effettua retry mostra tile rotte 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 di apertura. 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. Sostituiscilo 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 il 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 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 controlla il lato di lettura.
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 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. Prova con un browser reale o un client che conserva i cookie.
Non riportare mai UnsafeMode = true in una distribuzione a nodo singolo, e non trattarlo mai come 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)Passa lo stesso FileShareConfig con cui il documento è stato pubblicato.
Lista di controllo
- Costruisci il
FileShareConfigin un unico helper, registralo una sola volta e usalo da entrambe le metà. - Imposta
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?