Fondasi Platform

Libre WebUI mendukung profil lokal solo dan bersama team. Solo memakai SQLite, blob lokal terenkripsi, vektor tertanam, koordinasi lokal, dan pekerja tertanam. Team memakai PostgreSQL, blob S3 privat, PGVector, Redis, dan pekerja eksternal. Konfigurasi campuran ditolak.

Tonggak Saat Ini

Area	Fondasi	Pekerjaan tersisa
Persistensi	Repositori SQLite/PostgreSQL, migrasi tetap, transaksi	Domain baru memakai batas repositori
Blob	Penyimpanan terenkripsi, rentang, checksum, kuota	Pindahkan lampiran/avatar
Vektor	Vektor terenkripsi, ACL PGVector, pembangunan ulang aman	Pertahankan kontrak otoritas
Koordinasi	Peristiwa, cache, sewa, batas laju	Redis tidak otoritatif
Pekerjaan	Antrean, retry, batal, admin	Efek baru perlu idempotensi
Operasi	Kesehatan, cadangan, pemulihan	Uji setiap lingkungan

Profil Runtime

LIBRE_PLATFORM_MODE=solo memilih SQLite, blob lokal, vektor, koordinasi lokal, dan pekerja tertanam. Redis dalam solo tidak membuat berkas aman dibagikan.

LIBRE_PLATFORM_MODE=team memerlukan:

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

Migrasi Solo

Hentikan semua aplikasi/pekerja. Perintah libre-webui yang terpasang menyediakan libre-webui migrate-postgres; alternatifnya gunakan npx --yes libre-webui@latest atau npm run migrate:postgres --. Sumber memakai DATA_DIR yang sama dengan instalasi solo. Mulai dengan analisis:

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

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

Semua baris, plugin, blob, dan vektor harus terautentikasi sebelum selesai. ENCRYPTION_KEY harus cocok dengan .encryption_key; STORAGE_ENCRYPTION_KEYS memuat kunci aktif dan legacy.

Menjalankan Team

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

Ganti semua REPLACE_*. Buat kata sandi PostgreSQL dengan openssl rand -hex 32; kunci harus 64 karakter heksadesimal. POSTGRES_MIGRATION_MODE, POSTGRES_POOL_MAX, REDIS_CONNECT_TIMEOUT_MS, OLLAMA_BASE_URL, OLLAMA_TIMEOUT, OLLAMA_LONG_OPERATION_TIMEOUT, dan OLLAMA_MAX_CONTEXT dikirim sama ke aplikasi dan pekerja. Agent CLI lokal dan Codex OAuth tidak didukung pekerja eksternal.

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

Work tidak aktif tanpa 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 memakai proksi soket terfilter. Proksi mempersempit API tetapi bukan batas penyewa; gunakan VM khusus jika perlu isolasi. Jangan buka PostgreSQL, Redis, atau MinIO.

Batas Persistensi dan Migrasi

Repositori asinkron memakai unit kerja pada koneksi yang sama. Penyimpanan runtime dipilih melalui Persistence. Koordinator SQLite memvalidasi skema dan checksum migrasi saat mulai. Basis data/WAL disalin ke PLATFORM_PREFLIGHT_TMP_DIR sebelum layanan dimuat dan startup tidak bergantung pada /tmp yang terbatas.

Skema v4 menambahkan token kesetaraan email. Pemulihan mewajibkan kecocokan. Nilai kosong dinormalkan menjadi NULL, dan nilai lama diisi ulang sebelum menerima lalu lintas.

Runtime pekerjaan netral terhadap penggerak; kontrak umum tidak menerima pegangan better-sqlite3.

Fondasi Blob dan Vektor

Media/dokumen memakai BlobStore; RAG/memori memakai VectorStore. Metadata relasional dan referensi persisten otoritatif. Lampiran dan avatar belum dimigrasikan.

Pemulihan mengautentikasi setiap objek, vektor, selubung teks lama, dan suara dalam batas eksplisit. Batas bawaan: 250.000 objek, 64 GiB blob, 250.000 vektor, 4 GiB ciphertext, 500 juta komponen. Tes tertanam dapat menimpa batas melalui RecoveryInventoryOptions.

Blob Lokal Terenkripsi

