Implantações Distribuídas
Sirva um documento a partir de vários nós
Quando vários nós servem os mesmos documentos, o nó que renderiza um documento não é necessariamente o nó que responde às solicitações de página do navegador. Doconut divide essa tarefa em duas metades explícitas — um lado de escrita que publica os artefatos de um documento no armazenamento compartilhado, e um lado de leitura que os serve de qualquer nó.
Um único nó não precisa de nada disso: o caminho normal OpenDocumentAsync mantém o documento na memória desse nó e o vincula à sessão do navegador (veja Sessões e Segurança). Use esta página quando as solicitações de página podem chegar a um nó que nunca viu a abertura.
Como as duas metades se encaixam
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 pageA configuração compartilhada que ambas as metades precisam
O publicador grava com um FileShareConfig e o manipulador de leitura serve com um. Se RootPath ou UsePerTokenSubfolders diferirem entre eles, o outro nó responde 404. Construa a configuração em exatamente um lugar e registre‑a uma única vez, para que ambas as metades leiam o mesmo objeto:
var rootPath = builder.Configuration["Doconut:SharedRoot"]!; // por exemplo \\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,
};
}Passe asyncPublish: true ao ativar a publicação em segundo plano.
FileShareConfig está em Doconut.Clouds, junto com AzureConfig, AmazonConfig, GoogleCloudConfig, DropBoxConfig, RedisConfig, CDNConfig e FTPConfig.
| Propriedade | Propósito |
|---|---|
Location | CloudLocation.FileShare para um compartilhamento UNC/local |
RootPath | A pasta compartilhada que todo nó pode acessar |
UsePerTokenSubfolders | Mantenha os artefatos de cada documento em sua própria pasta {token} (padrão true) |
ReadReadyPollMs | Quanto tempo o lado de leitura espera por uma página que uma publicação em segundo plano ainda está gravando; 0 (o padrão) verifica uma vez. Não tem efeito em documentos publicados de forma síncrona |
Lado de escrita — publicar o documento
Injete DistributedDocumentPublisher e publique em vez de abrir uma sessão local. Uma chamada renderiza e grava o conjunto completo de artefatos — páginas, informações do documento, índice de busca e metadados — e retorna quando termina:
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 transporta Token, ArtifactPath, TotalPages e Format. O token vai para o navegador exatamente como um token de visualizador normal. Em um farm, o endpoint também retorna um ticket de acesso assinado — veja Segurança entre nós.
Lado de leitura — servir a partir do compartilhamento
Monte o manipulador FileShare no ramo que o cliente chama — /doconut, correspondendo a BasePath: 'doconut' — atrás da verificação de ticket:
var app = builder.Build();
app.UseDoconutResources();
app.Map("/doconut", branch =>
{
branch.UseDoconutDistributedDocumentSecurity(); // bilhetes assinados — veja abaixo
branch.UseDoconutCloud<FileShareCloudHandler>(options =>
{
options.Location = CloudLocation.FileShare;
options.CloudUploadConfig = app.Services.GetRequiredService<FileShareConfig>();
}, "/");
});UseDoconutCloud recebe o provedor como seu argumento de tipo. Os manipuladores são nomeados <Provider>CloudHandler — FileShareCloudHandler, AzureCloudHandler, AmazonS3CloudHandler, GoogleCloudHandler, DropBoxCloudHandler, RedisCloudHandler, FTPCloudHandler e CDNCloudHandler. Com o prefixo de caminho "/", o manipulador responde a cada requisição que chega ao seu ramo.
O manipulador CDN é somente leitura — ele serve o que já está no CDN; não faz upload.
Opcional: publicar em segundo plano
Por padrão, PublishAsync renderiza todo o documento antes de retornar. Para retornar assim que o token é criado e permitir que um worker hospedado renderize na mesma pasta, registre a fila de opt-in e construa a configuração compartilhada com asyncPublish: true:
builder.Services.AddDoconut(options => { /* … */ });
builder.Services.AddDoconutDistributedAsyncPublish();Sem esse registro nada é registrado e a publicação permanece síncrona, exatamente como antes.
Então chame EnqueueAsync em vez de PublishAsync. (DistributedDocumentPublishOptions.Async é apenas uma bandeira que seu próprio código pode ler para escolher entre os dois caminhos; o publicador a ignora.) A fila é limitada: quando está saturada, EnqueueAsync lança DistributedPublishQueueFullException. Responda com um 503 e um cabeçalho Retry-After para que os clientes recuem em vez de travar:
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 ainda não foram escritas: HTTP 202
Com publicação em segundo plano, uma solicitação de página pode chegar antes que o worker tenha escrito essa página. O lado de leitura aguarda até ReadReadyPollMs e então responde HTTP 202 Accepted em vez de bloquear a requisição.
FirstPagePriority = true encurta a espera para a primeira visualização: a página 1 é escrita na pasta do documento primeiro, então o documento abre enquanto as páginas posteriores ainda estão sendo renderizadas. Aplica‑se apenas à publicação em segundo plano em pastas por token (UsePerTokenSubfolders = true); o PublishAsync síncrono a ignora, pois seu chamador espera todo o documento de qualquer forma.
Isso transfere a espera para o cliente, onde ela é limitada e visível. Habilite a nova tentativa no widget:
const objViewer = $('#div_ctlDoc').docViewer({
BasePath: 'doconut',
ResPath: 'doconut-res/images',
retryOn409: true // tentativas 202 (e legado 409) respostas de prontidão
});Um cliente que não tenta novamente mostra blocos quebrados para páginas que ainda estão sendo renderizadas. O orçamento de tentativas e seus padrões (retryInitialDelayMs, retryBackoffFactor, retryMaxDelayMs, retryMaxAttempts, retryMaxTotalMs) estão documentados em ConfiguraçãoDoVisualizador.
Segurança entre nós
Tokens vinculados à sessão assumem que o nó de serviço viu a solicitação de abertura. Em um farm isso não ocorre, portanto a verificação por sessão rejeitaria solicitações legítimas; um farm, portanto, define UnsafeMode = true.
UnsafeMode = true não é o modelo de segurança — é a remoção de um que não se aplica mais. Substitua‑o por tickets de acesso assinados, que cada nó pode verificar independentemente. Quatro componentes trabalham juntos.
1. Registrar a segurança dos tickets em cada nó. Os tickets são protegidos com ASP.NET Core Data Protection, portanto cada nó deve usar o mesmo anel de chaves e nome de aplicação; um nó com chaves diferentes não pode ler um ticket emitido por outro nó.
using Microsoft.AspNetCore.DataProtection;
builder.Services.AddDataProtection()
.PersistKeysToFileSystem(new DirectoryInfo(@"\\fileserver\doconut-keys")) // compartilhado por cada nó
.SetApplicationName("doconut-farm");
builder.Services.AddDoconut(options => options.UnsafeMode = true);
builder.Services.AddDoconutDistributedDocumentSecurity(options =>
{
options.TicketLifetimeMinutes = 60; // o padrão
});2. Verificar tickets no lado de leitura. UseDoconutDistributedDocumentSecurity() vai na ramificação de leitura antes de UseDoconutCloud, como no exemplo do lado de leitura.
3. Emitir um ticket quando o documento é aberto. O ticket nomeia o token, o navegador (por meio de um cookie que o lado de leitura compara) e o usuário autenticado, se houver:
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);
// Vincule o ticket a este navegador através do cookie que o lado de leitura verifica.
var cookieName = security.Value.BrowserCookieName; // "doconut-client" por padrão
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. Passar ambos para o widget. O visualizador envia o ticket como access em cada solicitação:
const resp = await fetch('/api/open?fileName=Sample.pdf', { method: 'POST' });
const { token, access } = await resp.json();
objViewer.View(token, access);O lado de leitura recusa uma solicitação cujo ticket está ausente, inválido, emitido para outro token, expirado, vinculado a outro cookie de navegador ou emitido para outro usuário autenticado. Ele responde 403 — com a imagem de erro UnauthorizedMessage para solicitações de página e miniatura, como texto simples nos demais casos. Teste com um navegador real ou um cliente que mantenha cookies.
Nunca leve UnsafeMode = true de volta para uma implantação de nó único, e nunca o trate como um atalho para uma verificação de sessão falha em um nó — lá a correção correta é AddSession() / UseSession(). Veja Sessões e Segurança.
Encerrando um documento publicado
CloseDocument(token) no Viewer injetado descarta uma sessão local. Para remover os artefatos publicados de um documento do compartilhamento, o publicador expõe:
bool CloseDistributedDocument(FileShareConfig fileShareConfig, string token)Passe o mesmo FileShareConfig com o qual o documento foi publicado.
Checklist
- Construa o
FileShareConfigem um helper, registre‑o uma vez e use‑o em ambas as metades. - Aponte o
RootPathpara uma pasta que todo nó possa alcançar. - Publique com
PublishAsync(...), ouEnqueueAsync(...)com publicação em segundo plano. - Sirva com
UseDoconutCloud<FileShareCloudHandler>(...)no branch que o cliente chama. - Com publicação em segundo plano, habilite
FirstPagePriorityeretryOn409juntos, e dê ao lado de leitura umReadReadyPollMsnão zero. - Substitua a verificação por sessão por tickets de acesso assinados — um anel de chaves Data Protection em cada nó,
UseDoconutDistributedDocumentSecurity()no branch de leitura, um ticket do endpoint aberto — e não envieUnsafeMode = truesozinho. - Verifique abrindo um documento em um nó e solicitando uma página tardia de outro.
Esta página foi útil?