Розподілені розгортання
Обслуговуйте один документ з кількох вузлів
Коли кілька вузлів обслуговують одні й ті ж документи, вузол, який рендерить документ, не обов'язково є тим вузлом, який відповідає на запити сторінок браузера. 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. Токен передається браузеру точно так само, як звичайний токен переглядача. У фермі кінцева точка також повертає підписаний квиток доступу — див. Безпека між вузлами.
Сторона читання — обслуговування з спільного ресурсу
Змонтуйте обробник 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 є тільки для читання — він обслуговує те, що вже є на 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 записується у папку документа першою, тому документ відкривається, поки інші сторінки ще рендеряться. Воно застосовується лише до фонової публікації у папки per-token (UsePerTokenSubfolders = true); синхронний PublishAsync ігнорує це, оскільки його викликаючий чекає на весь документ у будь‑якому випадку.
Це переносить очікування на клієнта, де воно обмежене та видиме. Увімкніть повторну спробу у віджеті:
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, тому кожен вузол повинен використовувати один і той же ключовий кільце та назву застосунку; вузол з іншими ключами не зможе прочитати квиток, виданий іншим вузлом.
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; // "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 з кожним запитом:
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, яким документ був опублікований.
Контрольний список
- Створіть
FileShareConfigв одному допоміжному модулі, зареєструйте його один раз і використовуйте з обох частин. - Вкажіть
RootPathна теку, до якої може дістатися кожен вузол. - Публікуйте за допомогою
PublishAsync(...), абоEnqueueAsync(...)з фоновою публікацією. - Обслуговуйте за допомогою
UseDoconutCloud<FileShareCloudHandler>(...)на гілці, яку викликає клієнт. - При фоновой публікації увімкніть одночасно
FirstPagePriorityіretryOn409, і задайте для читальної сторони ненульове значенняReadReadyPollMs. - Замініть перевірку на сеанс підписаними квитками доступу — один кільце ключів Data Protection на кожному вузлі,
UseDoconutDistributedDocumentSecurity()на гілці читання, квиток від відкритого кінцевого пункту — і не розповсюджуйтеUnsafeMode = trueокремо. - Перевірте, відкривши документ на одному вузлі та запросивши пізню сторінку з іншого.
Чи була ця сторінка корисною?