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 render 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. Doconut chia công việc này thành hai nửa rõ ràng — một bên ghi xuất bản các artefact của tài liệu vào bộ nhớ chia sẻ, và một bên đọc phục vụ chúng từ bất kỳ nút nào.

Một nút duy nhất không cần bất kỳ điều này: đường dẫn OpenDocumentAsync bình thường giữ tài liệu trong bộ nhớ của nút đó và gắn nó vào phiên trình duyệt (xem Phiên làm việc & Bảo mật). Sử dụng trang này khi các yêu cầu trang có thể đến một nút chưa từng mở tài liệu.

Cách hai nửa này khớp nhau

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

Cấu hình chia sẻ mà cả hai nửa cần

Trình xuất bản ghi bằng một FileShareConfig, và trình xử lý đọc cũng sử dụng cùng một đối tượng để phục vụ. 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 nửa đọc cùng một đối tượng:

csharp
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,
    };
}

Chuyển 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.

Thuộc tínhMục đích
LocationCloudLocation.FileShare cho một chia sẻ UNC/cục bộ
RootPathThư mục chia sẻ mà mọi nút có thể truy cập
UsePerTokenSubfoldersGiữ 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)
ReadReadyPollMsThời gian mà bê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ộ

Bê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ẽ render 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:

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 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 bình thường. Trong một farm, endpoint cũng trả về một vé truy cập có chữ ký — xem Bảo mật trên các nút.

Mặt đọc — phục vụ từ chia sẻ

Gắn trình xử lý FileShare vào nhánh mà client gọi — /doconut, khớp với BasePath: 'doconut' — phía sau kiểm tra vé:

csharp
var app = builder.Build();

app.UseDoconutResources();
app.Map("/doconut", 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 nhận provider làm đối số kiểu. 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 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:

csharp
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ộ, giống 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 sẽ bỏ qua nó.) Hàng đợi có giới hạn: khi nó đầy, EnqueueAsync ném DistributedPublishQueueFullException. Trả lời bằng một 503 và một header Retry-After để client giảm tốc thay vì bị treo:

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);
    }
});

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 đó. Mặt đọ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 theo token (UsePerTokenSubfolders = true); PublishAsync đồng bộ bỏ qua nó, vì người gọi của nó luô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ể quan sát. Bật retry trên widget:

javascript
const objViewer = $('#div_ctlDoc').docViewer({
    BasePath:   'doconut',
    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 Cấu hình Viewer.

Bảo mật trên các nút

Các token gắn với phiên giả định nút phục vụ đã nhìn thấy yêu cầu mở đầu. Trong một cụm, nó không như vậy, 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 sẽ 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 nữa. 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 thành phần hoạt động 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 nhau không thể đọc vé mà nút khác đã phát hành.

csharp
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 vé khi tài liệu được mở. Vé ghi tên token, trình duyệt (qua một cookie mà phía đọc so sánh), và người dùng đã đăng nhập, nếu có:

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);

    // Liên kết vé này 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:

javascript
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 hình ảnh lỗi UnauthorizedMessage cho các yêu cầu trang và hình thu nhỏ, nếu không 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 một nút duy nhấ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 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:

text
bool CloseDistributedDocument(FileShareConfig fileShareConfig, string token)

Cung cấp cùng FileShareConfig mà tài liệu đã được xuất bản bằng.

Danh sách kiểm tra

  1. Xây dựng FileShareConfig trong một helper, đăng ký một lần, và sử dụng nó từ cả hai nửa.
  2. Chỉ định RootPath tới một thư mục mà mọi nút đều có thể truy cập.
  3. Xuất bản bằng PublishAsync(...), hoặc EnqueueAsync(...) với việc xuất bản nền.
  4. Phục vụ bằng UseDoconutCloud<FileShareCloudHandler>(...) trên nhánh mà khách hàng gọi.
  5. Khi xuất bản nền, bật FirstPagePriority và retryOn409 cùng lúc, và cung cấp cho phía đọc một ReadReadyPollMs không bằng không.
  6. 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ửi UnsafeMode = true một mình.
  7. 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 muộn từ nút khác.

Trang này có hữu ích không?