Verteilte Bereitstellungen

Ein Dokument von mehreren Knoten aus bereitstellen

Wenn mehrere Knoten dieselben Dokumente bereitstellen, ist der Knoten, der ein Dokument rendert, nicht unbedingt der Knoten, der die Seitenanfragen des Browsers beantwortet. Doconut teilt diese Aufgabe in zwei explizite Hälften — eine Schreibseite, die die Artefakte eines Dokuments in den gemeinsamen Speicher veröffentlicht, und eine Leseseite, die sie von jedem Knoten aus bereitstellt.

Ein einzelner Knoten benötigt das nicht: Der normale OpenDocumentAsync‑Pfad hält das Dokument im Speicher dieses Knotens und bindet es an die Browsersitzung (siehe Sitzungen & Sicherheit). Verwende diese Seite, wenn Seitenanfragen auf einem Knoten landen können, der das Öffnen nie gesehen hat.

Wie die beiden Hälften zusammenpassen

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

Die gemeinsam genutzte Konfiguration, die beide Hälften benötigen

Der Publisher schreibt mit einem FileShareConfig und der Lese‑Handler dient mit einem. Wenn RootPath oder UsePerTokenSubfolders zwischen ihnen unterschiedlich sind, liefert der andere Knoten 404. Baue die Konfiguration an genau einer Stelle und registriere sie einmal, sodass beide Hälften dasselbe Objekt lesen:

csharp
var rootPath = builder.Configuration["Doconut:SharedRoot"]!;   // z. B. \\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,
    };
}

Übergebe asyncPublish: true, wenn du das Hintergrundveröffentlichen aktivierst.

FileShareConfig befindet sich in Doconut.Clouds, zusammen mit AzureConfig, AmazonConfig, GoogleCloudConfig, DropBoxConfig, RedisConfig, CDNConfig und FTPConfig.

EigenschaftZweck
LocationCloudLocation.FileShare für einen UNC-/lokalen Share
RootPathDer freigegebene Ordner, den jeder Knoten erreichen kann
UsePerTokenSubfoldersBewahre die Artefakte jedes Dokuments in seinem eigenen {token}‑Ordner auf (Standard true)
ReadReadyPollMsWie lange die Leseseite auf eine Seite wartet, die ein Hintergrundveröffentlichen noch schreibt; 0 (der Standard) prüft einmal. Hat keine Auswirkung auf synchron veröffentlichte Dokumente

Schreibseite — Dokument veröffentlichen

Injiziere DistributedDocumentPublisher und veröffentliche, anstatt eine lokale Sitzung zu öffnen. Ein Aufruf rendert und schreibt das komplette Artefakt‑Set — Seiten, Dokumentinformationen, Suchindex und Metadaten — und kehrt zurück, sobald es fertig ist:

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 trägt Token, ArtifactPath, TotalPages und Format. Das Token gelangt exakt wie ein normales Viewer‑Token zum Browser. In einer Farm gibt der Endpunkt außerdem ein signiertes Zugriffsticket zurück — siehe Sicherheit über Knoten hinweg.

Lese‑Seite — vom Share aus bedienen

Binden Sie den FileShare‑Handler an den Zweig, den der Client aufruft — /doconut, passend zu BasePath: 'doconut' — hinter der Ticket‑Prüfung:

csharp
var app = builder.Build();

app.UseDoconutResources();
app.Map("/doconut", branch =>
{
    branch.UseDoconutDistributedDocumentSecurity();   // signierte Tickets — siehe unten
    branch.UseDoconutCloud<FileShareCloudHandler>(options =>
    {
        options.Location          = CloudLocation.FileShare;
        options.CloudUploadConfig = app.Services.GetRequiredService<FileShareConfig>();
    }, "/");
});

UseDoconutCloud verwendet den Provider als Typ‑Argument. Die Handler heißen <Provider>CloudHandler — FileShareCloudHandler, AzureCloudHandler, AmazonS3CloudHandler, GoogleCloudHandler, DropBoxCloudHandler, RedisCloudHandler, FTPCloudHandler und CDNCloudHandler. Mit dem Pfadpräfix "/" beantwortet der Handler jede Anfrage, die seinen Zweig erreicht.

