Распределённые развертывания
Обслуживание одного документа с нескольких узлов
Когда несколько узлов обслуживают одни и те же документы, узел, который рендерит документ, не обязательно является тем узлом, который отвечает на запросы страниц браузера. Doconut делит эту задачу на две явные части — сторону записи, публикующую артефакты документа в общее хранилище, и сторону чтения, обслуживающую их с любого узла.
Один отдельный узел не нуждается в этом: обычный путь OpenDocumentAsync хранит документ в памяти этого узла и привязывает его к сессии браузера (см. Сессии и безопасность). Используйте эту страницу, когда запросы страниц могут попадать на узел, который никогда не открывал документ.
Как две части сочетаются
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 pageОбщая конфигурация, необходимая обеим частям
Публикующий пишет с помощью FileShareConfig, а обработчик чтения обслуживает с помощью аналогичного. Если RootPath или UsePerTokenSubfolders различаются между ними, другой узел возвращает 404. Создайте конфигурацию в одном месте и зарегистрируйте её один раз, чтобы обе части читали один и тот же объект:
var rootPath = builder.Configuration["Doconut:SharedRoot"]!; // например \\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,
};
}Передайте asyncPublish: true, когда включаете фоновую публикацию.
FileShareConfig находится в Doconut.Clouds, вместе с AzureConfig, AmazonConfig, GoogleCloudConfig, DropBoxConfig, RedisConfig, CDNConfig и FTPConfig.
| Свойство | Назначение |
|---|---|
Location | CloudLocation.FileShare для UNC/локального общего ресурса |
RootPath | Общая папка, доступная каждому узлу |
UsePerTokenSubfolders | Хранить артефакты каждого документа в отдельной папке {token} (по умолчанию true) |
ReadReadyPollMs | Как долго сторона чтения ждёт страницу, пока фоновая публикация ещё пишет; 0 (по умолчанию) проверяет один раз. Не влияет на синхронно публикуемые документы |
Сторона записи — публикация документа
Внедрите DistributedDocumentPublisher и публикуйте вместо открытия локальной сессии. Один вызов рендерит и записывает полный набор артефактов — страницы, информацию о документе, поисковый индекс и метаданные — и возвращается после завершения:
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 содержит Token, ArtifactPath, TotalPages и Format. Токен передаётся браузеру точно так же, как обычный токен просмотрщика. В ферме конечная точка также возвращает подписанный билет доступа — см. Безопасность между узлами.
Читательная сторона — обслуживать из общего доступа
Подмонтируйте обработчик FileShare на ветку, которую вызывает клиент — /doconut, соответствующую BasePath: 'doconut' — за проверкой билета:
var app = builder.Build();
app.UseDoconutResources();
app.Map("/doconut", branch =>
{
branch.UseDoconutDistributedDocumentSecurity(); // подписанные билеты — см. ниже
branch.UseDoconutCloud<FileShareCloudHandler>(options =>
{
options.Location = CloudLocation.FileShare;
options.CloudUploadConfig = app.Services.GetRequiredService<FileShareConfig>();
}, "/");
});UseDoconutCloud принимает провайдера в качестве аргумента типа. Обработчики называются <Provider>CloudHandler — FileShareCloudHandler, AzureCloudHandler, AmazonS3CloudHandler, GoogleCloudHandler, DropBoxCloudHandler, RedisCloudHandler, FTPCloudHandler и CDNCloudHandler. С префиксом пути "/" обработчик отвечает на каждый запрос, попадающий в его ветку.
Обработчик CDN является только для чтения — он обслуживает то, что уже находится на CDN; он не загружает.
Опционально: публикация в фоновом режиме
По умолчанию PublishAsync рендерит весь документ перед возвратом. Чтобы вернуть ответ сразу после создания токена и позволить размещённому воркеру рендерить в ту же папку, зарегистрируйте очередь по желанию и сформируйте общую конфигурацию с помощью asyncPublish: true:
builder.Services.AddDoconut(options => { /* … */ });
builder.Services.AddDoconutDistributedAsyncPublish();Без этой регистрации ничего не регистрируется, и публикация остаётся синхронной, точно как и раньше.
Затем вызывайте EnqueueAsync вместо PublishAsync. (DistributedDocumentPublishOptions.Async — это лишь флаг, который ваш собственный код может прочитать, чтобы выбрать один из двух путей; издатель его игнорирует.) Очередь ограничена: когда она переполняется, EnqueueAsync бросает DistributedPublishQueueFullException. Ответьте на неё с помощью 503 и заголовка Retry-After, чтобы клиенты отступали, а не зависали:
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);
}
});Страницы, которые ещё не записаны: HTTP 202
При фоновой публикации запрос страницы может поступить до того, как воркер запишет эту страницу. Читательная сторона ждёт до ReadReadyPollMs, а затем отвечает HTTP 202 Accepted, вместо блокировки запроса.
FirstPagePriority = true сокращает ожидание первой загрузки: страница 1 записывается в папку документа первой, поэтому документ открывается, пока остальные страницы ещё рендерятся. Это применимо только к фоновой публикации в папки per-token (UsePerTokenSubfolders = true); синхронный PublishAsync игнорирует это, потому что его вызывающий ждёт весь документ в любом случае.
Это переносит ожидание на клиент, где оно ограничено и видно. Включите повторные попытки в виджете:
const objViewer = $('#div_ctlDoc').docViewer({
BasePath: 'doconut',
ResPath: 'doconut-res/images',
retryOn409: true // повторы 202 (и legacy 409) ответы готовности
});Клиент, который не делает повторные попытки, показывает повреждённые плитки для страниц, которые всё ещё рендерятся. Бюджет повторных попыток и его значения по умолчанию (retryInitialDelayMs, retryBackoffFactor, retryMaxDelayMs, retryMaxAttempts, retryMaxTotalMs) задокументированы в ViewerConfig.
Безопасность между узлами
Токены, привязанные к сессии, предполагают, что обслуживающий узел видел запрос на открытие. В ферме это не так, поэтому проверка на уровне сессии отклоняла бы законные запросы; ферма поэтому устанавливает UnsafeMode = true.
UnsafeMode = true не является моделью безопасности — это удаление той, которая более не применима. Замените его подписанными билетами доступа, которые каждый узел может проверять независимо. Четыре компонента работают вместе.
1. Зарегистрировать безопасность билетов на каждом узле. Билеты защищены с помощью ASP.NET Core Data Protection, поэтому каждый узел должен использовать один и тот же набор ключей и имя приложения; узел с другими ключами не сможет прочитать билет, выданный другим узлом.
using Microsoft.AspNetCore.DataProtection;
builder.Services.AddDataProtection()
.PersistKeysToFileSystem(new DirectoryInfo(@"\\fileserver\doconut-keys")) // общий для всех узлов
.SetApplicationName("doconut-farm");
builder.Services.AddDoconut(options => options.UnsafeMode = true);
builder.Services.AddDoconutDistributedDocumentSecurity(options =>
{
options.TicketLifetimeMinutes = 60; // по умолчанию
});2. Проверять билеты на стороне чтения. UseDoconutDistributedDocumentSecurity() размещается в ветке чтения перед UseDoconutCloud, как в примерe чтения.
3. Выдавать билет при открытии документа. Билет содержит имя токена, браузера (через cookie, который сравнивает сторона чтения) и авторизованного пользователя, если он есть:
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);
// Привяжите билет к этому браузеру через cookie, проверяемый читающей стороной
var cookieName = security.Value.BrowserCookieName; // "doconut-client" по умолчанию
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. Передать оба в виджет. Просмотрщик отправляет билет как access с каждым запросом:
const resp = await fetch('/api/open?fileName=Sample.pdf', { method: 'POST' });
const { token, access } = await resp.json();
objViewer.View(token, access);Сторона чтения отклоняет запрос, если билет отсутствует, недействителен, выдан для другого токена, просрочен, привязан к другому cookie браузера или выдан другому авторизованному пользователю. Она отвечает 403 — с изображением ошибки UnauthorizedMessage для запросов страниц и миниатюр, иначе в виде простого текста. Протестируйте в реальном браузере или клиенте, сохраняющем cookies.
Никогда не переносите UnsafeMode = true обратно в однопользовательскую (один-узловую) развертку и никогда не рассматривайте его как обход для неработающей проверки сессии на одном узле — в этом случае правильное решение — AddSession() / UseSession(). См. Сессии и безопасность.
Закрытие опубликованного документа
CloseDocument(token) на внедрённом Viewer освобождает локальную сессию. Чтобы удалить опубликованные артефакты документа из общего ресурса, издатель предоставляет:
bool CloseDistributedDocument(FileShareConfig fileShareConfig, string token)Передайте тот же FileShareConfig, с которым документ был опубликован.
Checklist
- Создайте
FileShareConfigв одном помощнике, зарегистрируйте его один раз и используйте из обеих половин. - Укажите
RootPathна папку, доступную каждому узлу. - Публикуйте с помощью
PublishAsync(...), либоEnqueueAsync(...)с фоновым опубликованием. - Обслуживайте с помощью
UseDoconutCloud<FileShareCloudHandler>(...)на ветке, которую вызывает клиент. - При фоновом опубликовании включите одновременно
FirstPagePriorityиretryOn409, и задайте стороне чтения ненулевое значениеReadReadyPollMs. - Замените проверку на каждый сеанс подписанными билетами доступа — один кольцо ключей Data Protection на каждом узле,
UseDoconutDistributedDocumentSecurity()на ветке чтения, билет от открытой конечной точки — и не распространяйтеUnsafeMode = trueотдельно. - Проверьте, открыв документ на одном узле и запросив позднюю страницу с другого.
Была ли эта страница полезной?