Základ platformy

Libre WebUI podporuje místní profil solo a sdílený profil team. Solo používá SQLite, šifrované místní bloby, šifrované vložené vektory, místní koordinaci a vložený trvalý worker. Team používá PostgreSQL, soukromé bloby kompatibilní s S3, PGVector, Redis a externí trvalý worker. Smíšené profily se při startu odmítnou místo tichého rozdělení stavu mezi místní a sdílené backendy.

Současný milník

Oblast	Implementovaný základ	Zbývající práce volajících
Trvalost	Repository SQLite/PostgreSQL, neměnné migrace, poolované transakce	Nové domény musí dodržovat hranice repository
Bloby	Šifrované místní/S3 streamování, ranges, checksumy a trvalé kvóty	Přesunout přílohy chatů, avatary a další inline binární pole
Vektory	Šifrované vložené vektory, ACL PGVector a bezpečná obnova indexu	Noví volající musí zachovat stejnou autoritu a životní cyklus
Koordinace	Místní/Redis události, cache, leases, rate limits, invalidace a zdraví	Redis nesmí být autoritativní
Úlohy/události	Fronty SQLite/PostgreSQL, transakční události, workery, retry, zrušení a admin	Každý nový vedlejší účinek vyžaduje idempotenci nebo outbox
Provoz	Brány zdraví, podepsané/šifrované archivy, obnova do čistého cíle a ověření	Cvičit obnovu a přijetí napříč replikami pro každé prostředí

Profily runtime

LIBRE_PLATFORM_MODE=solo je výchozí a vybírá SQLite, místní bloby, vložené vektory, místní koordinaci a vložený worker. Redis lze v solo zvolit, ale místní soubory ani SQLite tím nejsou bezpečné pro sdílení mezi replikami.

LIBRE_PLATFORM_MODE=team vyžaduje všechny sdílené závislosti současně:

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

Chybějící sdílená závislost nebo místní backend v profilu start zastaví.

Migrace existující instalace solo

Zastavte všechny aplikace a workery. Použijte nainstalované libre-webui, jinak npx --yes libre-webui@latest; ze zdrojů po buildu nahraďte libre-webui migrate-postgres příkazem npm run migrate:postgres --. Nastavte cílové PostgreSQL, S3 a verzované klíče a nejprve spusťte analýzu:

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

Aplikujte pouze do prázdného cíle z reportu. Přerušený běh zanechá journal s checksumem, který obnovte pro stejný zdroj a cí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

Značka dokončení se zapíše až po přenosu a ověření relačních řádků, definic pluginů, šifrovaných místních blobů, vložených vektorů a legacy vektorů person. ENCRYPTION_KEY musí odpovídat zdrojovému .encryption_key; STORAGE_ENCRYPTION_KEYS musí obsahovat aktivní klíč a odpovídající položku legacy.

Spuštění dodávaného týmového profilu

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

Nahraďte všechny hodnoty REPLACE_*. Heslo PostgreSQL používejte v URL-safe abecedě, například z openssl rand -hex 32. ENCRYPTION_KEY a každá hodnota STORAGE_ENCRYPTION_KEYS musí mít přesně 64 hex znaků. V nové instalaci se legacy rovná ENCRYPTION_KEY; při migraci SQLite oba odpovídají zdrojovému klíči. Pro nové bloby používejte jiný aktivní klíč a staré uchovávejte, dokud inventář nepotvrdí, že se nepoužívají.

Soubor může nastavit také POSTGRES_MIGRATION_MODE, POSTGRES_POOL_MAX, timeouty PostgreSQL, REDIS_CONNECT_TIMEOUT_MS, OLLAMA_BASE_URL, OLLAMA_TIMEOUT, OLLAMA_LONG_OPERATION_TIMEOUT a OLLAMA_MAX_CONTEXT. Timeouty poskytovatele přijímají 1 000–3 600 000 ms, kontext 128–2 097 152 tokenů a dlouhý timeout nesmí být kratší. Neplatná hodnota zastaví oba entrypointy před vytvořením stavu. Node-local Agent CLI a soubory Codex OAuth externí worker nepodporuje a nelze je zapnout.

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

