استقرارهای توزیع‌شده

سرو یک سند از چندین گره

هنگامی که چندین گره همان اسناد را سرو می‌کنند، گره‌ای که سند را رندر می‌کند لزوماً گره‌ای نیست که درخواست‌های صفحه مرورگر را پاسخ می‌دهد. Doconut این کار را به دو نیمه واضح تقسیم می‌کند — یک نیمهٔ نوشتن که آثار یک سند را به ذخیره‌سازی مشترک منتشر می‌کند، و یک نیمهٔ خواندن که آنها را از هر گره‌ای سرو می‌کند.

یک گرهٔ واحد نیازی به هیچ‌یک از این موارد ندارد: مسیر معمول OpenDocumentAsync سند را در حافظهٔ آن گره نگه می‌دارد و به جلسهٔ مرورگر متصل می‌کند (به جلسات و امنیت نگاه کنید). از این صفحه استفاده کنید وقتی درخواست‌های صفحه می‌توانند به گره‌ای برسند که هرگز سند را باز نکرده است.

چگونه دو نیمه با هم ترکیب می‌شوند

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

پیکربندی مشترکی که هر دو نیمه به آن نیاز دارند

ناشر با یک FileShareConfig می‌نویسد و دستگیرهٔ خواندن با یکی سرو می‌کند. اگر RootPath یا UsePerTokenSubfolders بین آنها متفاوت باشد، گرهٔ دیگر 404 برمی‌گرداند. پیکربندی را دقیقاً در یک مکان بسازید و یک‌بار ثبت کنید، تا هر دو نیمه همان شیء را بخوانند:

csharp
var rootPath = builder.Configuration["Doconut:SharedRoot"]!;   // مثلاً \\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 را پاس دهید.

FileShareConfig در Doconut.Clouds قرار دارد، همراه با AzureConfig، AmazonConfig، GoogleCloudConfig، DropBoxConfig، RedisConfig، CDNConfig و FTPConfig.

ویژگیهدف
LocationCloudLocation.FileShare برای یک اشتراک UNC/محلی
RootPathپوشهٔ مشترکی که هر گره می‌تواند به آن دسترسی داشته باشد
UsePerTokenSubfoldersآثار هر سند را در پوشهٔ {token} خود نگه دارید (پیش‌فرض true)
ReadReadyPollMsمدت زمانی که نیمهٔ خواندن برای صفحه‌ای که انتشار پس‌زمینه هنوز در حال نوشتن است، صبر می‌کند؛ 0 (پیش‌فرض) یک بار بررسی می‌کند. این بر اسنادی که به‌صورت همزمان منتشر می‌شوند تأثیری ندارد

بخش نوشتن — انتشار سند

DistributedDocumentPublisher را تزریق کنید و به‌جای باز کردن یک جلسهٔ محلی، منتشر کنید. یک فراخوانی تمام مجموعهٔ آثار — صفحات، اطلاعات سند، فهرست جستجو و متادیتا — را رندر و می‌نویسد و زمانی که تمام شد برمی‌گردد:

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 و Format است. توکن دقیقاً همانند یک توکن مشاهده‌گر عادی به مرورگر می‌رود. در یک مزرعه، نقطهٔ انتهایی همچنین یک بلیط دسترسی امضا‌شده برمی‌گرداند — به امنیت در میان گره‌ها نگاه کنید.

سمت خواندن — سرویس از اشتراک

دستگیره FileShare را بر روی شاخه‌ای که مشتری فراخوانی می‌کند — /doconut، مطابق با BasePath: 'doconut' — پشت بررسی بلیت نصب کنید:

csharp
var app = builder.Build();

app.UseDoconutResources();
app.Map("/doconut", branch =>
{
    branch.UseDoconutDistributedDocumentSecurity();   // بلیط‌های امضا شده — در زیر ببینید
    branch.UseDoconutCloud<FileShareCloudHandler>(options =>
    {
        options.Location          = CloudLocation.FileShare;
        options.CloudUploadConfig = app.Services.GetRequiredService<FileShareConfig>();
    }, "/");
});

UseDoconutCloud ارائه‌دهنده را به عنوان آرگومان نوع خود می‌گیرد. دستگیره‌ها با نام‌های <Provider>CloudHandler — FileShareCloudHandler، AzureCloudHandler، AmazonS3CloudHandler، GoogleCloudHandler، DropBoxCloudHandler، RedisCloudHandler، FTPCloudHandler و CDNCloudHandler نام‌گذاری می‌شوند. با پیشوند مسیر "/"، دستگیره به هر درخواستی که به شاخه‌اش می‌رسد پاسخ می‌دهد.

