Распределённые развертывания
Обслуживание одного документа с нескольких узлов
Когда несколько узлов обслуживают одни и те же документы, узел, который рендерит документ, не обязательно является узлом, отвечающим на запросы страниц браузера. 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 (и устаревший 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, как в пример чтения.
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; // \u0022doconut-client\u0022 по умолчанию
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отдельно. - Проверьте, открыв документ на одном узле и запросив позднюю страницу с другого.
Была ли эта страница полезной?