Розподілені розгортання
Обслуговуйте один документ з кількох вузлів
Коли кілька вузлів обслуговують одні й ті ж документи, вузол, який рендерить документ, не обов’язково є тим, що відповідає на запити сторінок браузера. Doconut розділяє цю задачу на дві чіткі частини — частина запису, що публікує артефакти документа у спільне сховище, і частина читання, що обслуговує їх з будь-якого вузла.
Одинокий вузол не потребує цього: звичайний шлях OpenDocumentAsync зберігає документ у пам’яті цього вузла і прив’язує його до сесії браузера (див. Сесії та безпека). Використовуйте цю сторінку, коли запити сторінок можуть потрапити на вузол, який ніколи не відкривав документ.
Як дві частини поєднуються
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. Створіть конфігурацію в одному місці та зареєструйте її один раз, щоб обидві частини читали один і той же об’єкт:
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.
| Властивість | Призначення |
|---|---|
Location | CloudLocation.FileShare для UNC/локального спільного ресурсу |
RootPath | Спільна папка, доступна всім вузлам |
UsePerTokenSubfolders | Зберігайте артефакти кожного документа у власній папці {token} (за замовчуванням true) |
ReadReadyPollMs | Як довго частина читання чекає на сторінку, яку фонове публікування ще записує; 0 (за замовчуванням) перевіряє один раз. Не впливає на документи, опубліковані синхронно |
Частина запису — публікація документа
Впровадьте DistributedDocumentPublisher і публікуйте замість відкриття локальної сесії. Один виклик рендерить і записує повний набір артефактів — сторінки, інформацію про документ, індекс пошуку та метадані — і повертається, коли завершено:
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' — за перевіркою квитка:
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:
builder.Services.AddDoconut(options => { /* … */ });
builder.Services.AddDoconutDistributedAsyncPublish();Без цієї реєстрації нічого не реєструється, і публікація залишається синхронною, точно як раніше.
Тоді викличте EnqueueAsync замість PublishAsync. (DistributedDocumentPublishOptions.Async — лише прапорець, який ваш код може прочитати, щоб вибрати між двома шляхами; видавець його ігнорує.) Черга має обмеження: коли вона переповнюється, EnqueueAsync викидає DistributedPublishQueueFullException. Відповідьте на це за допомогою 503 і заголовка Retry-After, щоб клієнти відступали, а не зависали:
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 ігнорує це, бо його викликатель чекає на весь документ у будь‑якому випадку.
Тим самим очікування переноситься до клієнта, де воно обмежене та видиме. Увімкніть повторні спроби у віджеті:
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, тому кожен вузол повинен використовувати один і той самий набір ключів та назву застосунку; вузол з іншими ключами не зможе прочитати квиток, виданий іншим вузлом.
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, який порівнює бік читання) та авторизованого користувача, якщо такий є:
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 з кожним запитом:
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 знищує локальний сеанс. Щоб видалити опубліковані артефакти документа з спільного ресурсу, видавець надає:
bool CloseDistributedDocument(FileShareConfig fileShareConfig, string token)Передайте той самий FileShareConfig, яким документ був опублікований.
Checklist
- Створіть
FileShareConfigв одному допоміжному модулі, зареєструйте його один раз і використовуйте з обох частин. - Вкажіть
RootPathна папку, до якої може дістатися кожен вузол. - Публікуйте за допомогою
PublishAsync(...), абоEnqueueAsync(...)з фонoвою публікацією. - Обслуговуйте за допомогою
UseDoconutCloud<FileShareCloudHandler>(...)на гілці, яку викликає клієнт. - При фонoвій публікації одночасно ввімкніть
FirstPagePriorityіretryOn409, і задайте читальній стороні ненульове значенняReadReadyPollMs. - Замініть перевірку на кожну сесію підписаними квитками доступу — один ключовий кільце Data Protection на кожному вузлі,
UseDoconutDistributedDocumentSecurity()на гілці читання, квиток від відкритого кінцевого пункту — і не розповсюджуйтеUnsafeMode = trueокремо. - Перевірте, відкривши документ на одному вузлі та запросивши пізню сторінку з іншого.
Чи була ця сторінка корисною?