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. Diese Version teilt diese Aufgabe in zwei explizite Hälften – eine Schreibseite, die die Artefakte eines Dokuments in gemeinsam genutzten Speicher veröffentlicht, und eine Leseseite, die sie von jedem Knoten aus bereitstellt.

Wenn Ihre Anwendung derzeit UseDoconutWebFarm(...) aufruft, ist diese Seite Ihr Ersatz. Weder UseDoconutWebFarm noch WebFarmOptions existieren in dieser Version.

Ihre Topologie ändert sich nicht. Zeigen Sie das gemeinsame Root auf denselben UNC-Pfad, den Sie heute verwenden, und jeder Knoten funktioniert weiterhin wie bisher. Was sich ändert, ist, dass das Veröffentlichen ein Aufruf ist, den Sie tätigen, anstatt einer Nebenwirkung des Renderns.

Was die Web-Farm-Middleware ersetzt hat

Früher erledigte eine Middleware alles: Sie stellte vorgerenderte Bilder aus einem gemeinsamen Ordner bereit und pollte, während ein anderer Knoten sie noch schrieb. Das Warten war ein blindes Budget – „bis zu drei Minuten blockieren in der Hoffnung, dass die Seite erscheint“.

Jetzt ist dieselbe Aufgabe in zwei Aufrufe aufgeteilt, die Sie sehen und nachvollziehen können:

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 gemeinsame 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, antwortet der andere Knoten mit 404. Erstellen Sie die Konfiguration an genau einer Stelle und registrieren Sie 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,
    };
}

Übergeben Sie asyncPublish: true, wenn Sie das Hintergrundveröffentlichen aktivieren.

FileShareConfig befindet sich in Doconut.Clouds, zusammen mit AzureConfig, AmazonConfig, GoogleCloudConfig, DropBoxConfig, RedisConfig, CDNConfig und FTPConfig. In der vorherigen Bibliothek waren diese in Doconut.Configs.Cloud; die Klassennamen haben sich nicht geändert.

EigenschaftZweck
LocationCloudLocation.FileShare für einen UNC-/lokalen Share
RootPathDer gemeinsame Ordner, den jeder Knoten erreichen kann
UsePerTokenSubfoldersBewahren Sie die Artefakte jedes Dokuments in seinem eigenen {token}-Ordner auf (Standard true)
ReadReadyPollMsWie lange die Leseseite auf eine Seite wartet, die noch von einem Hintergrundveröffentlichungsprozess geschrieben wird; 0 (der Standard) prüft einmal. Es hat keinen Einfluss auf synchron veröffentlichte Dokumente

Schreibseite – das Dokument veröffentlichen

Injizieren Sie DistributedDocumentPublisher und veröffentlichen Sie, anstatt eine lokale Sitzung zu öffnen. Ein Aufruf rendert und schreibt das komplette Satz von Artefakten – Seiten, Dokumentinformationen, Suchindex und Metadaten – und kehrt zurück, sobald er 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 wird an den Browser gesendet, genau wie ein normales Viewer-Token. In einer Farm gibt der Endpunkt außerdem ein signiertes Zugriffsticket zurück – siehe Sicherheit über Knoten hinweg.

Dieser einzelne Aufruf ersetzt das vorherige Paar – das Öffnen des Dokuments in einer lokalen Sitzung und anschließend das Ablegen von Bildern auf dem Share mit ExportToPng(sharedPath). ExportToPng und ExportToCloud haben hier kein Gegenstück.

Lese‑Seite — vom Share aus bereitstellen

Binde den FileShare‑Handler in denselben Branch ein, den der Client bereits aufruft, hinter der Ticket‑Prüfung:

csharp
var app = builder.Build();

app.UseDoconutResources();
app.MapWhen(
    ctx => ctx.Request.Path.Value?.EndsWith("DocImage.axd", StringComparison.OrdinalIgnoreCase) == true,
    branch =>
    {
        branch.UseDoconutDistributedDocumentSecurity();   // signierte Tickets — siehe unten
        branch.UseDoconutCloud<FileShareCloudHandler>(options =>
        {
            options.Location          = CloudLocation.FileShare;
            options.CloudUploadConfig = app.Services.GetRequiredService<FileShareConfig>();
        }, "/");
    });

