פריסות מבוזרות

שרת מסמך אחד ממספר צמתים

כאשר מספר צמתים משרתים את אותם המסמכים, הצומת שמרנדר מסמך אינו בהכרח הצומת שמגיב לבקשות הדף של הדפדפן. גרסה זו מחלקת את המשימה לשניים — צד כתיבה שמפרסם את הארטיפקטים של המסמך לאחסון משותף, ו-צד קריאה שמשרת אותם מכל צומת.

אם היישום שלך קורא כעת ל-UseDoconutWebFarm(...), דף זה הוא ההחלפה שלך. גם UseDoconutWebFarm וגם WebFarmOptions אינם קיימים בגרסה זו.

הטופולוגיה שלך לא משתנה. הפנה את השורש המשותף לאותו נתיב UNC שבו אתה משתמש היום וכל צומת ממשיך לפעול כפי שהוא פועל כעת. מה שמשתנה הוא שהפרסום הוא פעולה שאתה קורא לה, במקום להיות תופעת לוואי של הרינדור.

מה החליף את ה‑middleware של web‑farm

בעבר middleware אחד עשה את הכל: הוא שירת תמונות שהוכנו מראש מתיקייה משותפת ו-סקר בזמן שצומת אחר עדיין כתב אותן. ההמתנה הייתה תקציב עיוור — "חסום עד שלוש דקות בתקווה שהדף יופיע".

כעת אותה משימה היא שני קריאות שאתה יכול לראות ולנתח:

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. בספרייה הקודמת אלה היו ב-Doconut.Configs.Cloud; שמות המחלקות לא השתנו.

מאפייןמטרה
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. הטוקן נשלח לדפדפן בדיוק כמו טוקן צופה רגיל. בחווה, הקצה גם מחזיר כרטיס גישה חתום — ראה אבטחה בין צמתים.

קריאה יחידה זו מחליפה את הזוג הקודם — פתיחת המסמך לסשן מקומי ולאחר מכן פיזור תמונות על השיתוף עם ExportToPng(sharedPath). ExportToPng ו-ExportToCloud אין להם מקבילה כאן.

צד קריאה — שירות מהשיתוף

התקן את המטפל FileShare באותו ענף שהלקוח כבר קורא, מאחורי בדיקת הכרטיס:

csharp
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:

csharp
builder.Services.AddDoconut(options => { /* … */ });
builder.Services.AddDoconutDistributedAsyncPublish();

בלי רישום זה, שום דבר אינו נרשם והפרסום נשאר סינכרוני, בדיוק כמו קודם.

לאחר מכן קרא ל‑EnqueueAsync במקום PublishAsync. (DistributedDocumentPublishOptions.Async הוא רק דגל שהקוד שלך יכול לקרוא כדי לבחור בין שני הנתיבים; המפרסם מתעלם ממנו.) התור מוגבל: כאשר הוא רווי, EnqueueAsync זורק DistributedPublishQueueFullException. השב אליו עם 503 ו‑header של 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:   '/',
    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, ולכן כל צומת חייב להשתמש באותו טבעת מפתחות ובשם היישום; צומת עם מפתחות שונים אינו יכול לקרוא כרטיס שהונפק על ידי צומת אחר.

csharp
using Microsoft.AspNetCore.DataProtection;

builder.Services.AddDataProtection()
    .PersistKeysToFileSystem(new DirectoryInfo(@"\\fileserver\doconut-keys"))   // משותף על ידי כל node
    .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);

    // קשר את ה‑ticket לדפדפן הזה דרך ה‑cookie שה‑read side בודק.
    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 שבו פורסם המסמך.

מיפוי הגדרה-בהגדרה

קודםעכשיו
UseDoconutWebFarm(new WebFarmOptions { … })PublishAsync(...) בצד הכתיבה ועוד UseDoconutCloud<FileShareCloudHandler>(...) בצד הקריאה
WebFarmOptions.PathFileShareConfig.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.CloudDoconut.Clouds

רשימת בדיקה

  1. בנה את FileShareConfig בעוזר אחד, רשום אותו פעם אחת, והשתמש בו משני החצאים.
  2. הצב את RootPath על השיתוף שבו אתה כבר משתמש.
  3. פרסם עם PublishAsync(...); מחק כל קריאות ExportToPng / ExportToCloud.
  4. הגש עם UseDoconutCloud<FileShareCloudHandler>(...) על הסניף שהלקוח קורא.
  5. בפרסום רקע, הפעל את FirstPagePriority ו-retryOn409 יחד, ותן לצד הקריאה ערך ReadReadyPollMs שאינו אפס.
  6. החלף את בדיקת הפר-סשן בכרטיסי גישה חתומים — טבעת מפתחות Data Protection אחת על כל צומת, UseDoconutDistributedDocumentSecurity() על סניף הקריאה, כרטיס מהקצה הפתוח — ואל תשלח את UnsafeMode = true לבד.
  7. אמת על ידי פתיחת מסמך בצומת אחד ובקשת דף מאוחר מאחרת.

האם דף זה היה מועיל?