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. Rilis ini membagi pekerjaan tersebut menjadi dua bagian eksplisit — sisi penulisan yang memublikasikan artefak dokumen ke penyimpanan bersama, dan sisi pembacaan yang menyajikannya dari node mana pun.
Jika aplikasi Anda saat ini memanggil UseDoconutWebFarm(...), halaman ini adalah penggantinya. Baik UseDoconutWebFarm maupun WebFarmOptions tidak ada dalam rilis ini.
Topologi Anda tidak berubah. Arahkan root bersama ke jalur UNC yang sama yang Anda gunakan hari ini dan setiap node tetap bekerja seperti sebelumnya. Yang berubah adalah bahwa publikasi menjadi operasi yang Anda panggil, bukan efek samping dari proses rendering.
Apa yang menggantikan middleware web-farm
Sebelumnya satu middleware melakukan semuanya: ia menyajikan gambar yang sudah diprerender dari folder bersama dan polled sementara node lain masih menulisnya. Penantian itu adalah anggaran buta — "blokir hingga tiga menit berharap halaman muncul".
Sekarang pekerjaan yang sama menjadi dua panggilan yang dapat Anda lihat dan pahami:
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 pageKonfigurasi bersama yang dibutuhkan kedua bagian
Publisher menulis dengan FileShareConfig dan handler pembaca menyajikannya 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:
var rootPath = builder.Configuration["Doconut:SharedRoot"]!; // misalnya \\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. Pada pustaka sebelumnya ini berada di Doconut.Configs.Cloud; nama kelas tidak berubah.
| Properti | Tujuan |
|---|---|
Location | CloudLocation.FileShare untuk berbagi UNC/lokal |
RootPath | Folder bersama yang dapat dijangkau oleh setiap node |
UsePerTokenSubfolders | Simpan artefak setiap dokumen di folder {token} miliknya sendiri (default true) |
ReadReadyPollMs | Berapa 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
Suntikkan DistributedDocumentPublisher dan publikasikan alih-alih membuka sesi lokal. Satu panggilan merender dan menulis seluruh set artefak — halaman, info dokumen, indeks pencarian, dan metadata — dan mengembalikan hasil ketika selesai:
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. Di dalam farm, endpoint juga mengembalikan tiket akses yang ditandatangani — lihat Keamanan antar node.
Panggilan tunggal ini menggantikan pasangan sebelumnya — membuka dokumen ke dalam sesi lokal dan kemudian menyalurkan gambar ke share dengan ExportToPng(sharedPath). ExportToPng dan ExportToCloud tidak memiliki padanan di sini.
Sisi Baca — melayani dari share
Pasang handler FileShare pada cabang yang sama yang sudah dipanggil klien, di belakang pemeriksaan tiket:
var app = builder.Build();
app.UseDoconutResources();
app.MapWhen(
ctx => ctx.Request.Path.Value?.EndsWith("DocImage.axd", StringComparison.OrdinalIgnoreCase) == true,
branch =>
{
branch.UseDoconutDistributedDocumentSecurity(); // tiket yang ditandatangani — lihat di bawah
branch.UseDoconutCloud<FileShareCloudHandler>(options =>
{
options.Location = CloudLocation.FileShare;
options.CloudUploadConfig = app.Services.GetRequiredService<FileShareConfig>();
}, "/");
});UseDoconutCloud bersifat generik dalam rilis ini: penyedia adalah argumen tipe alih-alih nilai Location yang dipilih di dalam middleware. Handler dinamai <Provider>CloudHandler — FileShareCloudHandler, AzureCloudHandler, AmazonS3CloudHandler, GoogleCloudHandler, DropBoxCloudHandler, RedisCloudHandler, FTPCloudHandler, dan CDNCloudHandler. Dengan awalan jalur "/", handler menjawab setiap permintaan yang mencapai cabangnya.
Handler CDN bersifat read-only — ia melayani apa yang sudah ada di CDN; ia 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:
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 hanya sebuah flag yang dapat dibaca kode Anda untuk memilih antara dua jalur; penerbit mengabaikannya.) Antrian bersifat terbatas: ketika penuh, EnqueueAsync melempar DistributedPublishQueueFullException. Jawab dengan 503 dan header Retry-After sehingga klien mundur alih-alih terhenti:
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 waktu tunggu 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.
Itu memindahkan penundaan ke klien, di mana ia terbatas dan terlihat. Aktifkan retry pada widget:
const objViewer = $('#div_ctlDoc').docViewer({
BasePath: '/',
ResPath: 'doconut-res/images',
retryOn409: true // percobaan ulang 202 (dan legacy 409) respons kesiapan
});Klien yang tidak melakukan retry menampilkan ubin rusak untuk halaman yang masih merender. Anggaran retry dan nilai defaultnya (retryInitialDelayMs, retryBackoffFactor, retryMaxDelayMs, retryMaxAttempts, retryMaxTotalMs) didokumentasikan dalam ViewerConfig.
Pasangan ini — penerbitan latar belakang dengan FirstPagePriority, ditambah polling sisi baca — menggantikan pengaturan PageWaitTimeSeconds dan StartWaitFromPage sebelumnya. Kedua pengaturan tersebut tidak lagi ada.
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 oleh karena itu menetapkan UnsafeMode = true.
UnsafeMode = true bukan model keamanan — itu adalah penghapusan yang tidak lagi berlaku.
Ganti 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 node lain.
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() diletakkan pada cabang baca sebelum UseDoconutCloud, seperti pada contoh sisi baca.
3. Keluarkan tiket saat dokumen dibuka. Tiket menyebutkan token, browser (melalui cookie yang dibandingkan oleh sisi baca), dan pengguna yang masuk, jika ada:
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 tiket ke peramban ini melalui cookie yang diperiksa oleh sisi pembaca.
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:
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 masuk lain. Ia menjawab 403 — dengan gambar error 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 memperlakukannya sebagai jalan pintas untuk pemeriksaan sesi yang gagal pada satu node — di sana perbaikan yang tepat adalah AddSession() / UseSession(). Lihat Sesi & Keamanan.
Menutup dokumen yang dipublikasikan
CloseDocument(token) pada Viewer yang disuntikkan membuang sesi lokal. Untuk menghapus artefak yang dipublikasikan dari dokumen pada share, penerbit menyediakan:
bool CloseDistributedDocument(FileShareConfig fileShareConfig, string token)Berikan FileShareConfig yang sama dengan yang digunakan saat dokumen dipublikasikan.
Pemetaan per pengaturan
| Sebelumnya | Sekarang |
|---|---|
UseDoconutWebFarm(new WebFarmOptions { … }) | PublishAsync(...) pada sisi penulisan plus UseDoconutCloud<FileShareCloudHandler>(...) pada sisi pembacaan |
WebFarmOptions.Path | FileShareConfig.RootPath |
PageWaitTimeSeconds / StartWaitFromPage | Penerbitan latar belakang dengan DistributedDocumentPublishOptions.FirstPagePriority, serta FileShareConfig.ReadReadyPollMs |
viewer.OpenDocument(...) kemudian viewer.ExportToPng(share) | satu panggilan PublishAsync(...) |
viewer.ExportToCloud(cloudConfig) | PublishAsync(...) dengan konfigurasi penyedia |
UseDoconutCloud(new CloudOptions { Location = … }) | UseDoconutCloud<THandler>(options => …, pathPrefix) |
DocOptions.IsWebfarm / WebfarmPath | Masih ada, dieja IsWebFarm / WebFarmPath — tidak diperlukan pada jalur penerbitan |
Doconut.Configs.Cloud | Doconut.Clouds |
Daftar Periksa
- Bangun
FileShareConfigdalam satu pembantu, daftarkan sekali, dan gunakan dari kedua sisi. - Arahkan
RootPathke share yang sudah Anda gunakan. - Terbitkan dengan
PublishAsync(...); hapus semua panggilanExportToPng/ExportToCloud. - Layani dengan
UseDoconutCloud<FileShareCloudHandler>(...)pada cabang yang dipanggil klien. - Dengan penerbitan latar belakang, aktifkan
FirstPagePrioritydanretryOn409bersamaan, dan berikan sisi pembacaan nilaiReadReadyPollMsyang tidak nol. - Ganti pemeriksaan per-sesi dengan tiket akses yang ditandatangani — satu cincin kunci Data Protection pada setiap node,
UseDoconutDistributedDocumentSecurity()pada cabang pembacaan, tiket dari endpoint terbuka — dan jangan kirimUnsafeMode = truesendirian. - Verifikasi dengan membuka dokumen pada satu node dan meminta halaman terlambat dari node lain.
Apakah halaman ini membantu?