Déploiements distribués
Servir un document depuis plusieurs nœuds
Lorsque plusieurs nœuds servent les mêmes documents, le nœud qui rend un document n'est pas nécessairement celui qui répond aux requêtes de page du navigateur. Doconut divise cette tâche en deux moitiés explicites — un write side qui publie les artefacts d'un document dans un stockage partagé, et un read side qui les sert depuis n'importe quel nœud.
Un seul nœud n'a pas besoin de tout cela : le chemin normal OpenDocumentAsync conserve le document dans la mémoire de ce nœud et le lie à la session du navigateur (voir Sessions et sécurité). Utilisez cette page lorsque les requêtes de page peuvent atterrir sur un nœud qui n'a jamais vu l'ouverture.
Comment les deux moitiés s'emboîtent
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 configuration partagée dont les deux moitiés ont besoin
L'éditeur écrit avec un FileShareConfig et le gestionnaire de lecture le sert avec un. Si RootPath ou UsePerTokenSubfolders diffèrent entre eux, l'autre nœud renvoie 404. Construisez la configuration à un seul endroit et enregistrez‑la une fois, afin que les deux moitiés lisent le même objet :
var rootPath = builder.Configuration["Doconut:SharedRoot"]!; // par ex. \\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,
};
}Passez asyncPublish: true lorsque vous activez la publication en arrière‑plan.
FileShareConfig vit dans Doconut.Clouds, avec AzureConfig, AmazonConfig, GoogleCloudConfig, DropBoxConfig, RedisConfig, CDNConfig et FTPConfig.
| Propriété | Objectif |
|---|---|
Location | CloudLocation.FileShare pour un partage UNC/local |
RootPath | Le dossier partagé que chaque nœud peut atteindre |
UsePerTokenSubfolders | Conservez les artefacts de chaque document dans son propre dossier {token} (par défaut true) |
ReadReadyPollMs | Durée pendant laquelle le read side attend une page qu'une publication en arrière‑plan est encore en train d'écrire ; 0 (la valeur par défaut) vérifie une fois. Cela n'a aucun effet sur les documents publiés de façon synchrone |
Write side — publier le document
Injectez DistributedDocumentPublisher et publiez au lieu d'ouvrir une session locale. Un appel rend et écrit l'ensemble complet des artefacts — pages, informations du document, index de recherche et métadonnées — et renvoie lorsqu'il est terminé :
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 transporte Token, ArtifactPath, TotalPages et Format. Le token va au navigateur exactement comme le fait un token de visualiseur normal. Dans une ferme, le point de terminaison renvoie également un ticket d'accès signé — voir Sécurité entre nœuds.
Côté lecture — servir depuis le partage
Montez le gestionnaire FileShare sur la branche que le client appelle — /doconut, correspondant à BasePath: 'doconut' — derrière la vérification du ticket :
var app = builder.Build();
app.UseDoconutResources();
app.Map("/doconut", branch =>
{
branch.UseDoconutDistributedDocumentSecurity(); // tickets signés — voir ci-dessous
branch.UseDoconutCloud<FileShareCloudHandler>(options =>
{
options.Location = CloudLocation.FileShare;
options.CloudUploadConfig = app.Services.GetRequiredService<FileShareConfig>();
}, "/");
});UseDoconutCloud prend le fournisseur comme argument de type. Les gestionnaires sont nommés <Provider>CloudHandler — FileShareCloudHandler, AzureCloudHandler, AmazonS3CloudHandler, GoogleCloudHandler, DropBoxCloudHandler, RedisCloudHandler, FTPCloudHandler, et CDNCloudHandler. Avec le préfixe de chemin "/", le gestionnaire répond à chaque requête qui atteint sa branche.
Le gestionnaire CDN est en lecture seule — il sert ce qui est déjà sur le CDN ; il ne téléverse rien.
Optionnel : publier en arrière-plan
Par défaut PublishAsync rend le document complet avant de renvoyer la réponse. Pour renvoyer dès que le jeton est créé et laisser un worker hébergé rendre dans le même dossier, enregistrez la file d’attente d’opt‑in, et construisez la configuration partagée avec asyncPublish: true :
builder.Services.AddDoconut(options => { /* … */ });
builder.Services.AddDoconutDistributedAsyncPublish();Sans cet enregistrement, rien n’est enregistré et la publication reste synchrone, exactement comme avant.
Appelez alors EnqueueAsync au lieu de PublishAsync. (DistributedDocumentPublishOptions.Async n’est qu’un drapeau que votre propre code peut lire pour choisir entre les deux chemins ; l’éditeur l’ignore.) La file d’attente est bornée : lorsqu’elle est saturée, EnqueueAsync lève DistributedPublishQueueFullException. Répondez avec un 503 et un en‑tête Retry-After afin que les clients se retirent plutôt que de rester bloqués :
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);
}
});Pages qui ne sont pas encore écrites : HTTP 202
Avec la publication en arrière‑plan, une requête de page peut arriver avant que le worker n’ait écrit cette page. Le côté lecture attend jusqu’à ReadReadyPollMs puis répond HTTP 202 Accepted au lieu de bloquer la requête.
FirstPagePriority = true raccourcit l’attente pour la première vue : la page 1 est écrite dans le dossier du document en premier, de sorte que le document s’ouvre pendant que les pages suivantes sont encore en cours de rendu. Cela ne s’applique qu’à la publication en arrière‑plan dans des dossiers par jeton (UsePerTokenSubfolders = true) ; le PublishAsync synchrone l’ignore, car son appelant attend tout le document de toute façon.
Cela déplace l’attente vers le client, où elle est bornée et visible. Activez la nouvelle tentative sur le widget :
const objViewer = $('#div_ctlDoc').docViewer({
BasePath: 'doconut',
ResPath: 'doconut-res/images',
retryOn409: true // tentatives 202 (et legacy 409) réponses de disponibilité
});Un client qui ne réessaie pas affiche des tuiles cassées pour les pages qui sont encore en cours de rendu. Le budget de nouvelles tentatives et ses valeurs par défaut (retryInitialDelayMs, retryBackoffFactor, retryMaxDelayMs, retryMaxAttempts, retryMaxTotalMs) sont documentés dans Configuration du visualiseur.
Sécurité entre les nœuds
Les jetons liés à la session supposent que le nœud de service a vu la requête d'ouverture. Dans une ferme, ce n’est pas le cas, donc la vérification par session rejetterait les requêtes légitimes ; une ferme définit donc UnsafeMode = true.
UnsafeMode = true n’est pas le modèle de sécurité — c’est la suppression d’un qui n’est plus applicable. Remplacez‑le par des tickets d’accès signés, que chaque nœud peut vérifier indépendamment. Quatre éléments fonctionnent ensemble.
1. Enregistrer la sécurité des tickets sur chaque nœud. Les tickets sont protégés avec ASP.NET Core Data Protection, de sorte que chaque nœud doit utiliser le même anneau de clés et le même nom d’application ; un nœud avec des clés différentes ne peut pas lire un ticket émis par un autre nœud.
using Microsoft.AspNetCore.DataProtection;
builder.Services.AddDataProtection()
.PersistKeysToFileSystem(new DirectoryInfo(@"\\fileserver\doconut-keys")) // partagé par chaque nœud
.SetApplicationName("doconut-farm");
builder.Services.AddDoconut(options => options.UnsafeMode = true);
builder.Services.AddDoconutDistributedDocumentSecurity(options =>
{
options.TicketLifetimeMinutes = 60; // par défaut
});2. Vérifier les tickets côté lecture. UseDoconutDistributedDocumentSecurity() se place sur la branche de lecture avant UseDoconutCloud, comme dans l'exemple côté lecture.
3. Émettre un ticket lorsque le document est ouvert. Le ticket indique le jeton, le navigateur (via un cookie que le côté lecture compare), et l’utilisateur connecté, le cas échéant :
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);
// Liez le ticket à ce navigateur via le cookie que le côté lecture vérifie.
var cookieName = security.Value.BrowserCookieName; // "doconut-client" par défaut
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. Passer les deux au widget. Le visualiseur envoie le ticket en tant que access avec chaque requête :
const resp = await fetch('/api/open?fileName=Sample.pdf', { method: 'POST' });
const { token, access } = await resp.json();
objViewer.View(token, access);Le côté lecture refuse une requête dont le ticket est absent, invalide, émis pour un autre jeton, expiré, lié à un autre cookie de navigateur, ou émis pour un autre utilisateur connecté. Il répond 403 — avec l’image d’erreur UnauthorizedMessage pour les requêtes de page et de vignette, sinon en texte brut. Testez avec un vrai navigateur ou un client qui conserve les cookies.
Ne jamais ramener UnsafeMode = true dans un déploiement à nœud unique, et ne jamais le considérer comme un raccourci pour une vérification de session défaillante sur un nœud — la solution correcte est AddSession() / UseSession(). Voir Sessions et sécurité.
Fermeture d’un document publié
CloseDocument(token) sur le Viewer injecté libère une session locale. Pour supprimer les artefacts publiés d’un document du partage, l’éditeur expose :
bool CloseDistributedDocument(FileShareConfig fileShareConfig, string token)Passez le même FileShareConfig avec lequel le document a été publié.
Liste de contrôle
- Construisez le
FileShareConfigdans un seul helper, enregistrez‑le une fois, et utilisez‑le depuis les deux moitiés. - Pointez
RootPathvers un dossier accessible par chaque nœud. - Publiez avec
PublishAsync(...), ouEnqueueAsync(...)avec publication en arrière‑plan. - Servez avec
UseDoconutCloud<FileShareCloudHandler>(...)sur la branche appelée par le client. - Avec la publication en arrière‑plan, activez
FirstPagePriorityetretryOn409ensemble, et attribuez à la partie lecture unReadReadyPollMsnon nul. - Remplacez la vérification par session par des tickets d’accès signés — un anneau de clés Data Protection sur chaque nœud,
UseDoconutDistributedDocumentSecurity()sur la branche de lecture, un ticket depuis le point de terminaison ouvert — et ne distribuez pasUnsafeMode = trueseul. - Vérifiez en ouvrant un document sur un nœud et en demandant une page tardive depuis un autre.
Cette page était-elle utile ?