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 thành phần 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 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 chung mà cả hai nửa cần

Trình xuất bản ghi bằng một FileShareConfig và bộ 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 ở một nơi duy nhất 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,
    };
}

Cung cấp asyncPublish: true khi bạn bật đăng tải 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 thành phần 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 đăng tải 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ộ thành phần — 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 giống như một token viewer bình thường. Trong một cụm, endpoint cũng trả về một vé truy cập có chữ ký — xem Bảo mật giữa 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ủa nó. 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

Theo mặc định, PublishAsync 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ộ, 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 đi; nhà xuất bản sẽ bỏ qua nó.) Hàng đợi có giới hạn: khi nó 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:

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 ghi: 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 viết 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 per-token (UsePerTokenSubfolders = true); PublishAsync đồng bộ bỏ qua nó, vì người gọi của nó chờ toàn bộ tài liệu dù sao.

Điều này chuyển việc chờ sang client, nơi nó có giới hạn và hiển thị. Bật retry trên widget:

javascript
const objViewer = $('#div_ctlDoc').docViewer({
    BasePath:   'doconut',
    ResPath:    'doconut-res/images',
    retryOn409: true      // retries 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ụ đã thấy yêu cầu mở đầu. Trong một farm, nó không thấ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 farm 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 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 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 một vé khi tài liệu được mở. Vé ghi tên 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ó:

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é 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ỏ, còn lại dưới dạng văn bản thuần. Hãy thử nghiệm bằng 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 & Bảo mật.

Đóng tài liệu đã xuất bản

CloseDocument(token) trên Viewer được tiêm vào giải phóng một phiên cục bộ. Để loại bỏ 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ỉ tới 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 xuất bản nền.
  4. Phục vụ bằng UseDoconutCloud<FileShareCloudHandler>(...) trên nhánh mà client gọi.
  5. Khi sử dụng 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ác không.
  6. Thay thế kiểm tra per-session 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?