Plattformsgrund

Libre WebUI har en lokal solo-profil och en delad team-profil. Solo använder SQLite, krypterade lokala blobbar och inbäddade vektorer, lokal samordning och inbäddad beständig worker. Team använder PostgreSQL, privat S3-kompatibel bloblagring, PGVector, Redis och extern worker. Blandade profiler avvisas vid start i stället för att dela tillstånd mellan lokala och delade backend.

Aktuell milstolpe

Område	Implementerad grund	Återstående arbete
Beständighet	SQLite-/PostgreSQL-repositories, oföränderliga migrationer, poolade transaktioner	Nya domäner måste följa repositorygränser
Blobbar	Krypterad lokal/S3-strömning, ranges, checksummor, beständiga kvoter	Flytta chattbilagor, avatarer och kvarvarande inline-binärdata
Vektorer	Krypterade inbäddade vektorer, PGVector-ACL och raderingssäkra index	Nya anropare måste bevara behörighet och livscykel
Samordning	Lokala/Redis-events, cache, leases, rate limits, invalidation, health	Redis får inte bli auktoritativt
Jobb/events	SQLite/PostgreSQL-köer, transaktionella events, workers, retry, avbrott, admin	Varje ny sidoeffekt behöver idempotens eller outbox
Drift	Health-grindar, signerade/krypterade arkiv, återställning till rent mål, verifiering	Öva återställning och korsreplikacceptans per miljö

Runtime-profiler

LIBRE_PLATFORM_MODE=solo är standard och väljer SQLite, lokala blobbar, inbäddade vektorer, lokal samordning och inbäddad worker. Redis i solo gör inte lokala filer säkra att dela.

LIBRE_PLATFORM_MODE=team kräver samtidigt:

• DATABASE_BACKEND=postgres med DATABASE_URL;
• BLOB_STORE_BACKEND=s3;
• VECTOR_STORE_BACKEND=pgvector;
• COORDINATION_BACKEND=redis med REDIS_URL; och
• JOB_WORKER_MODE=external.

Saknat delat beroende eller lokal backend i profilen stoppar starten.

Migrera en befintlig solo-installation

Stoppa alla appar och workers. Använd installerat libre-webui, annars npx --yes libre-webui@latest; från källkod ersätter du libre-webui migrate-postgres efter bygge med npm run migrate:postgres --. Konfigurera målens PostgreSQL, S3 och versionsnycklar och kör först:

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

Applicera bara på tomt rapporterat mål. En avbruten körning lämnar en checksummad journal som ska återupptas för samma källa och mål:

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

Slutmarkören skrivs först när relationsrader, definitioner, krypterade blobbar, inbäddade vektorer och legacy-personavektorer överförts och autentiserats. ENCRYPTION_KEY måste matcha källans .encryption_key; STORAGE_ENCRYPTION_KEYS måste innehålla aktiv nyckel och motsvarande legacy.

Kör den medföljande teamprofilen

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

Ersätt alla REPLACE_*. PostgreSQL-lösenordet ska vara URL-säkert, exempelvis openssl rand -hex 32. ENCRYPTION_KEY och varje STORAGE_ENCRYPTION_KEYS-värde är exakt 64 hextecken. På ny installation är legacy lika med ENCRYPTION_KEY; vid SQLite-migrering lika med källnyckeln. Använd annan aktiv nyckel för nya blobbar och behåll gamla tills inventeringen visar att de inte används.

Filen får även ange POSTGRES_MIGRATION_MODE, POSTGRES_POOL_MAX, PostgreSQL-timeouts, REDIS_CONNECT_TIMEOUT_MS, OLLAMA_BASE_URL, OLLAMA_TIMEOUT, OLLAMA_LONG_OPERATION_TIMEOUT och OLLAMA_MAX_CONTEXT. Provider-timeouts är 1 000–3 600 000 ms, kontext 128–2 097 152 token och lång timeout får inte vara kortare. Ogiltiga värden stoppar båda entrypoints före tillstånd. Node-lokala Agent CLI och Codex OAuth stöds inte av externa workers och kan inte aktiveras.

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

Grundprofilen monterar ingen Docker-socket. För Work måste overlay ingå i varje kommando:

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

