Распределённые развертывания

Обслуживание одного документа с нескольких узлов

Когда несколько узлов обслуживают одни и те же документы, узел, который рендерит документ, не обязательно является узлом, отвечающим на запросы страниц браузера. Этот релиз разделяет эту задачу на две явные части — write side, публикующую артефакты документа в общую память, и read side, обслуживающую их с любого узла.

Если ваше приложение сейчас вызывает UseDoconutWebFarm(...), эта страница является его заменой. Ни UseDoconutWebFarm, ни WebFarmOptions не существуют в этом релизе.

Ваша топология не меняется. Укажите общий корень на тот же UNC‑путь, который вы используете сегодня, и каждый узел продолжит работать так же, как сейчас. Изменяется лишь то, что публикация — это операция, которую вы вызываете, а не побочный эффект рендеринга.

Что заменило middleware web-farm

Раньше один middleware делал всё: он обслуживал предварительно отрендеренные изображения из общей папки и получал пока другой узел всё ещё записывает их. Ожидание было слепым бюджетом — «блокировать до трёх минут в надежде, что страница появится».

text
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. Сформируйте конфигурацию в одном месте и зарегистрируйте её один раз, чтобы обе части читали один и тот же объект:

csharp
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; имена классов не изменились.

СвойствоОписание
LocationCloudLocation.FileShare для UNC/локального общего доступа
RootPathОбщая папка, доступная каждому узлу
UsePerTokenSubfoldersХранить артефакты каждого документа в собственной папке {token} (по умолчанию true)
ReadReadyPollMsКак долго read side ждёт страницу, которую фоновая публикация ещё записывает; 0 (по умолчанию) проверяет один раз. Не влияет на документы, публикуемые синхронно

Write side — публикация документа

Внедрите DistributedDocumentPublisher и публикуйте вместо открытия локальной сессии. Один вызов рендерит и записывает полный набор артефактов — страницы, информацию о документе, поисковый индекс и метаданные — и возвращается, когда завершён:

csharp
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 на той же ветке, которую уже вызывает клиент, за проверкой билета:

csharp
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:

csharp
builder.Services.AddDoconut(options => { /* … */ });
builder.Services.AddDoconutDistributedAsyncPublish();

Без этой регистрации ничего не регистрируется, и публикация остаётся синхронной, точно как и раньше.

Затем вызывайте EnqueueAsync вместо PublishAsync. (DistributedDocumentPublishOptions.Async — это лишь флаг, который ваш собственный код может читать, чтобы выбрать один из двух путей; издатель игнорирует его.) Очередь ограничена: когда она переполняется, EnqueueAsync бросает DistributedPublishQueueFullException. Ответьте на неё с помощью 503 и заголовка Retry-After, чтобы клиенты отступали, а не зависали:

csharp
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 игнорирует это, потому что его вызывающий ждёт весь документ в любом случае.

Это переносит ожидание на клиент, где оно ограничено и видно. Включите повторные попытки в виджете:

javascript
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, поэтому каждый узел должен использовать один и тот же набор ключей и имя приложения; узел с другими ключами не сможет прочитать билет, выданный другим узлом.

csharp
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, который сравнивает сторона чтения) и авторизованного пользователя, если он есть:

csharp
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 с каждым запросом:

javascript
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 завершает локальную сессию. Чтобы удалить опубликованные артефакты документа из общего доступа, издатель предоставляет:

text
bool CloseDistributedDocument(FileShareConfig fileShareConfig, string token)

Передайте тот же FileShareConfig, с которым документ был опубликован.

Сопоставление настройки за настройкой

ПредыдущееСейчас
UseDoconutWebFarm(new WebFarmOptions { … })PublishAsync(...) на стороне записи плюс UseDoconutCloud<FileShareCloudHandler>(...) на стороне чтения
WebFarmOptions.PathFileShareConfig.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.CloudDoconut.Clouds

Контрольный список

  1. Создайте FileShareConfig в одном вспомогательном модуле, зарегистрируйте его один раз и используйте в обеих частях.
  2. Укажите RootPath на уже используемый вами ресурс.
  3. Публикуйте с помощью PublishAsync(...); удалите любые вызовы ExportToPng / ExportToCloud.
  4. Обслуживайте с помощью UseDoconutCloud<FileShareCloudHandler>(...) на ветке, которую вызывает клиент.
  5. При фоновой публикации включите одновременно FirstPagePriority и retryOn409, и задайте стороне чтения ненулевое значение ReadReadyPollMs.
  6. Замените проверку на каждый сеанс подписанными билетами доступа — один кольцевой ключ Data Protection на каждом узле, UseDoconutDistributedDocumentSecurity() на ветке чтения, билет от открытой конечной точки — и не распространяйте UnsafeMode = true отдельно.
  7. Проверьте, открыв документ на одном узле и запросив позднюю страницу с другого.

Была ли эта страница полезной?