การปรับใช้แบบกระจาย
ให้บริการเอกสารหนึ่งจากหลายโหนด
เมื่อหลายโหนดให้บริการเอกสารเดียวกัน โหนดที่ทำการเรนเดอร์เอกสารไม่จำเป็นต้องเป็นโหนดที่ตอบคำขอหน้าเว็บของเบราว์เซอร์ Doconut แบ่งงานนั้นออกเป็นสองส่วนที่ชัดเจน — write side ที่เผยแพร่ศิลปวัตถุของเอกสารไปยังที่เก็บข้อมูลร่วม, และ read side ที่ให้บริการจากโหนดใดก็ได้.
โหนดเดียวไม่จำเป็นต้องใช้สิ่งเหล่านี้: เส้นทาง 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.
| คุณสมบัติ | วัตถุประสงค์ |
|---|---|
Location | CloudLocation.FileShare สำหรับการแชร์ UNC/โลคัล |
RootPath | โฟลเดอร์ที่แชร์ที่ทุกโหนดสามารถเข้าถึงได้ |
UsePerTokenSubfolders | เก็บศิลปวัตถุของแต่ละเอกสารไว้ในโฟลเดอร์ {token} ของตนเอง (ค่าเริ่มต้น true) |
ReadReadyPollMs | ระยะเวลาที่ read side รอหน้าที่การเผยแพร่ในพื้นหลังยังคงเขียนอยู่; 0 (ค่าเริ่มต้น) ตรวจสอบหนึ่งครั้ง. ไม่มีผลต่อเอกสารที่เผยแพร่แบบซิงโครนัส |
Write side — เผยแพร่เอกสาร
ฉีด 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();หากไม่มีการลงทะเบียนนี้ จะไม่มีการลงทะเบียนใด ๆ และการเผยแพร่จะคงอยู่ในโหมดซิงโครนัส เหมือนเดิม.
จากนั้นเรียก 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: '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 และชื่อแอปพลิเคชันเดียวกัน; โหนดที่มีคีย์ต่างกันไม่สามารถอ่านตั๋วที่โหนดอื่นออกให้ได้.
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()บนสาขาการอ่าน, ตั๋วจาก endpoint เปิด — และห้ามจัดส่งUnsafeMode = trueเพียงอย่างเดียว. - ตรวจสอบโดยเปิดเอกสารบนโหนดหนึ่งและขอหน้าที่ล่าช้าจากอีกโหนดหนึ่ง.
หน้านี้เป็นประโยชน์หรือไม่?