Overlayen använder en filtrerad intern socketproxy för app och worker. Ingen får rå socket eller värdmappade Work-ytor. Proxyytan omfattar info, images, containers, exec, volumes, networks och nödvändiga skrivmetoder. Detta minskar API-ytan men Docker är ingen tenantgräns eftersom containers kan bind-mounta värdsökvägar. Använd dedikerad VM eller separat/rootless daemon när värdisolering krävs.

Exponera inte Compose-ägda PostgreSQL, Redis eller MinIO. För hanterade beroenden använder du Helm-teamprofil och verifierad TLS. Readiness förblir misslyckad utan extern worker.

Beständighets- och migrationsgräns

Identitet och behörighet använder asynkrona repositories. En transaktionscallback får en unit of work på samma anslutning; global repositoryanvändning inuti avvisas. SQLite-migrationssamordnaren adopterar bara efter schemavalidering, registrerar namn/checksumma, verifierar vid varje start och avvisar nyare, okända eller ändrade ledgers. Readiness och recovery använder samma kontrakt.

Före tillståndstjänster kopieras SQLite plus aktiv WAL/SHM till privat scratch och valideras. PLATFORM_PREFLIGHT_TMP_DIR måste rymma databas och WAL; Docker/Helm monterar disk där i stället för begränsad /tmp. Saknad legacy-nyckel eller historisk nästlad datakatalog stoppar start före nytt tillstånd.

Schema v4 lägger till en nycklad likhetstoken för krypterad e-post. Recovery kräver matchning. Start tillåter saknad token med autentiserad e-post eller icke-envelope legacyvärde i det korta crashfönstret för backfill. Tomma äldre värden normaliseras till NULL; skadad envelope eller icke-null avvikelse stoppar preflight.

Apptjänster använder asynkrona dialect-repositories. Native SQLite begränsas till adaptrar, migration/recovery och injicerade health checks. Vald Persistence initierar runtime; PostgreSQL faller aldrig tillbaka till SQLite-singleton eller cwd-beroende JSON.

Den gemensamma jobbruntime är driverneutral. Actorbehörighet går genom vald identity repository, native jobb skapas vid en adaptergräns och transaktionella publishers får en ogenomskinlig executor, aldrig better-sqlite3. Gränstestet avvisar native handles i gemensamma jobb-, resurs-, identity-, chat- och Work-kontrakt.

Grund för blob- och vektorlagring

Genererad gallerimedia och dokumentkällor använder BlobStore; RAG och personaminne använder VectorStore. Legacy-gallerirader dubbelläses och adopteras som blobreferenser vid första åtkomst. Relationsmetadata och beständig referens är auktoritativa; leverantörs-URL och fysiska S3-nycklar sparas aldrig som innehåll. Chattbilagor, avatarer och övriga inlinefält är ännu inte migrerade.

Recovery autentiserar varje objekt och vektorenvelope sekventiellt under uttryckliga totalgränser, inklusive igenkännbara legacytexter och röst-envelopes med ENCRYPTION_KEY, utan kompatibilitetsfallback. Den initierar, reparerar, skriver eller raderar inget. Skadad chiffertext, fel nyckel, icke-kanonisk layout eller överskriden gräns blockerar.

Standardgränser: 250 000 lokala objekt, 64 GiB vardera krypterade och okrypterade blobbyte, 250 000 vektorrader, 4 GiB serialiserad vektorchiffertext och 500 miljoner komponenter. Tester kan överstyra via RecoveryInventoryOptions; CLI samplar eller hoppar aldrig över. Legacygränsen är en miljon fält och 16 GiB vardera lagrat och autentiserat klartextinnehåll.

Krypterade lokala blobbar

BlobStore är ägaravgränsad med strömmande put/read, metadata/stat, inkluderande byteintervall och idempotent radering. LocalEncryptedBlobStore skriver UUID-objekt under ${DATA_DIR}/blobs via exklusiv staging, fsync och atomisk rename, med katalog 0700 och fil 0600.

