分散デプロイメント

複数ノードから1つのドキュメントを提供する

複数のノードが同じドキュメントを提供する場合、ドキュメントをレンダリングするノードが必ずしもブラウザのページリクエストに応答するノードとは限りません。このリリースでは、その作業を明確に二つの側面に分割します — アーティファクトを共有ストレージに公開する 書き込み側 と、任意のノードからそれらを提供する 読み取り側 。

現在のアプリケーションが UseDoconutWebFarm(...) を呼び出している場合、このページが置き換えになります。このリリースには UseDoconutWebFarm も WebFarmOptions も存在しません。

トポロジーは変わりません。 共有ルートを現在使用しているのと同じ UNC パスに設定すれば、すべてのノードは今と同様に動作し続けます。変わるのは、公開がレンダリングの副作用ではなく、呼び出す操作になることです。

web-farm ミドルウェアの代替

以前は1つのミドルウェアがすべてを行っていました:共有フォルダーから事前にレンダリングされた画像を提供し、別のノードがまだ書き込み中である間ポーリングしました。待機は盲目的な予算で、"ページが表示されることを期待して最大3分ブロック" というものでした。

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

両側が必要とする共有設定

パブリッシャーは FileShareConfig を使用して書き込み、リードハンドラはそれで提供します。RootPath または UsePerTokenSubfolders がそれぞれ異なる場合、他方のノードは 404 を返します。 設定は正確に一か所で構築し、一度だけ登録することで、両側が同じオブジェクトを読み取ります:

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

バックグラウンド公開を有効にする際は asyncPublish: true を渡します。バックグラウンド公開。

FileShareConfig は Doconut.Clouds にあり、AzureConfig、AmazonConfig、GoogleCloudConfig、DropBoxConfig、RedisConfig、CDNConfig、および FTPConfig と共に存在します。前のライブラリではこれらは Doconut.Configs.Cloud にありましたが、クラス名は変更されていません。

PropertyPurpose
LocationUNC/ローカル共有用の CloudLocation.FileShare
RootPathすべてのノードがアクセスできる共有フォルダー
UsePerTokenSubfolders各ドキュメントのアーティファクトをそれぞれの {token} フォルダーに保持する(デフォルトは true)
ReadReadyPollMsバックグラウンド公開がまだ書き込み中のページに対して、読み取り側 が待機する時間;0(デフォルト)は一度だけチェックします。同期的に公開されたドキュメントには影響しません

書き込み側 — ドキュメントを公開

DistributedDocumentPublisher を注入し、ローカルセッションを開く代わりに公開します。1回の呼び出しでページ、ドキュメント情報、検索インデックス、メタデータという完全なアーティファクトセットをレンダリングして書き込み、完了すると戻ります:

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 は Token、ArtifactPath、TotalPages、および Format を含みます。トークンは通常のビューアートークンと同様にブラウザへ送られます。ファーム環境では、エンドポイントは署名付きアクセスチケットも返します — ノード間のセキュリティ。

この単一の呼び出しは、以前のペア(ドキュメントをローカルセッションで開き、ExportToPng(sharedPath) を使用して画像を共有にダンプする)を置き換えます。ExportToPng と ExportToCloud にはここに相当するものがありません。

リード側 — 共有から提供する

チケットチェックの後、クライアントがすでに呼び出している同じブランチに FileShare ハンドラをマウントします:

csharp
var app = builder.Build();

app.UseDoconutResources();
app.MapWhen(
    ctx => ctx.Request.Path.Value?.EndsWith("DocImage.axd", StringComparison.OrdinalIgnoreCase) == true,
    branch =>
    {
        branch.UseDoconutDistributedDocumentSecurity();   // 署名済みチケット — 以下を参照
        branch.UseDoconutCloud<FileShareCloudHandler>(options =>
        {
            options.Location          = CloudLocation.FileShare;
            options.CloudUploadConfig = app.Services.GetRequiredService<FileShareConfig>();
        }, "/");
    });

