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

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

Коли кілька вузлів обслуговують одні й ті ж документи, вузол, який рендерить документ, не обов'язково є тим вузлом, який відповідає на запити сторінок браузера. 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 виводить весь документ перед поверненням. Щоб повернутися одразу після створення токену та дозволити розміщеному воркеру рендерити у ту ж папку, зареєструйте чергу 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:   'doconut',
    ResPath:    'doconut-res/images',
    retryOn409: true      // повторні спроби 202 (і застарілий 409) відповіді готовності
});

Клієнт, який не повторює спробу, показує пошкоджені плитки для сторінок, які ще рендеряться. Бюджет повторних спроб та його значення за замовчуванням (retryInitialDelayMs, retryBackoffFactor, retryMaxDelayMs, retryMaxAttempts, retryMaxTotalMs) задокументовані в КонфігураціяПереглядача.

Безпека між вузлами

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

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

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

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