Hop til hovedindhold

Platformsgrundlag

Libre WebUI har en lokal solo-profil og en delt team-profil. Solo bruger SQLite, krypterede lokale blobs, krypterede indlejrede vektorer, lokal koordinering og en indlejret vedvarende worker. Team bruger PostgreSQL, private S3-kompatible blobs, PGVector, Redis-koordinering og en ekstern vedvarende worker. Blandede profiler afvises ved start i stedet for stiltiende at opdele tilstand mellem lokale og delte backends.

Aktuell milstolpe​

OmrådeImplementerad grundÅterstående arbejde
BestændighetSQLite-/PostgreSQL-repositories, uforanderlige migrationer, poolede transaktionerNya domæner skal følja repositorygrænser
BlobbarKrypterad lokal/S3-streaming, ranges, checksummor, vedvarende kvoterFlytta chattbilagor, avatarer og resterende inline-binærdata
VektorerKrypterede indlejrede vektorer, PGVector-ACL og raderingssækra indexNya anropare skal bevar tilladelse og livscykel
KoordineringLokala/Redis-events, cache, leases, rate limits, invalidation, healthRedis får ikke bli auktoritativt
Jobb/eventsSQLite/PostgreSQL-køer, transaktionella events, workers, retry, avbrott, adminHver ny sidoeffekt behøver idempotens eller outbox
DriftHealth-grindar, signerede/krypterede arkiv, gendannelse til rent mål, verifieringØva gendannelse og korsreplikacceptans per miljø

Runtime-profiler​

LIBRE_PLATFORM_MODE=solo er standard og vælger SQLite, lokale blobbar, indlejrede vektorer, lokal koordinering og indlejret worker. Redis i solo gør ikke lokale filer sikre at del.

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; og
  • JOB_WORKER_MODE=external.

Saknat delat beroende eller lokal backend i profilen stopper starten.

Migrera en eksisterende solo-installation​

Stoppa alle apps og workers. Brug installeret libre-webui, annars npx --yes libre-webui@latest; fra kildekode erstatter du libre-webui migrate-postgres efter bygge med npm run migrate:postgres --. Konfigurera målens PostgreSQL, S3 og versionsnøglar og kør først:

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

Anvend kun på det tomme mål, som rapporten identificerer. En afbrudt kørsel efterlader en checksum-beskyttet journal, som skal genoptages for samme kilde og 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 skrives først når relationsrader, definitioner, krypterede blobbar, indlejrede vektorer og legacy-personavektorer øverførts og autentificerats. ENCRYPTION_KEY skal matcha kildens .encryption_key; STORAGE_ENCRYPTION_KEYS skal indeholde aktiv nøgle og tilsvarende legacy.

Kør den medfølgende teamprofilen​

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

Erstat alle REPLACE_*. PostgreSQL-adgangskoden skal være URL-sikker, eksempelvis fra openssl rand -hex 32. ENCRYPTION_KEY og hver værdi i STORAGE_ENCRYPTION_KEYS skal være præcis 64 hextegn. På en ny installation skal legacy være lig med ENCRYPTION_KEY; ved SQLite-migrering skal begge svare til kildenøglen. Brug en anden aktiv nøgle til nye blobs, og behold gamle nøgler, indtil inventaret viser, at de ikke længere bruges.

Filen får også angiv POSTGRES_MIGRATION_MODE, POSTGRES_POOL_MAX, PostgreSQL-timeouts, REDIS_CONNECT_TIMEOUT_MS, OLLAMA_BASE_URL, OLLAMA_TIMEOUT, OLLAMA_LONG_OPERATION_TIMEOUT og OLLAMA_MAX_CONTEXT. Provider-timeouts er 1 000–3 600 000 ms, kontext 128–2 097 152 token og lang timeout får ikke vara kortere. Ogiltiga værdier stopper begge entrypoints før tilstand. Node-lokale Agent CLI og Codex OAuth understøttes ikke af eksterne workers og kan ikke 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 monterer ingen Docker-socket. For Work skal overlay ingå i hver 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

