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

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

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

โหนดเดียวไม่จำเป็นต้องใช้สิ่งเหล่านี้: เส้นทาง 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ระยะเวลาที่ read side รอหน้าที่การเผยแพร่ในพื้นหลังยังคงเขียนอยู่; 0 (ค่าเริ่มต้น) ตรวจสอบหนึ่งครั้ง. ไม่มีผลต่อเอกสารที่เผยแพร่แบบซิงโครนัส

Write side — เผยแพร่เอกสาร

ฉีด 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 เรนเดอร์เอกสารทั้งหมดก่อนจะคืนค่า. เพื่อให้คืนค่าโดยเร็วเมื่อโทเคนถูกสร้างและให้ 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:   'doconut',
    ResPath:    'doconut-res/images',
    retryOn409: true      // การลองใหม่ 202 (และ legacy 409) การตอบสนองความพร้อม
});

ไคลเอนต์ที่ ไม่ ทำการลองใหม่จะแสดงไทล์ที่เสียหายสำหรับหน้าที่ยังอยู่ระหว่างการเรนเดอร์. งบประมาณการลองใหม่และค่าเริ่มต้นของมัน (retryInitialDelayMs, retryBackoffFactor, retryMaxDelayMs, retryMaxAttempts, retryMaxTotalMs) ถูกอธิบายไว้ใน ViewerConfig.

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

โทเคนที่ผูกกับเซสชันสมมติว่าโหนดที่ให้บริการเห็นคำขอเปิดต้นทาง ในฟาร์มมันไม่ได้เห็น ดังนั้นการตรวจสอบต่อเซสชันจะปฏิเสธคำขอที่ถูกต้อง; ดังนั้นฟาร์มจึงตั้งค่า 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(). ดูที่ เซสชันและความปลอดภัย.

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

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

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