การปรับใช้แบบกระจาย

ให้บริการเอกสารหนึ่งจากหลายโหนด

เมื่อหลายโหนดให้บริการเอกสารเดียวกัน โหนดที่ทำการเรนเดอร์เอกสารไม่ได้จำเป็นต้องเป็นโหนดที่ตอบสนองคำขอหน้าเว็บของเบราว์เซอร์ รุ่นนี้จะแยกงานนั้นออกเป็นสองส่วนที่ชัดเจน — ด้านเขียน ที่เผยแพร่ศิลปวัตถุของเอกสารไปยังที่เก็บข้อมูลร่วม, และ ด้านอ่าน ที่ให้บริการจากโหนดใดก็ได้

หากแอปพลิเคชันของคุณในขณะนี้เรียก 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. โทเค็นจะส่งไปยังเบราว์เซอร์เช่นเดียวกับโทเค็นผู้ชมปกติ ในฟาร์ม, จุดสิ้นสุดยังคืนตั๋วการเข้าถึงที่ลงลายเซ็น — ดูที่ Security across nodes.

การเรียกเดียวนี้แทนที่คู่ก่อนหน้า — การเปิดเอกสารเข้าสู่เซสชันโลคัลและจากนั้นดัมพ์รูปภาพลงบนแชร์ด้วย 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 เรนเดอร์เอกสารทั้งหมดก่อนจะคืนค่า. เพื่อให้คืนค่าทันทีที่โทเคนถูกสร้างและให้ worker ที่โฮสต์เรนเดอร์ลงในโฟลเดอร์เดียวกัน, ลงทะเบียนคิว opt‑in, และสร้างการกำหนดค่าที่แชร์ด้วย 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

ด้วยการเผยแพร่ในพื้นหลัง, คำขอหน้าอาจมาถึงก่อนที่ worker จะเขียนหน้านั้น. ด้านการอ่านจะรอสูงสุดถึง 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) ได้รับการบันทึกใน การกำหนดค่า Viewer.

คู่นี้ — การเผยแพร่ในพื้นหลังกับ FirstPagePriority, พร้อมกับการโพลด้านการอ่าน — คือสิ่งที่แทนที่การตั้งค่า PageWaitTimeSeconds และ StartWaitFromPage ก่อนหน้า. ทั้งสองไม่มีอยู่แล้ว.

ความปลอดภัยข้ามโหนด

โทเค็นที่ผูกกับเซสชันถือว่าตัวโหนดที่ให้บริการได้เห็นคำขอเปิด. ในฟาร์มซึ่งไม่ได้เห็นคำขอนั้น, การตรวจสอบต่อเซสชันจึงปฏิเสธคำขอที่ถูกต้อง; ดังนั้นฟาร์มจึงตั้งค่า UnsafeMode = true.

UnsafeMode = true ไม่ใช่โมเดลความปลอดภัย — มันเป็นการลบโมเดลที่ไม่ใช้แล้ว. แทนที่ด้วยตั๋วการเข้าถึงที่ลงลายเซ็น, ซึ่งแต่ละโหนดสามารถตรวจสอบได้อย่างอิสระ. สี่ส่วนทำงานร่วมกัน.

1. ลงทะเบียนความปลอดภัยของตั๋วบนทุกโหนด. ตั๋วได้รับการปกป้องด้วย ASP.NET Core Data Protection, ดังนั้นทุกโหนดต้องใช้ key ring และชื่อแอปพลิเคชันเดียวกัน; โหนดที่ใช้คีย์ต่างกันจะไม่สามารถอ่านตั๋วที่โหนดอื่นออกให้ได้.

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(). ดูที่ Sessions & Security.

ปิดเอกสารที่เผยแพร่

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() บนสาขาอ่าน, ตั๋วจาก endpoint เปิด — และห้ามส่ง UnsafeMode = true เพียงอย่างเดียว.
  7. ตรวจสอบโดยเปิดเอกสารบนโหนดหนึ่งและขอหน้าที่ล่าช้าจากอีกโหนดหนึ่ง.

หน้านี้เป็นประโยชน์หรือไม่?