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

MinIO không còn phát hành container image. Hồ sơ team và CI kéo bản dựng MinIO server và client của Chainguard từ cgr.dev/chainguard, được ghim theo digest. Máy chủ hạn chế truy cập registry phải cho phép cgr.dev. Server chạy dưới quyền root như image chính thức trước đây, nên các volume tạo trước khi chuyển đổi vẫn ghi được.

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.

Bộ máy Strands tích hợp lưu các phiên trên trang của nó dưới dạng tệp trong <DATA_DIR>/strands/, không nằm trong cơ sở dữ liệu ứng dụng. Driver Work của nó không tạo kho bền cục bộ: dữ liệu SQL hiện có về tác vụ, lượt chạy, thông điệp, phê duyệt và job bền vẫn có thẩm quyền, kể cả phục hồi trên worker ngoài. Lựa chọn bộ máy được lưu cùng mô hình đã chọn dưới dạng strands:<model> (các lần chạy lưu với tiền tố cũ dsh:<model> sẽ mở thành lần chạy Strands) và giữ danh tính nhà cung cấp cùng quyền runtime hiện có.

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. Khởi động thành công lưu một dấu xác minh gắn với tệp cơ sở dữ liệu và schema; các lần sau dùng lại dấu đó cho đến khi tệp hoặc schema thay đổi. Định danh tệp được lưu dưới dạng chuỗi thập phân chính xác, kể cả định danh Windows/NTFS rất lớn. Dấu dạng số kiểu cũ kích hoạt một lần xác minh đầy đủ trước khi bị thay. 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.