Rozproszone wdrożenia

Udostępnij jeden dokument z kilku węzłów

Gdy kilka węzłów udostępnia te same dokumenty, węzeł renderujący dokument nie musi być tym, który odpowiada na żądania stron przeglądarki. Doconut 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.

Pojedynczy węzeł nie potrzebuje tego wszystkiego: standardowa ścieżka OpenDocumentAsync utrzymuje dokument w pamięci tego węzła i wiąże go z sesją przeglądarki (zobacz Sesje i bezpieczeństwo). Użyj tej strony, gdy żądania stron mogą trafić na węzeł, który nigdy nie widział otwarcia.

Jak dwie części pasują do siebie

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ęści

Wydawca zapisuje przy użyciu FileShareConfig, a obsługa odczytu serwuje przy użyciu tego samego. Jeśli RootPath lub UsePerTokenSubfolders różnią się między nimi, 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łaściwośćCel
LocationCloudLocation.FileShare dla udziału UNC/lokalnego
RootPathWspólny folder dostępny dla każdego węzła
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 wynik po zakończeniu:

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 przenosi Token, ArtifactPath, TotalPages i Format. Token jest przekazywany 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.

Strona odczytu — serwowanie z udostępnienia

Zamontuj obsługę FileShare na gałęzi, którą wywołuje klient — /doconut, pasującej do BasePath: 'doconut' — za kontrolą biletu:

csharp
var app = builder.Build();

app.UseDoconutResources();
app.Map("/doconut", branch =>
{
    branch.UseDoconutDistributedDocumentSecurity();   // podpisane bilety — zobacz poniżej
    branch.UseDoconutCloud<FileShareCloudHandler>(options =>
    {
        options.Location          = CloudLocation.FileShare;
        options.CloudUploadConfig = app.Services.GetRequiredService<FileShareConfig>();
    }, "/");
});

UseDoconutCloud przyjmuje dostawcę jako argument typu. Obsługujące są nazwane <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ć w tym samym folderze, 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 rejestrowane i publikowanie pozostaje synchroniczne, dokładnie jak wcześniej.

Następnie wywołaj EnqueueAsync zamiast PublishAsync. (DistributedDocumentPublishOptions.Async jest jedynie flagą, którą Twój własny kod może odczytać, aby wybrać jedną z dwóch ścieżek; publikujący ją ignoruje.) Kolejka ma ograniczenie: gdy jest nasycona, EnqueueAsync rzuca DistributedPublishQueueFullException. Odpowiedz na to przy pomocy 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 jeszcze nie zostały 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 wciąż są renderowane. 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.

To przenosi oczekiwanie na klienta, gdzie jest ograniczone i widoczne. Włącz ponawianie w widżecie:

javascript
const objViewer = $('#div_ctlDoc').docViewer({
    BasePath:   'doconut',
    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 są renderowane. Budżet ponowień i jego domyślne wartości (retryInitialDelayMs, retryBackoffFactor, retryMaxDelayMs, retryMaxAttempts, retryMaxTotalMs) są opisane w ViewerConfig.

Bezpieczeństwo węzłów

Tokeny powiązane z sesją zakładają, że węzeł obsługujący widział żą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ółdziałają razem.

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 będzie w stanie 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. Sprawdzaj bilety po stronie odczytu. UseDoconutDistributedDocumentSecurity() umieszcza się w gałęzi odczytu przed UseDoconutCloud, jak w przykładzie po stronie odczytu.

3. Wydaj bilet, gdy dokument jest otwierany. Bilet zawiera nazwę tokenu, przeglądarkę (poprzez ciasteczko, które porównuje strona odczytu) oraz zalogowanego użytkownika, jeśli taki 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ą poprzez ciasteczko, 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 elementy do widżetu. Przeglądarka wysyła bilet jako access w 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 dla innego zalogowanego użytkownika. Odpowiada 403 — z obrazkiem błędu UnauthorizedMessage dla żądań stron i miniatur, w pozostałych przypadkach 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 nie traktuj go jako obejścia nieudanego sprawdzenia sesji na jednym węźle — w takim przypadku 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.

Lista kontrolna

  1. Zbuduj FileShareConfig w jednym pomocniku, zarejestruj go raz i użyj go z obu połówek.
  2. Wskaż RootPath na folder, do którego może dotrzeć każdy węzeł.
  3. Publikuj przy użyciu PublishAsync(...), lub EnqueueAsync(...) z publikacją w tle.
  4. Serwuj przy użyciu UseDoconutCloud<FileShareCloudHandler>(...) na gałęzi, którą wywołuje klient.
  5. Przy publikacji w tle włącz jednocześnie FirstPagePriority i retryOn409 oraz przyznaj stronie odczytu niezerowy ReadReadyPollMs.
  6. Zastąp sprawdzanie per sesji podpisanymi biletami dostępu — jednym pierścieniem kluczy Data Protection na każdym węźle, UseDoconutDistributedDocumentSecurity() na gałęzi odczytu, biletem 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?