การปรับใช้แบบกระจาย
ให้บริการเอกสารหนึ่งจากหลายโหนด
เมื่อหลายโหนดให้บริการเอกสารเดียวกัน โหนดที่ทำการเรนเดอร์เอกสารไม่จำเป็นต้องเป็นโหนดที่ตอบคำขอหน้าเว็บของเบราว์เซอร์ Doconut แบ่งงานนั้นออกเป็นสองส่วนที่ชัดเจน — ด้านเขียน ที่เผยแพร่ศิลปวัตถุของเอกสารไปยังที่เก็บข้อมูลร่วม, และ ด้านอ่าน ที่ให้บริการจากโหนดใดก็ได้.
โหนดเดียวไม่จำเป็นต้องใช้สิ่งเหล่านี้: เส้นทาง OpenDocumentAsync ปกติจะเก็บเอกสารไว้ในหน่วยความจำของโหนดนั้นและผูกกับเซสชันของเบราว์เซอร์ (ดู เซสชันและความปลอดภัย). ใช้หน้านี้เมื่อคำขอหน้าเว็บอาจไปยังโหนดที่ไม่เคยเปิดเอกสาร.
วิธีการที่สองส่วนทำงานร่วมกัน
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.
| Property | วัตถุประสงค์ |
|---|---|
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. ตั๋วจะส่งไปยังเบราว์เซอร์เช่นเดียวกับตั๋วผู้ชมปกติ. ในฟาร์ม, จุดสิ้นสุดยังคืนตั๋วการเข้าถึงที่ลงลายเซ็น — ดู ความปลอดภัยข้ามโหนด.
ด้านการอ่าน — ให้บริการจากการแชร์
เมานท์ตัวจัดการ FileShare บนสาขาที่ไคลเอนต์เรียก — /doconut, ตรงกับ BasePath: 'doconut' — อยู่หลังการตรวจสอบตั๋ว:
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:
builder.Services.AddDoconut(options => { /* … */ });
builder.Services.AddDoconutDistributedAsyncPublish();หากไม่มีการลงทะเบียนนี้ จะไม่มีการลงทะเบียนใด ๆ และการเผยแพร่จะคงเป็นแบบ synchronous เหมือนเดิม.
จากนั้นเรียก 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 แบบ synchronous จะละเลยมัน, เนื่องจากผู้เรียกของมันรอเอกสารทั้งหมดอยู่แล้ว.
สิ่งนี้ย้ายการรอไปยังไคลเอนต์, ซึ่งมีขอบเขตและมองเห็นได้. เปิดใช้งานการลองใหม่บนวิดเจ็ต:
const objViewer = $('#div_ctlDoc').docViewer({
BasePath: 'doconut',
ResPath: 'doconut-res/images',
retryOn409: true // การลองใหม่ 202 (และ legacy 409) การตอบสนองความพร้อม
});ไคลเอนต์ที่ ไม่ ทำการลองใหม่จะแสดงไทล์ที่เสียสำหรับหน้าที่ยังกำลังเรนเดอร์. งบประมาณการลองใหม่และค่าเริ่มต้นของมัน (retryInitialDelayMs, retryBackoffFactor, retryMaxDelayMs, retryMaxAttempts, retryMaxTotalMs) ได้รับการอธิบายใน การกำหนดค่า Viewer.
ความปลอดภัยข้ามโหนด
โทเคนที่ผูกกับเซสชันสมมติว่าโหนดที่ให้บริการเห็นคำขอเปิดต้นทาง แต่ในฟาร์มโหนดอาจไม่ได้เห็น ทำให้การตรวจสอบต่อเซสชันจะปฏิเสธคำขอที่ถูกต้อง; ดังนั้นฟาร์มจึงตั้งค่า 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(). ดูที่ เซสชันและความปลอดภัย.
ปิดเอกสารที่เผยแพร่
CloseDocument(token) บน Viewer ที่ฉีดเข้ามาจะทำลายเซสชันในเครื่อง. เพื่อเอาส่วนประกอบที่เผยแพร่ของเอกสารออกจากแชร์, ผู้เผยแพร่เปิดให้:
bool CloseDistributedDocument(FileShareConfig fileShareConfig, string token)ส่ง FileShareConfig เดียวกันที่ใช้ในการเผยแพร่เอกสาร.
รายการตรวจสอบ
- สร้าง
FileShareConfigในตัวช่วยเดียว, ลงทะเบียนครั้งเดียว, และใช้จากทั้งสองส่วน. - ชี้
RootPathไปที่โฟลเดอร์ที่ทุกโหนดสามารถเข้าถึงได้. - เผยแพร่ด้วย
PublishAsync(...), หรือEnqueueAsync(...)พร้อมการเผยแพร่แบบพื้นหลัง. - ให้บริการด้วย
UseDoconutCloud<FileShareCloudHandler>(...)บนสาขาที่ลูกค้าเรียก. - เมื่อใช้การเผยแพร่แบบพื้นหลัง, เปิดใช้งาน
FirstPagePriorityและretryOn409พร้อมกัน, และให้ด้านการอ่านค่าReadReadyPollMsที่ไม่เป็นศูนย์. - แทนที่การตรวจสอบต่อเซสชันด้วยตั๋วการเข้าถึงที่ลงลายเซ็น — แหวนคีย์ Data Protection หนึ่งชุดบนทุกโหนด,
UseDoconutDistributedDocumentSecurity()บนสาขาการอ่าน, ตั๋วจากปลายทางเปิด — และห้ามจัดส่งUnsafeMode = trueเพียงอย่างเดียว. - ตรวจสอบโดยการเปิดเอกสารบนโหนดหนึ่งและขอหน้าที่ล่าช้าจากอีกโหนดหนึ่ง.
หน้านี้เป็นประโยชน์หรือไม่?