Dağıtılmış Dağıtımlar
Bir belgeyi birden fazla düğümden sun
Birden fazla düğüm aynı belgeleri hizmet verdiğinde, bir belgeyi işleyen düğüm mutlaka tarayıcının sayfa isteklerine yanıt veren düğüm olmayabilir. Bu sürüm bu işi iki açık bölüme ayırır — belge artefaktlarını ortak depolamaya yayınlayan bir yazma tarafı ve bunları herhangi bir düğümden sunan bir okuma tarafı.
Uygulamanız şu anda UseDoconutWebFarm(...) çağrısını yapıyorsa, bu sayfa onun yerini alır. Bu sürümde UseDoconutWebFarm ya da WebFarmOptions bulunmaz.
Topolojiniz değişmez. Paylaşılan kökü bugün kullandığınız aynı UNC yoluna işaret edin ve her düğüm mevcut şekilde çalışmaya devam eder. Değişen şey, yayınlamanın artık işleme yan etkisi yerine sizin çağırdığınız bir işlem olmasıdır.
Web-farm ara katmanının yerine ne geçti
Daha önce tek bir ara katman her şeyi yapıyordu: ortak bir klasörden önceden işlenmiş görüntüleri sunuyor ve başka bir düğüm hâlâ yazarken sorguluyordu. Bekleme, kör bir bütçeydi — “sayfanın ortaya çıkmasını umarak üç dakikaya kadar blokla”.
Şimdi aynı iş iki çağrı haline geldi; bunları görebilir ve mantıklı bir şekilde değerlendirebilirsiniz:
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 tarafın da ihtiyaç duyduğu ortak yapılandırma
Yayıncı bir FileShareConfig ile yazar; okuma işleyicisi de aynı türde bir nesneyle hizmet verir. Eğer RootPath veya UsePerTokenSubfolders arasında fark varsa, diğer düğüm 404 yanıtı verir. Yapılandırmayı tam olarak tek bir yerde oluşturun ve bir kez kaydedin, böylece her iki taraf da aynı nesneyi okur:
var rootPath = builder.Configuration["Doconut:SharedRoot"]!; // örn. \\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,
};
}Arka plan yayınlamayı etkinleştirdiğinizde asyncPublish: true geçirin. arka plan yayınlama
FileShareConfig, Doconut.Clouds içinde, AzureConfig, AmazonConfig, GoogleCloudConfig, DropBoxConfig, RedisConfig, CDNConfig ve FTPConfig ile birlikte bulunur. Önceki kütüphanede bunlar Doconut.Configs.Cloud içindeydi; sınıf adları değişmedi.
| Özellik | Amaç |
|---|---|
Location | CloudLocation.FileShare için UNC/yerel paylaşım |
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â yazmakta olan bir sayfa için okuma tarafının ne kadar bekleyeceği; 0 (varsayılan) bir kez kontrol eder. Senkron olarak yayınlanan belgeler üzerinde etkisi yoktur |
Yazma tarafı — belgeyi yayınla
DistributedDocumentPublisher enjekte edin ve yerel oturum açmak yerine yayınlayın. Tek bir çağrı, tam artefakt setini — sayfalar, belge bilgisi, arama indeksi ve meta veriler — oluşturur ve yazar, işlem tamamlandığında döner:
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 farmda, uç nokta ayrıca imzalı bir erişim bileti döndürür — Düğümler arası güvenlik.
Bu tek çağrı, önceki ikiliyi değiştirir — belgeyi yerel bir oturuma açmak ve ardından ExportToPng(sharedPath) ile görüntüleri paylaşıma dökmek. ExportToPng ve ExportToCloud burada bir karşılığı yoktur.
Okuma tarafı — paylaşımdan hizmet ver
FileShare işleyicisini, istemcinin zaten çağırdığı aynı dalda, bilet kontrolünün arkasına monte edin:
var app = builder.Build();
app.UseDoconutResources();
app.MapWhen(
ctx => ctx.Request.Path.Value?.EndsWith("DocImage.axd", StringComparison.OrdinalIgnoreCase) == true,
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 bu sürümde geneldir: sağlayıcı, ara katmanda içinde değiştirilen bir Location değerinden ziyade tip argümanıdır. İşleyicilerin adı <Provider>CloudHandler — FileShareCloudHandler, AzureCloudHandler, AmazonS3CloudHandler, GoogleCloudHandler, DropBoxCloudHandler, RedisCloudHandler, FTPCloudHandler ve CDNCloudHandler şeklindedir. "/" yol önekiyle, işleyici dalına ulaşan her isteğe yanıt verir.
CDN işleyicisi salt-okunur — CDN'de zaten olanı hizmet verir; yükleme yapmaz.
İsteğe bağlı: arka planda yayınla
Varsayılan olarak PublishAsync, döndürmeden önce tüm belgeyi işler. Token oluşturulduğunda hemen 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 senkron kalır, tam olarak önceki gibi.
Ardından PublishAsync yerine EnqueueAsync çağırın. (DistributedDocumentPublishOptions.Async yalnızca kendi kodunuzun iki yol arasında seçim yapması 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ünüm 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 token başına klasörlere 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: '/',
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 bozuk 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.
Bu çift — FirstPagePriority ile arka plan yayınlaması, artı okuma tarafı anketi — önceki PageWaitTimeSeconds ve StartWaitFromPage ayarlarının yerini alır. Artık hiçbiri mevcut değil.
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; bu nedenle bir çiftlik UnsafeMode = true ayarlar.
UnsafeMode = true güvenlik modeli değildir — artık geçerli olmayan bir modelin kaldırılmasıdır.
Bunu, her düğümün bağımsız olarak doğrulayabileceği imzalı erişim biletleriyle değiştirin. 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ğinde 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 iletin.
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ı çereziyle bağlanmış 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. 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ış artefaktlarını paylaşımdan kaldırmak için yayıncı şunları sunar:
bool CloseDistributedDocument(FileShareConfig fileShareConfig, string token)Belgenin yayınlandığı aynı FileShareConfig'yi iletin.
Ayar‑ayar haritalaması
| Önceki | Şimdi |
|---|---|
UseDoconutWebFarm(new WebFarmOptions { … }) | PublishAsync(...) yazma tarafında ve UseDoconutCloud<FileShareCloudHandler>(...) okuma tarafında |
WebFarmOptions.Path | FileShareConfig.RootPath |
PageWaitTimeSeconds / StartWaitFromPage | Arka plan yayınlama DistributedDocumentPublishOptions.FirstPagePriority ile, ve FileShareConfig.ReadReadyPollMs |
viewer.OpenDocument(...) ardından viewer.ExportToPng(share) | bir PublishAsync(...) çağrı |
viewer.ExportToCloud(cloudConfig) | PublishAsync(...) sağlayıcının yapılandırmasıyla |
UseDoconutCloud(new CloudOptions { Location = … }) | UseDoconutCloud<THandler>(options => …, pathPrefix) |
DocOptions.IsWebfarm / WebfarmPath | Hâlâ mevcut, IsWebFarm / WebFarmPath olarak yazılmış — yayın yolunda gerekli değil |
Doconut.Configs.Cloud | Doconut.Clouds |
Kontrol Listesi
- Tek bir yardımcıda
FileShareConfigoluşturun, bir kez kaydedin ve iki yarıdan da kullanın. RootPath'yi zaten kullandığınız paylaşıma işaret edin.PublishAsync(...)ile yayınlayın; herhangi birExportToPng/ExportToCloudçağrısını silin.- İstemcinin çağırdığı dalda
UseDoconutCloud<FileShareCloudHandler>(...)ile hizmet verin. - Arka plan yayınlamada,
FirstPagePriorityveretryOn409birlikte 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 = truetek başına göndermeyin. - Bir düğümde belge açarak ve diğerinden geç bir sayfa isteyerek doğrulayın.
Bu sayfa yardımcı oldu mu?