Penyebaran Terdistribusi

Layani satu dokumen dari beberapa node

Ketika beberapa node melayani dokumen yang sama, node yang merender sebuah dokumen tidak selalu merupakan node yang menjawab permintaan halaman browser. Doconut membagi pekerjaan itu menjadi dua bagian eksplisit — sisi penulisan yang mempublikasikan artefak dokumen ke penyimpanan bersama, dan sisi pembacaan yang melayaninya dari node mana pun.

Sebuah node tunggal tidak memerlukan semua ini: jalur OpenDocumentAsync normal menyimpan dokumen di memori node tersebut dan mengikatnya ke sesi browser (lihat Sesi & Keamanan). Gunakan halaman ini ketika permintaan halaman dapat jatuh pada node yang belum pernah melihat pembukaan.

Cara dua bagian tersebut berpasangan

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

Konfigurasi bersama yang dibutuhkan kedua bagian

Publisher menulis dengan FileShareConfig dan handler baca melayani dengan satu. Jika RootPath atau UsePerTokenSubfolders berbeda di antara keduanya, node lain akan menjawab 404. Bangun konfigurasi di satu tempat saja dan daftarkan sekali, sehingga kedua bagian membaca objek yang sama:

csharp
var rootPath = builder.Configuration["Doconut:SharedRoot"]!;   // mis. \\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,
    };
}

Berikan asyncPublish: true ketika Anda mengaktifkan penerbitan latar belakang.

FileShareConfig berada di Doconut.Clouds, bersama dengan AzureConfig, AmazonConfig, GoogleCloudConfig, DropBoxConfig, RedisConfig, CDNConfig, dan FTPConfig.

PropertiTujuan
LocationCloudLocation.FileShare untuk berbagi UNC/lokal
RootPathFolder bersama yang dapat dijangkau oleh setiap node
UsePerTokenSubfoldersSimpan artefak setiap dokumen di folder {token} masing-masing (default true)
ReadReadyPollMsBerapa lama sisi pembacaan menunggu halaman yang masih ditulis oleh penerbitan latar belakang; 0 (default) memeriksa sekali. Tidak berpengaruh pada dokumen yang dipublikasikan secara sinkron

Sisi Penulisan — publikasikan dokumen

Sematkan DistributedDocumentPublisher dan publikasikan alih-alih membuka sesi lokal. Satu panggilan merender dan menulis set artefak lengkap — halaman, info dokumen, indeks pencarian, dan metadata — dan mengembalikan ketika selesai:

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 membawa Token, ArtifactPath, TotalPages, dan Format. Token tersebut dikirim ke browser persis seperti token penampil normal. Dalam sebuah farm, endpoint juga mengembalikan tiket akses yang ditandatangani — lihat Keamanan lintas node.

Sisi Baca — melayani dari share

Pasang penangan FileShare pada cabang yang dipanggil klien — /doconut, cocok dengan BasePath: 'doconut' — di belakang pemeriksaan tiket:

csharp
var app = builder.Build();

app.UseDoconutResources();
app.Map("/doconut", branch =>
{
    branch.UseDoconutDistributedDocumentSecurity();   // tiket yang ditandatangani — lihat di bawah
    branch.UseDoconutCloud<FileShareCloudHandler>(options =>
    {
        options.Location          = CloudLocation.FileShare;
        options.CloudUploadConfig = app.Services.GetRequiredService<FileShareConfig>();
    }, "/");
});

UseDoconutCloud mengambil penyedia sebagai argumen tipe-nya. Penangan dinamai <Provider>CloudHandler — FileShareCloudHandler, AzureCloudHandler, AmazonS3CloudHandler, GoogleCloudHandler, DropBoxCloudHandler, RedisCloudHandler, FTPCloudHandler, dan CDNCloudHandler. Dengan awalan jalur "/", penangan menjawab setiap permintaan yang mencapai cabangnya.

Penangan CDN bersifat read-only — ia melayani apa yang sudah ada di CDN; tidak mengunggah.

Opsional: terbitkan di latar belakang

Secara default PublishAsync merender seluruh dokumen sebelum mengembalikan. Untuk mengembalikan segera setelah token dibuat dan membiarkan pekerja yang dihosting merender ke folder yang sama, daftarkan antrian opt-in, dan bangun konfigurasi bersama dengan asyncPublish: true:

csharp
builder.Services.AddDoconut(options => { /* … */ });
builder.Services.AddDoconutDistributedAsyncPublish();

Tanpa pendaftaran ini tidak ada yang terdaftar dan penerbitan tetap sinkron, persis seperti sebelumnya.

Kemudian panggil EnqueueAsync alih‑alih PublishAsync. (DistributedDocumentPublishOptions.Async hanyalah sebuah bendera yang kode Anda dapat baca untuk memilih antara dua jalur; penerbit mengabaikannya.) Antrian memiliki batas: ketika jenuh, EnqueueAsync melempar DistributedPublishQueueFullException. Jawab dengan 503 dan header Retry-After sehingga klien mundur alih‑alih terhenti:

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

Halaman yang belum ditulis: HTTP 202

Dengan penerbitan latar belakang, permintaan halaman dapat tiba sebelum pekerja menulis halaman tersebut. Sisi baca menunggu hingga ReadReadyPollMs dan kemudian menjawab HTTP 202 Accepted alih‑alih memblokir permintaan.

