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

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

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

זה מעביר את ההמתנה ללקוח, שם היא מוגבלת ונראית. אפשרו נסיונות חוזרים ב‑widget:

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. אמת על ידי פתיחת מסמך בצומת אחד ובקשת דף מאוחר מצומת אחר.

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