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. Cette version divise cette tâche en deux moitiés explicites — un côté écriture qui publie les artefacts d'un document dans le stockage partagé, et un côté lecture qui les sert depuis n'importe quel nœud.
Si votre application appelle actuellement UseDoconutWebFarm(...), cette page est votre remplacement. Ni UseDoconutWebFarm ni WebFarmOptions n'existent dans cette version.
Votre topologie ne change pas. Pointez la racine partagée vers le même chemin UNC que vous utilisez aujourd'hui et chaque nœud continue de fonctionner comme il le fait maintenant. Ce qui change, c'est que la publication est une opération que vous appelez, au lieu d'un effet secondaire du rendu.
Ce qui a remplacé le middleware web‑farm
Auparavant, un seul middleware faisait tout : il servait des images pré‑rendues depuis un dossier partagé et interrogeait pendant qu'un autre nœud les écrivait encore. L'attente était un budget aveugle — « bloquer jusqu'à trois minutes en espérant que la page apparaisse ».
Désormais, la même tâche se résume à deux appels que vous pouvez voir et raisonner :
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 sert avec un. Si RootPath ou UsePerTokenSubfolders diffèrent entre eux, l'autre nœud renvoie 404. Créez 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"]!; // 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 se trouve dans Doconut.Clouds, avec AzureConfig, AmazonConfig, GoogleCloudConfig, DropBoxConfig, RedisConfig, CDNConfig et FTPConfig. Dans la bibliothèque précédente, ceux‑ci étaient dans Doconut.Configs.Cloud ; les noms de classe n'ont pas changé.
| Propriété | Objectif |
|---|---|
Location | CloudLocation.FileShare pour un partage UNC/local |
RootPath | Le dossier partagé que chaque nœud peut atteindre |
UsePerTokenSubfolders | Conserver les artefacts de chaque document dans son propre dossier {token} (par défaut true) |
ReadReadyPollMs | Durée pendant laquelle le côté lecture 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 manière synchrone |
Côté écriture — 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 lorsque c'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 jeton va au navigateur exactement comme le fait un jeton de visualiseur normal. Dans un farm, le point de terminaison renvoie également un ticket d'accès signé — voir Sécurité entre les nœuds.
Cet appel unique remplace la paire précédente — ouvrir le document dans une session locale puis déposer les images sur le partage avec ExportToPng(sharedPath). ExportToPng et ExportToCloud n'ont aucun équivalent ici.
Côté lecture — servir depuis le partage
Montez le gestionnaire FileShare sur la même branche que le client appelle déjà, derrière la vérification du ticket :
var app = builder.Build();
app.UseDoconutResources();
app.MapWhen(
ctx => ctx.Request.Path.Value?.EndsWith("DocImage.axd", StringComparison.OrdinalIgnoreCase) == true,
branch =>
{
branch.UseDoconutDistributedDocumentSecurity(); // tickets signés — voir ci‑dessous
branch.UseDoconutCloud<FileShareCloudHandler>(options =>
{
options.Location = CloudLocation.FileShare;
options.CloudUploadConfig = app.Services.GetRequiredService<FileShareConfig>();
}, "/");
});UseDoconutCloud est générique dans cette version : le fournisseur est l'argument de type plutôt qu'une valeur Location commutée à l'intérieur du middleware. 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 pas.
Optionnel : publier en arrière-plan
Par défaut, PublishAsync rend le document complet avant de retourner. Pour retourner 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 ; le publieur 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 ralentissent plutôt que de bloquer :
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 non 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, ainsi 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 de toute façon le document complet.
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: '/',
ResPath: 'doconut-res/images',
retryOn409: true // tentatives 202 (et legacy 409) réponses de disponibilité
});Un client qui ne réessaye 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.
Cette paire — publication en arrière‑plan avec FirstPagePriority, plus le sondage côté lecture — remplace les paramètres précédents PageWaitTimeSeconds et StartWaitFromPage. Aucun des deux n'existe plus.
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 un farm, ce n’est pas le cas, donc la vérification par session rejetterait les requêtes légitimes ; un farm définit donc UnsafeMode = true.
UnsafeMode = true n’est pas le modèle de sécurité — c’est la suppression d’un modèle 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; // la valeur 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);
// Lier 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. Transmettre 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 alors AddSession() / UseSession(). Voir Sessions et Sécurité.
Fermer 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é.
Correspondance paramètre par paramètre
| Précédent | Actuel |
|---|---|
UseDoconutWebFarm(new WebFarmOptions { … }) | PublishAsync(...) sur le côté écriture plus UseDoconutCloud<FileShareCloudHandler>(...) sur le côté lecture |
WebFarmOptions.Path | FileShareConfig.RootPath |
PageWaitTimeSeconds / StartWaitFromPage | Publication en arrière-plan avec DistributedDocumentPublishOptions.FirstPagePriority, plus FileShareConfig.ReadReadyPollMs |
viewer.OpenDocument(...) puis viewer.ExportToPng(share) | un appel PublishAsync(...) |
viewer.ExportToCloud(cloudConfig) | PublishAsync(...) avec la configuration du fournisseur |
UseDoconutCloud(new CloudOptions { Location = … }) | UseDoconutCloud<THandler>(options => …, pathPrefix) |
DocOptions.IsWebfarm / WebfarmPath | Toujours présent, orthographié IsWebFarm / WebFarmPath — pas nécessaire sur le chemin de publication |
Doconut.Configs.Cloud | Doconut.Clouds |
Liste de contrôle
- Construisez le
FileShareConfigdans un seul helper, enregistrez‑le une fois, et utilisez‑le des deux moitiés. - Pointez
RootPathvers le partage que vous utilisez déjà. - Publiez avec
PublishAsync(...); supprimez tous les appelsExportToPng/ExportToCloud. - Servez avec
UseDoconutCloud<FileShareCloudHandler>(...)sur la branche appelée par le client. - Avec la publication en arrière-plan, activez
FirstPagePriorityetretryOn409ensemble, et donnez au côté 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 lecture, un ticket depuis le point d'accès ouvert — et ne déployez 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 ?