Varje objekt har slumpmässig 256-bitars datanyckel. AES-256-GCM krypterar metadata och autentiserar begränsade chunkar; AAD binder blob-id, ägare, syfte, chunkindex och klartextlängd. Versionsnyckelringen omsluter datanyckeln. Descriptor innehåller storlek, SHA-256, content type, tid, formatversion och key ID. Full läsning verifierar SHA-256 och range-läsning varje berörd chunk.

Kvoten reserverar före strömning, förbrukar verkliga byte och committar efter atomisk synlighet. SQLite använder BEGIN IMMEDIATE; PostgreSQL serializable transaktioner och radlås. BLOB_QUOTA_BYTES_PER_USER sätter ägargräns och BLOB_QUOTA_RESERVATION_TTL_MS övergiven reservation. S3-läget BLOB_STORE_BACKEND=s3 använder privat bucket, ogenomskinliga nycklar, appkrypterade strömmar, krypterade descriptors, ranges, båda SHA-256 och idempotent deletion med reconciliation. MinIO-test täcker korsreplik, tenantisolering, kvotkonkurrens och injicerade fel.

Krypterade inbäddade vektorer

VectorStore kräver actor för varje query/mutation. Rader bär namespace, tenantavgränsat ID, ägare, resource ID, embeddingmodell, dimensions, version, source revision, equality attributes och valfria grants.

SQLite tillämpar alla metadata- och ACL-predikat innan krypterade embeddings lämnar databasen; bara auktoriserade kandidater dekrypteras och cosine-poängsätts. Upsert ersätter embedding, ACL och attributes atomiskt; radering är ägaravgränsad. AES-256-GCM binder identitet och modell. Querybar metadata är klartext och får inte innehålla hemligheter.

VECTOR_STORE_BACKEND=pgvector tillämpar namespace, modell, dimension, version, resource, attribute, ägare och grant i samma SQL som distansordning och LIMIT. Global nearest-neighbor får inte efterfiltreras. Gruppmedlemskap löses betrott varje query; inskickade groupIds ignoreras.

Dokumentinläsning och regenerering fångar en oföränderlig specifikation: aktivering, modell, vektor-/chunkerversion, chunkstorlek, överlappning och likhetströskel. Samma specifikation styr chunks, relationspublicering, upsert och query. Metadata registrerar samlad chunkrevision och specifikation.

Regenerering håller förnybar lease per dokument och kontrollerar ägarrad och deletion tombstone före publicering samt före/efter vektormutation. En samtidig radering tar bort återskapade vektorer. Teamläsning muterar aldrig PGVector. SQLite får bara återpublicera om manifestet exakt bevisar modell och chunkkonfiguration.

Index ersätts i kompenserade batcher om högst 1 000, och exakthetskontroll sidindelar hela manifestet. Ett dokument får högst 100 000 chunks; den 100 001:a avvisas före embedding och jobbet dead-lettered utan retry.

Pre-manifest SQLite-vektorer saknar modellbevis. Första semantiska användningen skapar om alla vektorer från auktoritativ text under aktuell specifikation och lease; legacy-payload kopieras aldrig. Migrering till team stängs säkert om aktuellt manifest och exakt krypterat plattformsindex inte täcker dokumentet. Kör då solo med samma DATA_DIR och ENCRYPTION_KEY, välj embeddingmodell, använd Settings -> Documents -> Regenerate embeddings och kör dry-run igen.

SQLite krypterar embeddings efter ACL-filter; PGVector måste se numeriska embeddings och krypterar därför inte kolumnen på appnivå. Kräv TLS, krypterade PostgreSQL-volymer/backuper, minsta behörighet och loggar utan vektor/source. Attribut är querybar klartext och får aldrig ha hemligheter.

Lagringskrypteringsnycklar

Med versionsnyckelring krävs stabil 64-teckens ENCRYPTION_KEY, samma nyckel som exakt legacy i STORAGE_ENCRYPTION_KEYS, och ett STORAGE_ENCRYPTION_ACTIVE_KEY_ID. Skrivning använder aktiv, läsning alla konfigurerade. Behåll gamla tills objekt verifierats omskrivna.

Utan kartan används ENCRYPTION_KEY som legacy eller reguljära, privata, icke-symlänkade ${DATA_DIR}/.encryption_key. Fabriken skapar eller ersätter aldrig filen. Konflikt, saknad, felaktig eller okänd nyckel stänger säkert. Inbäddade queries summerar kandidater, chifferbyte och dimensionsarbete före dekryptering; överskriden budget måste begränsas med resource/metadata.