Der CDN‑Handler ist schreibgeschützt — er liefert, was bereits im CDN liegt; er lädt nichts hoch.

Optional: im Hintergrund veröffentlichen

Standardmäßig rendert PublishAsync das gesamte Dokument, bevor es zurückkehrt. Um sofort zurückzugeben, sobald das Token erstellt ist, und einen gehosteten Worker in denselben Ordner rendern zu lassen, registrieren Sie die Opt‑In‑Warteschlange und erstellen die gemeinsame Konfiguration mit asyncPublish: true:

csharp
builder.Services.AddDoconut(options => { /* … */ });
builder.Services.AddDoconutDistributedAsyncPublish();

Ohne diese Registrierung wird nichts registriert und das Veröffentlichen bleibt synchron, genau wie zuvor.

Rufen Sie dann EnqueueAsync anstelle von PublishAsync auf. (DistributedDocumentPublishOptions.Async ist nur ein Flag, das Ihr eigener Code lesen kann, um zwischen den beiden Pfaden zu wählen; der Publisher ignoriert es.) Die Warteschlange ist begrenzt: Wenn sie gesättigt ist, wirft EnqueueAsync DistributedPublishQueueFullException. Antworten Sie darauf mit einem 503 und einem Retry-After‑Header, damit Clients zurückziehen statt zu hängen:

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

Seiten, die noch nicht geschrieben sind: HTTP 202

Bei Hintergrundveröffentlichung kann eine Seitenanfrage eintreffen, bevor der Worker die Seite geschrieben hat. Die Lese‑Seite wartet bis zu ReadReadyPollMs und antwortet dann mit HTTP 202 Accepted, anstatt die Anfrage zu blockieren.

FirstPagePriority = true verkürzt die Wartezeit für die erste Ansicht: Seite 1 wird zuerst in den Ordner des Dokuments geschrieben, sodass das Dokument geöffnet wird, während spätere Seiten noch gerendert werden. Es gilt nur für Hintergrundveröffentlichung in pro‑Token‑Ordnern (UsePerTokenSubfolders = true); der synchrone PublishAsync ignoriert es, weil sein Aufrufer sowieso auf das gesamte Dokument wartet.

Damit wird das Warten auf den Client verlagert, wo es begrenzt und sichtbar ist. Aktivieren Sie das Wiederholen im Widget:

javascript
const objViewer = $('#div_ctlDoc').docViewer({
    BasePath:   'doconut',
    ResPath:    'doconut-res/images',
    retryOn409: true      // Wiederholungen 202 (und Legacy 409) Bereitschaftsantworten
});

Ein Client, der nicht erneut versucht, zeigt fehlerhafte Kacheln für Seiten, die noch gerendert werden. Das Wiederholungsbudget und seine Vorgaben (retryInitialDelayMs, retryBackoffFactor, retryMaxDelayMs, retryMaxAttempts, retryMaxTotalMs) sind dokumentiert in ViewerConfig.

Sicherheit über Knoten hinweg

Sitzungsgebundene Tokens gehen davon aus, dass der bedienende Knoten die Eröffnungsanfrage gesehen hat. In einem Farm tut er das nicht, sodass die pro‑Sitzungs‑Prüfung legitime Anfragen ablehnen würde; ein Farm setzt daher UnsafeMode = true.

UnsafeMode = true ist nicht das Sicherheitsmodell — es ist die Entfernung eines Modells, das nicht mehr gilt. Ersetzen Sie es durch signierte Zugriffstickets, die jeder Knoten unabhängig prüfen kann. Vier Komponenten arbeiten zusammen.

1. Registrieren Sie die Ticket‑Sicherheit auf jedem Knoten. Tickets werden mit ASP.NET Core Data Protection geschützt, sodass jeder Knoten denselben Schlüsselring und Anwendungsnamen verwenden muss; ein Knoten mit anderen Schlüsseln kann ein von einem anderen Knoten ausgestelltes Ticket nicht lesen.

