Μετάβαση στο κύριο περιεχόμενο

Έλεγχος ταυτότητας και ασφάλεια

Το Libre WebUI χρησιμοποιεί τοπικούς λογαριασμούς χρηστών με συνεδρίες JWT. Μια νέα εγκατάσταση επιτρέπει πάντα την αρχική δημιουργία ενός τοπικού διαχειριστή. Η δημόσια εγγραφή για κάθε μεταγενέστερο τοπικό λογαριασμό ή λογαριασμό OAuth είναι κλειστή από προεπιλογή.

Ρύθμιση πρώτης χρήσης​

Όταν η βάση δεδομένων δεν έχει χρήστες:

  1. Το Libre WebUI εμφανίζει τη ροή ρύθμισης πρώτης χρήσης.
  2. Ο χρήστης δημιουργεί τον πρώτο τοπικό λογαριασμό.
  3. Στον λογαριασμό εκχωρείται ο ρόλος admin.
  4. Κάθε μεταγενέστερη δημόσια εγγραφή παραμένει κλειστή, εκτός αν ενεργοποιηθεί ρητά.

Οι υπάρχουσες βάσεις δεδομένων διατηρούν τους τρέχοντες χρήστες και ρόλους τους.

Τοπικοί λογαριασμοί​

Η τοπική εγγραφή απαιτεί:

  • Όνομα χρήστη
  • Κωδικό πρόσβασης από 12 χαρακτήρες έως 72 byte UTF-8, με κεφαλαίο, πεζό και αριθμό
  • Προαιρετικό e-mail

Οι κωδικοί πρόσβασης κατακερματίζονται με bcrypt πριν αποθηκευτούν. Οι διαδρομές σύνδεσης και εγγραφής έχουν περιορισμό ρυθμού.

Έγκριση εγγραφής​

Η δημόσια εγγραφή δεν παρέχει από μόνη της πρόσβαση. Κάθε λογαριασμός που δημιουργείται μέσω της δημόσιας φόρμας εγγραφής ή παρόχου OAuth ξεκινά σε κατάσταση pending και πρέπει να εγκριθεί από διαχειριστή πριν μπορέσει να συνδεθεί.

Η μοναδική εξαίρεση είναι η αρχική δημιουργία: ο πρώτος πραγματικός λογαριασμός σε κενή βάση δεδομένων δημιουργείται ατομικά ως active με τον ρόλο admin, ώστε μια νέα εγκατάσταση να αποκτά λειτουργικό διαχειριστή. Κάθε μεταγενέστερη εγγραφή περιμένει αξιολόγηση.

Τι βλέπει ένας χρήστης σε αναμονή:

  • Η εγγραφή επιτυγχάνει αλλά δεν επιστρέφει token συνεδρίας. Το API απαντά 202 με approvalRequired: true και το UI εξηγεί ότι ο λογαριασμός πρέπει να εγκριθεί από διαχειριστή.
  • Η σύνδεση με κωδικό και σωστά διαπιστευτήρια απορρίπτεται με 403 και τον κωδικό ACCOUNT_PENDING ("Your account is waiting for administrator approval"). Μια σύνδεση OAuth ανακατευθύνει στη σελίδα σύνδεσης με ?approval=pending.
  • Η κατάσταση λογαριασμού διαβάζεται ξανά από τη βάση δεδομένων σε κάθε πιστοποιημένο αίτημα, επομένως μια συνεδρία δεν μπορεί ποτέ να διαρκέσει περισσότερο από την κατάσταση active του λογαριασμού.