Základní profil nepřipojuje Docker socket. Pro Work zahrňte v každém příkazu 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 používá filtrovanou interní Docker socket proxy pro aplikaci i worker. Žádný proces nedostane raw socket ani hostitelské Work složky. Proxy povoluje info, images, containers, exec, volumes, networks a potřebné zápisové metody. Zužuje API, ale Docker není hranicí tenantů, protože kontejnery mohou stále bind-mountovat hostitelské cesty. Je-li izolace hostitele důležitá, použijte dedikovanou VM nebo samostatný/rootless daemon.

Compose služby PostgreSQL, Redis a MinIO přímo nevystavujte. Pro spravované závislosti použijte týmový profil Helm a ověřené TLS. Readiness zůstane neúspěšná, dokud není přítomen externí worker.

Hranice trvalosti a migrací

Identity a oprávnění používají asynchronní repository. Callback transakce dostane unit of work na stejném připojení; použití globálního repository uvnitř se odmítne. Koordinátor migrací SQLite přijme starou instalaci až po validaci schématu, zapisuje název/checksum, ověřuje je při každém startu a odmítá novější, neznámý či pozměněný ledger. Readiness a obnova používají stejnou smlouvu.

Před službami se stavem se SQLite a aktivní WAL/SHM zkopírují do soukromého scratch prostoru a kopie se ověří. PLATFORM_PREFLIGHT_TMP_DIR musí pojmout databázi i WAL; Docker/Helm tam připojují disk namísto omezeného /tmp. Chybějící legacy klíč nebo historicky vnořená datová složka zastaví start před vytvořením nového stavu.

Schéma v4 přidává klíčovaný equality token pro šifrovaný e-mail. Obnova vyžaduje shodu. Start v úzkém crash okně dovolí chybějící token s ověřeným e-mailem nebo neobalenou legacy hodnotou, aby inicializace dokončila backfill. Prázdné staré hodnoty se normalizují na NULL; poškozená obálka či non-null neshoda zastaví preflight.

Aplikační služby používají asynchronní dialect repository. Nativní SQLite je omezená na adaptéry, migraci/obnovu a injektované health checks. Runtime inicializuje vybraná Persistence; PostgreSQL nikdy nespadne zpět na SQLite singleton ani JSON závislé na cwd.

Společný runtime trvalých úloh je driver-neutral. Oprávnění actor se čte z vybraného identity repository, nativní job repository se vytváří v jediné kompoziční hranici a transakční publishery dostávají opaque executor, nikdy handle better-sqlite3. Hranový test odmítá nativní handles ve společných smlouvách job, resource, identity, chat a Work.

Základ blobového a vektorového úložiště

Generovaná média galerie a zdrojové soubory dokumentů používají BlobStore; RAG dokumentů a paměť person používají VectorStore. Legacy řádky galerie se čtou dvojím způsobem a při prvním přístupu se adoptují jako blob reference. Autoritativní jsou relační metadata a trvalá reference; URL poskytovatele ani fyzické S3 klíče se neukládají jako obsah. Přílohy chatů, avatary a další inline binární pole zatím migrovány nejsou.

Recovery ověřuje každý objekt a vektorovou obálku postupně pod explicitními celkovými limity, včetně rozpoznatelných legacy textů a hlasových obálek s ENCRYPTION_KEY, bez kompatibilního fallbacku. Nic neinicializuje, neopravuje, nepřepisuje ani nemaže. Poškozený ciphertext, nesprávný klíč, nekanonická struktura či překročený limit blokují.

Výchozí limity jsou 250 000 místních objektů, 64 GiB šifrovaných i plaintext blob bajtů, 250 000 vektorových řádků, 4 GiB serializovaného ciphertextu vektorů a 500 milionů komponent. Testy mohou hodnoty přepsat přes RecoveryInventoryOptions; CLI nikdy nesampluje ani nepřeskakuje nadlimitní stav. Legacy kontrola má limit milion polí a 16 GiB uložených i ověřených plaintext bajtů.

Šifrované místní bloby

BlobStore je omezen vlastníkem a nabízí streamované put/read, metadata/stat, inkluzivní byte ranges a idempotentní smazání. LocalEncryptedBlobStore zapisuje objekty s UUID pod ${DATA_DIR}/blobs přes exkluzivní staging, fsync a atomický rename, se složkami 0700 a soubory 0600.

Každý objekt má náhodný 256bitový datový klíč. AES-256-GCM šifruje metadata a ověřuje omezené chunky; AAD váže blob id, vlastníka, účel, index chunku a délku plaintextu. Verzovaný keyring obaluje datový klíč. Descriptor obsahuje velikost, SHA-256, content type, čas, verzi formátu a key ID. Plné čtení ověří SHA-256 a range čtení každý dotčený chunk.

