Nền tảng hệ thống

solo dùng SQLite, blob cục bộ, vectơ nhúng, phối hợp cục bộ, tiến trình xử lý nhúng. team dùng PostgreSQL, S3, PGVector, Redis, tiến trình xử lý ngoài. Cấu hình trộn bị từ chối.

Mốc hiện tại

Mảng	Nền tảng	Việc còn lại
Lưu trữ	SQLite/PostgreSQL, migration cố định	Miền mới dùng repository
Blob	Mã hóa, range, checksum, quota	Di chuyển tệp nhị phân
Vektor	Mã hóa, ACL, xây lại an toàn	Giữ hợp đồng quyền
Phối hợp	Event, cache, lease, rate limit	Redis không là nguồn thật
Job	Hàng đợi, retry, cancel	Hiệu ứng mới cần idempotency
Vận hành	Health, backup, restore	Diễn tập

Hồ sơ runtime

LIBRE_PLATFORM_MODE=solo là mặc định. LIBRE_PLATFORM_MODE=team cần:

• DATABASE_BACKEND=postgres với DATABASE_URL;
• BLOB_STORE_BACKEND=s3;
• VECTOR_STORE_BACKEND=pgvector;
• COORDINATION_BACKEND=redis với REDIS_URL; và
• JOB_WORKER_MODE=external.

Chuyển solo

Dừng mọi ứng dụng và worker. Lệnh libre-webui đã cài cung cấp libre-webui migrate-postgres; cũng có thể dùng npx --yes libre-webui@latest hoặc npm run migrate:postgres -- với cùng DATA_DIR.

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

ENCRYPTION_KEY phải khớp .encryption_key; STORAGE_ENCRYPTION_KEYS chứa khóa hoạt động và legacy.

Chạy team

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

Thay mọi giá trị REPLACE_* và tạo mật khẩu bằng openssl rand -hex 32. Cấu hình gồm POSTGRES_MIGRATION_MODE, POSTGRES_POOL_MAX, REDIS_CONNECT_TIMEOUT_MS, OLLAMA_BASE_URL, OLLAMA_TIMEOUT, OLLAMA_LONG_OPERATION_TIMEOUT, OLLAMA_MAX_CONTEXT.

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

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

Proxy socket không phải ranh giới tenant. Không mở PostgreSQL, Redis, MinIO.

Ranh giới lưu trữ và migration

Repository bất đồng bộ dùng cùng kết nối. Runtime chọn qua Persistence; hợp đồng chung không nhận tay cầm better-sqlite3. SQLite kiểm tra migration và chép DB/WAL vào PLATFORM_PREFLIGHT_TMP_DIR, không phụ thuộc /tmp. Giá trị rỗng v4 thành NULL.

Blob và vectơ

BlobStore cho media/tài liệu; VectorStore cho RAG/bộ nhớ. Phục hồi xác thực mọi blob, vectơ và văn bản mã hóa trong giới hạn RecoveryInventoryOptions.

Blob cục bộ

LocalEncryptedBlobStore ghi ${DATA_DIR}/blobs bằng AES-256-GCM, quyền 0700/0600. SQLite quota dùng BEGIN IMMEDIATE. BLOB_QUOTA_BYTES_PER_USER, BLOB_QUOTA_RESERVATION_TTL_MS đặt giới hạn.

BLOB_STORE_BACKEND=s3 dùng bucket riêng, metadata PostgreSQL và xóa idempotent.

Vektor

VectorStore yêu cầu actor. SQLite áp dụng ACL trước giải mã. VECTOR_STORE_BACKEND=pgvector áp dụng predicate trong cùng SQL với LIMIT; bỏ qua groupIds từ caller.

Tài liệu giữ đặc tả mô hình/bộ chia cố định. Chỉ tối đa 100.000 đoạn; mỗi lô tối đa 1.000 vectơ. Tài liệu cũ phải chạy Settings -> Documents -> Regenerate embeddings trước khi chuyển sang team.

PGVector cần số dạng thường; dùng TLS, volume mã hóa, quyền tối thiểu và log an toàn.

Khóa

Dùng STORAGE_ENCRYPTION_ACTIVE_KEY_ID, STORAGE_ENCRYPTION_KEYS, ENCRYPTION_KEY. Nếu không, đọc ${DATA_DIR}/.encryption_key. Lỗi khóa làm startup thất bại.

Phối hợp

Redis cung cấp event, cache, lease và rate limit nhưng không là nguồn dữ liệu thật; không fallback cục bộ sau lỗi.

Job và event

SQLite v3 cung cấp job, attempt, stream, event; hỗ trợ enqueue idempotent, retry, cancel, dead-letter, replay. SQLite v13/PostgreSQL v12 thêm (stream_id, subject_id, global_cursor).

Lease không bảo đảm đúng một lần; hiệu ứng ngoài cần khóa idempotency hoặc outbox.

Sức khỏe

• /health, /health/live: tiến trình
• /health/ready: cơ sở dữ liệu, lược đồ, lưu trữ
• /health/deep: kiểm tra SQLite cho admin

Dùng libre-webui recovery-check --json; từ mã nguồn dùng npm run recovery:check -- --json. Xem Sẵn sàng phục hồi.

Nhiều bản sao

Team được chứng nhận cho 3+ bản sao với tiến trình xử lý ngoài. npm run test:team-platform kiểm thử lỗi Redis, tiến trình xử lý, S3 và cô lập. Dùng secrets.existingSecret, networkPolicy.enabled; pod không chạy root, hệ thống gốc chỉ đọc, seccomp RuntimeDefault.

Việc chuyển tiếp còn lại

Âm thanh, tệp đính kèm, avatar và nhị phân plugin cần siêu dữ liệu, điền bù, lưu giữ và kiểm thử xóa. Hiệu ứng mới cần đích bền vững, hủy/thử lại và đưa vào hàng đợi theo giao dịch.