UseDoconutCloud ist in dieser Version generisch: Der Provider ist das Typargument und nicht ein Location‑Wert, der innerhalb der Middleware umgeschaltet wird. 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 Branch erreicht.

Der CDN‑Handler ist read-only — 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ückzukehren, sobald das Token erstellt ist, und einen gehosteten Worker in denselben Ordner rendern zu lassen, registriere die Opt‑In‑Warteschlange und erstelle die geteilte Konfiguration mit asyncPublish: true:

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

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

Rufe dann EnqueueAsync anstelle von PublishAsync auf. (DistributedDocumentPublishOptions.Async ist nur ein Flag, das dein 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. Antworte darauf mit einem 503 und einem Retry-After‑Header, damit Clients zurückstecken 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 diese 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 zum Client verlagert, wo es begrenzt und sichtbar ist. Aktiviere das Wiederholen im Widget:

javascript
const objViewer = $('#div_ctlDoc').docViewer({
    BasePath:   '/',
    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.

Dieses Paar — Hintergrundveröffentlichung mit FirstPagePriority, plus die Lese‑Seiten‑Abfrage — ersetzt die vorherigen Einstellungen PageWaitTimeSeconds und StartWaitFromPage. Keine von beiden existiert noch.

Sicherheit über Knoten hinweg

Session‑gebundene Tokens gehen davon aus, dass der bedienende Knoten die Eröffnungsanfrage gesehen hat. In einem Farm‑Setup ist das nicht der Fall, sodass die pro‑Session‑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() wird im Lesezweig vor UseDoconutCloud eingefügt, wie im Beispiel für die Leseseite.

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 ist, für ein anderes Token ausgestellt wurde, abgelaufen ist, an ein anderes Browser‑Cookie gebunden ist oder an einen anderen angemeldeten Benutzer ausgestellt wurde. 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.

Verwenden Sie UnsafeMode = true niemals wieder in einer Einzelknoten‑Bereitstellung und behandeln Sie es nicht als Abkürzung für eine fehlgeschlagene Session‑Prü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)

Verwenden Sie dasselbe FileShareConfig, mit dem das Dokument veröffentlicht wurde.

Einstellung-für-Einstellung Zuordnung

VorherigeJetzt
UseDoconutWebFarm(new WebFarmOptions { … })PublishAsync(...) auf der Schreibseite plus UseDoconutCloud<FileShareCloudHandler>(...) auf der Leseseite
WebFarmOptions.PathFileShareConfig.RootPath
PageWaitTimeSeconds / StartWaitFromPageHintergrundveröffentlichung mit DistributedDocumentPublishOptions.FirstPagePriority, plus FileShareConfig.ReadReadyPollMs
viewer.OpenDocument(...) dann viewer.ExportToPng(share)ein PublishAsync(...) Aufruf
viewer.ExportToCloud(cloudConfig)PublishAsync(...) mit der Konfiguration des Anbieters
UseDoconutCloud(new CloudOptions { Location = … })UseDoconutCloud<THandler>(options => …, pathPrefix)
DocOptions.IsWebfarm / WebfarmPathNoch vorhanden, geschrieben IsWebFarm / WebFarmPath — nicht im Veröffentlichungsweg benötigt
Doconut.Configs.CloudDoconut.Clouds

Checkliste

  1. Erstelle das FileShareConfig in einem Helfer, registriere es einmal und verwende es von beiden Hälften aus.
  2. Richte RootPath auf die Freigabe, die du bereits nutzt, aus.
  3. Veröffentliche mit PublishAsync(...); lösche alle ExportToPng / ExportToCloud Aufrufe.
  4. Bediene mit UseDoconutCloud<FileShareCloudHandler>(...) auf dem Zweig, den der Client aufruft.
  5. Bei Hintergrundveröffentlichung schalte FirstPagePriority und retryOn409 zusammen ein und gib der Leseseite einen von Null verschiedenen ReadReadyPollMs.
  6. Ersetze die Sitzungsprüfung durch signierte Zugriffstickets — einen Data Protection-Schlüsselring auf jedem Knoten, UseDoconutDistributedDocumentSecurity() auf dem Lesezweig, ein Ticket vom offenen Endpunkt — und liefere UnsafeMode = true nicht allein aus.
  7. Verifiziere, indem du ein Dokument auf einem Knoten öffnest und von einem anderen einen späten Seitenaufruf anforderst.

War diese Seite hilfreich?