Despliegues Distribuidos
Sirve un documento desde varios nodos
Cuando varios nodos sirven los mismos documentos, el nodo que renderiza un documento no es necesariamente el nodo que responde a las solicitudes de página del navegador. Esta versión divide esa tarea en dos mitades explícitas — un lado de escritura que publica los artefactos de un documento en almacenamiento compartido, y un lado de lectura que los sirve desde cualquier nodo.
Si tu aplicación actualmente llama a UseDoconutWebFarm(...), esta página es tu reemplazo. Ni UseDoconutWebFarm ni WebFarmOptions existen en esta versión.
Tu topología no cambia. Apunta la raíz compartida al mismo camino UNC que usas hoy y cada nodo seguirá funcionando como lo hace ahora. Lo que cambia es que la publicación es una operación que llamas, en lugar de un efecto secundario de la renderización.
Qué reemplazó al middleware web-farm
Anteriormente un middleware hacía todo: servía imágenes pre‑renderizadas desde una carpeta compartida y encuestaba mientras otro nodo todavía las escribía. La espera era un presupuesto ciego — "bloquear hasta tres minutos esperando que la página aparezca".
Ahora el mismo trabajo son dos llamadas que puedes ver y razonar:
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 configuración compartida que ambas mitades necesitan
El publicador escribe con un FileShareConfig y el controlador de lectura sirve con uno. Si RootPath o UsePerTokenSubfolders difieren entre ellos, el otro nodo responde 404. Construye la configuración en un solo lugar y regístrala una vez, de modo que ambas mitades lean el mismo objeto:
var rootPath = builder.Configuration["Doconut:SharedRoot"]!; // p. ej. \\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,
};
}Pase asyncPublish: true cuando active la publicación en segundo plano(publicación en segundo plano).
FileShareConfig vive en Doconut.Clouds, junto con AzureConfig, AmazonConfig, GoogleCloudConfig, DropBoxConfig, RedisConfig, CDNConfig y FTPConfig. En la biblioteca anterior estos estaban en Doconut.Configs.Cloud; los nombres de clase no cambiaron.
| Propiedad | Propósito |
|---|---|
Location | CloudLocation.FileShare para un recurso compartido UNC/local |
RootPath | La carpeta compartida a la que puede acceder cualquier nodo |
UsePerTokenSubfolders | Mantenga los artefactos de cada documento en su propia carpeta {token} (predeterminado true) |
ReadReadyPollMs | Cuánto tiempo espera el lado de lectura por una página que una publicación en segundo plano aún está escribiendo; 0 (el predeterminado) verifica una vez. No tiene efecto en los documentos publicados de forma sincrónica |
Lado de escritura — publicar el documento
Inyecta DistributedDocumentPublisher y publica en lugar de abrir una sesión local. Una llamada renderiza y escribe el conjunto completo de artefactos — páginas, información del documento, índice de búsqueda y metadatos — y devuelve cuando ha terminado:
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 lleva Token, ArtifactPath, TotalPages y Format. El token se envía al navegador exactamente como lo hace un token de visor normal. En una granja, el punto final también devuelve un ticket de acceso firmado — vea Seguridad entre nodos(Seguridad entre nodos).
Esta única llamada reemplaza al par anterior — abrir el documento en una sesión local y luego volcar imágenes en el recurso compartido con ExportToPng(sharedPath). ExportToPng y ExportToCloud no tienen equivalente aquí.
Lado de lectura — servir desde el recurso compartido
Monte el controlador FileShare en la misma rama que el cliente ya llama, detrás de la verificación del ticket:
var app = builder.Build();
app.UseDoconutResources();
app.MapWhen(
ctx => ctx.Request.Path.Value?.EndsWith("DocImage.axd", StringComparison.OrdinalIgnoreCase) == true,
branch =>
{
branch.UseDoconutDistributedDocumentSecurity(); // tickets firmados — ver abajo
branch.UseDoconutCloud<FileShareCloudHandler>(options =>
{
options.Location = CloudLocation.FileShare;
options.CloudUploadConfig = app.Services.GetRequiredService<FileShareConfig>();
}, "/");
});UseDoconutCloud es genérico en esta versión: el proveedor es el argumento de tipo en lugar de un valor Location conmutado dentro del middleware. Los controladores se nombran <Provider>CloudHandler — FileShareCloudHandler, AzureCloudHandler, AmazonS3CloudHandler, GoogleCloudHandler, DropBoxCloudHandler, RedisCloudHandler, FTPCloudHandler y CDNCloudHandler. Con el prefijo de ruta "/", el controlador responde a cada solicitud que llega a su rama.
El controlador CDN es solo lectura — sirve lo que ya está en el CDN; no sube.
Opcional: publicar en segundo plano
Por defecto PublishAsync renderiza todo el documento antes de devolverlo. Para devolver tan pronto como el token se genera y permitir que un trabajador alojado renderice en la misma carpeta, registre la cola de opción y construya la configuración compartida con asyncPublish: true:
builder.Services.AddDoconut(options => { /* … */ });
builder.Services.AddDoconutDistributedAsyncPublish();Sin este registro no se registra nada y la publicación permanece sincrónica, exactamente como antes.
Luego llame a EnqueueAsync en lugar de PublishAsync. (DistributedDocumentPublishOptions.Async es solo una bandera que su propio código puede leer para elegir entre los dos caminos; el publicador lo ignora.) La cola es limitada: cuando está saturada, EnqueueAsync lanza DistributedPublishQueueFullException. Responda con un 503 y una cabecera Retry-After para que los clientes retrocedan en lugar de bloquearse:
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);
}
});Páginas que aún no están escritas: HTTP 202
Con la publicación en segundo plano, una solicitud de página puede llegar antes de que el trabajador haya escrito esa página. El lado de lectura espera hasta ReadReadyPollMs y luego responde HTTP 202 Accepted en lugar de bloquear la solicitud.
FirstPagePriority = true acorta la espera para la primera vista: la página 1 se escribe primero en la carpeta del documento, de modo que el documento se abre mientras las páginas posteriores siguen renderizándose. Solo se aplica a la publicación en segundo plano en carpetas por token (UsePerTokenSubfolders = true); el PublishAsync sincrónico lo ignora, porque su llamador espera todo el documento de todos modos.
Eso traslada la espera al cliente, donde está limitada y es visible. Habilite reintentos en el widget:
const objViewer = $('#div_ctlDoc').docViewer({
BasePath: '/',
ResPath: 'doconut-res/images',
retryOn409: true // reintentos 202 (y legado 409) respuestas de disponibilidad
});Un cliente que no reintenta muestra mosaicos rotos para las páginas que aún se están renderizando. El presupuesto de reintentos y sus valores predeterminados (retryInitialDelayMs, retryBackoffFactor, retryMaxDelayMs, retryMaxAttempts, retryMaxTotalMs) están documentados en ConfiguraciónDelVisor.
Este par — publicación en segundo plano con FirstPagePriority, más la encuesta del lado de lectura — es lo que reemplaza las configuraciones anteriores PageWaitTimeSeconds y StartWaitFromPage. Ninguna de ellas existe ya.
Seguridad entre nodos
Los tokens vinculados a la sesión asumen que el nodo que sirve vio la solicitud inicial. En una granja no lo hizo, por lo que la verificación por sesión rechazaría solicitudes legítimas; una granja por lo tanto establece UnsafeMode = true.
UnsafeMode = true no es el modelo de seguridad — es la eliminación de uno que ya no se aplica.
Reemplácelo con tickets de acceso firmados, que cada nodo puede verificar de forma independiente. Cuatro componentes trabajan juntos.
1. Registrar la seguridad de tickets en cada nodo.
Los tickets están protegidos con ASP.NET Core Data Protection, por lo que cada nodo debe usar el mismo anillo de claves y nombre de aplicación; un nodo con claves diferentes no puede leer un ticket emitido por otro nodo.
using Microsoft.AspNetCore.DataProtection;
builder.Services.AddDataProtection()
.PersistKeysToFileSystem(new DirectoryInfo(@"\\fileserver\doconut-keys")) // compartido por cada nodo
.SetApplicationName("doconut-farm");
builder.Services.AddDoconut(options => options.UnsafeMode = true);
builder.Services.AddDoconutDistributedDocumentSecurity(options =>
{
options.TicketLifetimeMinutes = 60; // el predeterminado
});2. Verificar los tickets en el lado de lectura.
UseDoconutDistributedDocumentSecurity() se coloca en la rama de lectura antes de UseDoconutCloud, como en el ejemplo del lado de lectura.
3. Emitir un ticket cuando se abre el documento.
El ticket nombra el token, el navegador (a través de una cookie que el lado de lectura compara), y el usuario autenticado, si lo hay:
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);
// Vincula el ticket a este navegador mediante la cookie que verifica el lado de lectura.
var cookieName = security.Value.BrowserCookieName; // "doconut-client" por defecto
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. Pasar ambos al widget.
El visor envía el ticket como access con cada solicitud:
const resp = await fetch('/api/open?fileName=Sample.pdf', { method: 'POST' });
const { token, access } = await resp.json();
objViewer.View(token, access);El lado de lectura rechaza una solicitud cuyo ticket falta, es inválido, fue emitido para otro token, está expirado, vinculado a otra cookie del navegador, o emitido a otro usuario autenticado. Responde 403 — con la imagen de error UnauthorizedMessage para solicitudes de página y miniatura, y como texto plano en caso contrario. Pruebe con un navegador real o un cliente que conserve cookies.
Nunca lleve UnsafeMode = true de vuelta a una implementación de un solo nodo, y nunca lo trate como un atajo para una verificación de sesión fallida en un nodo — allí la solución correcta es AddSession() / UseSession(). Vea Sesiones y Seguridad.
Cerrando un documento publicado
CloseDocument(token) en el Viewer inyectado elimina una sesión local. Para eliminar los artefactos publicados de un documento del recurso compartido, el publicador expone:
bool CloseDistributedDocument(FileShareConfig fileShareConfig, string token)Pase el mismo FileShareConfig con el que se publicó el documento.
Mapeo configuración por configuración
| Anterior | Ahora |
|---|---|
UseDoconutWebFarm(new WebFarmOptions { … }) | PublishAsync(...) en el lado de escritura más UseDoconutCloud<FileShareCloudHandler>(...) en el lado de lectura |
WebFarmOptions.Path | FileShareConfig.RootPath |
PageWaitTimeSeconds / StartWaitFromPage | Publicación en segundo plano con DistributedDocumentPublishOptions.FirstPagePriority, más FileShareConfig.ReadReadyPollMs |
viewer.OpenDocument(...) then viewer.ExportToPng(share) | una llamada PublishAsync(...) |
viewer.ExportToCloud(cloudConfig) | PublishAsync(...) con la configuración del proveedor |
UseDoconutCloud(new CloudOptions { Location = … }) | UseDoconutCloud<THandler>(options => …, pathPrefix) |
DocOptions.IsWebfarm / WebfarmPath | Todavía presente, escrito IsWebFarm / WebFarmPath — no necesario en la ruta de publicación |
Doconut.Configs.Cloud | Doconut.Clouds |
Lista de verificación
- Construye el
FileShareConfigen un único ayudante, regístralo una vez y úsalo desde ambas mitades. - Apunta
RootPathal recurso compartido que ya utilizas. - Publica con
PublishAsync(...); elimina cualquier llamadaExportToPng/ExportToCloud. - Sirve con
UseDoconutCloud<FileShareCloudHandler>(...)en la rama que llama el cliente. - Con la publicación en segundo plano, activa
FirstPagePriorityyretryOn409juntos, y da al lado de lectura unReadReadyPollMsdistinto de cero. - Reemplaza la verificación por sesión con tickets de acceso firmados — un anillo de claves Data Protection en cada nodo,
UseDoconutDistributedDocumentSecurity()en la rama de lectura, un ticket del punto final abierto — y no envíesUnsafeMode = truesolo. - Verifica abriendo un documento en un nodo y solicitando una página tardía desde otro.
¿Fue útil esta página?