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:
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 pageDie 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:
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.
| Eigenschaft | Zweck |
|---|---|
Location | CloudLocation.FileShare für einen UNC-/lokalen Share |
RootPath | Der gemeinsame Ordner, den jeder Knoten erreichen kann |
UsePerTokenSubfolders | Bewahren Sie die Artefakte jedes Dokuments in seinem eigenen {token}-Ordner auf (Standard true) |
ReadReadyPollMs | Wie 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:
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:
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:
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:
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:
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.
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:
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:
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:
bool CloseDistributedDocument(FileShareConfig fileShareConfig, string token)Verwenden Sie dasselbe FileShareConfig, mit dem das Dokument veröffentlicht wurde.
Einstellung-für-Einstellung Zuordnung
| Vorherige | Jetzt |
|---|---|
UseDoconutWebFarm(new WebFarmOptions { … }) | PublishAsync(...) auf der Schreibseite plus UseDoconutCloud<FileShareCloudHandler>(...) auf der Leseseite |
WebFarmOptions.Path | FileShareConfig.RootPath |
PageWaitTimeSeconds / StartWaitFromPage | Hintergrundverö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 / WebfarmPath | Noch vorhanden, geschrieben IsWebFarm / WebFarmPath — nicht im Veröffentlichungsweg benötigt |
Doconut.Configs.Cloud | Doconut.Clouds |
Checkliste
- Erstelle das
FileShareConfigin einem Helfer, registriere es einmal und verwende es von beiden Hälften aus. - Richte
RootPathauf die Freigabe, die du bereits nutzt, aus. - Veröffentliche mit
PublishAsync(...); lösche alleExportToPng/ExportToCloudAufrufe. - Bediene mit
UseDoconutCloud<FileShareCloudHandler>(...)auf dem Zweig, den der Client aufruft. - Bei Hintergrundveröffentlichung schalte
FirstPagePriorityundretryOn409zusammen ein und gib der Leseseite einen von Null verschiedenenReadReadyPollMs. - 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 liefereUnsafeMode = truenicht allein aus. - Verifiziere, indem du ein Dokument auf einem Knoten öffnest und von einem anderen einen späten Seitenaufruf anforderst.
War diese Seite hilfreich?