Θεμέλιο πλατφόρμας

Το Libre WebUI υποστηρίζει τοπικό προφίλ solo και κοινό team. Solo χρησιμοποιεί SQLite, κρυπτογραφημένα τοπικά blobs και embedded vectors, τοπικό coordination και embedded durable worker. Team χρησιμοποιεί PostgreSQL, private S3 blobs, PGVector, Redis και external worker. Μικτά profiles απορρίπτονται στην εκκίνηση αντί να χωρίζεται σιωπηρά η κατάσταση.

Τρέχον ορόσημο

Περιοχή	Υλοποιημένο θεμέλιο	Υπόλοιπο
Persistency	Repositories SQLite/PostgreSQL, immutable migrations, pooled transactions	Νέα domains μέσω repository boundaries
Blobs	Κρυπτογραφημένο local/S3 streaming, ranges, checksums, durable quotas	Μεταφορά attachments, avatars και inline binary
Vectors	Κρυπτογραφημένα embedded vectors, PGVector ACL, ασφαλές rebuild	Ίδια authority/lifecycle σε νέους callers
Coordination	Local/Redis events, cache, leases, rate limits, invalidation, health	Redis μη authoritative
Jobs/events	SQLite/PostgreSQL queues, transactional events, workers, retries, cancellation, admin	Idempotency ή outbox για κάθε side effect
Operations	Health gates, signed/encrypted archives, clean restore, verification	Restore/cross-replica acceptance ανά deployment

Προφίλ runtime

LIBRE_PLATFORM_MODE=solo είναι προεπιλογή: SQLite, local blobs, embedded vectors, local coordination, embedded worker. Redis στο solo δεν κάνει ασφαλή την κοινή χρήση τοπικών αρχείων.

LIBRE_PLATFORM_MODE=team απαιτεί μαζί:

• DATABASE_BACKEND=postgres με DATABASE_URL·
• BLOB_STORE_BACKEND=s3·
• VECTOR_STORE_BACKEND=pgvector·
• COORDINATION_BACKEND=redis με REDIS_URL· και
• JOB_WORKER_MODE=external.

Ελλιπής shared dependency ή local backend σταματά το start.

Μετανάστευση υπάρχοντος solo

Σταματήστε apps/workers. Χρησιμοποιήστε libre-webui, αλλιώς npx --yes libre-webui@latest· από source αντικαταστήστε libre-webui migrate-postgres με npm run migrate:postgres --. Ρυθμίστε στόχους και τρέξτε πρώτα:

libre-webui migrate-postgres \
  --source /absolute/path/to/data.sqlite \
  --plugins /absolute/path/to/plugins \
  --mode dry-run

Apply μόνο σε κενό στόχο. Διακοπή αφήνει checksummed journal για resume του ίδιου source/target:

libre-webui migrate-postgres \
  --source /absolute/path/to/data.sqlite \
  --plugins /absolute/path/to/plugins \
  --mode apply

# Only after an interrupted apply of this exact source and target:
libre-webui migrate-postgres \
  --source /absolute/path/to/data.sqlite \
  --plugins /absolute/path/to/plugins \
  --mode apply --resume

libre-webui migrate-postgres \
  --source /absolute/path/to/data.sqlite \
  --plugins /absolute/path/to/plugins \
  --mode validate

Completion marker γράφεται μετά τη μεταφορά relational rows, plugins, encrypted blobs, vectors και legacy persona vectors. ENCRYPTION_KEY ταιριάζει .encryption_key πηγής και STORAGE_ENCRYPTION_KEYS περιέχει active και legacy.

Εκτέλεση team profile

cp deploy/team/.env.example /absolute/path/to/libre-team.env
chmod 600 /absolute/path/to/libre-team.env

Αντικαταστήστε REPLACE_*. PostgreSQL password URL-safe, π.χ. openssl rand -hex 32. ENCRYPTION_KEY και κάθε STORAGE_ENCRYPTION_KEYS είναι 64 hex. Σε νέα εγκατάσταση legacy = ENCRYPTION_KEY, σε migration = source key. Χρησιμοποιήστε άλλο active key για νέα blobs και κρατήστε παλιά μέχρι verification.

