การปรับใช้แบบกระจาย
ให้บริการเอกสารหนึ่งจากหลายโหนด
เมื่อหลายโหนดให้บริการเอกสารเดียวกัน โหนดที่ทำการเรนเดอร์เอกสารไม่ได้จำเป็นต้องเป็นโหนดที่ตอบสนองคำขอหน้าเว็บของเบราว์เซอร์ รุ่นนี้จะแยกงานนั้นออกเป็นสองส่วนที่ชัดเจน — ด้านเขียน ที่เผยแพร่ศิลปวัตถุของเอกสารไปยังที่เก็บข้อมูลร่วม, และ ด้านอ่าน ที่ให้บริการจากโหนดใดก็ได้
หากแอปพลิเคชันของคุณในขณะนี้เรียก UseDoconutWebFarm(...), หน้านี้คือตัวทดแทนของคุณ ไม่มี UseDoconutWebFarm หรือ WebFarmOptions อยู่ในรุ่นนี้
โครงสร้างของคุณไม่เปลี่ยนแปลง ตั้งค่ารากที่แชร์ให้ชี้ไปยังเส้นทาง UNC เดียวกับที่คุณใช้วันนี้และทุกโหนดจะทำงานต่อไปเช่นเดิม สิ่งที่เปลี่ยนคือการเผยแพร่เป็นการดำเนินการที่คุณเรียกใช้, แทนที่จะเป็นผลข้างเคียงของการเรนเดอร์
สิ่งที่แทนที่ middleware web-farm
ก่อนหน้านี้ middleware ตัวเดียวทำทุกอย่าง: ให้บริการรูปภาพที่เรนเดอร์ล่วงหน้าออกจากโฟลเดอร์ที่แชร์และ โพล ขณะที่โหนดอื่นยังคงเขียนอยู่ การรอคอยเป็นงบประมาณที่ไม่มีข้อมูล — "บล็อกสูงสุดสามนาทีโดยคาดว่าหน้าจะปรากฏ"
ตอนนี้งานเดียวกันถูกแบ่งเป็นสองการเรียกที่คุณสามารถมองเห็นและทำเหตุผลได้:
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 สร้างการกำหนดค่าในที่เดียวเท่านั้นและลงทะเบียนเพียงครั้งเดียว, เพื่อให้ทั้งสองส่วนอ่านอ็อบเจ็กต์เดียวกัน:
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; ชื่อคลาสไม่ได้เปลี่ยนแปลง
| คุณสมบัติ | วัตถุประสงค์ |
|---|---|
Location | CloudLocation.FileShare สำหรับการแชร์ UNC/โลคัล |
RootPath | โฟลเดอร์ที่แชร์ที่ทุกโหนดสามารถเข้าถึงได้ |
UsePerTokenSubfolders | เก็บศิลปวัตถุของแต่ละเอกสารไว้ในโฟลเดอร์ {token} ของตนเอง (ค่าเริ่มต้น true) |
ReadReadyPollMs | ระยะเวลาที่ด้านอ่านรอหน้าที่การเผยแพร่เบื้องหลังยังคงเขียนอยู่; 0 (ค่าเริ่มต้น) ตรวจสอบหนึ่งครั้ง. ไม่มีผลต่อเอกสารที่เผยแพร่แบบซิงโครนัส |
ด้านเขียน — เผยแพร่เอกสาร
ฉีด DistributedDocumentPublisher และเผยแพร่แทนการเปิดเซสชันโลคัล การเรียกหนึ่งครั้งจะเรนเดอร์และเขียนชุดศิลปวัตถุครบชุด — หน้า, ข้อมูลเอกสาร, ดัชนีการค้นหา, และเมตาดาต้า — และคืนค่าตอนเสร็จสิ้น:
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 บนสาขาเดียวกับที่ไคลเอนต์เรียกอยู่แล้ว, หลังการตรวจสอบตั๋ว:
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:
builder.Services.AddDoconut(options => { /* … */ });
builder.Services.AddDoconutDistributedAsyncPublish();หากไม่มีการลงทะเบียนนี้ จะไม่มีการลงทะเบียนใด ๆ และการเผยแพร่จะคงเป็นแบบซิงโครนัส, เหมือนเดิม
จากนั้นเรียก EnqueueAsync แทน PublishAsync. (DistributedDocumentPublishOptions.Async เป็นเพียงแฟล็กที่โค้ดของคุณเองสามารถอ่านเพื่อเลือกเส้นทางระหว่างสองทาง; ผู้เผยแพร่จะละเลยมัน.) คิวมีขอบเขต: เมื่อเต็ม, EnqueueAsync จะโยน DistributedPublishQueueFullException. ตอบกลับด้วย 503 และหัวข้อ Retry-After เพื่อให้ไคลเอนต์ถอยหลังแทนที่จะค้าง:
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 แบบซิงโครนัสจะละเลยมัน, เนื่องจากผู้เรียกจะรอเอกสารทั้งหมดอยู่แล้ว
สิ่งนี้ย้ายการรอไปยังไคลเอนต์, ที่ซึ่งมันมีขอบเขตและมองเห็นได้. เปิดใช้งานการลองใหม่บนวิดเจ็ต:
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 และชื่อแอปพลิเคชันเดียวกัน; โหนดที่ใช้คีย์ต่างกันจะไม่สามารถอ่านตั๋วที่โหนดอื่นออกให้ได้.
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. ออกตั๋วเมื่อเอกสารถูกเปิด. ตั๋วจะระบุโทเค็น, เบราว์เซอร์ (ผ่านคุกกี้ที่ด้านการอ่านเปรียบเทียบ), และผู้ใช้ที่เข้าสู่ระบบ, หากมี:
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 กับทุกคำขอ:
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 ที่ฉีดเข้า จะทำลายเซสชันท้องถิ่น. เพื่อเอาส่วนประกอบที่เผยแพร่ของเอกสารออกจากแชร์, ผู้เผยแพร่เปิดเผย:
bool CloseDistributedDocument(FileShareConfig fileShareConfig, string token)ส่ง FileShareConfig เดียวกันที่ใช้ในการเผยแพร่เอกสาร.
การแมปตามการตั้งค่า
| ก่อนหน้า | ตอนนี้ |
|---|---|
UseDoconutWebFarm(new WebFarmOptions { … }) | PublishAsync(...) บนด้านเขียนและ UseDoconutCloud<FileShareCloudHandler>(...) บนด้านอ่าน |
WebFarmOptions.Path | FileShareConfig.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.Cloud | Doconut.Clouds |
รายการตรวจสอบ
- สร้าง
FileShareConfigในตัวช่วยเดียว, ลงทะเบียนหนึ่งครั้ง, และใช้จากทั้งสองส่วน. - ชี้
RootPathไปที่ส่วนที่คุณใช้อยู่แล้ว. - เผยแพร่ด้วย
PublishAsync(...); ลบการเรียกใด ๆ ของExportToPng/ExportToCloud. - ให้บริการด้วย
UseDoconutCloud<FileShareCloudHandler>(...)บนสาขาที่ไคลเอนต์เรียก. - เมื่อใช้การเผยแพร่เบื้องหลัง, เปิด
FirstPagePriorityและretryOn409พร้อมกัน, และให้ด้านอ่านค่าReadReadyPollMsที่ไม่เป็นศูนย์. - แทนที่การตรวจสอบต่อเซสชันด้วยตั๋วการเข้าถึงที่ลงนาม — วงแหวนคีย์ Data Protection หนึ่งวงบนทุกโหนด,
UseDoconutDistributedDocumentSecurity()บนสาขาอ่าน, ตั๋วจาก endpoint เปิด — และห้ามส่งUnsafeMode = trueเพียงอย่างเดียว. - ตรวจสอบโดยเปิดเอกสารบนโหนดหนึ่งและขอหน้าที่ล่าช้าจากอีกโหนดหนึ่ง.
หน้านี้เป็นประโยชน์หรือไม่?