Rozproszone wdrożenia

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

Kiedy kilka węzłów udostępnia te same dokumenty, węzeł, który renderuje dokument, nie musi być tym węzłem, który odpowiada na żądania stron przeglądarki. Doconut dzieli to zadanie na dwie wyraźne części — write side, który publikuje artefakty dokumentu w udostępnionym magazynie, oraz read side, który udostępnia 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ą

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 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ł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 read side czeka na stronę, którą publikacja 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 trafia do przeglądarki dokładnie tak, jak normalny 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 — serwuj z udostępnienia

Zamontuj obsługę FileShare na gałęzi wywoływanej przez klienta — /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ługi 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: publikuj w tle

Domyślnie PublishAsync renderuje cały dokument przed zwróceniem. Aby zwrócić natychmiast po wygenerowaniu tokenu i pozwolić hostowanemu workerowi renderować do tego samego folderu, zarejestruj kolejkę opt‑in i zbuduj współdzieloną konfigurację z 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 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 jest ograniczona: gdy jest nasycona, EnqueueAsync rzuca DistributedPublishQueueFullException. Odpowiedz na to za pomocą 503 i nagłówka Retry-After, aby klienci odczekali zamiast zaciąć 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ąż 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.

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, pokazuje uszkodzone kafelki dla stron, które wciąż się renderują. Budżet ponowień i jego domyślne wartości (retryInitialDelayMs, retryBackoffFactor, retryMaxDelayMs, retryMaxAttempts, retryMaxTotalMs) są udokumentowane w KonfiguracjaPodglądu.

Bezpieczeństwo pomiędzy węzłami

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ółdziałają.

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 zostaje otwarty. 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ą 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 do widżetu. Podgląd 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, wystawiony dla innego tokenu, wygasły, powiązany z innym ciasteczkiem przeglądarki lub wystawiony dla innego zalogowanego użytkownika. Odpowiada 403 — z obrazkiem błędu UnauthorizedMessage dla żądań stron i miniatur, w przeciwnym razie jako zwykły tekst. Przetestuj to 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 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) na 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żywaj z obu połówek.
  2. Wskaż RootPath na folder, do którego każdy węzeł ma dostęp.
  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 FirstPagePriority i retryOn409 jednocześnie oraz ustaw niezerowy ReadReadyPollMs po stronie odczytu.
  6. Zastąp sprawdzanie per‑sesja 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 wysyłaj 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?