Τι βλέπει ένας διαχειριστής:

  • Η Διαχείριση χρηστών εμφανίζει κάρτα Εκκρεμείς εγκρίσεις με τους λογαριασμούς σε αναμονή, καθένας με ενέργεια Ενεργοποίηση λογαριασμού και ενέργεια απόρριψης. Η απόρριψη ισοδυναμεί με διαγραφή· δεν υπάρχει ξεχωριστή κατάσταση αναστολής.
  • Οι διαχειριστές ειδοποιούνται μέσα στην εφαρμογή όσο είναι συνδεδεμένοι: εμφανίζεται σήμα στην καταχώριση Χρήστες και αναδυόμενη ειδοποίηση όταν φτάνουν νέες εγγραφές. Η σύνοψη εκκρεμών εγκρίσεων ελέγχεται περίπου μία φορά το λεπτό (GET /api/users/pending-approvals, μόνο για διαχειριστές).
  • Η έγκριση (PATCH /api/users/:id/approve, μόνο για διαχειριστές) καταγράφει ποιος διαχειριστής ενέκρινε τον λογαριασμό και πότε. Δεν αλλάζει τον ρόλο: οι εγκεκριμένοι λογαριασμοί διατηρούν τον ρόλο user μέχρι να τους προαγάγει διαχειριστής. Η έγκριση τίθεται σε ισχύ στην επόμενη προσπάθεια σύνδεσης του χρήστη· δεν χρειάζεται να δημιουργηθεί ξανά τίποτε.

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

Σκόπιμη ενεργοποίηση δημόσιας εγγραφής​

Η εγγραφή είναι απενεργοποιημένη από προεπιλογή. Ορίστε την παρακάτω μεταβλητή περιβάλλοντος backend μόνο για όσο διάστημα πρέπει να γίνονται δεκτοί νέοι τοπικοί λογαριασμοί ή λογαριασμοί OAuth:

ENABLE_SIGNUP=true

Επαναφέρετέ την σε false μετά από κάθε προγραμματισμένο παράθυρο εγγραφών. Οι υπάρχοντες τοπικοί χρήστες και χρήστες OAuth εξακολουθούν να μπορούν να συνδέονται, ενώ οι διαχειριστές μπορούν να δημιουργούν λογαριασμούς από τη Διαχείριση χρηστών όσο η δημόσια εγγραφή είναι κλειστή.

Μια κενή βάση δεδομένων επιτρέπει πάντα έναν τοπικό διαχειριστή, ακόμη και με ENABLE_SIGNUP=false· το OAuth δεν μπορεί να καταλάβει αυτή την αρχική θέση. Για ιδιωτική απομακρυσμένη ανάπτυξη, τοποθετήστε το όνομα host πίσω από λίστα επιτρεπόμενων ταυτοτήτων, όπως το Cloudflare Access, πριν εκκινήσετε την εφαρμογή και έπειτα δημιουργήστε τον αρχικό διαχειριστή μέσω αυτής της προστατευμένης διαδρομής.

Ρόλοι​

ΡόλοςΣκοπός
adminΔιαχείριση εγκατάστασης, χρηστών και ρυθμίσεων συστήματος και έμπιστη λειτουργία runtime Work
userΚανονικές ροές συνομιλίας, μοντέλων, περσόνων, εγγράφων και ρυθμίσεων

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

Πρόσβαση στο Work​

Το Work περιορίζεται από προεπιλογή στους διαχειριστές, επειδή επιτρέπει σε ένα επιλεγμένο μοντέλο να εκτελεί αυθαίρετες εντολές μέσα σε διαχειριζόμενο κοντέινερ. Ένας διαχειριστής μπορεί να ανοίξει το Work σε όλους τους ενεργούς χρήστες από την καρτέλα Διαχείριση χρηστών στις Ρυθμίσεις· η ρύθμιση διατηρείται στις επανεκκινήσεις και εφαρμόζεται αμέσως, ακόμη και σε ανοικτές συνεδρίες τερματικού. Οι χώροι εργασίας με φακέλους host παραμένουν διαθέσιμοι μόνο σε διαχειριστές σε κάθε λειτουργία, επειδή προσαρτούν διαδρομές διακομιστή. Αντιμετωπίζετε κάθε άτομο με πρόσβαση Work ως έμπιστο χειριστή runtime, όχι μόνο ως χρήστη WebUI.

