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

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

وقتی چندین گره همان اسناد را سرو می‌کنند، گره‌ای که یک سند را رندر می‌کند لزوماً گره‌ای نیست که درخواست‌های صفحه مرورگر را پاسخ می‌دهد. 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 بین آن‌ها متفاوت باشد، گرهٔ دیگر ۴۰۴ می‌دهد. پیکربندی را دقیقاً در یک مکان بسازید و یک‌بار ثبت کنید، تا هر دو نیمه همان شیء را بخوانند:

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مدت زمانی که read side برای صفحه‌ای که انتشار پس‌زمینه هنوز می‌نویسد، صبر می‌کند؛ 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 کل سند را قبل از بازگشت رندر می‌کند. برای بازگشت به محض ایجاد توکن و اجازه دادن به یک کارگر میزبانی‌شده برای رندر در همان پوشه، صف opt-in را ثبت کنید و پیکربندی مشترک را با 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 همزمان آن را نادیده می‌گیرد، زیرا فراخواننده‌اش به‌هر حال تا تمام سند صبر می‌کند.

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

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

کلاینتی که نه retry می‌کند، کاشی‌های خراب برای صفحاتی که هنوز در حال رندر هستند نشان می‌دهد. بودجه retry و مقادیر پیش‌فرض آن (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);

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

Checklist

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

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