Διανεμημένες Αναπτύξεις

Εξυπηρέτηση ενός εγγράφου από πολλούς κόμβους

Όταν πολλοί κόμβοι εξυπηρετούν τα ίδια έγγραφα, ο κόμβος που αποδίδει ένα έγγραφο δεν είναι απαραίτητα ο κόμβος που απαντά στα αιτήματα σελίδας του προγράμματος περιήγησης. Αυτή η έκδοση χωρίζει αυτή τη δουλειά σε δύο σαφείς μισά — μια πλευρά εγγραφής που δημοσιεύει τα τεχνικά αρχεία ενός εγγράφου σε κοινόχρηστη αποθήκευση, και μια πλευρά ανάγνωσης που τα εξυπηρετεί από οποιονδήποτε κόμβο.

Αν η εφαρμογή σας αυτή τη στιγμή καλεί UseDoconutWebFarm(...), αυτή η σελίδα είναι η αντικατάστασή της. Ούτε UseDoconutWebFarm ούτε WebFarmOptions υπάρχουν σε αυτή την έκδοση.

Η τοπολογία σας δεν αλλάζει. Κατευθύνετε τη κοινόχρηστη ρίζα στο ίδιο UNC μονοπάτι που χρησιμοποιείτε σήμερα και κάθε κόμβος συνεχίζει να λειτουργεί όπως τώρα. Η αλλαγή είναι ότι η δημοσίευση είναι μια λειτουργία που καλείτε, αντί για μια παρενέργεια της απόδοσης.

Τι αντικατέστησε το λογισμικό web-farm middleware

Προηγουμένως ένα middleware έκανε τα πάντα: εξυπηρετούσε προ‑αποδομένες εικόνες από έναν κοινόχρηστο φάκελο και ελέγχει ενώ ένας άλλος κόμβος συνέχιζε να τις γράφει. Η αναμονή ήταν ένας τυφλός προϋπολογισμός — «αποκλεισμός έως τρία λεπτά ελπίζοντας να εμφανιστεί η σελίδα».

Τώρα η ίδια εργασία είναι δύο κλήσεις που μπορείτε να δείτε και να κατανοήσετε:

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· τα ονόματα κλάσεων δεν άλλαξαν.

ΙδιότηταΣκοπός
LocationCloudLocation.FileShare για ένα UNC/τοπικό κοινόχρηστο
RootPathΟ κοινόχρηστος φάκελος που μπορεί να προσεγγίσει κάθε κόμβος
UsePerTokenSubfoldersΔιατηρεί τα τεχνικά αρχεία κάθε εγγράφου στον δικό του φάκελο {token} (προεπιλογή true)
ReadReadyPollMsΠόσο χρόνο η πλευρά ανάγνωσης περιμένει για μια σελίδα που μια δημοσίευση στο παρασκήνιο εξακολουθεί να γράφει· 0 (η προεπιλογή) ελέγχει μία φορά. Δεν επηρεάζει τα έγγραφα που δημοσιεύονται συγχρονισμένα

Πλευρά εγγραφής — δημοσίευση του εγγράφου

Ενσωματώστε DistributedDocumentPublisher και δημοσιεύστε αντί να ανοίξετε μια τοπική συνεδρία. Μία κλήση αποδίδει και γράφει το πλήρες σύνολο τεχνικών αρχείων — σελίδες, πληροφορίες εγγράφου, ευρετήριο αναζήτησης και μεταδεδομένα — και επιστρέφει όταν ολοκληρωθεί:

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. Το token πηγαίνει στον περιηγητή ακριβώς όπως κάνει ένα κανονικό token προβολέα. Σε ένα farm, το endpoint επιστρέφει επίσης ένα υπογεγραμμένο εισιτήριο πρόσβασης — δείτε Ασφάλεια μεταξύ κόμβων.

Αυτή η μοναδική κλήση αντικαθιστά το προηγούμενο ζεύγος — το άνοιγμα του εγγράφου σε μια τοπική συνεδρία και στη συνέχεια την αποθήκευση των εικόνων στο κοινόχρηστο με ExportToPng(sharedPath). ExportToPng και ExportToCloud δεν έχουν ισοδύναμο εδώ.

Πλευρά ανάγνωσης — εξυπηρέτηση από το share

Τοποθετήστε τον χειριστή 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 που εναλλάσσεται μέσα στο middleware. Οι χειριστές ονομάζονται <Provider>CloudHandler — FileShareCloudHandler, AzureCloudHandler, AmazonS3CloudHandler, GoogleCloudHandler, DropBoxCloudHandler, RedisCloudHandler, FTPCloudHandler, και CDNCloudHandler. Με το πρόθεμα διαδρομής "/", ο χειριστής απαντά σε κάθε αίτημα που φθάνει στη διακλάδωσή του.

