Rozproszone wdrożenia
Serwuj jeden dokument z kilku węzłów
Gdy kilka węzłów serwuje te same dokumenty, węzeł, który renderuje dokument, nie musi być tym, który odpowiada na żądania stron przeglądarki. To wydanie dzieli to zadanie na dwie wyraźne części — strona zapisu, która publikuje artefakty dokumentu w udostępnionym magazynie, oraz strona odczytu, która serwuje je z dowolnego węzła.
Jeśli Twoja aplikacja obecnie wywołuje UseDoconutWebFarm(...), ta strona jest jej zamiennikiem. Ani UseDoconutWebFarm, ani WebFarmOptions nie istnieją w tym wydaniu.
Twoja topologia się nie zmienia. Wskaż współdzielony katalog główny na tę samą ścieżkę UNC, której używasz dziś, i każdy węzeł będzie działał tak jak dotąd. Zmiana polega na tym, że publikowanie jest operacją, którą wywołujesz, zamiast skutkiem ubocznym renderowania.
Co zastąpiło middleware web-farm
Wcześniej jedno middleware robiło wszystko: serwowało wstępnie wyrenderowane obrazy z udostępnionego folderu i pollowało, podczas gdy inny węzeł nadal je zapisywał. Oczekiwanie było ślepym budżetem — „zablokuj do trzech minut, mając nadzieję, że strona się pojawi”.
Teraz to samo zadanie to dwa wywołania, które możesz zobaczyć i zrozumieć:
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 pageWspólna konfiguracja potrzebna obu częściom
Publisher zapisuje przy użyciu FileShareConfig, a obsługa odczytu serwuje przy użyciu jednego. Jeśli RootPath lub UsePerTokenSubfolders różnią się między sobą, drugi węzeł zwróci 404. Zbuduj konfigurację w dokładnie jednym miejscu i zarejestruj ją raz, aby obie części odczytywały ten sam obiekt:
var rootPath = builder.Configuration["Doconut:SharedRoot"]!; // np. \\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,
};
}Przekaż asyncPublish: true, gdy włączasz publikowanie w tle.
FileShareConfig znajduje się w Doconut.Clouds, razem z AzureConfig, AmazonConfig, GoogleCloudConfig, DropBoxConfig, RedisConfig, CDNConfig i FTPConfig. W poprzedniej bibliotece były one w Doconut.Configs.Cloud; nazwy klas nie uległy zmianie.
| Właściwość | Cel |
|---|---|
Location | CloudLocation.FileShare dla udziału UNC/lokalnego |
RootPath | Udostępniony folder, do którego ma dostęp każdy węzeł |
UsePerTokenSubfolders | Przechowuj artefakty każdego dokumentu w jego własnym folderze {token} (domyślnie true) |
ReadReadyPollMs | Jak długo strona odczytu czeka na stronę, którą publikowanie w tle nadal zapisuje; 0 (domyślnie) sprawdza raz. Nie ma wpływu na dokumenty publikowane synchronicznie |
Strona zapisu — publikowanie dokumentu
Wstrzyknij DistributedDocumentPublisher i publikuj zamiast otwierać lokalną sesję. Jedno wywołanie renderuje i zapisuje kompletny zestaw artefaktów — strony, informacje o dokumencie, indeks wyszukiwania i metadane — i zwraca, gdy zakończy się:
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 zawiera Token, ArtifactPath, TotalPages i Format. Token trafia do przeglądarki dokładnie tak, jak zwykły token przeglądarki. W farmie punkt końcowy również zwraca podpisany bilet dostępu — zobacz Bezpieczeństwo między węzłami.
To pojedyncze wywołanie zastępuje poprzednią parę — otwieranie dokumentu w lokalnej sesji i następnie zrzucanie obrazów na udział przy użyciu ExportToPng(sharedPath). ExportToPng i ExportToCloud nie mają tutaj odpowiednika.
Strona odczytu — serwowanie z udostępnienia
Zamontuj obsługę FileShare na tej samej gałęzi, którą klient już wywołuje, za kontrolą biletu:
var app = builder.Build();
app.UseDoconutResources();
app.MapWhen(
ctx => ctx.Request.Path.Value?.EndsWith("DocImage.axd", StringComparison.OrdinalIgnoreCase) == true,
branch =>
{
branch.UseDoconutDistributedDocumentSecurity(); // podpisane bilety — zobacz poniżej
branch.UseDoconutCloud<FileShareCloudHandler>(options =>
{
options.Location = CloudLocation.FileShare;
options.CloudUploadConfig = app.Services.GetRequiredService<FileShareConfig>();
}, "/");
});UseDoconutCloud jest generyczny w tej wersji: dostawca jest argumentem typu, a nie wartością Location przełączaną wewnątrz middleware. Obsługi mają nazwy <Provider>CloudHandler — FileShareCloudHandler, AzureCloudHandler, AmazonS3CloudHandler, GoogleCloudHandler, DropBoxCloudHandler, RedisCloudHandler, FTPCloudHandler i CDNCloudHandler. Z prefiksem ścieżki "/", obsługa odpowiada na każde żądanie, które dotrze do jej gałęzi.
Obsługa CDN jest tylko do odczytu — serwuje to, co już znajduje się w CDN; nie dokonuje przesyłania.
Opcjonalnie: publikowanie w tle
Domyślnie PublishAsync renderuje cały dokument przed zwróceniem. Aby zwrócić odpowiedź natychmiast po wygenerowaniu tokenu i pozwolić hostowanemu workerowi renderować do tego samego folderu, zarejestruj kolejkę opt‑in i zbuduj współdzieloną konfigurację przy użyciu asyncPublish: true:
builder.Services.AddDoconut(options => { /* … */ });
builder.Services.AddDoconutDistributedAsyncPublish();Bez tej rejestracji nic nie jest zarejestrowane i publikowanie pozostaje synchroniczne, dokładnie jak wcześniej.
Następnie wywołaj EnqueueAsync zamiast PublishAsync. (DistributedDocumentPublishOptions.Async jest tylko flagą, którą Twój własny kod może odczytać, aby wybrać jedną z dwóch ścieżek; wydawca ją ignoruje.) Kolejka ma ograniczenie: gdy jest nasycona, EnqueueAsync rzuca DistributedPublishQueueFullException. Odpowiedz na to przy użyciu 503 i nagłówka Retry-After, aby klienci odczekali zamiast zablokować się:
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);
}
});Strony, które nie zostały jeszcze zapisane: HTTP 202
Przy publikowaniu w tle żądanie strony może przyjść, zanim worker zapisze tę stronę. Strona odczytu czeka do ReadReadyPollMs, a następnie odpowiada HTTP 202 Accepted zamiast blokować żądanie.
FirstPagePriority = true skraca oczekiwanie na pierwsze wyświetlenie: strona 1 jest zapisywana najpierw w folderze dokumentu, więc dokument otwiera się, podczas gdy późniejsze strony nadal się renderują. Dotyczy to tylko publikowania w tle do folderów per‑token (UsePerTokenSubfolders = true); synchroniczny PublishAsync ignoruje to, ponieważ jego wywołujący czeka na cały dokument i tak.
To przenosi oczekiwanie na klienta, gdzie jest ograniczone i widoczne. Włącz ponawianie w widżecie:
const objViewer = $('#div_ctlDoc').docViewer({
BasePath: '/',
ResPath: 'doconut-res/images',
retryOn409: true // ponowne próby 202 (i starsze 409) odpowiedzi gotowości
});Klient, który nie ponawia, wyświetla uszkodzone kafelki dla stron, które nadal się renderują. Budżet ponowień i jego domyślne wartości (retryInitialDelayMs, retryBackoffFactor, retryMaxDelayMs, retryMaxAttempts, retryMaxTotalMs) są opisane w ViewerConfig.
Ta para — publikowanie w tle z FirstPagePriority, plus sondowanie po stronie odczytu — zastępuje poprzednie ustawienia PageWaitTimeSeconds i StartWaitFromPage. Żadne z nich już nie istnieje.
Bezpieczeństwo w różnych węzłach
Tokeny powiązane z sesją zakładają, że obsługujący węzeł zobaczył żądanie otwarcia. W farmie tak nie jest, więc sprawdzenie per‑sesja odrzuciłoby prawidłowe żądania; dlatego farma ustawia UnsafeMode = true.
UnsafeMode = true nie jest modelem bezpieczeństwa — jest usunięciem tego, które już nie ma zastosowania. Zastąp go podpisanymi biletami dostępu, które każdy węzeł może weryfikować niezależnie. Cztery elementy współpracują ze sobą.
1. Zarejestruj zabezpieczenia biletów na każdym węźle. Bilety są chronione przy użyciu ASP.NET Core Data Protection, więc każdy węzeł musi używać tego samego pierścienia kluczy i nazwy aplikacji; węzeł z innymi kluczami nie może odczytać biletu wydanego przez inny węzeł.
using Microsoft.AspNetCore.DataProtection;
builder.Services.AddDataProtection()
.PersistKeysToFileSystem(new DirectoryInfo(@"\\fileserver\doconut-keys")) // udostępniane przez każdy węzeł
.SetApplicationName("doconut-farm");
builder.Services.AddDoconut(options => options.UnsafeMode = true);
builder.Services.AddDoconutDistributedDocumentSecurity(options =>
{
options.TicketLifetimeMinutes = 60; // wartość domyślna
});2. Sprawdź bilety po stronie odczytu. UseDoconutDistributedDocumentSecurity() znajduje się w gałęzi odczytu przed UseDoconutCloud, jak w przykładzie po stronie odczytu.
3. Wystaw bilet, gdy dokument jest otwierany. Bilet zawiera nazwę tokenu, przeglądarki (poprzez ciasteczko, które porównuje strona odczytu) oraz zalogowanego użytkownika, jeśli istnieje:
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);
// Powiąż bilet z tą przeglądarką za pomocą ciasteczka, które sprawdza strona odczytująca
var cookieName = security.Value.BrowserCookieName; // "doconut-client" domyślnie
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. Przekaż oba do widżetu. Przeglądarka wysyła bilet jako access przy każdym żądaniu:
const resp = await fetch('/api/open?fileName=Sample.pdf', { method: 'POST' });
const { token, access } = await resp.json();
objViewer.View(token, access);Strona odczytu odrzuca żądanie, którego bilet jest brakujący, nieprawidłowy, wydany dla innego tokenu, wygasły, powiązany z innym ciasteczkiem przeglądarki lub wydany innemu zalogowanemu użytkownikowi. Odpowiada 403 — z obrazkiem błędu UnauthorizedMessage dla żądań stron i miniatur, w przeciwnym razie jako zwykły tekst. Przetestuj w prawdziwej przeglądarce lub kliencie, który zachowuje ciasteczka.
Nigdy nie przenoś UnsafeMode = true z powrotem do wdrożenia jednowęzłowego i nigdy nie traktuj go jako skrótu dla nieudanego sprawdzenia sesji na jednym węźle — tam właściwą poprawką jest AddSession() / UseSession(). Zobacz Sesje i bezpieczeństwo.
Zamykanie opublikowanego dokumentu
CloseDocument(token) w wstrzykniętym Viewer usuwa lokalną sesję. Aby usunąć opublikowane artefakty dokumentu z udostępnienia, wydawca udostępnia:
bool CloseDistributedDocument(FileShareConfig fileShareConfig, string token)Przekaż ten sam FileShareConfig, którym dokument został opublikowany.
Mapowanie ustawienie po ustawieniu
| Poprzedni | Obecny |
|---|---|
UseDoconutWebFarm(new WebFarmOptions { … }) | PublishAsync(...) po stronie zapisu plus UseDoconutCloud<FileShareCloudHandler>(...) po stronie odczytu |
WebFarmOptions.Path | FileShareConfig.RootPath |
PageWaitTimeSeconds / StartWaitFromPage | Publikowanie w tle z DistributedDocumentPublishOptions.FirstPagePriority, plus FileShareConfig.ReadReadyPollMs |
viewer.OpenDocument(...) następnie viewer.ExportToPng(share) | jedno wywołanie PublishAsync(...) |
viewer.ExportToCloud(cloudConfig) | PublishAsync(...) z konfiguracją dostawcy |
UseDoconutCloud(new CloudOptions { Location = … }) | UseDoconutCloud<THandler>(options => …, pathPrefix) |
DocOptions.IsWebfarm / WebfarmPath | Wciąż obecne, zapisane jako IsWebFarm / WebFarmPath — nie potrzebne na ścieżce publikacji |
Doconut.Configs.Cloud | Doconut.Clouds |
Lista kontrolna
- Zbuduj
FileShareConfigw jednym pomocniku, zarejestruj go raz i użyj z obu połówek. - Wskaż
RootPathna udział, którego już używasz. - Publikuj przy użyciu
PublishAsync(...); usuń wszystkie wywołaniaExportToPng/ExportToCloud. - Serwuj przy użyciu
UseDoconutCloud<FileShareCloudHandler>(...)na gałęzi, którą wywołuje klient. - W przypadku publikowania w tle włącz jednocześnie
FirstPagePriorityiretryOn409oraz ustaw niezerowyReadReadyPollMspo stronie odczytu. - Zastąp sprawdzanie per sesji podpisanymi biletami dostępu — jeden pierścień kluczy Data Protection na każdym węźle,
UseDoconutDistributedDocumentSecurity()na gałęzi odczytu, bilet z otwartego punktu końcowego — i nie dostarczajUnsafeMode = truesamodzielnie. - Zweryfikuj, otwierając dokument na jednym węźle i żądając późniejszej strony z innego.
Czy ta strona była pomocna?