Η εξουσιοδότηση διαχειριστή ελέγχεται έναντι του τρέχοντος ρόλου στη βάση δεδομένων και όχι μόνο του ρόλου που έχει αποθηκευτεί σε υπάρχον JWT. Επομένως, ο υποβιβασμός διαχειριστή ανακαλεί αμέσως την πρόσβαση Work. Στη συνέχεια, το backend επιχειρεί να ακυρώσει ενεργές εκτελέσεις και να σταματήσει τα κοντέινερ Work και τις προεπισκοπήσεις του χρήστη, διατηρώντας τις εγγραφές εργασιών και τους επώνυμους τόμους. Αν αποτύχει η εκκαθάριση Docker, η πρόσβαση παραμένει ανακλημένη, η αλλαγή ρόλου αναφέρει την αποτυχία εκκαθάρισης και ο χειριστής πρέπει να αποκαταστήσει την πρόσβαση Docker και να δοκιμάσει ξανά.

Η διαγραφή χρήστη καταστρέφει τα δεδομένα Work του. Το Libre WebUI σταματά πρώτα τα διαχειριζόμενα κοντέινερ και αφαιρεί τους τόμους Work του και έπειτα διαγράφει τον λογαριασμό και τις εγγραφές βάσης δεδομένων. Αν το Docker δεν μπορεί να αποδείξει ότι η εκκαθάριση πέτυχε, η διαγραφή λογαριασμού αποτυγχάνει, ώστε ο διαχειριστής να διορθώσει το πρόβλημα runtime και να προσπαθήσει ξανά.

Ομάδες και παραχωρήσεις πόρων​

Οι διαχειριστές μπορούν να δημιουργούν ομάδες και να διαχειρίζονται συμμετοχές από την καρτέλα Διαχείριση χρηστών στις Ρυθμίσεις. Οι ομάδες αποτελούν υποκείμενα παραχωρήσεων πόρων: ο κάτοχος μιας συνομιλίας, σημείωσης, εγγράφου, συλλογής γνώσης, φακέλου, περσόνας, προτροπής, δεξιότητας ή ημερολογίου μπορεί να παραχωρήσει πρόσβαση read, write ή admin σε χρήστη ή ομάδα μέσω του API πρόσβασης — κάθε επιφάνεια που μπορεί να κοινοποιηθεί χρησιμοποιεί το ίδιο παράθυρο κοινής χρήσης (βλ. Κοινή χρήση) — και οι διαχειριστές μπορούν με τον ίδιο τρόπο να περιορίσουν καταχωρισμένους διακομιστές εργαλείων σε χρήστες ή ομάδες. Οι πόροι παραμένουν ιδιωτικοί από προεπιλογή — ο καθολικός ρόλος admin δεν παρέχει πρόσβαση στο περιεχόμενο άλλων χρηστών. Η συμμετοχή αξιολογείται κατά το αίτημα, επομένως η αφαίρεση μέλους ανακαλεί αμέσως την πρόσβαση που του παραχωρήθηκε μέσω ομάδας. Η προβολή «πραγματική πρόσβαση» στην καρτέλα Διαχείριση χρηστών στις Ρυθμίσεις απαντά στο «γιατί έχει πρόσβαση αυτός ο χρήστης;» παραθέτοντας τον ρόλο, τις ομάδες, την πρόσβαση σε δυνατότητες και κάθε παραχώρηση που τον αφορά.

Αρχείο ελέγχου ασφάλειας​

Οι ενέργειες που αφορούν την ασφάλεια — συνδέσεις και αποτυχίες, αποσυνδέσεις, ανακλήσεις συνεδριών και token, αλλαγές χρηστών, ομάδων, παραχωρήσεων και token — καταγράφονται σε αρχείο ελέγχου μόνο για προσθήκη, ξεχωριστό από τις αναλύσεις χρήσης. Οι λεπτομέρειες ανωνυμοποιούνται πριν αποθηκευτούν: κλειδιά που μοιάζουν με μυστικά αφαιρούνται και τα μεγέθη ωφέλιμου φορτίου περιορίζονται, ώστε κωδικοί πρόσβασης, token και περιεχόμενο προτροπών να μην εισέρχονται ποτέ στο αρχείο. Οι μεταβολές ομάδων και παραχωρήσεων γράφουν το συμβάν ελέγχου στην ίδια συναλλαγή βάσης δεδομένων, ώστε μια αλλαγή να μην μπορεί να υπάρξει χωρίς ίχνος. Οι διαχειριστές μπορούν να υποβάλουν ερωτήματα στο αρχείο από την καρτέλα Διαχείριση χρηστών στις Ρυθμίσεις· η προεπιλεγμένη διατήρηση είναι 180 ημέρες (AUDIT_RETENTION_DAYS).

