النشر الموزع

خدمة مستند واحد من عدة عقد

عندما تقوم عدة عقد بخدمة نفس المستندات، فإن العقدة التي تقوم بإنشاء المستند ليست بالضرورة هي العقدة التي ترد على طلبات صفحات المتصفح. تقوم 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();

بدون هذا التسجيل لا يُسجَّل شيء ويظل النشر متزامنًا، تمامًا كما كان من قبل.

ثم استدعِ EnqueueAsync بدلًا من PublishAsync. (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 يختصر الانتظار للعرض الأول: تُكتب الصفحة 1 في مجلد المستند أولًا، لذا يفتح المستند بينما لا تزال الصفحات اللاحقة تُصوَّر. ينطبق ذلك فقط على النشر في الخلفية إلى مجلدات كل رمز مميز (UsePerTokenSubfolders = true)؛ الـ PublishAsync المتزامن يتجاهله، لأن المستدعي ينتظر المستند بالكامل على أي حال.

هذا ينقل الانتظار إلى العميل، حيث يكون محدودًا ومرئيًا. فعّل إعادة المحاولة على الواجهة:

javascript
const objViewer = $('#div_ctlDoc').docViewer({
    BasePath:   'doconut',
    ResPath:    'doconut-res/images',
    retryOn409: true      // محاولات إعادة 202 (و legacy 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);

    // ربط التذكرة بهذا المتصفح عبر ملف تعريف الارتباط الذي يتحقق منه الجانب القارئ.
    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. تحقق بفتح مستند على عقدة واحدة وطلب صفحة متأخرة من أخرى.

هل كانت هذه الصفحة مفيدة؟