Το αρχείο μπορεί να ορίσει POSTGRES_MIGRATION_MODE, POSTGRES_POOL_MAX, timeouts PostgreSQL, REDIS_CONNECT_TIMEOUT_MS, OLLAMA_BASE_URL, OLLAMA_TIMEOUT, OLLAMA_LONG_OPERATION_TIMEOUT, OLLAMA_MAX_CONTEXT. Timeouts 1.000–3.600.000 ms, context 128–2.097.152 tokens και long timeout όχι μικρότερο. Άκυρα values σταματούν entrypoints. Node-local Agent CLI και Codex OAuth δεν υποστηρίζονται σε external worker.

docker compose --env-file /absolute/path/to/libre-team.env \
  -f docker-compose.team.yml up --build --scale libre-webui=3 -d
docker compose --env-file /absolute/path/to/libre-team.env \
  -f docker-compose.team.yml ps

Το βασικό profile δεν mountάρει Docker socket. Για Work συμπεριλάβετε overlay:

docker compose --env-file /absolute/path/to/libre-team.env \
  -f docker-compose.team.yml -f docker-compose.team.work.yml \
  up --build --scale libre-webui=3 -d
docker compose --env-file /absolute/path/to/libre-team.env \
  -f docker-compose.team.yml -f docker-compose.team.work.yml ps

Overlay χρησιμοποιεί filtered internal proxy για app/worker. Δεν δίνει raw socket ή host folders. Επιτρέπει info, images, containers, exec, volumes, networks και απαραίτητα writes. Μειώνει API αλλά Docker δεν είναι tenant boundary επειδή containers μπορούν bind-mount host paths. Χρησιμοποιήστε dedicated VM ή rootless/separate daemon.

Μην εκθέτετε PostgreSQL, Redis, MinIO του Compose. Για managed dependencies χρησιμοποιήστε Helm team profile και TLS. Readiness αποτυγχάνει χωρίς external worker.

Όριο μονιμότητας και migration

Identity/authorization χρησιμοποιούν async repositories. Transaction callback λαμβάνει unit of work στο ίδιο connection· global repository μέσα απορρίπτεται. Ο coordinator SQLite υιοθετεί μετά schema validation, καταγράφει migration/checksum και απορρίπτει νέα, άγνωστα ή αλλαγμένα ledgers. Readiness/recovery χρησιμοποιούν ίδια σύμβαση.

Πριν stateful services, SQLite και WAL/SHM αντιγράφονται σε private scratch και επικυρώνονται. PLATFORM_PREFLIGHT_TMP_DIR πρέπει να χωρά database+WAL· Docker/Helm mountάρουν δίσκο αντί /tmp. Ελλιπές legacy key ή nested data directory σταματά start.

Schema v4 προσθέτει keyed equality token email. Recovery απαιτεί match. Start επιτρέπει προσωρινά ελλιπές token με authenticated email για backfill. Κενά γίνονται NULL, κατεστραμμένο envelope ή non-null mismatch αποτυγχάνει.

Υπηρεσίες χρησιμοποιούν async dialect repositories. Native SQLite περιορίζεται σε adapters, migration/recovery και injected health. Η Persistence αρχικοποιεί runtime· PostgreSQL δεν πέφτει σε SQLite ή cwd JSON.

Το durable runtime είναι driver-neutral. Actor authorization από identity repository, native job construction σε adapter boundary και publishers παίρνουν opaque executor, ποτέ better-sqlite3. Tests απορρίπτουν native handles σε common contracts.

Θεμέλιο blob και vector storage

Gallery media και document sources χρησιμοποιούν BlobStore, RAG και persona memory VectorStore. Legacy gallery rows dual-read και υιοθετούνται ως blob references. Relational metadata και durable reference είναι authoritative· provider URLs/S3 keys δεν αποθηκεύονται. Attachments/avatars δεν έχουν ακόμη μεταναστεύσει.

Recovery πιστοποιεί κάθε object/vector envelope σειριακά με όρια, μαζί με legacy texts και voice envelopes με ENCRYPTION_KEY, χωρίς compatibility fallback. Δεν αρχικοποιεί ή διορθώνει. Κατεστραμμένο ciphertext, λάθος key, μη canonical layout ή υπέρβαση μπλοκάρουν.

