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

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

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

Один отдельный узел не нуждается в этом: обычный путь OpenDocumentAsync хранит документ в памяти этого узла и привязывает его к сессии браузера (см. Сессии и безопасность). Используйте эту страницу, когда запросы страниц могут попадать на узел, который никогда не открывал документ.

Как две части сочетаются

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.

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

Сторона записи — публикация документа

Внедрите 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. Токен передаётся браузеру точно так же, как обычный токен просмотрщика. В ферме конечная точка также возвращает подписанный билет доступа — см. Безопасность между узлами.

Читательная сторона — обслуживать из общего доступа

Подмонтируйте обработчик FileShare на ветку, которую вызывает клиент — /doconut, соответствующую BasePath: 'doconut' — за проверкой билета:

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

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

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, как в примерe чтения.

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);

    // Привяжите билет к этому браузеру через 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 с каждым запросом:

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, с которым документ был опубликован.

Checklist

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

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