Розподілені розгортання

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

Коли кілька вузлів обслуговують одні й ті ж документи, вузол, який рендерить документ, не обов’язково є тим, що відповідає на запити браузера. Це випуск розділяє цю задачу на дві чіткі частини — частина запису, що публікує артефакти документа у спільне сховище, і частина читання, що обслуговує їх з будь‑якого вузла.

Якщо ваш застосунок зараз викликає UseDoconutWebFarm(...), ця сторінка є його заміною. Ні UseDoconutWebFarm, ні WebFarmOptions у цьому випуску не існують.

Ваша топологія не змінюється. Вкажіть спільний корінь на той самий UNC‑шлях, який ви використовуєте сьогодні, і кожен вузол продовжуватиме працювати так, як зараз. Змінюється лише те, що публікація стає операцією, яку ви викликаєте, а не побічним ефектом рендерингу.

Що замінило web‑farm проміжне ПЗ

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

Тепер те саме розділено на два виклики, які ви можете бачити і розуміти:

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Як довго частина читання чекає сторінку, яку фонове публікування ще записує; 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. Токен потрапляє в браузер точно так само, як звичайний токен переглядача. У фермі кінцева точка також повертає підписаний доступний квиток — див. Безпека між вузлами.

Цей один виклик замінює попередню пару — відкриття документа у локальну сесію та подальше вивантаження зображень у спільну папку за допомогою 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 є generic у цьому випуску: провайдер — це аргумент типу, а не значення Location, яке переключається всередині middleware. Обробники названі <Provider>CloudHandler — FileShareCloudHandler, AzureCloudHandler, AmazonS3CloudHandler, GoogleCloudHandler, DropBoxCloudHandler, RedisCloudHandler, FTPCloudHandler та CDNCloudHandler. З префіксом шляху "/", обробник відповідає на кожен запит, що досягає його гілки.

Обробник CDN є тільки для читання — він обслуговує те, що вже є на CDN; він не завантажує.

Необов’язково: публікація у фоні

За замовчуванням PublishAsync рендерить весь документ перед поверненням. Щоб повернути відповідь одразу після створення токену і дозволити розміщеному воркеру рендерити у ту ж папку, зареєструйте opt‑in чергу та створіть спільну конфігурацію за допомогою 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) задокументовані у КонфігураціяПереглядача.

Ця пара — фонова публікація з 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);

    // Прив'яжіть квиток до цього браузера через 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 для запитів сторінок та мініатюр, в іншому випадку простим текстом. Перевірте за допомогою реального браузера або клієнта, який зберігає cookie.

Ніколи не переносіть 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. Перевірте, відкривши документ на одному вузлі та запросивши пізню сторінку з іншого.

Чи була ця сторінка корисною?