Kvóta rezervuje kapacitu před streamem, spotřebuje skutečné bajty a commituje až po atomické viditelnosti. SQLite používá BEGIN IMMEDIATE; PostgreSQL serializable transakce a row locks. BLOB_QUOTA_BYTES_PER_USER nastavuje limit na vlastníka a BLOB_QUOTA_RESERVATION_TTL_MS život opuštěné rezervace.

BLOB_STORE_BACKEND=s3 používá soukromý S3-kompatibilní bucket, opaque klíče, aplikačně šifrované streamy, šifrované descriptory, ranges, obě SHA-256 a idempotentní deletion s reconciliation. Test MinIO pokrývá čtení/smazání napříč replikami, izolaci tenantů, souběh kvót a injektované chyby.

Šifrované vložené vektory

VectorStore vyžaduje actor pro každý query a mutation. Řádky nesou namespace, tenantové opaque ID, vlastníka, resource ID, embedding model, dimensions, version, source revision, equality attributes a volitelná grants.

SQLite aplikuje metadata a ACL predicates před opuštěním databáze šifrovanými embeddings; dešifrují a cosine skórují se jen oprávnění kandidáti. Upsert atomicky nahrazuje embedding, ACL i attributes; smazání je omezené vlastníkem. AES-256-GCM váže identitu a model. Dotazovatelná metadata zůstávají plaintext a nesmějí obsahovat tajemství.

VECTOR_STORE_BACKEND=pgvector aplikuje namespace, model, dimensions, version, resource, attribute, owner a grant ve stejném SQL jako řazení vzdálenosti a LIMIT. Globální nearest-neighbor se nesmí postfiltrovat. Členství ve skupině se při každém query řeší důvěryhodně; dodaná groupIds se ignorují.

Ingest dokumentů a regenerace zachytí před prací neměnnou specifikaci: aktivace, model, verze vektoru/chunkeru, velikost chunku, overlap a similarity threshold. Tatáž specifikace řídí chunky, relační publikaci, upsert a query. Metadata zapisují souhrnnou revizi chunků a specifikaci.

Regenerace drží obnovitelný lease dokumentu a kontroluje řádek vlastníka i deletion tombstone před publikací a před/po mutaci vektorů. Souběžné smazání odstraní znovu vytvořené vektory. Team čtení nikdy nemění PGVector. SQLite smí líně publikovat pouze při přesném důkazu modelu a konfigurace v manifestu.

Indexy se nahrazují kompenzovanými dávkami nejvýše 1 000 vektorů a kontrola prochází celý manifest. Dokument smí mít nejvýše 100 000 chunků; 100 001. se odmítne před embeddingem a úloha dead-lettered bez retry.

SQLite před manifesty může obsahovat ověřené inline vektory bez důkazu modelu. První sémantické použití je znovu vytvoří z autoritativního textu pod aktuální specifikací a lease; legacy payload se nekopíruje. Migrace do team se bezpečně odmítne bez úplného aktuálního manifestu a přesného šifrovaného platformního indexu. Spusťte solo se stejnými DATA_DIR a ENCRYPTION_KEY, vyberte embedding model, použijte Settings -> Documents -> Regenerate embeddings a opakujte dry-run.

SQLite šifruje embeddings po ACL filtru; PGVector musí pracovat s číselnými embeddings a sloupec proto aplikačně nešifruje. Vyžadujte TLS, šifrované PostgreSQL volumes/zálohy, minimální oprávnění a logy bez vektorů či zdroje. Attributes jsou dotazovatelný plaintext a nesmějí obsahovat tajemství.

Klíče šifrování úložiště

S verzovaným keyringem se vyžaduje stabilní 64znakový ENCRYPTION_KEY, stejný klíč jako přesná položka legacy v STORAGE_ENCRYPTION_KEYS a STORAGE_ENCRYPTION_ACTIVE_KEY_ID. Zápis používá aktivní klíč, čtení všechny nakonfigurované. Staré ponechte až do ověřeného přepsání objektů.

Bez mapy se použije ENCRYPTION_KEY jako legacy nebo regulární soukromý nesymlinkovaný ${DATA_DIR}/.encryption_key. Factory soubor nikdy nevytváří ani nenahrazuje. Konflikt, chybějící, poškozený či neznámý klíč bezpečně zastaví start. Vložený query sčítá kandidáty, ciphertext bajty a práci podle dimensions před dešifrováním; překročený rozpočet musí být zúžen resource či metadata rozsahem.

