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ć:

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

Wspó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:

csharp
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
LocationCloudLocation.FileShare dla udziału UNC/lokalnego
RootPathUdostępniony folder, do którego ma dostęp każdy węzeł
UsePerTokenSubfoldersPrzechowuj artefakty każdego dokumentu w jego własnym folderze {token} (domyślnie true)
ReadReadyPollMsJak 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ę:

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 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:

csharp
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:

csharp
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ę:

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);
    }
});

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:

javascript
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ł.

csharp
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:

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);

    // 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:

javascript
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:

text
bool CloseDistributedDocument(FileShareConfig fileShareConfig, string token)

Przekaż ten sam FileShareConfig, którym dokument został opublikowany.

Mapowanie ustawienie po ustawieniu

PoprzedniObecny
UseDoconutWebFarm(new WebFarmOptions { … })PublishAsync(...) po stronie zapisu plus UseDoconutCloud<FileShareCloudHandler>(...) po stronie odczytu
WebFarmOptions.PathFileShareConfig.RootPath
PageWaitTimeSeconds / StartWaitFromPagePublikowanie 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 / WebfarmPathWciąż obecne, zapisane jako IsWebFarm / WebFarmPath — nie potrzebne na ścieżce publikacji
Doconut.Configs.CloudDoconut.Clouds

Lista kontrolna

  1. Zbuduj FileShareConfig w jednym pomocniku, zarejestruj go raz i użyj z obu połówek.
  2. Wskaż RootPath na udział, którego już używasz.
  3. Publikuj przy użyciu PublishAsync(...); usuń wszystkie wywołania ExportToPng / ExportToCloud.
  4. Serwuj przy użyciu UseDoconutCloud<FileShareCloudHandler>(...) na gałęzi, którą wywołuje klient.
  5. W przypadku publikowania w tle włącz jednocześnie FirstPagePriority i retryOn409 oraz ustaw niezerowy ReadReadyPollMs po stronie odczytu.
  6. 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 dostarczaj UnsafeMode = true samodzielnie.
  7. Zweryfikuj, otwierając dokument na jednym węźle i żądając późniejszej strony z innego.

Czy ta strona była pomocna?