Ο χειριστής CDN είναι μόνο για ανάγνωση — εξυπηρετεί ό,τι υπάρχει ήδη στο CDN· δεν κάνει ανέβασμα.

Προαιρετικό: δημοσίευση στο παρασκήνιο

Από προεπιλογή, το PublishAsync αποδίδει ολόκληρο το έγγραφο πριν επιστρέψει. Για να επιστρέψετε αμέσως μόλις δημιουργηθεί το token και να αφήσετε έναν φιλοξενούμενο worker να αποδώσει στον ίδιο φάκελο, εγγράψτε την ουρά επιλογής, και δημιουργήστε τη κοινή διαμόρφωση με το asyncPublish: true:

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

Χωρίς αυτήν την εγγραφή, τίποτα δεν καταχωρείται και η δημοσίευση παραμένει συγχρονισμένη, ακριβώς όπως πριν.

Στη συνέχεια καλέστε το EnqueueAsync αντί για το PublishAsync. (Το 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

Με τη δημοσίευση στο παρασκήνιο, ένα αίτημα σελίδας μπορεί να φτάσει πριν ο worker γράψει τη σελίδα. Η πλευρά ανάγνωσης περιμένει έως ReadReadyPollMs και στη συνέχεια απαντά HTTP 202 Accepted αντί να μπλοκάρει το αίτημα.

FirstPagePriority = true συντομεύει την αναμονή για την πρώτη προβολή: η σελίδα 1 γράφεται πρώτα στο φάκελο του εγγράφου, έτσι το έγγραφο ανοίγει ενώ οι επόμενες σελίδες εξακολουθούν να αποδίδονται. Εφαρμόζεται μόνο στη δημοσίευση στο παρασκήνιο σε φακέλους ανά token (UsePerTokenSubfolders = true); το συγχρονισμένο PublishAsync το αγνοεί, επειδή ο καλών του περιμένει ολόκληρο το έγγραφο οπωσδήποτε.

Αυτό μεταφέρει την αναμονή στον πελάτη, όπου είναι περιορισμένη και ορατή. Ενεργοποιήστε την επανάληψη (retry) στο widget:

javascript
const objViewer = $('#div_ctlDoc').docViewer({
    BasePath:   '/',
    ResPath:    'doconut-res/images',
    retryOn409: true      // επαναπροσπάθειες 202 (και παλαιό 409) απαντήσεις ετοιμότητας
});

Ένας πελάτης που δεν κάνει επανάληψη εμφανίζει σπασμένα πλακίδια για σελίδες που εξακολουθούν να αποδίδονται. Ο προϋπολογισμός επανάληψης και οι προεπιλογές του (retryInitialDelayMs, retryBackoffFactor, retryMaxDelayMs, retryMaxAttempts, retryMaxTotalMs) τεκμηριώνονται στο ViewerConfig.

Αυτό το ζεύγος — η δημοσίευση στο παρασκήνιο με FirstPagePriority, συν το polling στην πλευρά ανάγνωσης — αντικαθιστά τις προηγούμενες ρυθμίσεις PageWaitTimeSeconds και StartWaitFromPage. Καμία από αυτές δεν υπάρχει πλέον.

Ασφάλεια μεταξύ κόμβων

Τα διακριτικά που δεσμεύονται στη συνεδρία υποθέτουν ότι ο εξυπηρετητής κόμβος είδε το αρχικό αίτημα. Σε ένα σύμπλεγμα δεν το έκανε, έτσι ο έλεγχος ανά συνεδρία θα απορρίψει νόμιμα αιτήματα· ένα σύμπλεγμα επομένως ορίζει UnsafeMode = true.

UnsafeMode = true δεν είναι το μοντέλο ασφαλείας — είναι η αφαίρεση ενός που δεν ισχύει πια. Αντικαταστήστε το με υπογεγραμμένα εισιτήρια πρόσβασης, τα οποία κάθε κόμβος μπορεί να επαληθεύσει ανεξάρτητα. Τα τέσσερα στοιχεία λειτουργούν μαζί.

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. Εκδώστε ένα εισιτήριο όταν ανοίγεται το έγγραφο. Το εισιτήριο ονομάζει το διακριτικό, το πρόγραμμα περιήγησης (μέσω ενός cookie που συγκρίνει η πλευρά ανάγνωσης) και τον συνδεδεμένο χρήστη, εάν υπάρχει:

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. Μεταβιβάστε και τα δύο στο widget. Ο προβολέας στέλνει το εισιτήριο ως access με κάθε αίτημα:

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

Η πλευρά ανάγνωσης απορρίπτει ένα αίτημα του οποίου το εισιτήριο λείπει, είναι άκυρο, εκδόθηκε για άλλο διακριτικό, έχει λήξει, είναι δεσμευμένο σε άλλο cookie προγράμματος περιήγησης ή εκδόθηκε σε άλλο συνδεδεμένο χρήστη. Απαντά με 403 — με την εικόνα σφάλματος UnauthorizedMessage για αιτήματα σελίδας και μικρογραφίας, αλλιώς ως απλό κείμενο. Δοκιμάστε με ένα πραγματικό πρόγραμμα περιήγησης ή έναν πελάτη που διατηρεί cookies.

Ποτέ μην μεταφέρετε το UnsafeMode = true πίσω σε μια ανάπτυξη μονοκόμβου, και ποτέ μην το θεωρείτε συντόμευση για έναν αποτυχημένο έλεγχο συνεδρίας σε έναν κόμβο — εκεί η σωστή διόρθωση είναι AddSession() / UseSession(). Δείτε το Συνεδρίες & Ασφάλεια.

Κλείσιμο ενός δημοσιευμένου εγγράφου

CloseDocument(token) στο ενσωματωμένο Viewer διαγράφει μια τοπική συνεδρία. Για να αφαιρέσετε τα δημοσιευμένα τεχνητά ενός εγγράφου από το κοινόχρηστο, ο εκδότης εκθέτει:

text
bool CloseDistributedDocument(FileShareConfig fileShareConfig, string token)

Περάστε το ίδιο FileShareConfig με το οποίο δημοσιεύτηκε το έγγραφο.

Αντιστοίχιση ρύθμισης-προς-ρύθμιση

ΠροηγούμενοΤώρα
UseDoconutWebFarm(new WebFarmOptions { … })PublishAsync(...) στην πλευρά εγγραφής και UseDoconutCloud<FileShareCloudHandler>(...) στην πλευρά ανάγνωσης
WebFarmOptions.PathFileShareConfig.RootPath
PageWaitTimeSeconds / StartWaitFromPageΔημοσίευση στο παρασκήνιο με DistributedDocumentPublishOptions.FirstPagePriority, και FileShareConfig.ReadReadyPollMs
viewer.OpenDocument(...) then viewer.ExportToPng(share)μια κλήση PublishAsync(...)
viewer.ExportToCloud(cloudConfig)PublishAsync(...) με τη ρύθμιση του παρόχου
UseDoconutCloud(new CloudOptions { Location = … })UseDoconutCloud<THandler>(options => …, pathPrefix)
DocOptions.IsWebfarm / WebfarmPathΑκόμα υπάρχει, γραμμένο IsWebFarm / WebFarmPath — δεν χρειάζεται στη διαδρομή δημοσίευσης
Doconut.Configs.CloudDoconut.Clouds

Λίστα ελέγχου

  1. Δομήστε το FileShareConfig σε έναν βοηθό, καταχωρίστε το μία φορά και χρησιμοποιήστε το και από τις δύο πλευρές.
  2. Κατευθύνετε το RootPath στο κοινόχρηστο που ήδη χρησιμοποιείτε.
  3. Δημοσιεύστε με PublishAsync(...)· διαγράψτε τυχόν κλήσεις ExportToPng / ExportToCloud.
  4. Σερβίρετε με UseDoconutCloud<FileShareCloudHandler>(...) στον κλάδο που καλεί ο πελάτης.
  5. Με τη δημοσίευση στο παρασκήνιο, ενεργοποιήστε τα FirstPagePriority και retryOn409 μαζί, και δώστε στην πλευρά ανάγνωσης ένα μη μηδενικό ReadReadyPollMs.
  6. Αντικαταστήστε τον έλεγχο ανά συνεδρία με υπογεγραμμένα εισιτήρια πρόσβασης — ένα δαχτυλίδι κλειδιών Προστασίας Δεδομένων σε κάθε κόμβο, UseDoconutDistributedDocumentSecurity() στον κλάδο ανάγνωσης, ένα εισιτήριο από το ανοιχτό άκρο — και μην διανείμετε το UnsafeMode = true μόνο του.
  7. Επαληθεύστε ανοίγοντας ένα έγγραφο σε έναν κόμβο και ζητώντας μια καθυστερημένη σελίδα από έναν άλλο.

Ήταν αυτή η σελίδα χρήσιμη;