Συνεδρίες​

Το backend υπογράφει τα JWT με JWT_SECRET. Ορίστε ένα σταθερό μυστικό στην παραγωγή:

JWT_SECRET=replace-with-a-long-random-secret

Η αλλαγή του JWT_SECRET ακυρώνει τις υπάρχουσες συνεδρίες. Τα token τοπικής σύνδεσης και σύνδεσης OAuth χρησιμοποιούν το JWT_EXPIRES_IN, με προεπιλογή 7d· η αλλαγή αυτής της τιμής επηρεάζει τις νέες συνεδρίες. Οι συνδέσεις WebSocket ανταλλάσσουν το μόνιμο token με βραχύβιο, εφάπαξ εισιτήριο και κλείνουν όταν λήξει η υποκείμενη συνεδρία.

Κάθε σύνδεση δημιουργεί επίσης εγγραφή συνεδρίας στον διακομιστή, δεσμευμένη στο JWT. Οι Ρυθμίσεις → Συνεδρίες παραθέτουν κάθε συσκευή με τη μέθοδο σύνδεσης, την πρώτη και τελευταία δραστηριότητα και τη λήξη. Η ανάκληση μιας συνεδρίας εκεί (ή η «Αποσύνδεση άλλων συνεδριών») ακυρώνει αμέσως το token της σε κάθε replica και κλείνει τις ενεργές συνδέσεις WebSocket· η αποσύνδεση ανακαλεί την τρέχουσα συνεδρία με τον ίδιο τρόπο. Τα token που εκδόθηκαν πριν από αυτή τη δυνατότητα δεν περιέχουν id συνεδρίας και παραμένουν έγκυρα μέχρι τη λήξη τους, εκτός αν η «Αποσύνδεση άλλων συνεδριών» από νέα σύνδεση ορίσει επίσης χρονικό όριο ανά λογαριασμό που τα απορρίπτει.

Έλεγχος ταυτότητας δύο παραγόντων και passkeys​

Οι Ρυθμίσεις → Συνεδρίες διαχειρίζονται τόσο τους δεύτερους παράγοντες όσο και τη σύνδεση χωρίς κωδικό πρόσβασης:

  • Εφαρμογή ελέγχου ταυτότητας (TOTP). Η εγγραφή εμφανίζει ένα μυστικό base32 και σύνδεσμο otpauth:// για οποιαδήποτε εφαρμογή ελέγχου ταυτότητας· η επιβεβαίωση του πρώτου 6ψήφιου κωδικού την ενεργοποιεί και αποκαλύπτει δέκα εφάπαξ κωδικούς ανάκτησης. Στη συνέχεια, η σύνδεση με κωδικό πρόσβασης επιστρέφει βραχύβια πρόκληση αντί για συνεδρία και το POST /api/auth/mfa/verify ολοκληρώνει τη σύνδεση με κωδικό TOTP ή κωδικό ανάκτησης. Καταγράφεται το χρονικό βήμα κάθε αποδεκτού κωδικού, ώστε ένας υποκλαπείς κωδικός να μην μπορεί να επαναχρησιμοποιηθεί· οι κωδικοί ανάκτησης αποθηκεύονται μόνο ως μονόδρομα token αναζήτησης με κλειδί και καθένας λειτουργεί ακριβώς μία φορά. Η απενεργοποίηση ή νέα δημιουργία κωδικών ανάκτησης απαιτεί νέα απόδειξη ενός παράγοντα.
  • Passkeys (WebAuthn). Η «Σύνδεση με passkey» πραγματοποιεί σύνδεση χωρίς κωδικό πρόσβασης με ανιχνεύσιμο διαπιστευτήριο· η επαλήθευση χρήστη (κλείδωμα οθόνης, βιομετρικό στοιχείο ή PIN) απαιτείται κατά την εγγραφή και τη σύνδεση. Η βεβαίωση γίνεται δεκτή ως none, υποστηρίζονται διαπιστευτήρια ES256 και EdDSA και το υλικό διαπιστευτηρίων κρυπτογραφείται κατά την αποθήκευση, ενώ το id διατηρείται ως token αναζήτησης με κλειδί. Οι προκλήσεις είναι εφάπαξ και λήγουν μετά από πέντε λεπτά· ένας μη μηδενικός μετρητής υπογραφής που δεν αυξάνεται απορρίπτεται ως ένδειξη κλώνου. Τα passkeys χρειάζονται ασφαλή προέλευση (HTTPS) ή localhost στην ανάπτυξη· ορίστε WEBAUTHN_RP_ID όταν η εγκατάσταση είναι προσβάσιμη με περισσότερα από ένα ονόματα host.

