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

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

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

اگر برنامهٔ شما در حال حاضر UseDoconutWebFarm(...) را فراخوانی می‌کند، این صفحه جایگزین شماست. هیچ‌کدام از UseDoconutWebFarm یا WebFarmOptions در این نسخه وجود ندارند.

توپولوژی شما تغییر نمی‌کند. ریشهٔ مشترک را به همان مسیر UNC که امروز استفاده می‌کنید اشاره کنید و هر گره همان‌طور که اکنون کار می‌کند ادامه می‌دهد. آنچه تغییر می‌کند این است که انتشار یک عملیات است که شما فراخوانی می‌کنید، نه یک اثر جانبی رندر.

چه چیزی جایگزین میدلور وب‌فارم شد

قبلاً یک میدلور همه کارها را انجام می‌داد: تصاویر پیش‌رندر شده را از یک پوشهٔ مشترک سرو می‌کرد و در حالی که گرهٔ دیگری هنوز آن‌ها را می‌نوشت پرسش می‌کرد. انتظار یک بودجهٔ کور بود — «تا سه دقیقه مسدود بمانید به امید ظاهر شدن صفحه».

اکنون همان کار به دو فراخوانی تبدیل شده که می‌توانید ببینید و دربارهٔ آن استدلال کنید:

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. در کتابخانهٔ قبلی این‌ها در Doconut.Configs.Cloud بودند؛ نام کلاس‌ها تغییر نکرده‌اند.

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

این فراخوانی تک‌جمله‌ای جایگزین جفت قبلی می‌شود — باز کردن سند در یک جلسهٔ محلی و سپس ریختن تصاویر بر روی اشتراک با ExportToPng(sharedPath). ExportToPng و ExportToCloud در اینجا معادلی ندارند.

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

دستگیره FileShare را بر روی همان شاخه‌ای که مشتری قبلاً فراخوانی می‌کند، پشت بررسی بلیت نصب کنید:

csharp
var app = builder.Build();

app.UseDoconutResources();
app.MapWhen(
    ctx => ctx.Request.Path.Value?.EndsWith("DocImage.axd", StringComparison.OrdinalIgnoreCase) == true,
    branch =>
    {
        branch.UseDoconutDistributedDocumentSecurity();   // بلیت‌های امضا شده — زیر را ببینید
        branch.UseDoconutCloud<FileShareCloudHandler>(options =>
        {
            options.Location          = CloudLocation.FileShare;
            options.CloudUploadConfig = app.Services.GetRequiredService<FileShareConfig>();
        }, "/");
    });

UseDoconutCloud در این نسخه عمومی است: فراهم‌کننده به عنوان آرگومان نوع است نه یک مقدار Location که داخل میدل‌ویر سوئیچ می‌شود. دستگیره‌ها با نام‌های <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 پذیرفته شد را پاسخ می‌دهد.

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

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

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

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

این جفت — انتشار در پس‌زمینه با FirstPagePriority، به‌همراه نظرسنجی سمت خواندن — آنچه تنظیمات قبلی PageWaitTimeSeconds و StartWaitFromPage را جایگزین می‌کند. هیچ‌کدام دیگر وجود ندارند.

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

توکن‌های وابسته به جلسه فرض می‌کنند که گره سرویس‌دهنده درخواست اولیه را دیده است. در یک مزرعه این‌طور نیست، بنابراین بررسی در هر جلسه درخواست‌های معتبر را رد می‌کند؛ بنابراین یک مزرعه 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);

    // بلیط را از طریق کوکی که سمت خواندن بررسی می‌کند به این مرورگر متصل کنید.
    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 را که سند با آن منتشر شده بود، پاس بدهید.

تنظیم به تنظیم نگاشت

قبلیاکنون
UseDoconutWebFarm(new WebFarmOptions { … })PublishAsync(...) در سمت نوشتن به‌اضافه UseDoconutCloud<FileShareCloudHandler>(...) در سمت خواندن
WebFarmOptions.PathFileShareConfig.RootPath
PageWaitTimeSeconds / StartWaitFromPageانتشار پس‌زمینه با DistributedDocumentPublishOptions.FirstPagePriority، به‌اضافه FileShareConfig.ReadReadyPollMs
viewer.OpenDocument(...) then viewer.ExportToPng(share)یک PublishAsync(...) فراخوانی
viewer.ExportToCloud(cloudConfig)PublishAsync(...) با پیکربندی ارائه‌دهنده
UseDoconutCloud(new CloudOptions { Location = … })UseDoconutCloud<THandler>(options => …, pathPrefix)
DocOptions.IsWebfarm / WebfarmPathهنوز موجود است، به صورت IsWebFarm / WebFarmPath نوشته می‌شود — در مسیر انتشار نیازی به آن نیست
Doconut.Configs.CloudDoconut.Clouds

فهرست بررسی

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

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