Dağıtılmış Dağıtımlar
Bir belgeyi birden fazla düğümden sun
When several nodes serve the same documents, the node that renders a document is not necessarily the node that answers the browser's page requests. Doconut splits that job into two explicit halves — a write side that publishes a document's artifacts into shared storage, and a read side that serves them from any node.
A single node does not need any of this: the normal OpenDocumentAsync path keeps the document in that node's memory and binds it to the browser session (see Oturumlar ve Güvenlik). Use this page when page requests can land on a node that never saw the open.
İki yarının nasıl birleştirildiği
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 pageHer iki yarının da ihtiyaç duyduğu ortak yapılandırma
The publisher writes with a FileShareConfig and the read handler serves with one. If RootPath or UsePerTokenSubfolders differ between them, the other node answers 404. Build the config in exactly one place and register it once, so both halves read the same object:
var rootPath = builder.Configuration["Doconut:SharedRoot"]!; // örnek olarak \\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,
};
}Pass asyncPublish: true when you turn on arka plan yayınlama.
FileShareConfig lives in Doconut.Clouds, together with AzureConfig, AmazonConfig, GoogleCloudConfig, DropBoxConfig, RedisConfig, CDNConfig, and FTPConfig.
| Özellik | Amaç |
|---|---|
Location | CloudLocation.FileShare bir UNC/yerel paylaşım için |
RootPath | Her düğümün erişebileceği ortak klasör |
UsePerTokenSubfolders | Her belgenin artefaktlarını kendi {token} klasöründe tut (varsayılan true) |
ReadReadyPollMs | Arka plan yayını hâlâ yazarken bir sayfanın ne kadar süre bekleyeceği; 0 (varsayılan) bir kez kontrol eder. Senkron olarak yayınlanan belgeler üzerinde etkisi yoktur |
Write side — belgeyi yayınla
Inject DistributedDocumentPublisher and publish instead of opening a local session. One call renders and writes the complete artifact set — pages, document info, search index, and metadata — and returns when it is done:
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, Token, ArtifactPath, TotalPages ve Format taşır. Token, normal bir görüntüleyici tokeni gibi tarayıcıya tam olarak gönderilir. Bir çiftlikte, uç nokta ayrıca imzalı bir erişim bileti döndürür — see Düğümler arası Güvenlik.
Okuma tarafı — paylaşımdan hizmet ver
İstemcinin çağırdığı dalda FileShare işleyicisini bağlayın — /doconut, BasePath: 'doconut' ile eşleşen — bilet kontrolünün arkasında:
var app = builder.Build();
app.UseDoconutResources();
app.Map("/doconut", branch =>
{
branch.UseDoconutDistributedDocumentSecurity(); // imzalı biletler — aşağıya bakın
branch.UseDoconutCloud<FileShareCloudHandler>(options =>
{
options.Location = CloudLocation.FileShare;
options.CloudUploadConfig = app.Services.GetRequiredService<FileShareConfig>();
}, "/");
});UseDoconutCloud sağlayıcıyı tip argümanı olarak alır. İşleyicilerin adları <Provider>CloudHandler — FileShareCloudHandler, AzureCloudHandler, AmazonS3CloudHandler, GoogleCloudHandler, DropBoxCloudHandler, RedisCloudHandler, FTPCloudHandler ve CDNCloudHandler. "/" yol önekiyle, işleyici dalına ulaşan her isteğe yanıt verir.
CDN işleyicisi yalnızca-okunur — CDN'de zaten bulunanı hizmet verir; yükleme yapmaz.
İsteğe Bağlı: arka planda yayınla
Varsayılan olarak PublishAsync, döndürmeden önce tüm belgeyi oluşturur. Token oluşturulduğu anda döndürmek ve barındırılan bir işçinin aynı klasöre render etmesine izin vermek için, isteğe bağlı kuyruğu kaydedin ve asyncPublish: true ile paylaşılan yapılandırmayı oluşturun:
builder.Services.AddDoconut(options => { /* … */ });
builder.Services.AddDoconutDistributedAsyncPublish();Bu kayıt olmadan hiçbir şey kaydedilmez ve yayınlama, daha önceki gibi senkron kalır.
Ardından PublishAsync yerine EnqueueAsync çağırın. (DistributedDocumentPublishOptions.Async yalnızca kendi kodunuzun iki yol arasında seçim yapabilmesi için okuyabileceği bir bayraktır; yayıncı bunu görmez.) Kuyruk sınırlıdır: dolduğunda, EnqueueAsync DistributedPublishQueueFullException fırlatır. Bunu bir 503 ve bir Retry-After başlığıyla yanıtlayın, böylece istemciler durmak yerine geri çekilir:
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);
}
});Henüz yazılmamış sayfalar: HTTP 202
Arka plan yayınlamasıyla, bir sayfa isteği işçi o sayfayı yazmadan önce gelebilir. Okuma tarafı ReadReadyPollMs kadar bekler ve ardından isteği engellemek yerine HTTP 202 Accepted yanıtını verir.
FirstPagePriority = true ilk görüntüleme için beklemeyi kısaltır: sayfa 1 önce belgenin klasörüne yazılır, böylece belge daha sonraki sayfalar hâlâ render olurken açılır. Bu yalnızca per-token klasörlerine arka plan yayınlaması için geçerlidir (UsePerTokenSubfolders = true); senkron PublishAsync bunu görmez, çünkü çağıranı zaten tüm belgeyi bekler.
Bu beklemeyi istemciye taşır, burada sınırlı ve görünürdür. Widget'ta yeniden denemeyi etkinleştirin:
const objViewer = $('#div_ctlDoc').docViewer({
BasePath: 'doconut',
ResPath: 'doconut-res/images',
retryOn409: true // 202 yeniden denemeler (ve eski 409) hazırlık yanıtları
});Yeniden denemeyen bir istemci, hâlâ render olan sayfalar için kırık döşemeler gösterir. Yeniden deneme bütçesi ve varsayılanları (retryInitialDelayMs, retryBackoffFactor, retryMaxDelayMs, retryMaxAttempts, retryMaxTotalMs), GörüntüleyiciYapılandırması içinde belgelenmiştir.
Düğümler arası güvenlik
Oturuma bağlı tokenlar, hizmet veren düğümün açılış isteğini gördüğünü varsayar. Bir çiftlikte bu gerçekleşmez, bu yüzden oturum başına kontrol, geçerli istekleri reddeder; bir çiftlik bu nedenle UnsafeMode = true ayarlar.
UnsafeMode = true güvenlik modeli değildir — artık geçerli olmayan bir modelin kaldırılmasıdır. Bunu imzalı erişim biletleriyle değiştirin, her düğüm bunları bağımsız olarak doğrulayabilir. Dört parça birlikte çalışır.
1. Her düğümde bilet güvenliğini kaydedin. Biletler ASP.NET Core Data Protection ile korunur, bu yüzden her düğüm aynı anahtar halkasını ve uygulama adını kullanmalıdır; farklı anahtarlara sahip bir düğüm, başka bir düğümün oluşturduğu bileti okuyamaz.
using Microsoft.AspNetCore.DataProtection;
builder.Services.AddDataProtection()
.PersistKeysToFileSystem(new DirectoryInfo(@"\\fileserver\doconut-keys")) // her düğüm tarafından paylaşılan
.SetApplicationName("doconut-farm");
builder.Services.AddDoconut(options => options.UnsafeMode = true);
builder.Services.AddDoconutDistributedDocumentSecurity(options =>
{
options.TicketLifetimeMinutes = 60; // varsayılan
});2. Okuma tarafında biletleri kontrol edin. UseDoconutDistributedDocumentSecurity(), UseDoconutCloud'den önce okuma dalına eklenir, okuma tarafı örneği olduğu gibi.
3. Belge açıldığında bir bilet oluşturun. Bilet, tokenı, tarayıcıyı (okuma tarafının karşılaştırdığı bir çerez aracılığıyla) ve varsa oturum açmış kullanıcıyı adlandırır:
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);
// Bileti, okuma tarafının kontrol ettiği çerez aracılığıyla bu tarayıcıya bağlayın.
var cookieName = security.Value.BrowserCookieName; // "doconut-client" varsayılan olarak
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. İkisini de widget'a geçirin. Görüntüleyici, her istekle birlikte bileti access olarak gönderir:
const resp = await fetch('/api/open?fileName=Sample.pdf', { method: 'POST' });
const { token, access } = await resp.json();
objViewer.View(token, access);Okuma tarafı, bileti eksik, geçersiz, başka bir token için oluşturulmuş, süresi dolmuş, başka bir tarayıcı çerezine bağlı veya başka bir oturum açmış kullanıcıya ait olan istekleri reddeder. 403 yanıtını verir — sayfa ve küçük resim istekleri için UnauthorizedMessage hata resmiyle, aksi takdirde düz metin olarak. Gerçek bir tarayıcı veya çerezleri tutan bir istemciyle test edin.
UnsafeMode = true'yi tek düğümlü bir dağıtıma geri getirmeyin ve onu bir düğümde başarısız oturum kontrolü için bir kısayol olarak kullanmayın — burada doğru düzeltme AddSession() / UseSession()'dir. Bakınız Oturumlar ve Güvenlik.
Yayınlanmış bir belgeyi kapatma
CloseDocument(token), enjekte edilen Viewer üzerinde yerel bir oturumu sonlandırır. Bir belgenin yayınlanmış eserlerini paylaşımdan kaldırmak için yayıncı şunları sunar:
bool CloseDistributedDocument(FileShareConfig fileShareConfig, string token)Belgenin yayınlandığı aynı FileShareConfig'yi geçirin.
Checklist
- Tek bir yardımcıda
FileShareConfig'i oluşturun, bir kez kaydedin ve iki yarıdan da kullanın. RootPath'i her düğümün erişebileceği bir klasöre yönlendirin.PublishAsync(...)ile yayınlayın, ya da arka plan yayınlamasıylaEnqueueAsync(...)kullanın.- İstemcinin çağırdığı dalda
UseDoconutCloud<FileShareCloudHandler>(...)ile hizmet verin. - Arka plan yayınlamasıyla,
FirstPagePriorityveretryOn409'yi birlikte etkinleştirin ve okuma tarafına sıfır olmayan birReadReadyPollMsverin. - Oturum başına kontrolü imzalı erişim biletleriyle değiştirin — her düğümde bir Data Protection anahtar halkası, okuma dalında
UseDoconutDistributedDocumentSecurity(), açık uç noktadan bir bilet — veUnsafeMode = true'ı yalnız başına göndermeyin. - Bir düğümde bir belge açarak ve diğerinden geç bir sayfa isteyerek doğrulayın.
Bu sayfa yardımcı oldu mu?