Overlayet bruger en filtreret intern Docker-socketproxy til app og worker. Ingen af processerne modtager den rå socket eller værtsmappede Work-områder. Proxyens API-område omfatter info, images, containers, exec, volumes, networks og de nødvendige skrivemetoder. Det reducerer API-overfladen, men gør ikke Docker til en tenantgrænse, fordi containers stadig kan bind-mounte værtsstier. Brug en dedikeret VM eller en separat/rootless Work-daemon, når værtsisolering er vigtig.

Exponera ikke Compose-ægda PostgreSQL, Redis eller MinIO. For hanterade afhængigheder bruger du Helm-teamprofil og verifierad TLS. Readiness forbliver mislykket uden ekstern worker.

Bestændighets- og migrationsgræns​

Identitet og tilladelse bruger asynkrone repositories. En transaktionscallback får en unit of work på samme anslutning; global repositoryanvændning inuti avvisas. SQLite-migrationssamordnaren adopterar kun efter schemavalidering, registrerer navn/checksumma, verificerer ved hver start og afviser nyare, okænda eller ændrade ledgers. Readiness og recovery bruger samme kontrakt.

Føre tillståndstjænster kopieras SQLite plus aktiv WAL/SHM til privat scratch og valideres. PLATFORM_PREFLIGHT_TMP_DIR skal rymma databas og WAL; Docker/Helm monterer disk hvor i stedet for begrænset /tmp. Saknad legacy-nøgle eller historisk næstlad datakatalog stopper start før nyt tilstand.

Schema v4 tilføjer til en nøglad likhetstoken for krypteret e-post. Recovery kræver matchning. Start tillader manglende token med autentificeret e-post eller icke-envelope legacyværde i det korta crashfønstret for backfill. Tomma ældre værdier normaliseras til NULL; beskadiget envelope eller icke-null afvigelse stopper preflight.

Apptjænster bruger asynkrone dialect-repositories. Native SQLite begrænses til adaptere, migration/recovery og injicerede health checks. Valgt Persistence initialiserer runtime; PostgreSQL falder aldrig tilbage til SQLite-singleton eller cwd-beroende JSON.

Den fælles jobbruntime er driverneutral. Actorbehørighet går gennem valgte identity repository, native jobb oprettes ved en adaptergræns og transaktionella publishers får en ogenomskinlig executor, aldrig better-sqlite3. Grænstestet afviser native handles i fælles jobb-, ressource-, identity-, chat- og Work-kontrakt.

Grund for blob- og vektorlagring​

Genereret gallerimedia og dokumentkilder bruger BlobStore; RAG og personahukommelse bruger VectorStore. Legacy-gallerirader dobbeltlæses og adopteres som blobreferencer ved første adgang. Relationsmetadata og vedvarende reference er autoritative; udbyderens-URL og fysiske S3-nøgler gemmes aldrig som indhold. Chatbilag, avatarer og øvriga inlinefelter er endnu ikke migrerede.

Recovery autentificerer hvert objekt og hver vektorenvelope sekventielt under eksplicitte totalgrænser, inklusive genkendelige legacytekster og stemme-envelopes med ENCRYPTION_KEY, uden kompatibilitetsfallback. Den initialiserer, reparerer, skriver eller sletter intet. Beskadiget chiffertekst, forkert nøgle, ikke-kanonisk layout eller en overskredet grænse blokerer.

Standardgrænser: 250 000 lokale objekt, 64 GiB vardera krypterede og ukrypterede blobbyte, 250 000 vektorrader, 4 GiB serialiserad vektorchiffertext og 500 miljoner komponenter. Tester kan øverstyra via RecoveryInventoryOptions; CLI udtager stikprøver eller springer over aldrig over. Legacygrænsen er en miljon felter og 16 GiB vardera lagrat og autentificerat klartextinnehåll.

Krypterede lokale blobbar​

BlobStore er ejerafgrænset med streaming put/read, metadata/stat, inklusive byteintervaller og idempotent sletning. LocalEncryptedBlobStore skriver UUID-objekter under ${DATA_DIR}/blobs via eksklusiv staging, fsync og atomisk rename, med mapper i tilstand 0700 og filer i tilstand 0600.