دستگیره CDN فقط‑خواندنی است — آنچه در CDN موجود است سرویس می‌دهد؛ آپلود نمی‌کند.

اختیاری: انتشار در پس‌زمینه

به‌طور پیش‌فرض PublishAsync کل سند را قبل از بازگشت رندر می‌کند. برای بازگشت به محض ایجاد توکن و اجازه دادن به یک کارگر میزبانی‌شده برای رندر در همان پوشه، صف انتخابی را ثبت کنید و پیکربندی مشترک را با asyncPublish: true بسازید:

csharp
builder.Services.AddDoconut(options => { /* … */ });
builder.Services.AddDoconutDistributedAsyncPublish();

بدون این ثبت، هیچ چیزی ثبت نمی‌شود و انتشار به‌صورت همزمان باقی می‌ماند، دقیقاً همان‌طور که قبلاً بود.

سپس به جای PublishAsync، EnqueueAsync را فراخوانی کنید. (DistributedDocumentPublishOptions.Async فقط یک پرچم است که کد شما می‌تواند آن را بخواند تا بین دو مسیر انتخاب کند؛ ناشر آن را نادیده می‌گیرد.) صف محدود است: وقتی اشباع می‌شود، EnqueueAsync خطای DistributedPublishQueueFullException را پرتاب می‌کند. با یک 503 و یک هدر Retry-After به آن پاسخ دهید تا مشتریان به‌جای گیر کردن، عقب‌نشینی کنند:

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);
    }
});

صفحاتی که هنوز نوشته نشده‌اند: HTTP 202

با انتشار پس‌زمینه، درخواست صفحه می‌تواند پیش از اینکه کارگر آن صفحه را بنویسد، برسد. سمت خواندن تا حداکثر ReadReadyPollMs صبر می‌کند و سپس به‌جای مسدود کردن درخواست، HTTP 202 Accepted را پاسخ می‌دهد.

FirstPagePriority = true زمان انتظار برای اولین نمایش را کوتاه می‌کند: صفحه ۱ ابتدا در پوشه سند نوشته می‌شود، بنابراین سند باز می‌شود در حالی که صفحات بعدی هنوز در حال رندر هستند. این فقط برای انتشار پس‌زمینه در پوشه‌های توکن‌به‌توکن (UsePerTokenSubfolders = true) اعمال می‌شود؛ PublishAsync همزمان آن را نادیده می‌گیرد، زیرا فراخواننده‌اش به‌هر حال تا تمام سند صبر می‌کند.

این انتظار را به سمت مشتری منتقل می‌کند، جایی که محدود و قابل مشاهده است. قابلیت تلاش مجدد را در ویجت فعال کنید:

javascript
const objViewer = $('#div_ctlDoc').docViewer({
    BasePath:   'doconut',
    ResPath:    'doconut-res/images',
    retryOn409: true      // پاسخ‌های آمادگی 202 (و 409 قدیمی) برای تلاش‌های مجدد
});

یک مشتری که تلاش مجدد نمی‌کند، کاشی‌های خراب برای صفحاتی که هنوز در حال رندر هستند نشان می‌دهد. بودجهٔ تلاش مجدد و پیش‌فرض‌های آن (retryInitialDelayMs، retryBackoffFactor، retryMaxDelayMs، retryMaxAttempts، retryMaxTotalMs) در پیکربندی‌نمایشگر مستند شده‌اند.

امنیت در میان گره‌ها

توکن‌های وابسته به جلسه فرض می‌کنند گره سرویس‌دهنده درخواست اولیه را دیده است. در یک مزرعه این‌طور نیست، بنابراین بررسی در سطح هر جلسه درخواست‌های معتبر را رد می‌کند؛ یک مزرعه بنابراین UnsafeMode = true را تنظیم می‌کند.

UnsafeMode = true مدل امنیتی نیست — بلکه حذف یکی است که دیگر اعمال نمی‌شود.
آن را با بلیت‌های دسترسی امضا شده جایگزین کنید، که هر گره می‌تواند به‌طور مستقل آن را تأیید کند. چهار بخش با هم کار می‌کنند.

1. ثبت امنیت بلیت در هر گره.
بلیت‌ها با ASP.NET Core Data Protection محافظت می‌شوند، بنابراین هر گره باید از همان حلقه کلید و نام برنامه استفاده کند؛ گره‌ای با کلیدهای متفاوت نمی‌تواند بلیت صادر شده توسط گره دیگر را بخواند.

