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

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

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

Сторона читання — обслуговування з share

Змонтуйте обробник 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 є read-only — він обслуговує те, що вже знаходиться на 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 спочатку записується у папку документа, тому документ відкривається, поки інші сторінки ще рендеряться. Це застосовується лише до фонового публікування у папки за токеном (UsePerTokenSubfolders = true); синхронний PublishAsync ігнорує це, бо його викликатель чекає на весь документ у будь‑якому випадку.

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

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

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;   // \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 з кожним запитом:

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

Checklist

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

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