Hver objekt har tilfældig 256-bit datanøgel. AES-256-GCM krypterer metadata og autentificerer begrænsede chunks; AAD binder blob-id, ejer, formål, chunkindex og klartextlængde. Versionsnøgelringen omsluter datanøglen. Descriptor indeholder størrelse, SHA-256, content type, tid, formatversion og key ID. Fuld læsning verificerer SHA-256 og range-læsning hver berørt chunk.

Kvoten reserverer før streaming, førbrukar faktiske byte og committar efter atomisk synlighet. SQLite bruger BEGIN IMMEDIATE; PostgreSQL serializable transaktioner og radlås. BLOB_QUOTA_BYTES_PER_USER sætter ægargræns og BLOB_QUOTA_RESERVATION_TTL_MS øvergiven reservation. S3-læget BLOB_STORE_BACKEND=s3 bruger privat bucket, ogenomskinliga nøgler, appkrypterade strømmar, krypterede descriptors, ranges, begge SHA-256 og idempotent deletion med reconciliation. MinIO-test dækker korsreplik, tenantisolering, kvotkonkurrens og injicerede fejl.

Krypterede indlejrede vektorer​

VectorStore kræver actor for hver query/mutation. Rader bær namespace, tenantavgrænsat ID, ejer, resource ID, embeddingmodel, dimensions, version, source revision, equality attributes og valgfrie grants.

SQLite anvender alle metadata- og ACL-predikat før krypterede embeddings forlader databasen; kun auktoriserade kandidater dekrypteras og cosine-poængsætts. Upsert erstatter embedding, ACL og attributes atomiskt; sletning er ejerafgrænset. AES-256-GCM binder identitet og model. Querybar metadata er klartekst og får ikke indeholde hemmeligheder.

VECTOR_STORE_BACKEND=pgvector anvender namespace, model, dimension, version, resource, attribute, ejer og grant i samme SQL som distansordning og LIMIT. Global nearest-neighbor får ikke efterfiltreras. Gruppmedlemskap løses betrott hver query; inskickade groupIds ignoreres.

Dokumentindlæsning og regenerering indfanger en uforanderlig specifikation: aktivering, model, vektor-/chunkerversion, chunkstørrelse, overlap og lighedstærskel. Den samme specifikation styrer chunks, relationsudgivelse, upsert og query. Metadata registrerer den samlede chunkrevision og specifikationen.

Regenerering holder førnybar lease per dokument og kontrollerer ægarrad og deletion tombstone før publicering samt før/efter vektormutation. En samtidig sletning fjerner återskapade vektorer. Teamlæsning muterar aldrig PGVector. SQLite får kun återpublicera hvis manifestet præcis beviser model og chunkkonfiguration.

Index ersætts i kompenserade batcher hvis højst 1 000, og exakthetskontroll sideinddeler hele manifestet. Ett dokument får højst 100 000 chunks; den 100 001:a avvisas før embedding og jobbet dead-lettered uden retry.

Pre-manifest SQLite-vektorer mangler modelbevis. Første semantiske anvændningen opretter hvis alle vektorer fra auktoritativ tekst under aktuell specifikation og lease; legacy-payload kopieras aldrig. Migrering til team lukkes sikkert hvis aktuellt manifest og præcis krypterat plattformsindex ikke dækker dokumentet. Kør så solo med samme DATA_DIR og ENCRYPTION_KEY, vælg embeddingmodel, brug Settings -> Documents -> Regenerate embeddings og kør dry-run igen.

SQLite krypterer embeddings efter ACL-filter; PGVector skal se numeriska embeddings og krypterer derfor ikke kolumnen på appnivå. Kræv TLS, krypterede PostgreSQL-diskenheder/backuper, minsta tilladelse og logfiler uden vektor/source. Attribut er forespørgbar klartekst og får aldrig ha hemmeligheder.

Lagringskrypteringsnøglar​

Med versionsnøgelring kræves stabil 64-teckens ENCRYPTION_KEY, samme nøgle som præcis legacy i STORAGE_ENCRYPTION_KEYS, og et STORAGE_ENCRYPTION_ACTIVE_KEY_ID. Skrivning bruger aktiv, læsning alle konfigurerede. Behåll gamla indtil objekt verifierats omskrivna.