Όρια: 250.000 local objects, 64 GiB encrypted/plain blob bytes, 250.000 vector rows, 4 GiB serialized ciphertext, 500 εκατομμύρια components. Tests μπορούν override με RecoveryInventoryOptions, CLI δεν κάνει sampling. Legacy όριο ένα εκατομμύριο fields και 16 GiB.

Κρυπτογραφημένα τοπικά blobs

BlobStore είναι owner-scoped με streaming put/read, metadata/stat, inclusive ranges και idempotent deletion. LocalEncryptedBlobStore γράφει UUID objects κάτω από ${DATA_DIR}/blobs μέσω staging, fsync και atomic rename, directories 0700, files 0600.

Κάθε object έχει random 256-bit data key. AES-256-GCM κρυπτογραφεί metadata και chunks· AAD δένει blob id, owner, purpose, chunk index, length. Versioned keyring τυλίγει key. Descriptor έχει size, SHA-256, content type, time, version και key ID. Full read επαληθεύει SHA-256 και range κάθε chunk.

Quota κάνει reservation πριν streaming, καταναλώνει actual bytes και commit μετά atomic visibility. SQLite BEGIN IMMEDIATE, PostgreSQL serializable/locks. BLOB_QUOTA_BYTES_PER_USER θέτει limit και BLOB_QUOTA_RESERVATION_TTL_MS TTL.

BLOB_STORE_BACKEND=s3 χρησιμοποιεί private bucket, opaque keys, encrypted streams/descriptors, ranges, SHA-256 και idempotent deletion με reconciliation. MinIO tests cross-replica, tenant isolation, quota contention και injected failures.

Κρυπτογραφημένα embedded vectors

VectorStore απαιτεί actor σε κάθε query/mutation. Rows έχουν namespace, tenant ID, owner, resource ID, model, dimensions, version, revision, attributes και grants.

SQLite εφαρμόζει metadata/ACL predicates πριν φύγει ciphertext· μόνο authorized candidates αποκρυπτογραφούνται και cosine-scored. Upsert αντικαθιστά embedding/ACL/attributes atomic. AES-256-GCM δένει identity/model. Queryable metadata είναι plaintext χωρίς secrets.

VECTOR_STORE_BACKEND=pgvector εφαρμόζει predicates στο ίδιο SQL με distance και LIMIT. Απαγορεύεται post-filter global neighbors. Group membership επιλύεται trusted σε κάθε query και supplied groupIds αγνοείται.

Ingestion/regeneration καταγράφει immutable spec: enabled, model, vector/chunker version, chunk size, overlap, threshold. Ίδιο spec ελέγχει chunks, publication, upsert και query. Metadata καταγράφει revision/spec.

Regeneration κρατά renewable lease και ελέγχει owner row/tombstone πριν και μετά mutation. Concurrent deletion αφαιρεί recreated vectors. Team reads δεν mutate PGVector. SQLite republish μόνο με ακριβές manifest.

Indexes αντικαθίστανται σε batches 1.000 και ελέγχεται πλήρες manifest. Έγγραφο έως 100.000 chunks· το 100.001 απορρίπτεται πριν embedding και job dead-lettered χωρίς retry.

Pre-manifest vectors χωρίς model proof ξαναδημιουργούνται από authoritative text υπό current spec/lease. Migration σε team αποτυγχάνει χωρίς πλήρες current manifest και exact encrypted index. Τρέξτε solo με ίδια DATA_DIR, ENCRYPTION_KEY, επιλέξτε model, Settings -> Documents -> Regenerate embeddings, ξανατρέξτε dry-run.

SQLite κρυπτογραφεί embeddings μετά ACL· PGVector χρειάζεται numeric column και δεν το κρυπτογραφεί application-level. Απαιτήστε TLS, encrypted volumes/backups, least privilege και logs χωρίς vectors/source. Attributes είναι plaintext χωρίς secrets.

Κλειδιά κρυπτογράφησης storage