Samordning

Kontraktet erbjuder events, utgående cache, fenced leases och fixed-window-rate limits. Lokal implementation gäller en replik. Redis använder separata command/subscription-klienter, begränsade payloads, namespacing, atomiska skript, unika owner tokens och fencing och faller aldrig tillbaka lokalt efter fel.

Redis är inte sanningskälla. Behörighet, beständiga jobb och återspelbara events stannar i databasen; Redis används för väckning, cacheinvalidering, presence, kvot och samordning. Kritiska sidoeffekter validerar databaslease/fencing token.

Beständiga jobb och events

SQLite migration v3 skapar jobb-, attempt-, stream-head- och eventtabeller med idempotent enqueue, begränsad retry, cancellation, progress, heartbeat/reclaim, dead letter och global cursor-replay. Krypterad JSON använder plattformsnyckelring och jobb-/eventidentitet som AAD; referenser är begränsade ogenomskinliga ID:n.

SQLite v13 och PostgreSQL v12 lägger index (stream_id, subject_id, global_cursor) så filter tillämpas före catch-up. Registrerade handlers hanterar dokument, mediakontinuation och resursrensning. Skapande/radering köar jobb i samma transaktion och rensning tar bort vektorer, blobbar, referenser, cache och köat arbete på retry-säkert sätt.

Recovery räknar tillstånd/försök, stream/cursor, blockerar aktiva jobb, autentiserar payloads och avvisar head-avvikelser och sekvensluckor. Monotona lease tokens stoppar gamla workers men ger inte exactly-once; handlers behöver leverantörsidempotens eller transaktionell outbox/inbox och omvalidering före varje sidoeffekt.

SQLite v4 använder unik nycklad e-postlookup (HMAC) bredvid slumpmässig chiffertext för atomisk dubblettkontroll utan deterministisk kryptering. Start autentiserar och backfillar äldre e-post före trafik.

Hälsa och återställning

• /health och /health/live gäller bara processen.
• /health/ready kontrollerar databas, schema, skrivbar lagring och obligatoriska beroenden, inte valfria leverantörer.
• /health/deep kräver administratör och kör begränsad SQLite-integritet/foreign key utanför eventloopen samt valfria providerprober som varningar.

Kör libre-webui recovery-check --json eller efter källbygge npm run recovery:check -- --json. Den skrivskyddade inventeringen rapporterar schema/nycklar, blobbar, vektorer, chiffertext, jobb/events, storlekar, insticksprogram, media, Work-resurser/etiketter, checkpoints, aktiva körningar, blockerare och undantag. Det är en pre-backup-grind, inte full backup. Se Återställningsberedskap.

Certifierad drift med flera repliker

Team är certifierad för minst tre apprepliker och en extern worker när PostgreSQL, PGVector, Redis, S3, delade hemligheter och JOB_WORKER_MODE=external konfigureras tillsammans. Helm vägrar fler än en replik utan komplett profil och migration väljer en ledare med PostgreSQL advisory lock.

Release kör npm run test:team-platform med verklig image och testar stream-resumption, worker-död mitt i skrivning, deterministisk replay, Redis-avbrott med auktoritativ SQL, återkallelse, rate-limit, S3-delete-retry och tenantisolering. secrets.existingSecret och networkPolicy.enabled härdar ytterligare. Podstandard är non-root, skrivskyddad rot, borttagna capabilities, seccomp RuntimeDefault och ingen privilege escalation.

Kvarvarande övergångar

Röstljud, chattbilagor, avatarer och framtida binärresurser behöver explicit metadata, dual-read/backfill, retention och deletionstest innan blobmigrering. Nya embeddinganrop måste bära modell, dimension, version, revision, ägare, resource scope och betrodda grants genom VectorStore.

Nya långvariga eller synliga sidoeffekter måste registrera durable resource target, stödja avbrott/retry och använda transaktionell enqueue/outbox med relationsmutationen. Lägg varje resurs i korsreplik- och backup-/restore-grindar före teamaktivering.