BlobStore menyediakan put/read streaming, metadata/stat, rentang, dan hapus idempoten. LocalEncryptedBlobStore menulis di ${DATA_DIR}/blobs dengan AES-256-GCM, fsync, penggantian nama atomik, izin 0700/0600.

Setiap objek memiliki kunci 256 bit, SHA-256, tipe, waktu, versi, dan ID kunci. Kuota dipesan sebelum streaming; SQLite memakai BEGIN IMMEDIATE. BLOB_QUOTA_BYTES_PER_USER dan BLOB_QUOTA_RESERVATION_TTL_MS mengatur batas.

BLOB_STORE_BACKEND=s3 memakai bucket privat, kunci buram, stream terenkripsi, metadata PostgreSQL, rentang HTTP, dan penghapusan idempoten.

Vektor Tertanam Terenkripsi

VectorStore memerlukan aktor. SQLite menerapkan namespace/model/dimensi/versi, pemilik, izin, sumber daya, atribut sebelum dekripsi. Embedding memakai AES-256-GCM; metadata kueri tetap teks biasa dan tidak boleh menyimpan rahasia.

VECTOR_STORE_BACKEND=pgvector menerapkan semua predikat dalam SQL yang sama dengan LIMIT. groupIds pemanggil diabaikan; keanggotaan dipercaya diperiksa setiap kueri.

Pemrosesan dokumen menangkap spesifikasi tetap: model, versi, pemotong, ukuran, tumpang tindih, ambang. Regenerasi memegang sewa dan memeriksa penghapusan sebelum/sesudah mutasi.

Indeks diganti dalam batch 1.000 vektor. Dokumen maksimal 100.000 bagian; bagian 100.001 ditolak. Dokumen lama harus diregenerasi sebelum migrasi team dengan Settings -> Documents -> Regenerate embeddings.

SQLite mengenkripsi embedding; PGVector memerlukan angka teks biasa. Gunakan TLS, penyimpanan terenkripsi, peran minimal, dan log aman.

Kunci Enkripsi

Tetapkan ENCRYPTION_KEY 64 karakter, STORAGE_ENCRYPTION_KEYS dengan legacy, serta STORAGE_ENCRYPTION_ACTIVE_KEY_ID. Tanpa peta, adaptor membaca ${DATA_DIR}/.encryption_key. Konflik atau kunci hilang menolak startup.

Koordinasi

Kontrak menyediakan peristiwa, cache, sewa berpagar, dan batas laju. Redis tidak pernah kembali ke koordinasi lokal setelah kesalahan dan bukan sumber kebenaran; otorisasi serta pekerjaan tetap di basis data.

Pekerjaan dan Peristiwa Persisten

SQLite v3 menyediakan tabel pekerjaan, percobaan, kepala aliran, dan peristiwa. Mendukung enqueue idempoten, retry, batal, kemajuan, sewa, dead-letter, dan replay. SQLite v13/PostgreSQL v12 menambahkan indeks (stream_id, subject_id, global_cursor).

Pekerja mendaftarkan handler dokumen, media, dan pembersihan. Token sewa mencegah pekerja basi, tetapi tidak menjamin tepat sekali; efek eksternal perlu kunci idempotensi atau outbox.

Kesehatan dan Pemulihan

• /health dan /health/live memeriksa proses;
• /health/ready memeriksa basis data, skema, penyimpanan, dependensi; dan
• /health/deep menjalankan integritas SQLite bagi admin.

Gunakan libre-webui recovery-check --json atau npm run recovery:check -- --json. Lihat Kesiapan Pemulihan.

Operasi Multi-Replika Bersertifikasi

Team disertifikasi untuk tiga replika atau lebih dengan pekerja eksternal. Helm menolak banyak replika tanpa profil lengkap. npm run test:team-platform menguji kegagalan Redis, pekerja, S3, batas laju, dan isolasi. Operator dapat memakai secrets.existingSecret dan mengaktifkan networkPolicy.enabled. Keamanan pod: non-root, root hanya-baca, kapabilitas dilepas, seccomp RuntimeDefault.

Transisi yang Tersisa

Audio suara, lampiran, avatar, dan biner plugin memerlukan metadata referensi, backfill, retensi, dan tes hapus. Efek baru memerlukan target persisten, pembatalan, retry, dan enqueue transaksional sebelum team.