分散デプロイ

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

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 と共に配置されています。

プロパティ目的
LocationCloudLocation.FileShare 用の UNC/ローカル共有
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 は、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:   'doconut',
    ResPath:    'doconut-res/images',
    retryOn409: true      // リトライ 202 (およびレガシー 409) レディネス応答
});

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

ノード間のセキュリティ

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

Checklist

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

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