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). Verwenden Sie 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. 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öffentlichung aktivieren.
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 gemeinsam genutzte 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 einer Hintergrundveröffentlichung geschrieben wird; 0 (der Standard) prüft einmal. Sie hat keine Auswirkung auf synchron veröffentlichte Dokumente |
Schreibseite — 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, wenn 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 genau wie ein normales Viewer-Token an den Browser gesendet. In einem Farm-Setup gibt der Endpunkt außerdem ein signiertes Zugriffsticket zurück — siehe Sicherheit über Knoten hinweg.
Lese‑Seite — vom Share aus bereitstellen
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 nimmt den Provider als Typargument. Handler werden <Provider>CloudHandler — FileShareCloudHandler, AzureCloudHandler, AmazonS3CloudHandler, GoogleCloudHandler, DropBoxCloudHandler, RedisCloudHandler, FTPCloudHandler und CDNCloudHandler genannt. 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 vorhanden ist; 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 Sie die geteilte 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ücktreten 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 rendern. Es gilt nur für Hintergrundveröffentlichung in pro‑Token‑Ordnern (UsePerTokenSubfolders = true); das synchrone PublishAsync ignoriert es, weil sein Aufrufer ohnehin auf das gesamte Dokument wartet.
Damit wird das Warten zum Client verlagert, wo es begrenzt und sichtbar ist. Aktivieren Sie das erneute Versuchen 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 rendern. 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 geschieht 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 verifizieren kann. Vier Komponenten arbeiten zusammen.
1. Registrieren Sie die Ticket‑Sicherheit auf jedem Knoten. Tickets sind 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; // der Standard
});2. Überprüfen Sie Tickets auf der Leseseite. UseDoconutDistributedDocumentSecurity() kommt auf den Lesezweig vor UseDoconutCloud, 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, für ein anderes Token ausgestellt, abgelaufen, an ein anderes Browser‑Cookie gebunden oder an 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 Einzelknoten‑Bereitstellung und behandeln Sie es niemals 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)Verwenden Sie dasselbe FileShareConfig, mit dem das Dokument veröffentlicht wurde.
Checklist
- 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. - Diene mit
UseDoconutCloud<FileShareCloudHandler>(...)auf dem Zweig, den der Client aufruft. - Bei Hintergrundveröffentlichung aktiviere
FirstPagePriorityundretryOn409zusammen und gib der Leseseite ein von Null verschiedenesReadReadyPollMs. - 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 versendeUnsafeMode = truenicht allein. - Verifiziere, indem du ein Dokument auf einem Knoten öffnest und eine späte Seite von einem anderen anforderst.
War diese Seite hilfreich?