Με versioned keyring απαιτείται σταθερό 64-char ENCRYPTION_KEY, ίδιο στο legacy του STORAGE_ENCRYPTION_KEYS και STORAGE_ENCRYPTION_ACTIVE_KEY_ID. Writes active, reads όλα. Κρατήστε παλιά μέχρι verified rewrite.

Χωρίς map χρησιμοποιείται ENCRYPTION_KEY ως legacy ή private regular ${DATA_DIR}/.encryption_key. Factory δεν δημιουργεί/αντικαθιστά. Conflict, missing, malformed ή unknown key αποτυγχάνει κλειστά. Embedded query υπολογίζει budget candidates/bytes/dimensions πριν decrypt.

Συντονισμός

Η σύμβαση προσφέρει events, expiring cache, fenced leases και fixed-window rate limits. Local implementation για ένα replica. Redis έχει ξεχωριστά clients, bounded payloads, namespace, atomic scripts, owner tokens και fencing και δεν πέφτει σε local μετά σφάλμα.

Redis δεν είναι source of truth. Authorization, durable jobs και replayable events μένουν database· Redis για wake-up, cache invalidation, presence, quota, coordination. Critical side effect επαληθεύει lease/fencing.

Durable jobs και events

SQLite v3 παρέχει job/attempt/stream/event tables με idempotent enqueue, retry, cancellation, progress, heartbeat/reclaim, dead letter και global cursor replay. Encrypted JSON χρησιμοποιεί keyring και identity ως AAD· references bounded opaque IDs.

SQLite v13/PostgreSQL v12 προσθέτουν (stream_id, subject_id, global_cursor) ώστε filters προηγούνται catch-up. Handlers καλύπτουν documents, media continuation και cleanup. Creation/deletion enqueue στο ίδιο transaction και cleanup αφαιρεί vectors, blobs, references, cache και queued work.

Recovery μετρά states/attempts, streams/cursors, μπλοκάρει ενεργά, πιστοποιεί payloads και απορρίπτει head mismatch/sequence gaps. Monotonic lease tokens δεν παρέχουν exactly-once· handlers χρειάζονται idempotency ή outbox/inbox και revalidation.

SQLite v4 χρησιμοποιεί unique keyed email lookup HMAC δίπλα σε random ciphertext για atomic duplicates. Start πιστοποιεί/backfills legacy email.

Υγεία και ανάκτηση

• /health και /health/live μόνο process.
• /health/ready database, schema, writable storage και required dependencies, όχι optional providers.
• /health/deep admin, bounded SQLite integrity/foreign key και optional provider warnings.

Τρέξτε libre-webui recovery-check --json ή npm run recovery:check -- --json. Το read-only inventory αναφέρει schema/keys, blobs, vectors, ciphertext, jobs/events, sizes, plugins, media, Work resources/labels, checkpoints, active runs, blockers και exclusions. Είναι pre-backup gate. Δείτε Ετοιμότητα ανάκτησης.

Πιστοποιημένη λειτουργία πολλών replicas

Team πιστοποιείται για 3+ app replicas και external worker όταν PostgreSQL, PGVector, Redis, S3, shared secrets και JOB_WORKER_MODE=external ρυθμίζονται μαζί. Helm απορρίπτει πολλαπλά replicas χωρίς πλήρες profile και migration επιλέγει leader με PostgreSQL advisory lock.

Release τρέχει npm run test:team-platform με πραγματικό image και δοκιμάζει stream resume, worker death, replay, Redis outage με SQL, revocation, rate limits, S3 retry και tenant isolation. secrets.existingSecret και networkPolicy.enabled σκληραίνουν pods. Defaults: non-root, read-only root, dropped capabilities, seccomp RuntimeDefault, no privilege escalation.

Υπόλοιπες μεταβάσεις

Voice audio, chat attachments, avatars και future binary resources χρειάζονται metadata, dual-read/backfill, retention και deletion tests πριν blob migration. Κάθε embedding caller πρέπει μέσω VectorStore να μεταφέρει model, dimensions, version, revision, owner, scope και trusted grants.

Νέα long-running side effects πρέπει να register durable target, υποστηρίζουν cancellation/retry και transactional enqueue/outbox. Προσθέστε κάθε resource στα cross-replica και backup/restore gates πριν team.