Dağıtılmış Dağıtımlar

Bir belgeyi birden fazla düğümden hizmet ver

Birden fazla düğüm aynı belgeleri hizmet verdiğinde, bir belgeyi işleyen düğüm, tarayıcının sayfa isteklerine yanıt veren düğüm olmak zorunda değildir. Doconut bu işi iki açık yarıya ayırır — bir yazma tarafı belge artefaktlarını paylaşılan depolamaya yayınlar ve bir okuma tarafı bunları herhangi bir düğümden hizmet verir.

Tek bir düğüm bunun hiçbirine ihtiyaç duymaz: normal OpenDocumentAsync yolu belgeyi o düğümün belleğinde tutar ve tarayıcı oturumuna bağlar (bkz. Oturumlar ve Güvenlik). Sayfa isteklerinin hiç belgeyi açmamış bir düğüme düşebileceği durumlarda bu sayfayı kullanın.

İki yarının nasıl bir araya geldiği

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 yarının da ihtiyaç duyduğu ortak yapılandırma

Yayıncı bir FileShareConfig ile yazar ve okuma işleyicisi bir tane ile 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 yarı da aynı nesneyi okur:

csharp
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,
    };
}

asyncPublish: true'yi, arka plan yayınlama etkinleştirdiğinizde geçirin.

FileShareConfig, Doconut.Clouds içinde bulunur, AzureConfig, AmazonConfig, GoogleCloudConfig, DropBoxConfig, RedisConfig, CDNConfig ve FTPConfig ile birlikte.

ÖzellikAmaç
LocationCloudLocation.FileShare bir UNC/yerel paylaşım için
RootPathHer düğümün erişebileceği ortak klasör
UsePerTokenSubfoldersHer belgenin artefaktlarını kendi {token} klasöründe tut (varsayılan true)
ReadReadyPollMsOkuma tarafının, arka plan yayını hâlâ yazarken bir sayfayı ne kadar bekleyeceği; 0 (varsayılan) bir kez kontrol eder. Senkron olarak yayınlanan belgelere etkisi yoktur.

Yazma tarafı — belgeyi yayınla

DistributedDocumentPublisher enjekte edin ve yerel bir 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 çiftlikte, uç nokta ayrıca imzalı bir erişim bileti döndürür — bkz. 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:

csharp
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 adı <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 salt-okunur — CDN'de zaten olanı sunar; yükleme yapmaz.

İsteğe bağlı: arka planda yayınla

Varsayılan olarak PublishAsync tüm belgeyi döndürmeden önce 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 yapabilmesi için okuyabileceği bir bayraktır; yayıncı bunu yok sayar.) 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ü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 token başına klasörlere arka plan yayınlaması için geçerlidir (UsePerTokenSubfolders = true); senkron PublishAsync bunu yok sayar, çü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:   'doconut',
    ResPath:    'doconut-res/images',
    retryOn409: true      // 202 yeniden deneme (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ı belirteçler, 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 yapılan kontrol meşru 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, 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ği olduğu gibi.

3. Belge açıldığında bir bilet oluşturun. Bilet, belirteci, 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);

    // Okuma tarafının kontrol ettiği çerez aracılığıyla bu tarayıcıya bileti bağla.
    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 aktarın. Görüntüleyici, bileti her istekle 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 belirteç 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 görüntüsüyle, aksi takdirde düz metin olarak. Gerçek bir tarayıcı veya çerezleri tutan bir istemci ile test edin.

UnsafeMode = true'yi tek düğümlü bir dağıtıma geri getirmeyin ve asla 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 paylaşımdaki yayınlanmış artefaktlarını kaldırmak için yayıncı şu şeyi sunar:

text
bool CloseDistributedDocument(FileShareConfig fileShareConfig, string token)

Belgenin yayınlandığı aynı FileShareConfig'yi geçirin.

Kontrol Listesi

  1. Tek bir yardımcıda FileShareConfig'i oluşturun, bir kez kaydedin ve iki yarıdan da kullanın.
  2. RootPath'i her düğümün erişebileceği bir klasöre yönlendirin.
  3. PublishAsync(...) ile yayınlayın, ya da arka plan yayınlamasıyla EnqueueAsync(...) kullanın.
  4. İstemcinin çağırdığı dalda UseDoconutCloud<FileShareCloudHandler>(...) ile hizmet verin.
  5. Arka plan yayınlamasıyla, FirstPagePriority ve retryOn409'yi 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'ı yalnız başına göndermeyin.
  7. Bir düğümde bir belge açarak ve diğerinden geç bir sayfa isteyerek doğrulayın.

Bu sayfa yardımcı oldu mu?