النشر الموزع
خدمة مستند واحد من عدة عقد
عندما تقوم عدة عقد بخدمة نفس المستندات، فإن العقدة التي تُنشئ المستند ليست بالضرورة العقدة التي ترد على طلبات صفحات المتصفح. هذا الإصدار يقسم هذه المهمة إلى نصفين واضحين — جانب الكتابة الذي ينشر قطع المستند إلى التخزين المشترك، وجانب القراءة الذي يخدمها من أي عقدة.
إذا كان تطبيقك يستدعي حاليًا UseDoconutWebFarm(...)، فإن هذه الصفحة هي بديلك. لا يوجد ولا UseDoconutWebFarm ولا WebFarmOptions في هذا الإصدار.
بنيتك لا تتغير. قم بتوجيه الجذر المشترك إلى نفس مسار UNC الذي تستخدمه اليوم وستستمر كل عقدة في العمل كما هي الآن. ما يتغير هو أن النشر أصبح عملية تستدعيها، بدلاً من أن يكون تأثيرًا جانبيًا للإنشاء.
ما حلّ بديل middleware الخاص بـ web-farm
سابقًا كان هناك middleware واحد يقوم بكل شيء: كان يخدم الصور المُسبق إنشائها من مجلد مشترك ويستطلع بينما كانت عقدة أخرى لا تزال تكتبها. الانتظار كان ميزانية عمياء — "احجز حتى ثلاث دقائق على أمل ظهور الصفحة".
الآن نفس المهمة هي استدعاءان يمكنك رؤيتهما والتفكير فيهما:
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. أنشئ التكوين في مكان واحد بالضبط وسجّله مرة واحدة، بحيث يقرأ كلا النصفين نفس الكائن:
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؛ لم تتغير أسماء الفئات.
| الخاصية | الغرض |
|---|---|
Location | CloudLocation.FileShare لمشاركة UNC/محلية |
RootPath | المجلد المشترك الذي يمكن لكل عقدة الوصول إليه |
UsePerTokenSubfolders | احتفظ بقطع كل مستند في مجلد {token} الخاص به (الافتراضي true) |
ReadReadyPollMs | المدة التي ينتظرها جانب القراءة لصفحة ما زال النشر في الخلفية يكتبها؛ 0 (الافتراضي) يتحقق مرة واحدة. لا تأثير له على المستندات المنشورة بشكل متزامن |
جانب الكتابة — نشر المستند
قم بحقن DistributedDocumentPublisher وانشر بدلاً من فتح جلسة محلية. استدعاء واحد يُنشئ ويكتب مجموعة القطع الكاملة — الصفحات، معلومات المستند، فهرس البحث، والبيانات الوصفية — ويعود عندما يكتمل:
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. الرمز يُرسل إلى المتصفح تمامًا كما يحدث مع رمز المشاهد العادي. في بيئة farm، تُعيد نقطة النهاية أيضًا تذكرة وصول موقعة — راجع الأمان عبر العقد.
هذا الاستدعاء الواحد يحل محل الزوج السابق — فتح المستند في جلسة محلية ثم تفريغ الصور إلى المشاركة باستخدام ExportToPng(sharedPath). لا يوجد ما يُقابل ExportToPng وExportToCloud هنا.
الجانب القارئ — الخدمة من المشاركة
قم بتركيب معالج FileShare على نفس الفرع الذي يستدعيه العميل بالفعل، خلف فحص التذكرة:
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:
builder.Services.AddDoconut(options => { /* … */ });
builder.Services.AddDoconutDistributedAsyncPublish();بدون هذا التسجيل لا يُسجَّل شيء ويظل النشر متزامناً، تماماً كما كان من قبل.
ثم استدعِ EnqueueAsync بدلاً من PublishAsync. (DistributedDocumentPublishOptions.Async هو مجرد علم يمكن لكودك قراءته لاختيار أحد المسارين؛ الناشر يتجاهله.) الطابور محدود: عندما يُشبَع، EnqueueAsync يرمي DistributedPublishQueueFullException. أجب عليه بـ 503 ورأس Retry-After حتى يتراجع العملاء بدلاً من التوقف:
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 المتزامن يتجاهله، لأن المستدعي ينتظر المستند بالكامل على أي حال.
هذا ينقل الانتظار إلى العميل، حيث يكون محدودًا ومرئيًا. فعّل إعادة المحاولة على الواجهة:
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، لذا يجب على كل عقدة استخدام حلقة المفاتيح واسم التطبيق نفسه؛ العقدة التي لديها مفاتيح مختلفة لا يمكنها قراءة تذكرة أصدرتها عقدة أخرى.
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. أصدر تذكرة عند فتح المستند. التذكرة تسمي الرمز، المتصفح (من خلال ملف تعريف الارتباط الذي يقارنه الجانب القارئ)، والمستخدم الموقع إذا كان موجودًا:
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 مع كل طلب:
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 المُحقن يُنهي جلسة محلية. لإزالة القطع المنشورة للمستند من المشاركة، يُظهر الناشر:
bool CloseDistributedDocument(FileShareConfig fileShareConfig, string token)مرّر نفس FileShareConfig التي نُشر المستند بها.
تعيين خطوة بخطوة
| السابق | الآن |
|---|---|
UseDoconutWebFarm(new WebFarmOptions { … }) | PublishAsync(...) على جانب الكتابة بالإضافة إلى UseDoconutCloud<FileShareCloudHandler>(...) على جانب القراءة |
WebFarmOptions.Path | FileShareConfig.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.Cloud | Doconut.Clouds |
قائمة التحقق
- قم بإنشاء
FileShareConfigفي مساعد واحد، سجّله مرة واحدة، واستخدمه من كلا النصفين. - وجّه
RootPathإلى المشاركة التي تستخدمها بالفعل. - انشر باستخدام
PublishAsync(...)؛ احذف أي استدعاءاتExportToPng/ExportToCloud. - قدّم باستخدام
UseDoconutCloud<FileShareCloudHandler>(...)على الفرع الذي يستدعيه العميل. - مع النشر الخلفي، فعّل
FirstPagePriorityوretryOn409معًا، ومنح جانب القراءة قيمة غير صفرية لـReadReadyPollMs. - استبدل فحص كل جلسة بتذاكر وصول موقعة — حلقة مفتاح حماية البيانات واحدة على كل عقدة،
UseDoconutDistributedDocumentSecurity()على فرع القراءة، تذكرة من نقطة النهاية المفتوحة — ولا تقم بشحنUnsafeMode = trueبمفرده. - تحقق بفتح مستند على عقدة واحدة وطلب صفحة متأخرة من أخرى.
هل كانت هذه الصفحة مفيدة؟