Triển khai Phân tán
Phục vụ một tài liệu từ nhiều nút
Khi nhiều nút phục vụ cùng một tài liệu, nút thực hiện việc kết xuất tài liệu không nhất thiết là nút trả lời các yêu cầu trang của trình duyệt. Bản phát hành này chia công việc đó thành hai phần rõ ràng — một phần ghi xuất bản các artefact của tài liệu vào bộ nhớ chia sẻ, và một phần đọc phục vụ chúng từ bất kỳ nút nào.
Nếu ứng dụng của bạn hiện đang gọi UseDoconutWebFarm(...), trang này là sự thay thế cho nó. Cả UseDoconutWebFarm và WebFarmOptions đều không tồn tại trong bản phát hành này.
Kiến trúc của bạn không thay đổi. Đặt gốc chia sẻ vào cùng đường UNC mà bạn đang dùng hôm nay và mọi nút sẽ tiếp tục hoạt động như hiện tại. Điều thay đổi là việc xuất bản trở thành một thao tác bạn gọi, thay vì là hiệu ứng phụ của quá trình kết xuất.
Điều gì đã thay thế middleware web-farm
Trước đây một middleware thực hiện mọi việc: nó phục vụ các hình ảnh được kết xuất trước từ một thư mục chia sẻ và được kiểm tra định kỳ trong khi một nút khác vẫn đang ghi chúng. Thời gian chờ là một ngân sách mù — “khóa tối đa ba phút hy vọng trang xuất hiện”.
Bây giờ cùng một công việc được chia thành hai lời gọi mà bạn có thể thấy và suy xét:
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 pageCấu hình chung mà cả hai phần cần
Bộ xuất bản ghi bằng một FileShareConfig và trình xử lý đọc phục vụ bằng một. Nếu RootPath hoặc UsePerTokenSubfolders khác nhau giữa chúng, nút còn lại sẽ trả về 404. Xây dựng cấu hình ở đúng một nơi và đăng ký một lần, để cả hai phần đều đọc cùng một đối tượng:
var rootPath = builder.Configuration["Doconut:SharedRoot"]!; // ví dụ: \\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,
};
}Gửi asyncPublish: true khi bạn bật xuất bản nền.
FileShareConfig nằm trong Doconut.Clouds, cùng với AzureConfig, AmazonConfig, GoogleCloudConfig, DropBoxConfig, RedisConfig, CDNConfig, và FTPConfig. Trong thư viện trước đây chúng nằm trong Doconut.Configs.Cloud; tên lớp không thay đổi.
| Thuộc tính | Mục đích |
|---|---|
Location | CloudLocation.FileShare cho một chia sẻ UNC/cục bộ |
RootPath | Thư mục chia sẻ mà mọi nút có thể truy cập |
UsePerTokenSubfolders | Giữ các artefact của mỗi tài liệu trong thư mục {token} riêng của nó (mặc định true) |
ReadReadyPollMs | Thời gian mà phần đọc chờ một trang mà quá trình xuất bản nền vẫn đang ghi; 0 (mặc định) kiểm tra một lần. Nó không ảnh hưởng đến các tài liệu được xuất bản đồng bộ |
Phần ghi — xuất bản tài liệu
Tiêm DistributedDocumentPublisher và xuất bản thay vì mở một phiên cục bộ. Một lời gọi sẽ kết xuất và ghi toàn bộ bộ artefact — các trang, thông tin tài liệu, chỉ mục tìm kiếm và siêu dữ liệu — và trả về khi hoàn thành:
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 mang Token, ArtifactPath, TotalPages, và Format. Token này được gửi tới trình duyệt chính xác như một token viewer thông thường. Trong một cụm, điểm cuối cũng trả về một ticket truy cập có chữ ký — xem Bảo mật giữa các nút.
Lời gọi duy nhất này thay thế cặp trước — mở tài liệu vào một phiên cục bộ và sau đó đổ hình ảnh lên chia sẻ bằng ExportToPng(sharedPath). ExportToPng và ExportToCloud không có tương đương ở đây.
Bên đọc — phục vụ từ chia sẻ
Gắn trình xử lý FileShare vào cùng nhánh mà client đã gọi, phía sau kiểm tra vé:
var app = builder.Build();
app.UseDoconutResources();
app.MapWhen(
ctx => ctx.Request.Path.Value?.EndsWith("DocImage.axd", StringComparison.OrdinalIgnoreCase) == true,
branch =>
{
branch.UseDoconutDistributedDocumentSecurity(); // vé đã ký — xem bên dưới
branch.UseDoconutCloud<FileShareCloudHandler>(options =>
{
options.Location = CloudLocation.FileShare;
options.CloudUploadConfig = app.Services.GetRequiredService<FileShareConfig>();
}, "/");
});UseDoconutCloud là generic trong phiên bản này: nhà cung cấp là đối số kiểu thay vì một giá trị Location được chuyển đổi bên trong middleware. Các trình xử lý được đặt tên <Provider>CloudHandler — FileShareCloudHandler, AzureCloudHandler, AmazonS3CloudHandler, GoogleCloudHandler, DropBoxCloudHandler, RedisCloudHandler, FTPCloudHandler, và CDNCloudHandler. Với tiền tố đường dẫn "/", trình xử lý trả lời mọi yêu cầu đến nhánh của nó.
Trình xử lý CDN là chỉ-đọc — nó phục vụ những gì đã có trên CDN; nó không tải lên.
Tùy chọn: xuất bản trong nền
Mặc định, PublishAsync sẽ render toàn bộ tài liệu trước khi trả về. Để trả về ngay khi token được tạo và cho phép một worker được lưu trữ render vào cùng thư mục, đăng ký hàng đợi opt-in, và xây dựng cấu hình chia sẻ với asyncPublish: true:
builder.Services.AddDoconut(options => { /* … */ });
builder.Services.AddDoconutDistributedAsyncPublish();Nếu không có đăng ký này, không có gì được đăng ký và việc xuất bản vẫn đồng bộ, chính xác như trước.
Sau đó gọi EnqueueAsync thay vì PublishAsync. (DistributedDocumentPublishOptions.Async chỉ là một cờ mà mã của bạn có thể đọc để chọn giữa hai đường dẫn; nhà xuất bản bỏ qua nó.) Hàng đợi có giới hạn: khi bị đầy, EnqueueAsync ném DistributedPublishQueueFullException. Trả lời nó bằng một 503 và một header Retry-After để client giảm tốc thay vì bị treo:
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);
}
});Các trang chưa được viết: HTTP 202
Với việc xuất bản nền, một yêu cầu trang có thể đến trước khi worker đã ghi trang đó. Bên đọc chờ tối đa ReadReadyPollMs và sau đó trả lời HTTP 202 Accepted thay vì chặn yêu cầu.
FirstPagePriority = true rút ngắn thời gian chờ cho lần xem đầu tiên: trang 1 được ghi vào thư mục của tài liệu trước, vì vậy tài liệu mở trong khi các trang sau vẫn đang render. Nó chỉ áp dụng cho việc xuất bản nền vào các thư mục per-token (UsePerTokenSubfolders = true); PublishAsync đồng bộ bỏ qua nó, vì người gọi của nó vẫn chờ toàn bộ tài liệu.
Điều này chuyển thời gian chờ sang client, nơi nó có giới hạn và có thể nhìn thấy. Bật tính năng retry trên widget:
const objViewer = $('#div_ctlDoc').docViewer({
BasePath: '/',
ResPath: 'doconut-res/images',
retryOn409: true // các lần thử lại 202 (và legacy 409) phản hồi sẵn sàng
});Một client không thực hiện retry sẽ hiển thị các ô bị hỏng cho các trang vẫn đang render. Ngân sách retry và các giá trị mặc định của nó (retryInitialDelayMs, retryBackoffFactor, retryMaxDelayMs, retryMaxAttempts, retryMaxTotalMs) được tài liệu hoá trong ViewerConfig.
Cặp này — xuất bản nền với FirstPagePriority, cộng với việc poll phía đọc — là những gì thay thế các cài đặt PageWaitTimeSeconds và StartWaitFromPage trước đây. Cả hai đều không còn tồn tại.
Bảo mật trên các nút
Các token ràng buộc phiên giả định nút phục vụ đã thấy yêu cầu mở đầu. Trong một cụm nó không, vì vậy kiểm tra theo phiên sẽ từ chối các yêu cầu hợp lệ; do đó một cụm thiết lập UnsafeMode = true.
UnsafeMode = true không phải là mô hình bảo mật — nó là việc loại bỏ một mô hình không còn áp dụng. Thay thế nó bằng các vé truy cập có chữ ký, mà mỗi nút có thể xác minh độc lập. Bốn phần làm việc cùng nhau.
1. Đăng ký bảo mật vé trên mỗi nút. Các vé được bảo vệ bằng ASP.NET Core Data Protection, vì vậy mỗi nút phải sử dụng cùng một vòng khóa và tên ứng dụng; một nút có khóa khác không thể đọc vé mà nút khác phát hành.
using Microsoft.AspNetCore.DataProtection;
builder.Services.AddDataProtection()
.PersistKeysToFileSystem(new DirectoryInfo(@"\\fileserver\doconut-keys")) // được chia sẻ bởi mọi nút
.SetApplicationName("doconut-farm");
builder.Services.AddDoconut(options => options.UnsafeMode = true);
builder.Services.AddDoconutDistributedDocumentSecurity(options =>
{
options.TicketLifetimeMinutes = 60; // mặc định
});2. Kiểm tra vé ở phía đọc. UseDoconutDistributedDocumentSecurity() được đặt trên nhánh đọc trước UseDoconutCloud, như trong mẫu phía đọc.
3. Phát hành một vé khi tài liệu được mở. Vé ghi lại token, trình duyệt (thông qua cookie mà phía đọc so sánh), và người dùng đã đăng nhập, nếu có:
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);
// Liên kết vé với trình duyệt này thông qua cookie mà phía đọc kiểm tra.
var cookieName = security.Value.BrowserCookieName; // "doconut-client" mặc định
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. Truyền cả hai cho widget. Trình xem gửi vé dưới dạng access với mỗi yêu cầu:
const resp = await fetch('/api/open?fileName=Sample.pdf', { method: 'POST' });
const { token, access } = await resp.json();
objViewer.View(token, access);Phía đọc từ chối một yêu cầu mà vé bị thiếu, không hợp lệ, được phát hành cho token khác, đã hết hạn, gắn với cookie trình duyệt khác, hoặc được phát hành cho người dùng đã đăng nhập khác. Nó trả về 403 — kèm theo hình ảnh lỗi UnauthorizedMessage cho các yêu cầu trang và hình thu nhỏ, còn lại là văn bản thuần. Hãy thử với trình duyệt thực hoặc một client giữ cookie.
Không bao giờ mang UnsafeMode = true trở lại triển khai đơn nút, và không bao giờ coi nó như một lối tắt cho việc kiểm tra phiên thất bại trên một nút — ở đó cách khắc phục đúng là AddSession() / UseSession(). Xem Phiên và Bảo mật.
Đóng tài liệu đã xuất bản
CloseDocument(token) trên Viewer được tiêm vào sẽ giải phóng một phiên cục bộ. Để xóa các artefact đã xuất bản của tài liệu khỏi chia sẻ, nhà xuất bản cung cấp:
bool CloseDistributedDocument(FileShareConfig fileShareConfig, string token)Cung cấp cùng FileShareConfig mà tài liệu đã được xuất bản cùng.
Ánh xạ từng cài đặt
| Trước đây | Hiện tại |
|---|---|
UseDoconutWebFarm(new WebFarmOptions { … }) | PublishAsync(...) trên phía ghi cộng với UseDoconutCloud<FileShareCloudHandler>(...) trên phía đọc |
WebFarmOptions.Path | FileShareConfig.RootPath |
PageWaitTimeSeconds / StartWaitFromPage | Xuất bản nền với DistributedDocumentPublishOptions.FirstPagePriority, cộng với FileShareConfig.ReadReadyPollMs |
viewer.OpenDocument(...) then viewer.ExportToPng(share) | một cuộc gọi PublishAsync(...) |
viewer.ExportToCloud(cloudConfig) | PublishAsync(...) với cấu hình của nhà cung cấp |
UseDoconutCloud(new CloudOptions { Location = … }) | UseDoconutCloud<THandler>(options => …, pathPrefix) |
DocOptions.IsWebfarm / WebfarmPath | Vẫn tồn tại, viết là IsWebFarm / WebFarmPath — không cần trên đường xuất bản |
Doconut.Configs.Cloud | Doconut.Clouds |
Danh sách kiểm tra
- Xây dựng
FileShareConfigtrong một helper, đăng ký một lần, và sử dụng nó từ cả hai nửa. - Chỉ định
RootPathtới chia sẻ bạn đã sử dụng. - Xuất bản với
PublishAsync(...); xóa mọi cuộc gọiExportToPng/ExportToCloud. - Phục vụ với
UseDoconutCloud<FileShareCloudHandler>(...)trên nhánh mà client gọi. - Với xuất bản nền, bật
FirstPagePriorityvàretryOn409cùng lúc, và cung cấp cho phía đọc mộtReadReadyPollMskhác không. - Thay thế kiểm tra theo phiên bằng vé truy cập có chữ ký — một vòng khóa Data Protection trên mỗi nút,
UseDoconutDistributedDocumentSecurity()trên nhánh đọc, một vé từ endpoint mở — và không gửiUnsafeMode = trueriêng lẻ. - Xác minh bằng cách mở một tài liệu trên một nút và yêu cầu một trang trễ từ nút khác.
Trang này có hữu ích không?