Распределённые развертывания
Обслуживание одного документа с нескольких узлов
Когда несколько узлов обслуживают одни и те же документы, узел, который рендерит документ, не обязательно является узлом, отвечающим на запросы страниц браузера. Этот релиз разделяет эту задачу на две явные части — write side, публикующую артефакты документа в общую память, и read side, обслуживающую их с любого узла.
Если ваше приложение сейчас вызывает UseDoconutWebFarm(...), эта страница является его заменой. Ни UseDoconutWebFarm, ни WebFarmOptions не существуют в этом релизе.
Ваша топология не меняется. Укажите общий корень на тот же UNC‑путь, который вы используете сегодня, и каждый узел продолжит работать так же, как сейчас. Изменяется лишь то, что публикация — это операция, которую вы вызываете, а не побочный эффект рендеринга.
Что заменило middleware web-farm
Раньше один middleware делал всё: он обслуживал предварительно отрендеренные изображения из общей папки и получал пока другой узел всё ещё записывает их. Ожидание было слепым бюджетом — «блокировать до трёх минут в надежде, что страница появится».
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. В предыдущей библиотеке они находились в Doconut.Configs.Cloud; имена классов не изменились.
| Свойство | Описание |
|---|---|
Location | CloudLocation.FileShare для UNC/локального общего доступа |
RootPath | Общая папка, доступная каждому узлу |
UsePerTokenSubfolders | Хранить артефакты каждого документа в собственной папке {token} (по умолчанию true) |
ReadReadyPollMs | Как долго read side ждёт страницу, которую фоновая публикация ещё записывает; 0 (по умолчанию) проверяет один раз. Не влияет на документы, публикуемые синхронно |
Write side — публикация документа
Внедрите 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. Токен передаётся браузеру точно так же, как обычный токен просмотрщика. В ферме конечная точка также возвращает подписанный билет доступа — см. Безопасность между узлами.
Этот один вызов заменяет предыдущую пару — открытие документа в локальной сессии и последующее выгрузку изображений на общий ресурс с помощью ExportToPng(sharedPath). ExportToPng и ExportToCloud здесь не имеют эквивалента.
Читательная сторона — обслуживать из общего доступа
Подмонтируйте обработчик FileShare на той же ветке, которую уже вызывает клиент, за проверкой билета:
var app = builder.Build();
app.UseDoconutResources();
app.MapWhen(
ctx => ctx.Request.Path.Value?.EndsWith("DocImage.axd", StringComparison.OrdinalIgnoreCase) == true,
branch =>
{
branch.UseDoconutDistributedDocumentSecurity(); // подписанные билеты — см. ниже
branch.UseDoconutCloud<FileShareCloudHandler>(options =>
{
options.Location = CloudLocation.FileShare;
options.CloudUploadConfig = app.Services.GetRequiredService<FileShareConfig>();
}, "/");
});UseDoconutCloud является обобщённым в этом выпуске: провайдер — это аргумент типа, а не значение Location, переключаемое внутри middleware. Обработчики называются <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: '/',
ResPath: 'doconut-res/images',
retryOn409: true // повторы 202 (и устаревший 409) ответы готовности
});Клиент, который не делает повторные попытки, показывает сломанные плитки для страниц, которые ещё рендерятся. Бюджет повторных попыток и его значения по умолчанию (retryInitialDelayMs, retryBackoffFactor, retryMaxDelayMs, retryMaxAttempts, retryMaxTotalMs) задокументированы в ViewerConfig.
Эта пара — фоновая публикация с FirstPagePriority, плюс опрос читательной стороны — заменяет предыдущие настройки PageWaitTimeSeconds и StartWaitFromPage. Ни одна из них больше не существует.
Безопасность между узлами
Токены, привязанные к сессии, предполагают, что обслуживающий узел видел запрос на открытие. В ферме это не так, поэтому проверка на уровне сессии отклоняла бы законные запросы; ферма поэтому устанавливает 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);
// Привяжите ticket к этому browser через cookie, который проверяет read side
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, с которым документ был опубликован.
Сопоставление настройки за настройкой
| Предыдущее | Сейчас |
|---|---|
UseDoconutWebFarm(new WebFarmOptions { … }) | PublishAsync(...) на стороне записи плюс UseDoconutCloud<FileShareCloudHandler>(...) на стороне чтения |
WebFarmOptions.Path | FileShareConfig.RootPath |
PageWaitTimeSeconds / StartWaitFromPage | Фоновая публикация с DistributedDocumentPublishOptions.FirstPagePriority, плюс FileShareConfig.ReadReadyPollMs |
viewer.OpenDocument(...) then viewer.ExportToPng(share) | один вызов PublishAsync(...) |
viewer.ExportToCloud(cloudConfig) | PublishAsync(...) с конфигурацией провайдера |
UseDoconutCloud(new CloudOptions { Location = … }) | UseDoconutCloud<THandler>(options => …, pathPrefix) |
DocOptions.IsWebfarm / WebfarmPath | Всё ещё присутствует, написано IsWebFarm / WebFarmPath — не требуется на пути публикации |
Doconut.Configs.Cloud | Doconut.Clouds |
Контрольный список
- Создайте
FileShareConfigв одном вспомогательном модуле, зарегистрируйте его один раз и используйте в обеих частях. - Укажите
RootPathна уже используемый вами ресурс. - Публикуйте с помощью
PublishAsync(...); удалите любые вызовыExportToPng/ExportToCloud. - Обслуживайте с помощью
UseDoconutCloud<FileShareCloudHandler>(...)на ветке, которую вызывает клиент. - При фоновой публикации включите одновременно
FirstPagePriorityиretryOn409, и задайте стороне чтения ненулевое значениеReadReadyPollMs. - Замените проверку на каждый сеанс подписанными билетами доступа — один кольцевой ключ Data Protection на каждом узле,
UseDoconutDistributedDocumentSecurity()на ветке чтения, билет от открытой конечной точки — и не распространяйтеUnsafeMode = trueотдельно. - Проверьте, открыв документ на одном узле и запросив позднюю страницу с другого.
Была ли эта страница полезной?