النشر الموزع
خدمة مستند واحد من عدة عقد
عندما تقوم عدة عقد بخدمة نفس المستندات، فإن العقدة التي تقوم بإنشاء المستند ليست بالضرورة هي العقدة التي ترد على طلبات صفحات المتصفح. تقوم Doconut بتقسيم هذه المهمة إلى نصفين واضحين — الجانب الكتابي الذي ينشر مخرجات المستند إلى التخزين المشترك، والجانب القارئ الذي يخدمها من أي عقدة.
العقدة الواحدة لا تحتاج إلى أي من ذلك: مسار OpenDocumentAsync العادي يحتفظ بالمستند في ذاكرة تلك العقدة ويربطه بجلسة المتصفح (انظر الجلسات والأمان). استخدم هذه الصفحة عندما يمكن أن تصل طلبات الصفحات إلى عقدة لم تشاهد الفتح أبداً.
كيف يتناسب النصفان
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.
| الخاصية | الغرض |
|---|---|
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. التوكن ينتقل إلى المتصفح تمامًا كما يفعل توكن المشاهد العادي. في مزرعة، تُعيد نقطة النهاية أيضًا تذكرة وصول موقعة — انظر الأمان عبر العقد.
الجانب القارئ — الخدمة من المشاركة
قم بتركيب معالج FileShare على الفرع الذي يستدعيه العميل — /doconut، مطابقًا BasePath: 'doconut' — خلف فحص التذكرة:
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:
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: '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، لذا يجب على كل عقدة استخدام حلقة المفاتيح واسم التطبيق نفسه؛ لا يمكن لعقدة ذات مفاتيح مختلفة قراءة تذكرة أصدرتها عقدة أخرى.
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 التي نُشر المستند بها.
قائمة التحقق
- قم بإنشاء
FileShareConfigفي مساعد واحد، سجّله مرة واحدة، واستخدمه من كلا النصفين. - وجّه
RootPathإلى مجلد يمكن لكل عقدة الوصول إليه. - انشر باستخدام
PublishAsync(...)، أوEnqueueAsync(...)مع النشر الخلفي. - قدّم باستخدام
UseDoconutCloud<FileShareCloudHandler>(...)على الفرع الذي يستدعيه العميل. - مع النشر الخلفي، فعّل
FirstPagePriorityوretryOn409معًا، وامنح الجانب القارئ قيمة غير صفرية لـReadReadyPollMs. - استبدل فحص كل جلسة بتذاكر وصول موقّعة — حلقة مفتاح حماية البيانات واحدة على كل عقدة،
UseDoconutDistributedDocumentSecurity()على الفرع القارئ، تذكرة من نقطة النهاية المفتوحة — ولا تقم بشحنUnsafeMode = trueبمفرده. - تحقق بفتح مستند على عقدة واحدة وطلب صفحة متأخرة من أخرى.
هل كانت هذه الصفحة مفيدة؟