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:

text
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 page

Her 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:

csharp
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.

ÖzellikAmaç
LocationCloudLocation.FileShare için UNC/yerel paylaşım
RootPathHer düğümün erişebileceği ortak klasör
UsePerTokenSubfoldersHer belgenin artefaktlarını kendi {token} klasöründe tut (varsayılan true)
ReadReadyPollMsArka 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:

csharp
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:

csharp
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:

csharp
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:

csharp
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:

javascript
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.

csharp
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:

csharp
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:

javascript
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:

text
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.PathFileShareConfig.RootPath
PageWaitTimeSeconds / StartWaitFromPageArka 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 / WebfarmPathHâlâ mevcut, IsWebFarm / WebFarmPath olarak yazılmış — yayın yolunda gerekli değil
Doconut.Configs.CloudDoconut.Clouds

Kontrol Listesi

  1. Tek bir yardımcıda FileShareConfig oluşturun, bir kez kaydedin ve iki yarıdan da kullanın.
  2. RootPath'yi zaten kullandığınız paylaşıma işaret edin.
  3. PublishAsync(...) ile yayınlayın; herhangi bir ExportToPng / ExportToCloud çağrısını silin.
  4. İstemcinin çağırdığı dalda UseDoconutCloud<FileShareCloudHandler>(...) ile hizmet verin.
  5. Arka plan yayınlamada, FirstPagePriority ve retryOn409 birlikte etkinleştirin ve okuma tarafına sıfır olmayan bir ReadReadyPollMs verin.
  6. 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 — ve UnsafeMode = true tek başına göndermeyin.
  7. Bir düğümde belge açarak ve diğerinden geç bir sayfa isteyerek doğrulayın.

Bu sayfa yardımcı oldu mu?