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
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 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:
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.
| Eigenschaft | Zweck |
|---|---|
Location | CloudLocation.FileShare für einen UNC-/lokalen Share |
RootPath | Der freigegebene Ordner, den jeder Knoten erreichen kann |
UsePerTokenSubfolders | Bewahre die Artefakte jedes Dokuments in seinem eigenen {token}‑Ordner auf (Standard true) |
ReadReadyPollMs | Wie 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:
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:
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:
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:
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:
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.
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:
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, 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:
bool CloseDistributedDocument(FileShareConfig fileShareConfig, string token)Übergeben Sie das gleiche FileShareConfig, mit dem das Dokument veröffentlicht wurde.
Checkliste
- Erstelle das
FileShareConfigin einem Helfer, registriere es einmal und verwende es von beiden Hälften. - Zeige
RootPathauf einen Ordner, den jeder Knoten erreichen kann. - Veröffentliche mit
PublishAsync(...), oderEnqueueAsync(...)mit Hintergrundveröffentlichung. - Bediene mit
UseDoconutCloud<FileShareCloudHandler>(...)auf dem Zweig, den der Client aufruft. - Bei Hintergrundveröffentlichung aktiviere
FirstPagePriorityundretryOn409zusammen und gib der Leseseite einen von Null verschiedenenReadReadyPollMs. - 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 versendeUnsafeMode = truenicht allein. - Verifiziere, indem du ein Dokument auf einem Knoten öffnest und von einem anderen eine späte Seite anforderst.
War diese Seite hilfreich?