Despliegues Distribuidos
Sirva 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. Doconut 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.
Un solo nodo no necesita nada de esto: la ruta normal OpenDocumentAsync mantiene el documento en la memoria de ese nodo y lo vincula a la sesión del navegador (ver Sesiones y Seguridad). Use esta página cuando las solicitudes de página pueden llegar a un nodo que nunca vio la apertura.
Cómo encajan las dos mitades
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 manejador de lectura sirve con uno. Si RootPath o UsePerTokenSubfolders difieren entre sí, el otro nodo responde 404. Construya la configuración en un solo lugar y regístrela 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.
FileShareConfig vive en Doconut.Clouds, junto con AzureConfig, AmazonConfig, GoogleCloudConfig, DropBoxConfig, RedisConfig, CDNConfig y FTPConfig.
| Propiedad | Propósito |
|---|---|
Location | CloudLocation.FileShare para un recurso 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} (por defecto 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 valor por defecto) verifica una vez. No tiene efecto en los documentos publicados de forma sincrónica |
Lado de escritura — publicar el documento
Inyecte DistributedDocumentPublisher y publique 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 endpoint también devuelve un ticket de acceso firmado — vea Seguridad entre nodos.
Lado de lectura — servir desde el recurso compartido
Montar el controlador FileShare en la rama que llama el cliente — /doconut, coincidiendo con BasePath: 'doconut' — detrás de la verificación del ticket:
var app = builder.Build();
app.UseDoconutResources();
app.Map("/doconut", branch =>
{
branch.UseDoconutDistributedDocumentSecurity(); // tickets firmados — ver abajo
branch.UseDoconutCloud<FileShareCloudHandler>(options =>
{
options.Location = CloudLocation.FileShare;
options.CloudUploadConfig = app.Services.GetRequiredService<FileShareConfig>();
}, "/");
});UseDoconutCloud toma el proveedor como su argumento de tipo. 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 nada.
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 opt‑in 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 la ignora.) La cola está limitada: cuando se satura, 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 se han escrito: 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. Sólo 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 la reintento en el widget:
const objViewer = $('#div_ctlDoc').docViewer({
BasePath: 'doconut',
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 reintento y sus valores predeterminados (retryInitialDelayMs, retryBackoffFactor, retryMaxDelayMs, retryMaxAttempts, retryMaxTotalMs) están documentados en ConfiguraciónDelVisor.
Seguridad entre nodos
Los tokens vinculados a la sesión asumen que el nodo que sirve vio la solicitud de apertura. 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 aplica. Reemplácelo con tickets de acceso firmados, que cada nodo puede verificar de forma independiente. Cuatro piezas trabajan juntas.
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 a través de 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, 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.
Cerrar un documento publicado
CloseDocument(token) en el Viewer inyectado elimina una sesión local. Para eliminar los artefactos publicados de un documento del share, el publicador expone:
bool CloseDistributedDocument(FileShareConfig fileShareConfig, string token)Pase el mismo FileShareConfig con el que se publicó el documento.
Lista de verificación
- Construye el
FileShareConfigen un único ayudante, regístralo una vez y úsalo desde ambas mitades. - Apunta
RootPatha una carpeta a la que cada nodo pueda acceder. - Publica con
PublishAsync(...), oEnqueueAsync(...)con publicación en segundo plano. - Sirve con
UseDoconutCloud<FileShareCloudHandler>(...)en la rama que el cliente solicita. - Con publicación en segundo plano, activa
FirstPagePriorityyretryOn409juntos, y otorga al lado de lectura unReadReadyPollMsdistinto de cero. - Reemplaza la verificación por sesión con tickets de acceso firmados — un anillo de claves de Protección de Datos 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?