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

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

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

צומת יחיד אינו זקוק לכל זה: הנתיב הרגיל OpenDocumentAsync שומר את המסמך בזיכרון של הצומת ומקשר אותו למושב הדפדפן (ראה Sessions & Security). השתמש בדף זה כאשר בקשות דף יכולות להגיע לצומת שמעולם לא ראה את הפתיחה.

איך שני החצאים מתאימים

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שמור את artefacts של כל מסמך בתיקייה משלו של {token} (ברירת מחדל true)
ReadReadyPollMsכמה זמן צד הקריאה מחכה לדף שפרסום ברקע עדיין כותב; 0 (ברירת המחדל) בודק פעם אחת. אין לזה השפעה על מסמכים שפורסמו באופן סינכרוני

צד כתיבה — פרסום המסמך

הזרק DistributedDocumentPublisher ופרסם במקום לפתוח מושב מקומי. קריאה אחת מרנדרת וכותבת את כל קבוצת ה‑artefacts — דפים, מידע על המסמך, אינדקס חיפוש, ו‑metadata — ומחזירה כאשר היא הסתיימה:

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. החלף את הבדיקה לכל סשן בכרטיסי גישה חתומים — טבעת מפתחות של Data Protection אחת על כל צומת, UseDoconutDistributedDocumentSecurity() על סניף הקריאה, כרטיס מהקצה הפתוח — ואל תשלח את UnsafeMode = true לבד.
  7. אמת על‑ידי פתיחת מסמך בצומת אחד ובקשת דף מאוחר מאחרת.

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