csharp
using Microsoft.AspNetCore.DataProtection;

builder.Services.AddDataProtection()
    .PersistKeysToFileSystem(new DirectoryInfo(@"\\fileserver\doconut-keys"))   // von jedem Knoten gemeinsam genutzt
    .SetApplicationName("doconut-farm");

builder.Services.AddDoconut(options => options.UnsafeMode = true);
builder.Services.AddDoconutDistributedDocumentSecurity(options =>
{
    options.TicketLifetimeMinutes = 60;   // Standard
});

2. Überprüfen Sie Tickets auf der Leseseite. UseDoconutDistributedDocumentSecurity() kommt auf den Lesezweig vor UseDoconutCloud, wie im das Read‑Side‑Beispiel.

3. Stellen Sie ein Ticket aus, wenn das Dokument geöffnet wird. Das Ticket benennt das Token, den Browser (über ein Cookie, das die Leseseite vergleicht) und den angemeldeten Benutzer, falls vorhanden:

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

    // Binde das Ticket an diesen Browser über das Cookie, das die Leseseite prüft.
    var cookieName = security.Value.BrowserCookieName;   // "doconut-client" standardmäßig
    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. Übergeben Sie beide an das Widget. Der Viewer sendet das Ticket als access mit jeder Anfrage:

javascript
const resp = await fetch('/api/open?fileName=Sample.pdf', { method: 'POST' });
const { token, access } = await resp.json();
objViewer.View(token, access);

Die Leseseite verweigert eine Anfrage, deren Ticket fehlt, ungültig, für ein anderes Token ausgestellt, abgelaufen, an ein anderes Browser‑Cookie gebunden oder für einen anderen angemeldeten Benutzer ausgestellt ist. Sie antwortet mit 403 — mit dem UnauthorizedMessage Fehlermotiv für Seiten‑ und Thumbnail‑Anfragen, sonst als Klartext. Testen Sie mit einem echten Browser oder einem Client, der Cookies speichert.

Tragen Sie UnsafeMode = true niemals zurück in eine Single‑Node‑Bereitstellung und behandeln Sie es nicht als Abkürzung für eine fehlgeschlagene Sitzungsprüfung auf einem Knoten — dort ist die korrekte Lösung AddSession() / UseSession(). Siehe Sitzungen & Sicherheit.

Schließen eines veröffentlichten Dokuments

CloseDocument(token) auf dem injizierten Viewer beendet eine lokale Sitzung. Um die veröffentlichten Artefakte eines Dokuments aus dem Share zu entfernen, stellt der Publisher bereit:

text
bool CloseDistributedDocument(FileShareConfig fileShareConfig, string token)

Übergeben Sie das gleiche FileShareConfig, mit dem das Dokument veröffentlicht wurde.

Checkliste

  1. Erstelle das FileShareConfig in einem Helfer, registriere es einmal und verwende es von beiden Hälften.
  2. Zeige RootPath auf einen Ordner, den jeder Knoten erreichen kann.
  3. Veröffentliche mit PublishAsync(...), oder EnqueueAsync(...) mit Hintergrundveröffentlichung.
  4. Bediene mit UseDoconutCloud<FileShareCloudHandler>(...) auf dem Zweig, den der Client aufruft.
  5. Bei Hintergrundveröffentlichung aktiviere FirstPagePriority und retryOn409 zusammen und gib der Leseseite einen von Null verschiedenen ReadReadyPollMs.
  6. Ersetze die per‑Session‑Prüfung durch signierte Zugriffstickets — einen Data‑Protection‑Schlüsselring auf jedem Knoten, UseDoconutDistributedDocumentSecurity() auf dem Lesezweig, ein Ticket vom offenen Endpunkt — und versende UnsafeMode = true nicht allein.
  7. Verifiziere, indem du ein Dokument auf einem Knoten öffnest und von einem anderen eine späte Seite anforderst.

War diese Seite hilfreich?