Το token πρόκλησης MFA που εκδίδεται μετά από σωστό κωδικό πρόσβασης υπογράφεται με μυστικό που παράγεται από το JWT_SECRET αλλά είναι διαφορετικό από αυτό: δεν μπορεί ποτέ να πιστοποιήσει αίτημα API, δεσμεύεται σε έναν λογαριασμό και έναν σκοπό και καταναλώνεται όταν επιτύχει.

Οι διαχειριστές μπορούν να απαιτήσουν δεύτερο παράγοντα για κάθε λογαριασμό (Χρήστες → κάρτα πολιτικής δύο παραγόντων ή καρφίτσωμα με MFA_REQUIRED_MODE=required). Οι χρήστες χωρίς δεύτερο παράγοντα καθοδηγούνται στην εγγραφή κατά την επόμενη σύνδεσή τους πριν εκδοθεί συνεδρία. Οι διαχειριστές μπορούν επίσης να επαναφέρουν την εγγραφή TOTP ενός χρήστη από τη λίστα χρηστών για ανάκτηση λογαριασμού· τα passkeys παραμένουν, επειδή τα διαχειρίζεται ο χρήστης από τις ρυθμίσεις. Η εγγραφή, η ενεργοποίηση, οι αποτυχίες επαλήθευσης, η απενεργοποίηση, οι αλλαγές πολιτικής, η εγγραφή/αφαίρεση passkey και οι επαναφορές διαχειριστή καταγράφονται στο αρχείο ελέγχου ασφάλειας.

Το MFA εφαρμόζεται στις συνδέσεις με κωδικό πρόσβασης. Οι συνδέσεις OAuth και OIDC βασίζονται στον δεύτερο παράγοντα του παρόχου ταυτότητας και δεν προκαλούνται ξανά. Τα token API δεν επηρεάζονται: δεν χρησιμοποιούν ποτέ τον έλεγχο ταυτότητας συνεδρίας.

Token API​

Οι Ρυθμίσεις → Κλειδιά API δημιουργούν token προσωπικής πρόσβασης (πρόθεμα lwk_) για προγραμματιστική χρήση. Το μυστικό εμφανίζεται μία φορά και αποθηκεύεται μόνο ως hash. Κάθε token διαθέτει ρητή λίστα πεδίων (chat, models, documents, notes, personas, media, work, admin)· το backend αντιστοιχίζει κάθε οικογένεια διαδρομών σε απαιτούμενο πεδίο, επομένως ένα token μόνο για σημειώσεις δεν μπορεί να προσπελάσει συνομιλίες ή διαχείριση και η διαχείριση συνεδριών δεν είναι ποτέ προσβάσιμη με token. Τα token υποστηρίζουν προαιρετική λήξη, παρακολουθούν την τελευταία χρήση, μπορούν να ανακληθούν ανά πάσα στιγμή και έχουν περιορισμό ρυθμού ανά token σε όλες τις replica. Token με πεδίο admin μπορούν να δημιουργηθούν μόνο από διαχειριστές και κατά τη χρήση εξακολουθούν να απαιτούν ο λογαριασμός να έχει τον ρόλο admin. Ένα token με πεδίο chat είναι επίσης το κλειδί για το δημόσιο API /v1 που είναι συμβατό με OpenAI.

Cloudflare Turnstile​

Το Turnstile προστατεύει τη σύνδεση και την εγγραφή με κωδικό πρόσβασης όταν έχουν ρυθμιστεί και τα δύο κλειδιά:

TURNSTILE_SITE_KEY=...
TURNSTILE_SECRET_KEY=...
TURNSTILE_EXPECTED_HOSTNAME=chat.example.com

Το frontend εκχωρεί διακριτές ενέργειες login και signup. Το backend επαληθεύει το token με το Cloudflare και απορρίπτει απόκριση της οποίας το όνομα host ή η ενέργεια δεν συμφωνεί με το αίτημα. Το BASE_URL παρέχει το αναμενόμενο όνομα host όταν το TURNSTILE_EXPECTED_HOSTNAME δεν έχει οριστεί ρητά.

Αν λείπει οποιοδήποτε από τα δύο κλειδιά, το Turnstile απενεργοποιείται.

GitHub OAuth​

Ρυθμίστε:

GITHUB_CLIENT_ID=...
GITHUB_CLIENT_SECRET=...
GITHUB_CALLBACK_URL=https://your-domain.example/api/auth/oauth/github/callback

Η ροή GitHub OAuth δημιουργεί τοπικούς χρήστες με ονόματα που έχουν πρόθεμα gh_ και εκχωρεί από προεπιλογή τον ρόλο user.

Hugging Face OAuth​

Ρυθμίστε:

HUGGINGFACE_CLIENT_ID=...
HUGGINGFACE_CLIENT_SECRET=...
HUGGINGFACE_CALLBACK_URL=https://your-domain.example/api/auth/oauth/huggingface/callback

Η ροή Hugging Face OAuth δημιουργεί τοπικούς χρήστες με ονόματα που έχουν πρόθεμα hf_ και εκχωρεί από προεπιλογή τον ρόλο user.

Και οι δύο πάροχοι OAuth χρησιμοποιούν κρυπτογραφικά τυχαία τιμή state δεσμευμένη σε βραχύβιο cookie HttpOnly, SameSite. Το callback απορρίπτει state που λείπει ή δεν συμφωνεί. Μετά από επιτυχημένο callback, το JWT επιστρέφει στο frontend μέσα σε cookie HttpOnly διάρκειας 60 δευτερολέπτων, το οποίο ανταλλάσσεται και διαγράφεται αμέσως· τα bearer token δεν τοποθετούνται ποτέ σε URL callback, στο ιστορικό προγράμματος περιήγησης ή σε header referrer.

Ανακατευθύνσεις και CORS​

Ορίστε το BASE_URL για τις προεπιλογές callback και το CORS_ORIGIN για πρόσβαση από πρόγραμμα περιήγησης:

BASE_URL=https://your-domain.example
CORS_ORIGIN=https://your-domain.example

Για τοπική ανάπτυξη, συμπεριλάβετε την προέλευση ανάπτυξης Vite:

CORS_ORIGIN=http://localhost:5173,http://127.0.0.1:5173

Λειτουργία επίδειξης​

Η λειτουργία επίδειξης είναι λειτουργία προεπισκόπησης του frontend. Προσυμπληρώνει απενεργοποιημένα δοκιμαστικά διαπιστευτήρια και χρησιμοποιεί εικονικές αποκρίσεις API. Δεν αποτελεί λειτουργία ελέγχου ταυτότητας για παραγωγή.

Λίστα ελέγχου ασφάλειας​

  • Ορίστε ισχυρό JWT_SECRET.
  • Διατηρείτε το DATA_DIR σε μόνιμο χώρο αποθήκευσης με έλεγχο πρόσβασης.
  • Δημιουργείτε αντίγραφο ασφαλείας του ENCRYPTION_KEY μαζί με τη βάση δεδομένων.
  • Ρυθμίστε το Turnstile για δημόσια εγγραφή.
  • Χρησιμοποιήστε HTTPS για δημόσιες αναπτύξεις.
  • Περιορίστε τα κλειδιά API παρόχων στο ελάχιστο απαιτούμενο πεδίο.
  • Διατηρείτε ακριβείς τις URL callback OAuth.
  • Παραχωρείτε πρόσβαση Work (λογαριασμοί διαχειριστών ή λειτουργία ανοικτή σε όλους τους χρήστες) μόνο σε άτομα που εμπιστεύεστε για τη λειτουργία του runtime κοντέινερ του backend.

Σχετική τεκμηρίωση​