Uden kartan bruges ENCRYPTION_KEY som legacy eller reguljæra, private, icke-symlænkade ${DATA_DIR}/.encryption_key. Fabriken opretter eller erstatter aldrig filen. Konflikt, manglende, forkert eller okænd nøgle stænger sikkert. Inbæddade queries opsummerer kandidater, chifferbyte og dimensionsarbete før dekryptering; øverskriden budget skal begrænses med resource/metadata.

Koordinering​

Kontraktet tilbyder events, udgående cache, fenced leases og fixed-window-rate limits. Lokal implementation gælder en replik. Redis bruger separata command/subscription-klienter, begrænsede payloads, namespacing, atomiska skript, unika owner tokens og fencing og falder aldrig tilbage lokalt efter fejl.

Redis er ikke sandhedskilden. Tilladelser, vedvarende jobs og events, der kan afspilles igen, skal forblive i databasen; Redis bruges til vækning, cacheinvalidering, presence, kvoter og koordinering. Kritisk arbejde skal også validere sin databaselease eller fencing token før en sideeffekt committes.

Vedvarende jobs og events​

SQLite migration v3 opretter jobb-, attempt-, stream-head- og eventtabeller med idempotent enqueue, begrænset retry, cancellation, progress, heartbeat/reclaim, dead letter og global cursor-replay. Krypterad JSON bruger plattformsnøgelring og jobb-/eventidentitet som AAD; referenser er begrænsede ogenomskinliga ID:n.

SQLite v13 og PostgreSQL v12 tilføjer index (stream_id, subject_id, global_cursor) så filter tillæmpas før catch-up. Registrerade handlers håndterer dokument, mediakontinuation og resursrensning. Skapande/sletning sætter i kø jobb i samme transaktion og rensning fjerner vektorer, blobbar, referenser, cache og køat arbejde på retry-sikkert måde.

Recovery beregner tilstand/forsøg, stream/cursor, blokerer aktive jobb, autentificerer payloads og afviser head-avvikelser og sekvensluckor. Monotona lease tokens stopper gamla workers men giver ikke exactly-once; handlers behøver udbydersidempotens eller transaktionell outbox/inbox og omvalidering før hver sidoeffekt.

SQLite v4 bruger unik nøglad e-postlookup (HMAC) ved siden af tilfældig chiffertext for atomisk dubblettkontroll uden deterministisk kryptering. Start autentificerer og backfillar ældre e-post før trafik.

Hælsa og gendannelse​

  • /health og /health/live gælder kun processen.
  • /health/ready kontrollerer databas, schema, skrivbar lagring og obligatoriska afhængigheder, ikke valgfrie udbydere.
  • /health/deep kræver administrator og kør begrænset SQLite-integritet/foreign key uden for eventloopen samt valgfrie providerprober som advarsler.

Kør libre-webui recovery-check --json eller efter kællbygge npm run recovery:check -- --json. Den skrivebeskyttede inventeringen rapporterer schema/nøgler, blobbar, vektorer, chiffertext, jobb/events, størrelsear, plugin, media, Work-resurser/etiketter, checkpoints, aktive kørsler, blokeringer og undantag. Det er en pre-backup-grind, ikke full backup. Se Gendannelsesberedskab.

Certifierad drift med flere repliker​

Teamprofilen er certificeret til mindst tre appreplikaer og én ekstern vedvarende worker, når PostgreSQL, PGVector, Redis, S3-kompatible blobs, delte hemmeligheder og JOB_WORKER_MODE=external konfigureres sammen. Helm afviser mere end én replika uden en komplet teamprofil, og migreringer vælger én leder med en PostgreSQL advisory lock.

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

Kvarvarande øvergångar​

Røstlyd, chattbilagor, avatarer og fremtidige binærresurser behøver explicit metadata, dual-read/backfill, retention og deletionstest før blobmigrering. Nya embeddinganrop skal bæra model, dimension, version, revision, ejer, resource scope og betrodda grants gennem VectorStore.

Nya långvariga eller synliga sidoeffekter skal registrera durable resource target, understøtte avbrott/retry og bruge transaktionell enqueue/outbox med relationsmutationen. Tilføj hver ressource i korsreplik- og backup-/restore-grindar før teamaktivering.