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

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

Όταν πολλοί κόμβοι εξυπηρετούν τα ίδια έγγραφα, ο κόμβος που αποδίδει ένα έγγραφο δεν είναι απαραίτητα ο κόμβος που απαντά στα αιτήματα σελίδων του προγράμματος περιήγησης. 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 και δημοσιεύστε αντί να ανοίξετε τοπική συνεδρία. Μία κλήση αποδίδει και γράφει το πλήρες σύνολο τεχνητών στοιχείων — σελίδες, πληροφορίες εγγράφου, ευρετήριο αναζήτησης και μεταδεδομένα — και επιστρέφει όταν ολοκληρωθεί:

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

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

Τοποθετήστε τον χειριστή 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();

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

Στη συνέχεια, καλέστε 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

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

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

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

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

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

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

Τα διακριτικά που δεσμεύονται σε συνεδρία υποθέτουν ότι ο εξυπηρετών κόμβος είδε το αρχικό αίτημα. Σε ένα farm δεν το έκανε, έτσι ο έλεγχος ανά συνεδρία θα απορρίψει νόμιμα αιτήματα· ένα farm επομένως ορίζει 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 απελευθερώνει μια τοπική συνεδρία. Για να αφαιρέσετε τα δημοσιευμένα τεχνουργήματα ενός εγγράφου από το share, ο εκδότης εκθέτει:

text
bool CloseDistributedDocument(FileShareConfig fileShareConfig, string token)

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

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

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

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