Koordinace

Smlouva nabízí události, expirovanou cache, fenced leases a fixed-window rate limits. Místní implementace je jen pro jednu repliku. Redis používá oddělené command/subscription klienty, omezené payloady, namespacing, atomické skripty, jedinečné owner tokens a fencing a po chybě nikdy nespadne zpět místně.

Redis není zdrojem pravdy. Oprávnění, trvalé úlohy a přehratelné události zůstávají v databázi; Redis slouží pro wake-up, invalidaci cache, presence, kvóty a koordinaci. Kritický vedlejší účinek musí ověřit database lease či fencing token.

Trvalé úlohy a události

SQLite migrace v3 vytváří tabulky job, attempt, stream head a ordered events s idempotentním enqueue, omezeným retry, cancellation, progress, heartbeat/reclaim, dead letter a replay přes global cursor. Šifrovaný JSON používá platformní keyring s identitou job/event jako AAD; reference jsou omezená opaque ID.

SQLite v13 a PostgreSQL v12 přidávají index (stream_id, subject_id, global_cursor), takže filtry platí před catch-up limitem. Registrované handlers pokrývají dokumenty, pokračování médií a retry-safe cleanup. Vytvoření/smazání řadí úlohu ve stejné transakci a cleanup odstraňuje vektory, bloby, reference, cache i práci ve frontě.

Recovery počítá stavy a pokusy, streamy/cursory, blokuje aktivní práci, ověřuje payloady a odmítá nesouhlas headu či mezery sekvence. Monotonic lease tokens zadrží starý worker, ale neposkytují exactly-once; handler potřebuje idempotency poskytovatele nebo transakční outbox/inbox a nové ověření před vedlejším účinkem.

SQLite v4 používá unikátní klíčovaný lookup e-mailu (HMAC) vedle náhodného ciphertextu pro atomickou kontrolu duplicit bez deterministického šifrování. Start ověří a doplní legacy e-maily před provozem.

Zdraví a obnova

• /health a /health/live kontrolují pouze proces.
• /health/ready kontroluje databázi, schéma, zapisovatelné úložiště a povinné závislosti, nikoli volitelné poskytovatele.
• /health/deep vyžaduje administrátora, provádí omezenou kontrolu SQLite/foreign key mimo event loop a volitelné provider probes uvádí jako varování.

Spusťte libre-webui recovery-check --json nebo ze zdrojů po buildu npm run recovery:check -- --json. Read-only inventář hlásí schéma/klíče, bloby, vektory, ciphertext, úlohy/události, velikosti, pluginy, média, prostředky Work a labels, checkpoints, aktivní běhy, blokátory a výjimky. Je to pre-backup brána, nikoli úplná záloha. Viz Připravenost k obnově.

Certifikovaný provoz s více replikami

Team je certifikován pro nejméně tři aplikační repliky a jeden externí trvalý worker, pokud jsou společně nastaveny PostgreSQL, PGVector, Redis, S3, sdílená tajemství a JOB_WORKER_MODE=external. Helm odmítá více replik bez úplného profilu a migrace volí jediného lídra pomocí PostgreSQL advisory lock.

Release spouští npm run test:team-platform se skutečným image a ověřuje pokračování streamů, smrt workeru uprostřed zápisu, deterministický replay, výpadek Redis s autoritativním SQL, odvolání oprávnění, sdílené rate limits, retry smazání S3 a izolaci tenantů. secrets.existingSecret a networkPolicy.enabled dále zpřísní pody. Výchozí bezpečnost je non-root, read-only root, odstraněné capabilities, seccomp RuntimeDefault a bez privilege escalation.

Zbývající přechody

Hlasový zvuk, přílohy chatů, avatary a budoucí binární prostředky vyžadují explicitní metadata, dual-read/backfill, retention a test smazání před migrací do blobů. Každý nový embedding volající musí přes VectorStore nést model, dimensions, version, source revision, owner, resource scope a trusted grants.

Nové dlouhotrvající či externě viditelné vedlejší účinky musí registrovat durable resource target, podporovat cancellation/retry a používat transakční enqueue/outbox s relační mutací. Před zapnutím v team přidejte každý prostředek do bran napříč replikami a backup/restore.