UseDoconutCloud はこのリリースで汎用的です: プロバイダーはミドルウェア内部で切り替えられる Location 値ではなく、型引数として指定されます。ハンドラは <Provider>CloudHandler — FileShareCloudHandler、AzureCloudHandler、AmazonS3CloudHandler、GoogleCloudHandler、DropBoxCloudHandler、RedisCloudHandler、FTPCloudHandler、CDNCloudHandler と命名されています。パスプレフィックス "/" を付けることで、ハンドラはそのブランチに到達したすべてのリクエストに応答します。

CDN ハンドラは 読み取り専用 です — 既に CDN にあるものを提供し、アップロードは行いません。

オプション: バックグラウンドでの公開

デフォルトでは PublishAsync がドキュメント全体をレンダリングしてから返します。トークンが生成されたらすぐに返し、ホストされたワーカーが同じフォルダーにレンダリングさせるには、オプトインキューを登録し、asyncPublish: true で共有設定を構築します:

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

この登録がない場合は何も登録されず、パブリッシュは同期的に実行され、従来どおりになります。

その後、EnqueueAsync を呼び出し、PublishAsync の代わりに使用します。(DistributedDocumentPublishOptions.Async は自分のコードが読み取って 2 つのパスのどちらかを選択できるフラグで、パブリッシャーは無視します)。キューは上限があり、飽和すると EnqueueAsync が DistributedPublishQueueFullException をスローします。クライアントが停止せずにバックオフできるよう、503 と Retry-After ヘッダーで応答してください:

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

まだ書き込まれていないページ: HTTP 202

バックグラウンドパブリッシュを使用すると、ワーカーがページを書き込む前にページリクエストが到着することがあります。リードサイドは最大 ReadReadyPollMs 待機し、その後 HTTP 202 Accepted を返してリクエストをブロックしません。

FirstPagePriority = true は最初のビューの待機時間を短縮します: ページ 1 がドキュメントのフォルダーに最初に書き込まれるため、後続のページがまだレンダリング中でもドキュメントは開きます。これはトークンごとのフォルダーへのバックグラウンドパブリッシュ (UsePerTokenSubfolders = true) のみで適用され、同期的な PublishAsync は無視します。なぜなら呼び出し側がドキュメント全体の完了を待つからです。

これにより待機はクライアント側に移り、上限と可視性が確保されます。ウィジェットでリトライを有効にしてください:

javascript
const objViewer = $('#div_ctlDoc').docViewer({
    BasePath:   '/',
    ResPath:    'doconut-res/images',
    retryOn409: true      // リトライ 202 (およびレガシー 409) レディネス応答
});

リトライしないクライアントは、まだレンダリング中のページのタイルが壊れた状態で表示されます。リトライ予算とそのデフォルト (retryInitialDelayMs、retryBackoffFactor、retryMaxDelayMs、retryMaxAttempts、retryMaxTotalMs) は ViewerConfig に記載されています。

この組み合わせ — FirstPagePriority を使用したバックグラウンドパブリッシュとリードサイドポーリング — は、従来の PageWaitTimeSeconds と StartWaitFromPage 設定に取って代わります。どちらももう存在しません。

ノード間のセキュリティ

セッションバウンドトークンは、提供ノードが最初のリクエストを確認したことを前提としています。ファーム環境ではそれが行われないため、セッションごとのチェックは正当なリクエストを拒否してしまいます。そのため、ファームでは UnsafeMode = true が設定されます。

UnsafeMode = true はセキュリティモデルではなく、もはや適用されないものを削除したものです。 これを署名付きアクセスチケットに置き換えます。各ノードは独立して検証できます。4つの要素が連携して動作します。

1. 各ノードでチケットのセキュリティを登録する。 チケットは ASP.NET Core Data Protection で保護されているため、すべてのノードは同じキーリングとアプリケーション名を使用する必要があります。異なるキーを持つノードは、他のノードが発行したチケットを読み取れません。

csharp
using Microsoft.AspNetCore.DataProtection;

builder.Services.AddDataProtection()
    .PersistKeysToFileSystem(new DirectoryInfo(@"\\fileserver\doconut-keys"))   // 各ノードによって共有される
    .SetApplicationName("doconut-farm");

