分散デプロイ

複数ノードから単一ドキュメントを提供

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

単一のノードではこれらは不要です:通常の OpenDocumentAsync パスはドキュメントをそのノードのメモリに保持し、ブラウザセッションにバインドします(セッションとセキュリティ を参照)。ページリクエストが開いたことのないノードに届く可能性がある場合は、このページを使用してください。

二つの半分の組み合わせ

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 と共に存在します。

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

読み取り側 — 共有から提供

クライアントが呼び出すブランチに FileShare ハンドラをマウントします — /doconut、BasePath: 'doconut' に一致させて — チケットチェックの後で:

csharp
var app = builder.Build();

app.UseDoconutResources();
app.Map("/doconut", branch =>
{
    branch.UseDoconutDistributedDocumentSecurity();   // 署名済みチケット — 以下をご覧ください
    branch.UseDoconutCloud<FileShareCloudHandler>(options =>
    {
        options.Location          = CloudLocation.FileShare;
        options.CloudUploadConfig = app.Services.GetRequiredService<FileShareConfig>();
    }, "/");
});

UseDoconutCloud はプロバイダーを型引数として受け取ります。ハンドラは <Provider>CloudHandler — FileShareCloudHandler、AzureCloudHandler、AmazonS3CloudHandler、GoogleCloudHandler、DropBoxCloudHandler、RedisCloudHandler、FTPCloudHandler、および CDNCloudHandler と名付けられます。パスプレフィックス "/" を使用すると、ハンドラはそのブランチに到達したすべてのリクエストに応答します。

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

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

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

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

この登録がないと何も登録されず、公開は同期的に行われ、以前と全く同じになります。

次に PublishAsync の代わりに EnqueueAsync を呼び出します。(DistributedDocumentPublishOptions.Async は自分のコードが読み取って二つのパスのどちらかを選択できるフラグであり、パブリッシャーは無視します。) キューは上限があり、飽和すると 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:   'doconut',
    ResPath:    'doconut-res/images',
    retryOn409: true      // リトライ 202 (およびレガシー 409) レディネス応答
});

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

ノード間のセキュリティ

セッションに紐付くトークンは、提供ノードが最初のリクエストを確認したことを前提としています。ファーム環境ではそれが行われないため、セッションごとのチェックは正当なリクエストを拒否してしまいます。そのため、ファームでは 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);

    // 読み取り側がチェックする cookie を介して、このブラウザにチケットをバインドします。
    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 を渡してください。

チェックリスト

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

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