FirstPagePriority = true mempersingkat penantian untuk tampilan pertama: halaman 1 ditulis ke folder dokumen terlebih dahulu, sehingga dokumen terbuka sementara halaman berikutnya masih merender. Ini hanya berlaku untuk penerbitan latar belakang ke folder per‑token (UsePerTokenSubfolders = true); PublishAsync sinkron mengabaikannya, karena pemanggilnya menunggu seluruh dokumen tetap.

Hal ini memindahkan penantian ke klien, di mana penantian terbatas dan terlihat. Aktifkan percobaan ulang pada widget:

javascript
const objViewer = $('#div_ctlDoc').docViewer({
    BasePath:   'doconut',
    ResPath:    'doconut-res/images',
    retryOn409: true      // percobaan ulang 202 (dan legacy 409) respons kesiapan
});

Klien yang tidak melakukan percobaan ulang menampilkan ubin rusak untuk halaman yang masih merender. Anggaran percobaan ulang dan nilai bakunya (retryInitialDelayMs, retryBackoffFactor, retryMaxDelayMs, retryMaxAttempts, retryMaxTotalMs) didokumentasikan dalam KonfigurasiPenampil.

Keamanan lintas node

Token yang terikat pada sesi mengasumsikan node yang melayani melihat permintaan pembuka. Pada sebuah farm, hal itu tidak terjadi, sehingga pemeriksaan per-sesi akan menolak permintaan yang sah; sebuah farm karenanya menetapkan UnsafeMode = true.

UnsafeMode = true bukan model keamanan — itu adalah penghapusan yang tidak lagi berlaku.
Gantikan dengan tiket akses yang ditandatangani, yang dapat diverifikasi secara independen oleh setiap node. Empat komponen bekerja bersama.

1. Daftarkan keamanan tiket pada setiap node.
Tiket dilindungi dengan ASP.NET Core Data Protection, sehingga setiap node harus menggunakan ring kunci dan nama aplikasi yang sama; node dengan kunci yang berbeda tidak dapat membaca tiket yang dikeluarkan oleh node lain.

csharp
using Microsoft.AspNetCore.DataProtection;

builder.Services.AddDataProtection()
    .PersistKeysToFileSystem(new DirectoryInfo(@"\\fileserver\doconut-keys"))   // dibagikan oleh setiap node
    .SetApplicationName("doconut-farm");

builder.Services.AddDoconut(options => options.UnsafeMode = true);
builder.Services.AddDoconutDistributedDocumentSecurity(options =>
{
    options.TicketLifetimeMinutes = 60;   // nilai default
});

2. Periksa tiket pada sisi baca.
UseDoconutDistributedDocumentSecurity() ditempatkan pada cabang baca sebelum UseDoconutCloud, seperti pada contoh sisi baca.

3. Terbitkan tiket ketika dokumen dibuka.
Tiket menyebutkan token, browser (melalui cookie yang dibandingkan oleh sisi baca), dan pengguna yang masuk, jika ada:

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

    // Hubungkan ticket ke browser ini melalui cookie yang diperiksa oleh read side.
    var cookieName = security.Value.BrowserCookieName;   // "doconut-client" secara default
    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. Kirim keduanya ke widget.
Penampil mengirim tiket sebagai access dengan setiap permintaan:

javascript
const resp = await fetch('/api/open?fileName=Sample.pdf', { method: 'POST' });
const { token, access } = await resp.json();
objViewer.View(token, access);

Sisi baca menolak permintaan yang tiketnya hilang, tidak valid, dikeluarkan untuk token lain, kedaluwarsa, terikat pada cookie browser lain, atau dikeluarkan untuk pengguna yang masuk lain. Ia menjawab 403 — dengan gambar kesalahan UnauthorizedMessage untuk permintaan halaman dan thumbnail, sebagai teks biasa dalam kasus lain. Uji dengan browser nyata atau klien yang menyimpan cookie.

Jangan pernah membawa UnsafeMode = true kembali ke penyebaran satu node, dan jangan pernah menganggapnya sebagai jalan pintas untuk pemeriksaan sesi yang gagal pada satu node — di sana perbaikan yang tepat adalah AddSession() / UseSession(). Lihat Sesi & Keamanan.

CloseDocument(token) pada Viewer yang disuntikkan membuang sesi lokal. Untuk menghapus artefak yang dipublikasikan dari dokumen di share, penerbit menyediakan:

text
bool CloseDistributedDocument(FileShareConfig fileShareConfig, string token)

Berikan FileShareConfig yang sama dengan yang digunakan saat dokumen dipublikasikan.

Daftar Periksa

  1. Bangun FileShareConfig dalam satu pembantu, daftarkan sekali, dan gunakan dari kedua belahnya.
  2. Arahkan RootPath ke folder yang dapat dijangkau oleh setiap node.
  3. Terbitkan dengan PublishAsync(...), atau EnqueueAsync(...) dengan penerbitan latar belakang.
  4. Layani dengan UseDoconutCloud<FileShareCloudHandler>(...) pada cabang yang dipanggil klien.
  5. Dengan penerbitan latar belakang, aktifkan FirstPagePriority dan retryOn409 secara bersamaan, dan berikan sisi baca nilai ReadReadyPollMs yang tidak nol.
  6. Ganti pemeriksaan per‑sesi dengan tiket akses yang ditandatangani — satu cincin kunci Data Protection pada setiap node, UseDoconutDistributedDocumentSecurity() pada cabang baca, tiket dari endpoint terbuka — dan jangan kirim UnsafeMode = true sendiri.
  7. Verifikasi dengan membuka dokumen pada satu node dan meminta halaman akhir dari node lain.

Apakah halaman ini membantu?