builder.Services.AddDoconut(options => options.UnsafeMode = true);
builder.Services.AddDoconutDistributedDocumentSecurity(options =>
{
    options.TicketLifetimeMinutes = 60;   // デフォルト
});

2. 読み取り側でチケットをチェックする。 UseDoconutDistributedDocumentSecurity() は UseDoconutCloud の前に読み取りブランチに配置されます。詳細は 読み取り側サンプル を参照してください。

3. ドキュメントが開かれたときにチケットを発行する。 チケットはトークン、ブラウザー(読み取り側が比較するクッキーを通じて)、およびサインインユーザー(存在する場合)を指定します。

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

    // 読み取り側がチェックするクッキーを介して、このブラウザーにチケットをバインドする。
    var cookieName = security.Value.BrowserCookieName;   // "doconut-client" デフォルトで
    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. 両方をウィジェットに渡す。 ビューアは各リクエストに対してチケットを access として送信します。

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

読み取り側は、チケットが欠落している、無効である、別のトークン用に発行された、期限切れ、別のブラウザクッキーに紐付いている、または別のサインインユーザーに発行されたリクエストを拒否します。ステータス 403 を返します — ページおよびサムネイルのリクエストの場合は UnauthorizedMessage エラー画像が返され、その他の場合はプレーンテキストです。クッキーを保持する実際のブラウザまたはクライアントでテストしてください。

単一ノード展開に UnsafeMode = true を持ち込んだり、1つのノードで失敗するセッションチェックのショートカットとして扱ったりしないでください。その場合、正しい修正は AddSession() / UseSession() です。参照: セッションとセキュリティ。

公開ドキュメントのクローズ

CloseDocument(token) は注入された Viewer 上でローカルセッションを破棄します。ドキュメントの公開アーティファクトを共有から削除するために、パブリッシャーは以下を公開します:

text
bool CloseDistributedDocument(FileShareConfig fileShareConfig, string token)

ドキュメントが公開されたときと同じ FileShareConfig を渡してください。

設定ごとのマッピング

以前現在
UseDoconutWebFarm(new WebFarmOptions { … })書き込み側の PublishAsync(...) と読み取り側の UseDoconutCloud<FileShareCloudHandler>(...)
WebFarmOptions.PathFileShareConfig.RootPath
PageWaitTimeSeconds / StartWaitFromPageDistributedDocumentPublishOptions.FirstPagePriority を使用したバックグラウンドパブリッシュ、さらに FileShareConfig.ReadReadyPollMs
viewer.OpenDocument(...) その後 viewer.ExportToPng(share)1つの PublishAsync(...) 呼び出し
viewer.ExportToCloud(cloudConfig)プロバイダーの設定で PublishAsync(...)
UseDoconutCloud(new CloudOptions { Location = … })UseDoconutCloud<THandler>(options => …, pathPrefix)
DocOptions.IsWebfarm / WebfarmPath依然として存在し、IsWebFarm / WebFarmPath と表記されます — パブリッシュパスでは不要です
Doconut.Configs.CloudDoconut.Clouds

チェックリスト

  1. 1つのヘルパーで FileShareConfig を構築し、1回だけ登録して、両方の側から使用します。
  2. RootPath を既に使用している共有に指します。
  3. PublishAsync(...) で公開し、ExportToPng / ExportToCloud の呼び出しをすべて削除します。
  4. クライアントが呼び出すブランチで UseDoconutCloud<FileShareCloudHandler>(...) を使用して提供します。
  5. バックグラウンドパブリッシュの場合、FirstPagePriority と retryOn409 を同時に有効にし、読み取り側にゼロでない ReadReadyPollMs を設定します。
  6. セッションごとのチェックを署名付きアクセスチケットに置き換えます — 各ノードに 1 つの Data Protection キーリング、読み取りブランチに UseDoconutDistributedDocumentSecurity()、オープンエンドポイントからのチケット — そして UnsafeMode = true を単独で配布しないでください。
  7. 1つのノードでドキュメントを開き、別のノードから遅延ページを要求して検証します。

このページは役に立ちましたか?