التوزيعات الموزعة

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

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

الأمان عبر العقد

تفترض الرموز المرتبطة بالجلسة أن العقدة الخادمة رأت طلب الفتح. في مجموعة لم يحدث ذلك، لذا فإن فحص الجلسة لكل جلسة سيُرفض الطلبات الشرعية؛ لذلك تقوم المجموعة بتعيين 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. تحقق بفتح مستند على عقدة واحدة وطلب صفحة متأخرة من أخرى.

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