csharp
using Microsoft.AspNetCore.DataProtection;

builder.Services.AddDataProtection()
    .PersistKeysToFileSystem(new DirectoryInfo(@"\\fileserver\doconut-keys"))   // به اشتراک گذاشته شده توسط هر گره
    .SetApplicationName("doconut-farm");

builder.Services.AddDoconut(options => options.UnsafeMode = true);
builder.Services.AddDoconutDistributedDocumentSecurity(options =>
{
    options.TicketLifetimeMinutes = 60;   // پیش‌فرض
});

2. بررسی بلیت‌ها در سمت خواندن.
UseDoconutDistributedDocumentSecurity() قبل از UseDoconutCloud در شاخهٔ خواندن قرار می‌گیرد، همان‌طور که در نمونهٔ سمت‑خواندن آمده است.

3. صدور بلیت هنگام باز شدن سند.
بلیت شامل نام توکن، مرورگر (از طریق کوکی‌ای که سمت خواندن مقایسه می‌کند) و کاربر وارد شده، در صورت وجود، می‌شود:

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);

    // ticket را به این browser از طریق cookie که سمت خواندن بررسی می‌کند، متصل کنید.
    var cookieName = security.Value.BrowserCookieName;   // "doconut-client" به طور پیش‌فرض
    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. هر دو را به ویجت پاس دهید.
نمایشگر بلیت را به‌عنوان access همراه با هر درخواست ارسال می‌کند:

javascript
const resp = await fetch('/api/open?fileName=Sample.pdf', { method: 'POST' });
const { token, access } = await resp.json();
objViewer.View(token, access);

سمت خواندن درخواست‌هایی که بلیت آن‌ها گم شده، نامعتبر، برای توکن دیگری صادر شده، منقضی شده، به کوکی مرورگر دیگری متصل شده یا برای کاربر وارد شده دیگری صادر شده‌اند، رد می‌کند. پاسخ 403 می‌دهد — همراه با تصویر خطای UnauthorizedMessage برای درخواست‌های صفحه و تصویر بندانگشتی، و در غیر این صورت به‌صورت متن ساده. با مرورگر واقعی یا کلاینتی که کوکی‌ها را نگه می‌دارد، تست کنید.

هرگز UnsafeMode = true را به‌یک استقرار تک‌گره‌ای بازنگردانید، و هرگز آن را به‌عنوان یک راه‌حل کوتاه برای بررسی جلسهٔ ناموفق در یک گره در نظر نگیرید — در آنجا اصلاح صحیح AddSession() / UseSession() است. ببینید جلسات و امنیت.

بستن یک سند منتشر شده

CloseDocument(token) بر روی Viewer تزریق‌شده یک جلسهٔ محلی را از بین می‌برد. برای حذف آثار منتشر شدهٔ یک سند از اشتراک، ناشر ارائه می‌دهد:

text
bool CloseDistributedDocument(FileShareConfig fileShareConfig, string token)

همان FileShareConfig را که سند با آن منتشر شده بود، پاس دهید.

چک‌لیست

  1. ساخت FileShareConfig را در یک کمک‌کننده انجام دهید، یک‌بار ثبت کنید و از هر دو نیمه استفاده کنید.
  2. RootPath را به پوشه‌ای که هر گره می‌تواند به آن دسترسی داشته باشد، اشاره کنید.
  3. با PublishAsync(...) منتشر کنید، یا با EnqueueAsync(...) به همراه انتشار پس‌زمینه.
  4. با UseDoconutCloud<FileShareCloudHandler>(...) بر روی شاخه‌ای که مشتری فراخوانی می‌کند، سرو کنید.
  5. در انتشار پس‌زمینه، FirstPagePriority و retryOn409 را همزمان فعال کنید و به سمت خواندن مقدار غیر صفر ReadReadyPollMs بدهید.
  6. بررسی هر جلسه را با بلیت‌های دسترسی امضا شده جایگزین کنید — یک حلقه کلید حفاظت داده بر روی هر گره، UseDoconutDistributedDocumentSecurity() بر روی شاخه خواندن، بلیت از نقطه انتهایی باز — و UnsafeMode = true را به تنهایی ارسال نکنید.
  7. با باز کردن یک سند در یک گره و درخواست صفحه‌ای دیرهنگام از گره دیگر، تأیید کنید.

آیا این صفحه مفید بود؟