Κατανεμημένες Αναπτύξεις
Εξυπηρέτηση ενός εγγράφου από πολλούς κόμβους
Όταν πολλοί κόμβοι εξυπηρετούν τα ίδια έγγραφα, ο κόμβος που αποδίδει ένα έγγραφο δεν είναι απαραίτητα ο κόμβος που απαντά στα αιτήματα σελίδων του προγράμματος περιήγησης. Το Doconut χωρίζει αυτή τη δουλειά σε δύο σαφείς μισά — μια πλευρά εγγραφής που δημοσιεύει τα τεχνικά στοιχεία ενός εγγράφου σε κοινόχρηστη αποθήκη, και μια πλευρά ανάγνωσης που τα εξυπηρετεί από οποιονδήποτε κόμβο.
Ένας μόνος κόμβος δεν χρειάζεται τίποτα από αυτό: η κανονική διαδρομή OpenDocumentAsync διατηρεί το έγγραφο στη μνήμη αυτού του κόμβου και το συνδέει με τη συνεδρία του προγράμματος περιήγησης (δείτε Συνεδρίες & Ασφάλεια). Χρησιμοποιήστε αυτή τη σελίδα όταν τα αιτήματα σελίδας μπορούν να καταλήξουν σε έναν κόμβο που δεν έχει δει ποτέ το άνοιγμα.
Πώς ταιριάζουν τα δύο μισά
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. Δημιουργήστε τη διαμόρφωση σε ακριβώς ένα μέρος και καταχωρίστε την μία φορά, ώστε και τα δύο μισά να διαβάζουν το ίδιο αντικείμενο:
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.
| Ιδιότητα | Σκοπός |
|---|---|
Location | CloudLocation.FileShare για κοινή χρήση UNC/τοπική |
RootPath | Ο κοινόχρηστος φάκελος που μπορεί να προσεγγίσει κάθε κόμβος |
UsePerTokenSubfolders | Διατηρεί τα τεχνικά στοιχεία κάθε εγγράφου στον δικό του φάκελο {token} (προεπιλογή true) |
ReadReadyPollMs | Πόσο χρόνο περιμένει η πλευρά ανάγνωσης για μια σελίδα που μια background publish εξακολουθεί να γράφει· 0 (η προεπιλογή) ελέγχει μία φορά. Δεν έχει καμία επίδραση στα έγγραφα που δημοσιεύονται συγχρονισμένα |
Πλευρά εγγραφής — δημοσίευση του εγγράφου
Ενθέστε DistributedDocumentPublisher και δημοσιεύστε αντί να ανοίξετε τοπική συνεδρία. Μία κλήση αποδίδει και γράφει το πλήρες σύνολο τεχνικών στοιχείων — σελίδες, πληροφορίες εγγράφου, ευρετήριο αναζήτησης και μεταδεδομένα — και επιστρέφει όταν ολοκληρωθεί:
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 επιστρέφει επίσης ένα υπογεγραμμένο εισιτήριο πρόσβασης — δείτε Ασφάλεια μεταξύ κόμβων.
Πλευρά ανάγνωσης — εξυπηρέτηση από το κοινόχρηστο
Τοποθετήστε τον χειριστή FileShare στον κλάδο που καλεί ο πελάτης — /doconut, ταιριάζοντας με το BasePath: 'doconut' — πίσω από τον έλεγχο του εισιτηρίου:
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:
builder.Services.AddDoconut(options => { /* … */ });
builder.Services.AddDoconutDistributedAsyncPublish();Χωρίς αυτήν την εγγραφή, τίποτα δεν καταχωρείται και η δημοσίευση παραμένει συγχρονισμένη, ακριβώς όπως πριν.
Στη συνέχεια, καλέστε το EnqueueAsync αντί για το PublishAsync. (Το DistributedDocumentPublishOptions.Async είναι μόνο μια σημαία που μπορεί να διαβάσει ο δικός σας κώδικας για να επιλέξει μεταξύ των δύο διαδρομών· ο εκδότη το αγνοεί.) Η ουρά είναι περιορισμένη: όταν κορεστεί, το EnqueueAsync ρίχνει DistributedPublishQueueFullException. Απαντήστε το με ένα 503 και μια κεφαλίδα Retry-After ώστε οι πελάτες να υποχωρήσουν αντί να κολλήσουν:
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:
const objViewer = $('#div_ctlDoc').docViewer({
BasePath: 'doconut',
ResPath: 'doconut-res/images',
retryOn409: true // επαναπροσπάθειες 202 (και legacy 409) απαντήσεις ετοιμότητας
});Ένας πελάτης που δεν επαναπροσπαθεί εμφανίζει σπασμένα πλακίδια για σελίδες που εξακολουθούν να αποδίδονται. Ο προϋπολογισμός επαναπροσπάθειας και οι προεπιλογές του (retryInitialDelayMs, retryBackoffFactor, retryMaxDelayMs, retryMaxAttempts, retryMaxTotalMs) τεκμηριώνονται στο ViewerConfig.
Ασφάλεια μεταξύ κόμβων
Τα διακριτικά που συνδέονται με τη συνεδρία υποθέτουν ότι ο κόμβος εξυπηρέτησης είδε το αρχικό αίτημα. Σε ένα farm δεν το έκανε, έτσι ο έλεγχος ανά συνεδρία θα απορρίψει νόμιμα αιτήματα· ένα farm επομένως ορίζει UnsafeMode = true.
UnsafeMode = true δεν είναι το μοντέλο ασφαλείας — είναι η αφαίρεση ενός που δεν ισχύει πια. Αντικαταστήστε το με υπογεγραμμένα εισιτήρια πρόσβασης, τα οποία κάθε κόμβος μπορεί να επαληθεύσει ανεξάρτητα. Τέσσερα στοιχεία συνεργάζονται.
1. Καταχωρίστε την ασφάλεια των εισιτηρίων σε κάθε κόμβο. Τα εισιτήρια προστατεύονται με το ASP.NET Core Data Protection, έτσι κάθε κόμβος πρέπει να χρησιμοποιεί το ίδιο σύνολο κλειδιών και το ίδιο όνομα εφαρμογής· ένας κόμβος με διαφορετικά κλειδιά δεν μπορεί να διαβάσει ένα εισιτήριο που εκδόθηκε από άλλο κόμβο.
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 που συγκρίνει η πλευρά ανάγνωσης) και τον συνδεδεμένο χρήστη, εάν υπάρχει:
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 με κάθε αίτημα:
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, ο εκδότες εκθέτει:
bool CloseDistributedDocument(FileShareConfig fileShareConfig, string token)Περάστε το ίδιο FileShareConfig με το οποίο δημοσιεύτηκε το έγγραφο.
Λίστα ελέγχου
- Δομήστε το
FileShareConfigσε έναν βοηθό, καταχωρίστε το μία φορά και χρησιμοποιήστε το και από τις δύο πλευρές. - Κατευθύνετε το
RootPathσε έναν φάκελο που μπορεί να προσεγγίσει κάθε κόμβος. - Δημοσιεύστε με
PublishAsync(...), ήEnqueueAsync(...)με δημοσίευση στο παρασκήνιο. - Εξυπηρετήστε με
UseDoconutCloud<FileShareCloudHandler>(...)στον κλάδο που καλεί ο πελάτης. - Με τη δημοσίευση στο παρασκήνιο, ενεργοποιήστε τα
FirstPagePriorityκαιretryOn409μαζί, και δώστε στην πλευρά ανάγνωσης ένα μη μηδενικόReadReadyPollMs. - Αντικαταστήστε τον έλεγχο ανά συνεδρία με υπογεγραμμένα εισιτήρια πρόσβασης — ένα δαχτυλίδι κλειδιών Data Protection σε κάθε κόμβο,
UseDoconutDistributedDocumentSecurity()στον κλάδο ανάγνωσης, ένα εισιτήριο από το ανοιχτό άκρο — και μην αποστέλλετε τοUnsafeMode = trueμόνο του. - Επαληθεύστε ανοίγοντας ένα έγγραφο σε έναν κόμβο και ζητώντας μια καθυστερημένη σελίδα από έναν άλλο.
Ήταν αυτή η σελίδα χρήσιμη;