Biến môi trường
Trang này liệt kê các biến môi trường dành cho nhà vận hành được backend, frontend và tập lệnh bảo trì Libre WebUI hiện tại đọc. Các canary nội bộ chỉ dùng cho kiểm thử chủ ý không được liệt kê.
Máy chủ backend
| Biến | Mặc định | Mục đích |
|---|---|---|
NODE_ENV | development | Chế độ runtime |
PORT | 3001 khi phát triển, 8080 khi production | Cổng HTTP backend |
TRUST_PROXY | chưa đặt (0 trong Helm) | Số hop reverse proxy đáng tin cậy chính xác để suy ra địa chỉ máy khách |
CORS_ORIGIN | các origin phát triển cục bộ | Các origin trình duyệt được phép, phân tách bằng dấu phẩy |
SERVE_FRONTEND | chưa đặt | Phục vụ frontend đã build từ backend khi true |
DOCKER_ENV | chưa đặt | Bật hành vi hướng Docker khi true |
DATA_DIR | backend/data; ~/.libre-webui trong CLI đóng gói | Thư mục dữ liệu bền vững |
PLATFORM_PREFLIGHT_TMP_DIR | backend/temp/preflight; cache người dùng trong CLI đóng gói | Vùng tạm cho bản sao kiểm tra khởi động DB/WAL riêng tư; cần đủ chỗ cho cơ sở dữ liệu và WAL |
PLUGIN_UPLOAD_TEMP_DIR | libre-webui-plugin-uploads trong thư mục tạm của OS | Vùng tạm cho plugin đang được tải lên |
PLUGINS_DIR | $DATA_DIR/plugins | Thư mục có thể ghi cho plugin đã cài/tùy chỉnh |
BASE_URL | http://localhost:3001 | URL cơ sở cho giá trị callback OAuth mặc định |
LOG_LEVEL | info (warn trong kiểm thử) | Mức nhật ký backend |
LOG_FORMAT | text | json chuyển sang nhật ký một dòng có cấu trúc với dấu thời gian, ID tương quan và biên tập |
OTEL_EXPORTER_OTLP_ENDPOINT | chưa đặt | Xuất telemetry JSON OTLP/HTTP tùy chọn; chưa đặt nghĩa là không telemetry nào rời tiến trình |
OTEL_EXPORTER_OTLP_HEADERS | chưa đặt | Header key=value phân tách bằng dấu phẩy gửi đến bộ thu OTLP (ví dụ xác thực) |
OTEL_SERVICE_NAME | libre-webui | Thuộc tính tài nguyên service.name trên telemetry được xuất |
WEBUI_HOST | loopback; 0.0.0.0 trong Docker | Địa chỉ lắng nghe HTTP |
OPEN_BROWSER | true khi phục vụ frontend | Đặt false để ngăn tự động mở trình duyệt |
FULL_DOCUMENT_CONTEXT_MAX_TOKENS | 32000 | Bộ bảo vệ token cho chế độ ngữ cảnh toàn tài liệu theo cuộc trò chuyện (1000-2000000) |
GALLERY_RETENTION_DAYS | chưa đặt (giữ mãi mãi) | Xóa media thư viện cũ hơn số ngày này qua lượt quét của trình lập lịch |
RECOVERY_DRILL_INTERVAL_HOURS | chưa đặt (tắt diễn tập) | Tự động chạy diễn tập khôi phục đã xác minh mỗi N giờ (hồ sơ solo) |
RECOVERY_DRILL_HISTORY | 60 | Số mục lịch sử diễn tập khôi phục được giữ lại |
Khi chạy từ nguồn, các giá trị tương đối DATA_DIR, PLUGINS_DIR và PLATFORM_PREFLIGHT_TMP_DIR được neo tại thư mục backend, không phụ thuộc thư mục làm việc của shell. Vì vậy, nếu chưa đặt DATA_DIR—hoặc dùng ví dụ nguồn mới DATA_DIR=./data—các lệnh không gian làm việc root và backend dùng backend/data. Để tương thích, cấu hình nguồn hiện có chứa DATA_DIR=./backend/data tiếp tục chọn backend/backend/data; chỉ đổi trong một lần sao lưu và di chuyển có chủ đích khi dịch vụ đã dừng. Hồ sơ nguồn chưa đặt cũng tiếp tục dùng backend/backend/data khi đó là kho bền vững duy nhất hiện có. Nếu cả hai vị trí đều chứa trạng thái và chưa chọn đường dẫn, quá trình khởi động từ chối an toàn thay vì đoán, sao chép hoặc hợp nhất.
Các trình khởi chạy npx, npm toàn cục và Homebrew tương tác lại giữ dữ liệu trong ~/.libre-webui. DATA_DIR tương đối được cung cấp rõ cho trình khởi chạy được phân giải từ thư mục làm việc của người gọi và đổi thành đường dẫn tuyệt đối trước khi backend khởi động. PLUGINS_DIR tương đối được cấu hình rõ tuân theo cùng quy tắc; khi chưa đặt, plugin có thể ghi vẫn ở $DATA_DIR/plugins. Vùng tạm kiểm tra mặc định là cache người dùng có thể ghi bên ngoài thư mục dữ liệu: ~/Library/Caches/libre-webui trên macOS, %LOCALAPPDATA%\libre-webui trên Windows hoặc ${XDG_CACHE_HOME:-~/.cache}/libre-webui trên hệ thống khác. Dịch vụ Homebrew ghim cùng thư mục dữ liệu home và dùng var/libre-webui/preflight của Homebrew làm vùng tạm. Đặt rõ PLATFORM_PREFLIGHT_TMP_DIR nếu cache không đủ chứa cơ sở dữ liệu và WAL. Các bản triển khai Docker và Helm đi kèm dùng đường dẫn tuyệt đối /app/backend/data và /app/backend/temp/preflight trên các mount riêng.
Nền tảng cơ sở
Hồ sơ solo mặc định dùng SQLite, blob cục bộ mã hóa, vector nhúng mã hóa, phối hợp cục bộ và worker bền vững nhúng. Hồ sơ team dùng PostgreSQL, blob riêng tư tương thích S3, PGVector, Redis và worker bên ngoài. Cấu hình team từ chối an toàn: mọi dependency dùng chung phải được chọn cùng nhau.
| Biến | Mặc định | Mục đích |
|---|---|---|
LIBRE_PLATFORM_MODE | solo | Chọn hồ sơ solo hoặc team nhất quán |
DATABASE_BACKEND | sqlite | Chọn sqlite hoặc postgres |
DATABASE_URL | chưa đặt | URL kết nối PostgreSQL, bắt buộc với postgres |
DATABASE_SSL_MODE | verify-full | Chính sách TLS PostgreSQL: disable, require hoặc verify-full xác minh tên máy chủ |
POSTGRES_MIGRATION_MODE | apply | Chạy di chuyển tương thích dưới khóa leader hoặc dùng validate để kiểm tra lược đồ chỉ đọc |
POSTGRES_POOL_MAX | 10 | Số kết nối PostgreSQL tối đa mỗi tiến trình ứng dụng hoặc worker (1-100) |
POSTGRES_CONNECT_TIMEOUT_MS | 5000 | Thời gian chờ kết nối PostgreSQL (1-60000 ms) |
POSTGRES_IDLE_TIMEOUT_MS | 30000 | Thời gian chờ kết nối PostgreSQL nhàn rỗi (1-600000 ms) |
POSTGRES_STATEMENT_TIMEOUT_MS | 30000 | Thời gian chờ câu lệnh PostgreSQL (1-600000 ms) |
POSTGRES_MIGRATION_LOCK_TIMEOUT_MS | 60000 | Thời gian chờ khóa leader di chuyển (1-600000 ms) |
BLOB_STORE_BACKEND | local | Chọn lưu trữ local mã hóa hoặc s3 riêng tư |
VECTOR_STORE_BACKEND | embedded với SQLite | Chọn vector embedded mã hóa hoặc pgvector |
COORDINATION_BACKEND | local trong solo; redis trong team | Chọn phối hợp cục bộ theo tiến trình hoặc Redis |
REDIS_URL | chưa đặt | URL redis: hoặc rediss:, bắt buộc khi phối hợp Redis |
REDIS_KEY_PREFIX | libre | Namespace 1-64 ký tự cho khóa phối hợp Libre |
REDIS_CONNECT_TIMEOUT_MS | 5000 | Thời gian chờ kết nối Redis ban đầu, tối đa 60 giây |
JOB_WORKER_MODE | embedded trong solo; external trong team | Chạy trình xử lý trong ứng dụng hoặc worker dùng chung độc lập |
RESOURCE_LEASE_TTL_MS | 30000 | TTL lease phối hợp cho quyền sở hữu tài nguyên công việc bền vững (5000-300000; khởi động thất bại ngoài phạm vi) |
JOB_WORKER_CONCURRENCY | 4 | Số công việc bền vững một worker có thể chạy đồng thời (1-32) |
CHAT_STREAM_EVENT_RETENTION_HOURS | 24 | Số giờ giữ sự kiện đoạn luồng trò chuyện trước khi lượt quét hàng giờ xóa |
PLATFORM_EVENT_RETENTION_DAYS | 30 | Số ngày giữ sự kiện bền vững trước khi lượt quét hàng giờ xóa |
PLATFORM_JOB_RETENTION_DAYS | 30 | Số ngày giữ công việc ngoài vòng đời đã xong trước khi lượt quét hàng giờ xóa |
LIBRE_SKIP_STARTUP_INTEGRITY_SCAN | chưa đặt | 1 bỏ qua lần quét ciphertext cũ chuyên sâu ở lần khởi động sau (lối thoát; bình thường cache theo thế hệ lược đồ) |
STORAGE_ENCRYPTION_KEYS | chưa đặt | Ánh xạ khóa JSON bí mật; hiện phải có legacy khớp ENCRYPTION_KEY |
STORAGE_ENCRYPTION_ACTIVE_KEY_ID | chưa đặt | ID khóa dùng cho lần ghi blob cục bộ và vector nhúng mới |
BLOB_QUOTA_BYTES_PER_USER | 10737418240 | Số byte blob văn bản thuần bền vững tối đa mỗi chủ sở hữu (số nguyên an toàn dương) |
BLOB_QUOTA_RESERVATION_TTL_MS | 3600000 | Thời gian tồn tại của đặt chỗ hạn ngạch streaming bị bỏ dở (ít nhất 60000 ms) |
S3_BUCKET | chưa đặt | Bucket riêng tư tương thích S3, bắt buộc với s3 |
S3_REGION | chưa đặt | Khu vực S3, bắt buộc với s3 |
S3_ENDPOINT | mặc định nhà cung cấp | Endpoint HTTP(S) tuyệt đối tùy chọn cho MinIO hoặc dịch vụ tương thích khác |
S3_ACCESS_KEY_ID | chuỗi thông tin xác thực SDK | Khóa truy cập S3 rõ ràng tùy chọn |
S3_SECRET_ACCESS_KEY | chuỗi thông tin xác thực SDK | Bắt buộc khi đặt khóa truy cập rõ ràng |
S3_SESSION_TOKEN | chưa đặt | Token tùy chọn đi kèm thông tin xác thực S3 rõ ràng |
S3_FORCE_PATH_STYLE | false | Đặt true cho dịch vụ yêu cầu kiểu địa chỉ theo đường dẫn |
S3_BLOB_PREFIX | libre/blobs | Tiền tố khóa bucket mờ do Libre sở hữu |
Khi không có ánh xạ khóa lưu trữ có phiên bản, adapter lưu trữ dùng ENCRYPTION_KEY hiện có làm ID khóa legacy; nếu cũng không có giá trị này, chúng đọc ${DATA_DIR}/.encryption_key hiện có mà không tạo hoặc sửa. Cấu hình rõ ràng và tệp bền vững phải thống nhất. Nếu đưa ánh xạ có phiên bản vào khi khóa cũ tồn tại, hãy giữ khóa đó dưới đúng ID legacy đến khi mọi đối tượng và vector được viết lại hoặc bọc lại và xác minh. Xung đột, quyền tệp không an toàn, symlink và khóa cấu hình bị thiếu đều bị từ chối an toàn.
Redis dùng để phối hợp, không phải lưu trữ chuẩn. Chỉ chọn Redis không làm SQLite, tệp cục bộ hoặc trạng thái khác do tiến trình sở hữu trở nên an toàn trên nhiều replica. Trong chế độ team, giới hạn tốc độ HTTP, kết nối trò chuyện/WebSocket, công việc nhà cung cấp STT/TTS/âm thanh, nhập kho lưu trữ và phiên terminal Work dùng cơ chế tiếp nhận chung dựa trên Redis. Dung lượng áp dụng trên toàn bộ replica thay vì từng tiến trình. Lỗi tiếp nhận hoặc gia hạn quyền trả 503 hoặc hủy thao tác đang chạy; Libre không bao giờ quay về bộ đếm cục bộ độc lập.
Xem Nền tảng cơ sở.
Hồ sơ Compose team và chart Helm đi kèm chuyển mọi bộ chọn nền tảng cùng giá trị tinh chỉnh team ở trên đến cả ứng dụng và worker bên ngoài. Trong chart Helm, bộ chọn không bí mật nằm dưới env; đặt secrets.redisUrl, secrets.databaseUrl và secrets.storageEncryptionKeys cho kết nối hoặc vật liệu khóa. Giới hạn pool PostgreSQL áp dụng theo tiến trình: dành ít nhất (replicaCount + worker.replicaCount) * POSTGRES_POOL_MAX kết nối, cộng khoảng dự phòng vận hành và di chuyển. Giữ DATABASE_SSL_MODE=verify-full cho PostgreSQL được quản lý hoặc từ xa. Chỉ hồ sơ Compose team đi kèm chọn disable vì listener cơ sở dữ liệu bị cô lập trên mạng dự án riêng. Helm team cũng cần một secrets.jwtSecret ổn định và gắn cùng khóa Secret vào mọi pod ứng dụng và worker; thiếu bí mật JWT sẽ tạo vật liệu ký cục bộ theo tiến trình. S3 nhận khóa mờ và ciphertext; URL bucket và nhà cung cấp không được lưu trong siêu dữ liệu ứng dụng.
Kho lưu trữ solo và team tích hợp giữ các cài đặt pool và thời gian chờ PostgreSQL, thời gian chờ kết nối Redis, cả hai cài đặt hạn ngạch blob, bộ chọn nền tảng và cài đặt địa chỉ S3 trong cấu hình được bảo vệ, ký và mã hóa. Nhờ đó, khôi phục sạch có thể công bố các giá trị vận hành cần thiết để tái tạo bản triển khai tương ứng mà không đặt chúng vào siêu dữ liệu kho lưu trữ dạng văn bản thuần.
Cặp ứng dụng/worker bên ngoài Compose và Helm team đi kèm nhận cùng các giá trị đã phân giải OLLAMA_BASE_URL, OLLAMA_TIMEOUT, OLLAMA_LONG_OPERATION_TIMEOUT và OLLAMA_MAX_CONTEXT. Lệnh gọi nhà cung cấp cho embedding tài liệu, trò chuyện bền vững và lượt Work chạy trong worker, nên các giá trị không được khác nhau giữa tiến trình. Cả hai điểm vào máy chủ phân tích ba giá trị số thành số nguyên dương cơ số 10 hoàn chỉnh trước khi tạo trạng thái cục bộ hoặc kết nối trạng thái chung. Giá trị một phần như 300000ms, ký hiệu số mũ/hex, giá trị ngoài phạm vi và thời gian chờ thao tác dài thấp hơn thời gian chuẩn sẽ làm khởi động thất bại.
Helm giới hạn TRUST_PROXY thành số hop nguyên chính xác từ 0 đến 16 và chỉ chuyển đến pod ứng dụng HTTP. Giữ mặc định 0 cho lưu lượng trực tiếp. Đặt số cố định chính xác cho chuỗi ingress/load balancer; không dùng dạng true không giới hạn của runtime. Số sai sẽ gom máy khách dưới địa chỉ proxy để áp dụng giới hạn chung hoặc tin địa chỉ do máy khách cung cấp.
Tương thích lược đồ PostgreSQL yêu cầu đúng phiên bản. Ứng dụng và worker Helm dùng Recreate; rút và dừng mọi pod cũ trước khi nâng cấp team, sau đó cho một tiến trình mới di chuyển dưới khóa leader tư vấn. Không chạy phiên bản binary hỗn hợp hoặc tuyên bố triển khai lược đồ không downtime. Rollback nghĩa là khôi phục kho team đã xác minh trước nâng cấp vào đích PostgreSQL/S3 sạch trước khi khởi động binary cũ tương ứng.
Ứng dụng team đang hoạt động cần worker.replicaCount >= 1; Helm từ chối ứng dụng sống không có worker bền vững thay vì chờ kiểm tra sẵn sàng thất bại. Đặt cả số ứng dụng và worker về không để tạm ngưng hoàn toàn. Ứng dụng bằng không với worker dương là chế độ rút hoặc khôi phục chỉ dành cho worker có chủ đích và tiếp tục xử lý công việc trong hàng đợi mà không phục vụ lưu lượng web.
Trình hỗ trợ sao lưu riêng tư
Các biến này cấu hình deploy/private/libre-webui-backup và được tập lệnh bảo trì đọc, không phải tiến trình ứng dụng:
| Biến | Mặc định | Mục đích |
|---|---|---|
LIBRE_WEBUI_STACK_DIR | /opt/libre-webui | Thư mục chứa tệp Compose riêng tư |
LIBRE_WEBUI_BACKUP_DIR | /var/backups/libre-webui | Thư mục bảo vệ cho bộ sao lưu và tệp khóa |
LIBRE_WEBUI_BACKUP_RETENTION_DAYS | 14 | Tuổi mà sau đó bộ sao lưu hoàn tất bị xóa |
LIBRE_WEBUI_CONTAINER_NAME | libre-webui | Container ứng dụng đã triển khai cần kiểm tra |
LIBRE_WEBUI_BACKUP_KEY_DIR | /etc/libre-webui/backup-keys | Thư mục khóa mã hóa kho lưu trữ và ký riêng tư |
LIBRE_WEBUI_RESTORE_IMAGE | bắt buộc khi khôi phục | ID hoặc digest image Libre bất biến đã xem xét |
LIBRE_WEBUI_RESTORE_CONFIG_DIR | đường dẫn theo volume dưới /etc/libre-webui/restored | Thư mục mới cho cấu hình đã khôi phục |
Unit systemd nạp ghi đè sao lưu từ tệp tùy chọn do root sở hữu /etc/libre-webui/backup.env. Đặt chế độ 0600. Thư mục stack, thời gian giữ, tên container và thư mục khóa sao lưu có thể đặt trực tiếp tại đó. Sandbox hệ thống tệp của unit chỉ cho ghi dưới thư mục sao lưu mặc định. LIBRE_WEBUI_BACKUP_DIR tùy chỉnh còn cần đúng thư mục đã tạo trước trong drop-in dịch vụ ReadWritePaths=; xem
Triển khai từ xa riêng tư.
Xác thực và bảo mật
| Biến | Mặc định | Mục đích |
|---|---|---|
ENABLE_SIGNUP | false | Cho phép đăng ký sau quản trị viên cục bộ đầu tiên |
JWT_SECRET | tạo/fallback khi phát triển | Bí mật ký JWT; đặt rõ trong production |
JWT_EXPIRES_IN | 7d | Thời gian tồn tại token phiên |
ENCRYPTION_KEY | tạo tự động | Khóa hex 64 ký tự cho giá trị mã hóa |
DEBUG_ENCRYPTION | chưa đặt | Ghi đầu ra debug mã hóa khi được đặt |
TURNSTILE_SITE_KEY | chưa đặt | Khóa site Cloudflare Turnstile cho đăng nhập và đăng ký |
TURNSTILE_SECRET_KEY | chưa đặt | Khóa bí mật Cloudflare Turnstile để backend xác minh |
TURNSTILE_EXPECTED_HOSTNAME | tên máy chủ từ BASE_URL | Tên máy chủ bắt buộc trong phản hồi xác minh Cloudflare |
MFA_REQUIRED_MODE | chưa đặt (công tắc admin, optional) | Ghim chính sách hai yếu tố vào optional hoặc required |
WEBAUTHN_RP_ID | tên máy chủ yêu cầu | ID relying party cố định cho passkey sau nhiều tên máy chủ |
VAPID_PUBLIC_KEY | tạo và lưu mã hóa | Ghim khóa công khai VAPID Web Push (điểm P-256 base64url) |
VAPID_PRIVATE_KEY | tạo và lưu mã hóa | Ghim khóa riêng VAPID Web Push (scalar base64url) |
VAPID_SUBJECT | mailto:admin@localhost | Khẳng định liên hệ trong ủy quyền Web Push đã ký |
Turnstile chỉ được bật khi có cả hai khóa Turnstile.
ENABLE_SIGNUP=false vẫn cho phép quản trị viên cục bộ đầu tiên trên cơ sở dữ liệu trống, sau đó chặn thêm tài khoản cục bộ và OAuth. Hãy bảo vệ tuyến khởi tạo có thể truy cập từ xa bằng ranh giới danh tính bên ngoài trước lần khởi động đầu.
Mỗi JWT phát hành được gắn với phiên phía máy chủ (khẳng định sid), nên đăng xuất hoặc thu hồi phiên từ Cài đặt → Phiên lập tức vô hiệu token trên mọi replica và đóng kết nối WebSocket đang hoạt động. Có thể cấu hình thời gian giữ kiểm toán bảo mật:
| Biến | Mặc định | Mục đích |
|---|---|---|
AUDIT_RETENTION_DAYS | 180 | Số ngày giữ hàng trong nhật ký sự kiện kiểm toán bảo mật |
Đăng nhập một lần OIDC chung
Có thể dùng bất kỳ nhà cung cấp OpenID Connect nào có tài liệu khám phá để đăng nhập. Luồng dùng PKCE (S256), trạng thái CSRF và nonce được xác minh trong token ID đã kiểm tra chữ ký. Danh tính được liên kết theo khẳng định sub ổn định.
| Biến | Mặc định | Mục đích |
|---|---|---|
OIDC_ISSUER_URL | chưa đặt | URL cơ sở nhà phát hành; khám phá tải từ <issuer>/.well-known/openid-configuration |
OIDC_CLIENT_ID | chưa đặt | ID máy khách OAuth đã đăng ký với nhà cung cấp |
OIDC_CLIENT_SECRET | chưa đặt | Bí mật máy khách OAuth |
OIDC_DISPLAY_NAME | Single Sign-On | Nhãn hiển thị trên nút đăng nhập |
OIDC_SCOPES | openid profile email | Các phạm vi được yêu cầu |
OIDC_CALLBACK_URL | BASE_URL + tuyến callback OIDC | URI chuyển hướng đã đăng ký với nhà cung cấp |
OIDC_ALLOWED_EMAIL_DOMAINS | chưa đặt | Danh sách dấu phẩy; khi đặt, cần email đã xác minh trong một miền |
OIDC_GROUP_CLAIM | groups | Khẳng định token ID chứa tên nhóm |
OIDC_ADMIN_GROUPS | chưa đặt | Danh sách dấu phẩy; khi đặt, vai trò admin theo thành viên khẳng định mỗi lần đăng nhập |
OIDC_SYNC_GROUPS | false | true đồng bộ thành viên nhóm Libre với khẳng định nhóm mỗi lần đăng nhập |
OIDC chỉ được bật khi có đủ URL nhà phát hành, ID máy khách và bí mật máy khách. Email đã được tài khoản cục bộ chưa liên kết sử dụng sẽ bị từ chối thay vì âm thầm hợp nhất, và việc tạo tài khoản vẫn tuân theo ENABLE_SIGNUP.
Có thể tinh chỉnh tiếp nhận WebSocket Trò chuyện mà không làm yếu xác thực:
| Biến | Mặc định | Mục đích |
|---|---|---|
CHAT_WS_MAX_PAYLOAD_BYTES | 10 MiB | Kích thước tin nhắn WebSocket tối đa được nhận |
CHAT_WS_MAX_MESSAGES_PER_MINUTE | 120 | Trần tin nhắn WebSocket mỗi kết nối |
CHAT_WS_MAX_ACTIVE_GENERATIONS_PER_USER | 4 | Lượt tạo của nhà cung cấp được phép mỗi tài khoản |
CHAT_WS_MAX_CONNECTIONS_PER_USER | 5 | Socket đã xác thực đồng thời mỗi tài khoản |
WEBSOCKET_TICKET_TTL_MS | 30000 | Thời gian sống vé Chat/Work dùng một lần; tối đa 60 giây |
Trình duyệt đổi header Authorization thông thường lấy vé mờ và chỉ đặt giá trị tồn tại ngắn đó trong URL nâng cấp WebSocket. Vé dùng một lần, gắn với giao thức và phiên, chỉ được lưu dưới dạng hash. Nhờ vậy token phiên bền vững không vào nhật ký đích-yêu-cầu của reverse proxy. Khi cấu hình CORS_ORIGIN hoặc BASE_URL, nâng cấp trình duyệt có header Origin phải khớp một origin đã cấu hình. Đặt ít nhất một giá trị cho bản triển khai có thể truy cập từ xa; nếu không có cả hai, bộ lọc Origin cho phép để tương thích phát triển cục bộ. Nâng cấp không origin chủ ý vẫn được hỗ trợ cho Electron và máy khách không phải trình duyệt, nơi kiểm soát Origin của trình duyệt không có; chúng vẫn cần vé dùng một lần hợp lệ và nhận cùng kiểm tra tài khoản hiện tại, quyền Work và tác vụ. Xem vé là ranh giới xác thực và hạn chế quyền không qua trình duyệt bằng TLS, tường lửa và reverse proxy thông thường của bản triển khai.
OAuth
| Biến | Mục đích |
|---|---|
GITHUB_CLIENT_ID | ID máy khách GitHub OAuth |
GITHUB_CLIENT_SECRET | Bí mật máy khách GitHub OAuth |
GITHUB_CALLBACK_URL | Ghi đè URL callback GitHub |
HUGGINGFACE_CLIENT_ID | ID máy khách Hugging Face OAuth |
HUGGINGFACE_CLIENT_SECRET | Bí mật máy khách Hugging Face OAuth |
HUGGINGFACE_CALLBACK_URL | Ghi đè URL callback Hugging Face |
Nếu URL callback chưa đặt, Libre WebUI tạo giá trị mặc định từ BASE_URL.
Ollama
| Biến | Mặc định | Mục đích |
|---|---|---|
OLLAMA_BASE_URL | http://localhost:11434 | URL cơ sở API Ollama |
OLLAMA_TIMEOUT | 300000 | Thời gian chờ yêu cầu Ollama chuẩn (1.000-3.600.000 ms) |
OLLAMA_LONG_OPERATION_TIMEOUT | 900000 | Thời gian chờ thao tác dài (1.000-3.600.000 ms và không ngắn hơn OLLAMA_TIMEOUT) |
OLLAMA_MAX_CONTEXT | 32768 | Ngữ cảnh mô hình tối đa tự động áp dụng (128-2.097.152 token) |
Tìm kiếm web
| Biến | Mặc định | Mục đích |
|---|---|---|
SEARXNG_URL | chưa đặt | Endpoint SearXNG mặc định cho tìm kiếm web; admin vẫn bật trong Cài đặt > Tìm kiếm |
Libre Claw
| Biến | Mặc định | Mục đích |
|---|---|---|
LIBRE_CLAW_BASE_URL | http://127.0.0.1:8766 | URL daemon Libre Claw tùy chọn |
LIBRE_CLAW_TIMEOUT_MS | 30000 | Thời gian chờ yêu cầu HTTP Libre Claw |
Runtime Work
Các biến này cấu hình việc thực thi Work trên máy hoặc cluster Kubernetes chạy backend Libre WebUI. Docker là runtime mặc định; chart Helm chọn Kubernetes khi work.enabled=true.
| Biến | Mặc định | Mục đích |
|---|---|---|
WORK_RUNTIME_IMAGE | node:22.22-bookworm@sha256:2d178f2785b96dfbf62a416ca2e40f50e30150b4ff3320d706f0d96e90600eb3 | Image đã ghim dùng cho sandbox Work |
WORK_DOCKER_COMMAND | docker | Chương trình CLI backend Docker khả dụng cho tiến trình |
WORK_COMMAND_TIMEOUT_MS | 120000 | Thời gian chờ mặc định; công cụ có thể yêu cầu tối đa 600000 ms |
WORK_MAX_OUTPUT_CHARS | 50000 | Giới hạn stdout/stderr được ghi, áp dụng cho từng luồng |
WORK_MAX_AGENT_ROUNDS | 48 | Ngân sách vòng mô hình/công cụ không phụ thuộc nhà cung cấp cho một lượt |
WORK_STATUS_BLURB_MODEL | 1 | Đặt 0 để bỏ yêu cầu mô hình viết dòng trạng thái tác tử sau một lượt |
WORK_MEMORY_LIMIT | 2g | Giới hạn bộ nhớ truyền cho mỗi container Work |
WORK_CPU_LIMIT | 2 | Giới hạn CPU truyền cho mỗi container Work |
WORK_PIDS_LIMIT | 256 | Giới hạn tiến trình truyền cho mỗi container Work |
WORK_PREVIEW_PORT | 4173 | Cổng máy chủ xem trước phải dùng trong container tác vụ |
WORK_PREVIEW_BIND | 127.0.0.1 | Giao diện host nơi cổng xem trước tác vụ được công bố; bản triển khai Compose trên Docker Engine thuần phải dùng giao diện cầu nối không công khai nhưng tới được |
WORK_DOCKER_PUBLISHED_HOST | mặc định của ứng dụng: giống WORK_PREVIEW_BIND; mặc định của Compose: host.docker.internal | Host/IP phía backend cho cổng xem trước, màn hình và âm thanh do Docker công bố |
WORK_COMPUTER_SCREEN_PORT | 6080 | Cổng container của cầu màn hình Work Computer (websockify) trong sandbox có GUI |
WORK_COMPUTER_AUDIO_PORT | 6081 | Cổng container của cầu âm thanh Work Computer (websockify → PulseAudio monitor) trong sandbox có GUI |
WORK_MAX_ACTIVE_RUNTIMES_GLOBAL | 3 | Tác vụ dựa trên runtime đồng thời cho toàn phiên bản |
WORK_MAX_ACTIVE_RUNTIMES_PER_USER | 2 | Tác vụ dựa trên runtime đồng thời cho một người dùng |
WORK_MAX_TASKS_GLOBAL | 500 | Số tác vụ Work bền vững tối đa cho toàn phiên bản |
WORK_MAX_TASKS_PER_USER | 100 | Số tác vụ Work bền vững tối đa cho một quản trị viên |
WORK_NETWORK_NAME | libre-webui-work | Mạng bridge sandbox được quản lý cho tác vụ có mạng |
WORK_RUN_LEASE_WAIT_MS | 60000 | Thời gian lượt chờ lease runtime chung của tác vụ trước khi báo xung đột replica (chế độ team) |
WORK_RUNTIME_DNS | chưa đặt | IP resolver phân tách dấu phẩy buộc dùng cho tác vụ có mạng |
WORK_DOCKER_SOCKET | DOCKER_HOST nếu unix:// hoặc tcp://, nếu không /var/run/docker.sock | Endpoint Docker Engine cho terminal và chẩn đoán |
WORK_TERMINAL_MAX_SESSIONS_PER_TASK | 2 | Terminal trình duyệt đồng thời gắn vào một tác vụ |
WORK_TERMINAL_IDLE_TIMEOUT_MS | 900000 | Thời gian nhàn rỗi trước khi đóng phiên terminal |
WORK_RUNTIME_IDLE_TIMEOUT_MS | 0 (tắt) | Dừng sandbox sau thời gian không hoạt động này (cả bản xem trước) |
WORK_HOST_WORKSPACES_ENABLED | false | Cho phép tác vụ dùng thư mục host thay vì volume |
WORK_HOST_WORKSPACE_ROOTS | thư mục home của người dùng máy chủ | Các root phân tách : mà không gian làm việc host phải nằm trong |
WORK_RUNTIME_BACKEND | docker | Backend sandbox: docker hoặc kubernetes |
WORK_K8S_NAMESPACE | libre-webui-work | Namespace chứa Pod và PVC sandbox Kubernetes |
WORK_K8S_STORAGE_CLASS | mặc định cluster | StorageClass cho PVC không gian làm việc |
WORK_K8S_WORKSPACE_SIZE | 5Gi | Kích thước PVC không gian làm việc theo tác vụ (hạn ngạch đĩa thực) |
WORK_K8S_POD_READY_TIMEOUT_MS | 900000 | Chờ Pod sandbox đạt Running (gồm tải image) |
WORK_K8S_POD_GONE_TIMEOUT_MS | 60000 | Chờ Pod sandbox đã xóa biến mất |
AGENT_CLI_MODELS_ENABLED | chưa đặt (công tắc admin, tắt) | Ghim tính năng Tác tử bật/tắt; chưa đặt để công tắc admin trong Quản lý người dùng quyết định (mặc định tắt) |
TOOLS_ACCESS_MODE | chưa đặt (công tắc admin, chỉ admin) | Ghim công cụ trò chuyện vào admins hoặc all-users và khóa công tắc admin |
STT_ACCESS_MODE | chưa đặt (công tắc admin, mọi người dùng) | Ghim giọng nói thành văn bản vào admins hoặc all-users và khóa công tắc admin |
TTS_ACCESS_MODE | chưa đặt (công tắc admin, mọi người dùng) | Ghim văn bản thành giọng nói vào admins hoặc all-users và khóa công tắc admin |
VOICE_MODE_ACCESS_MODE | chưa đặt (công tắc admin, mọi người dùng) | Ghim chế độ giọng nói rảnh tay vào admins hoặc all-users và khóa công tắc admin |
VOICE_CLONING_ACCESS_MODE | chưa đặt (công tắc admin, mọi người dùng) | Ghim nhân bản giọng nói vào admins hoặc all-users và khóa công tắc admin |
TOOLS_PRIVATE_NETWORK_ALLOWLIST | chưa đặt | Tên host chính xác mà máy chủ công cụ và webhook được phân giải thành địa chỉ riêng; phân tách dấu phẩy, ghim |
AGENT_CLI_TIMEOUT_MS | 600000 | Thời gian CLI tác tử được chạy trước khi bị dừng |
CODEX_OAUTH_MODELS_ENABLED | true | Cung cấp nhà cung cấp Codex (ChatGPT) cho admin |
CODEX_HOME | ~/.codex | Nơi đọc đăng nhập CLI Codex (auth.json) |
Binary CLI tác tử và thông tin Codex OAuth là cục bộ theo node. Chúng chỉ được hỗ trợ trong tiến trình solo, nơi khám phá và thực thi thấy cùng hệ thống tệp và môi trường. Chế độ team thực thi công việc trò chuyện bền vững trong worker bên ngoài, nên cần cả AGENT_CLI_MODELS_ENABLED=false và CODEX_OAUTH_MODELS_ENABLED=false; quá trình khởi động từ chối mọi giá trị khác thay vì quảng bá nhà cung cấp có thể chỉ tồn tại trên một replica ứng dụng. Hãy dùng Ollama hoặc plugin nhà cung cấp có thông tin xác thực và định tuyến được lưu trong PostgreSQL chung hoặc chuyển tiếp giống nhau đến mọi ứng dụng và worker.
Trên backend Docker, không gian làm việc host bind-mount thư mục thật vào /workspace, nên tác vụ đọc và ghi trực tiếp các tệp đó thay vì làm việc trong volume Docker riêng. Kubernetes từ chối không gian làm việc thư mục host. Đây là việc chủ ý giảm bảo vệ sandbox Docker: giữ WORK_HOST_WORKSPACES_ENABLED tắt trừ khi thật sự cần và thu hẹp WORK_HOST_WORKSPACE_ROOTS tối đa. Đường dẫn yêu cầu được phân giải qua symlink trước khi kiểm tra với root; các thư mục như .ssh, .gnupg, .aws và .config bị từ chối hoàn toàn.
Mô hình CLI tác tử đưa các tác tử lập trình đã cài trên máy chủ (claude, codex) thành mô hình trò chuyện có thể chọn, nên tác tử theo gói thuê bao có thể trả lời không cần khóa API. Chỉ quản trị viên thấy chúng, CLI chạy dưới người dùng máy chủ Libre WebUI và kế thừa thông tin tác tử của người dùng đó—hãy xem như cấp quyền shell cho các tác tử này.
Trên Docker, tác vụ Work có mạng gắn vào bridge WORK_NETWORK_NAME được quản lý, tạo với giao tiếp liên container bị tắt để một sandbox không thể truy cập sandbox khác hoặc container của bản triển khai. WORK_RUNTIME_DNS là móc chính sách egress Docker được hỗ trợ: trỏ đến resolver lọc để áp dụng danh sách cho phép/từ chối theo tên. Mục không phải địa chỉ IPv4/IPv6 bị từ chối và ghi nhật ký. Lọc DNS không giới hạn egress IP trực tiếp; thêm quy tắc tường lửa host nếu bản triển khai yêu cầu. Backend Kubernetes dùng NetworkPolicy từ chối mặc định của chart và giá trị work.networkPolicy.blockedEgressCidrs.
Trên Docker, terminal tương tác và chẩn đoán hệ thống giao tiếp trực tiếp với API Docker Engine. Chúng dùng WORK_DOCKER_SOCKET nếu đặt, nếu không là DOCKER_HOST—socket unix:// hoặc endpoint tcp:// HTTP thuần như proxy socket (xem docker-compose.socket-proxy.yml)—nếu không là /var/run/docker.sock. DOCKER_HOST mà máy khách này không giao tiếp được (ssh://, hoặc tcp:// với DOCKER_TLS_VERIFY) sẽ báo terminal và chẩn đoán Docker không khả dụng; phần còn lại của Work tiếp tục chạy qua CLI Docker, vốn tự hiểu các endpoint đó. Trên Kubernetes, terminal dùng tài nguyên con exec của Pod và không dùng endpoint Docker.
Work đọc các giá trị này khi backend khởi động. Cổng xem trước nằm bên trong container tác vụ; Libre WebUI công bố đến cổng loopback được gán động thay vì đưa giá trị trực tiếp ra mọi giao diện host.
Giữ image runtime ghim ở phiên bản hoặc digest đã xem xét. Tăng đồng thời hoặc giới hạn tài nguyên sẽ tăng dung lượng runtime mà một hay nhiều lượt tự động có thể dùng. WORK_MAX_AGENT_ROUNDS áp dụng như nhau cho Ollama và lượt dựa trên plugin; không có mức thấp hơn chỉ cho plugin. Ngân sách an toàn lệnh gọi công cụ là max(128, WORK_MAX_AGENT_ROUNDS × 8). Khi lượt dùng hết ngân sách vòng, Work yêu cầu mô hình bàn giao cuối không công cụ và kết thúc ở trạng thái terminal needs_input, thay vì trả lỗi giới hạn vòng thô hoặc tuyên bố thành công. Lượt tiếp theo tiếp tục trong cùng không gian làm việc bền vững. Đầu ra công cụ được lưu có giới hạn riêng khoảng 20.000 ký tự nguồn cộng dấu cắt ngắn.
Các biến sau tinh chỉnh runtime Work đã có thể truy cập. Bản triển khai Compose một phiên bản trong repository bật mặc định: image có CLI Docker và các tệp Compose gắn socket Docker host. Hai biến cấp Compose điều khiển kết nối đó:
| Biến | Mặc định | Mục đích |
|---|---|---|
DOCKER_GID | 0 | ID nhóm của socket Docker host, thêm vào người dùng container |
DOCKER_SOCKET | /var/run/docker.sock | Đường host của socket Docker cần gắn |
DOCKER_GID phải là nhóm của socket như nhìn từ trong container; host macOS báo giá trị khác. Cơ sở Compose team không gắn socket và giữ Work dựa trên Docker không khả dụng đến khi thêm docker-compose.team.work.yml. Overlay production đó cấp cùng endpoint proxy lọc nội bộ cho ứng dụng và worker, không bao giờ gắn socket hoặc nhóm socket. Proxy chỉ cho phần API Docker runtime dùng, nhưng tạo container vẫn là thông tin xác thực kiểm soát host Docker; hãy dùng daemon Work riêng hoặc rootless để có ranh giới mạnh hơn. Chart Helm không bao giờ gắn socket runtime node. Bật backend Work Pod/PVC native bằng work.enabled=true.
Hồ sơ solo phải giữ ở không hoặc một replica ứng dụng vì dùng SQLite, tệp cục bộ và phối hợp cục bộ theo tiến trình. Chart Helm chấp nhận không để tạm ngưng có chủ đích và từ chối số replica solo lớn hơn hoặc tự động mở rộng solo. Hồ sơ team đầy đủ có thể dùng nhiều replica ứng dụng và worker bên ngoài vì PostgreSQL, S3, PGVector và Redis sở hữu trạng thái chung. Pod sandbox Work mở rộng độc lập trong cả hai hồ sơ; ở chế độ team, worker bên ngoài nhận cùng image runtime Kubernetes, StorageClass và giới hạn work.env như pod ứng dụng.
Tệp Compose repository cũng nhận WEBUI_BIND_ADDRESS (mặc định 127.0.0.1) và WEBUI_PORT (mặc định 8080). Giữ loopback mặc định trừ khi LAN đáng tin cậy hoặc reverse proxy host phải truy cập cổng.
Khám phá mô hình nhà cung cấp
Danh mục mô hình của nhà cung cấp được tự khám phá lại khi thiếu hoặc cũ, nên việc nạp lại phản ánh các mô hình mà nhà cung cấp hiện phục vụ. Các biến sau tinh chỉnh chu kỳ:
| Biến | Mặc định | Mục đích |
|---|---|---|
PLUGIN_MODEL_DISCOVERY_TTL_MS | 21600000 (6 giờ) | Tuổi mà danh mục lưu được làm mới ở lần đọc danh sách plugin tiếp theo |
PLUGIN_MODEL_DISCOVERY_RETRY_MS | 600000 (10 phút) | Khoảng cách tối thiểu giữa các lần thử để không thăm dò nhà cung cấp lỗi thường xuyên |
PLUGIN_MODEL_DISCOVERY_REFRESH_DEADLINE_MS | 3000 | Thời gian phản hồi danh sách plugin chờ làm mới trước khi trả lời |
Lần làm mới vượt thời hạn vẫn hoàn tất và được phục vụ ở yêu cầu tiếp theo. Làm mới mô hình rõ ràng luôn liên hệ nhà cung cấp và bỏ qua khoảng thời gian.
Khóa plugin nhà cung cấp
Plugin nhà cung cấp có thể dùng khóa môi trường làm mặc định toàn bản triển khai:
| Biến | Nhà cung cấp |
|---|---|
OPENAI_API_KEY | OpenAI và OpenAI TTS |
ANTHROPIC_API_KEY | Anthropic |
GROQ_API_KEY | Groq |
GEMINI_API_KEY | Google Gemini |
MISTRAL_API_KEY | Mistral |
OPENROUTER_API_KEY | OpenRouter |
KIMI_API_KEY | Kimi Code của Moonshot AI |
GITHUB_API_KEY | GitHub Models |
HUGGINGFACE_API_KEY | API Hugging Face tại nơi được cấu hình |
ELEVENLABS_API_KEY | ElevenLabs TTS |
COMFYUI_API_KEY | Bản triển khai ComfyUI cần khóa API |
Người dùng cũng có thể lưu thông tin xác thực nhà cung cấp trong UI nếu ưu tiên khóa theo người dùng. Khóa môi trường chỉ dùng với phép chiếu định tuyến và xác thực của định nghĩa đi kèm không bị che khuất. Định nghĩa nhập, định nghĩa có thể ghi dùng lại ID đi kèm và tuyến tùy chỉnh do quản trị viên lưu cần thông tin xác thực của cùng tài khoản. Libre WebUI không gắn khóa môi trường vào các tuyến đó hoặc đưa ra qua khám phá và kiểm tra khả dụng. Độ tin cậy đến từ hash biên dịch của từng manifest phát hành, nên bố cục container nơi thư mục plugin cũ và đi kèm chung đường dẫn vẫn được hỗ trợ mà không xem manifest đã sửa là đi kèm.
Khóa người dùng lưu được gắn với định nghĩa nhà cung cấp hiệu lực, nguồn, hợp đồng xác thực và giá trị định tuyến. Người dùng phải lưu lại khóa sau khi quản trị viên đổi đích. Khóa chưa gắn trước nâng cấp chỉ được chấp nhận và gắn ở lần dùng đầu với định nghĩa phát hành chính xác dùng tuyến đi kèm.
Khi chạy từ nguồn, PLUGINS_DIR tương đối được phân giải từ thư mục backend. Trình khởi chạy đóng gói đổi giá trị tương đối cấu hình rõ thành đường tuyệt đối theo người gọi trước khi chạy backend. Để tương thích, Libre còn đọc thư mục xác định backend/plugins và vị trí lịch sử từ cấu hình trước. Hãy chuyển định nghĩa vào $DATA_DIR/plugins; khôi phục báo đường cũ là trạng thái ngoài và chặn ảnh chụp chỉ volume khi định nghĩa tùy chỉnh còn ở đó. Thư mục plugin và định nghĩa JSON phải là mục vật lý thông thường—Libre không theo symlink plugin.
Frontend
| Biến | Mặc định | Mục đích |
|---|---|---|
VITE_API_BASE_URL | proxy phát triển cùng nguồn gốc hoặc API production | URL cơ sở API frontend |
VITE_WS_BASE_URL | suy ra từ URL API | Cơ sở ws:/wss: tuyệt đối cho socket Chat và Work |
VITE_APP_VERSION | phiên bản gói do cấu hình Vite chèn | Phiên bản ứng dụng hiển thị |
VITE_DEMO_MODE | false | Bật giả lập chế độ demo khi true |
VITE_API_TIMEOUT | 300000 | Thời gian chờ API frontend theo mili giây |
VITE_BACKEND_URL | http://localhost:3001 | Một số thành phần hỗ trợ xác thực sử dụng |
VITE_DEBUG_VERBOSE | chưa đặt | Bật nhật ký debug frontend chi tiết khi phát triển |
VITE_LOG_LEVEL | chưa đặt | Ghi đè mức nhật ký frontend |
ELECTRON_BUILD | chưa đặt | Bật hành vi Vite riêng cho Electron khi true |
VITE_WS_BASE_URL ghi đè mọi fallback WebSocket cho Chat và terminal Work. Có thể chứa tiền tố đường reverse proxy nhưng phải là URL ws: hoặc wss: tuyệt đối, không thông tin xác thực, truy vấn hoặc fragment. Khi chưa đặt, máy khách Electron file: dùng ws://localhost:3001; máy khách trình duyệt suy cơ sở lần lượt từ VITE_API_BASE_URL, rồi đến origin của trình duyệt. Vite proxy origin phát triển đến backend ở cổng 3001.
Tập lệnh bảo trì
| Biến | Mục đích |
|---|---|
CHANGELOG_AI | Đặt 0 để tắt bản nháp changelog hỗ trợ AI |
CHANGELOG_AI_MODEL | Mô hình Ollama để tạo bản phát hành/changelog |
CHANGELOG_AI_TIMEOUT_MS | Thời gian chờ tạo changelog AI theo mili giây |
Ví dụ:
CHANGELOG_AI_MODEL=glm-5.2:cloud npm run changelog
CHANGELOG_AI=0 npm run release:minor
Ví dụ production
NODE_ENV=production
PORT=3001
SERVE_FRONTEND=true
DATA_DIR=/data/libre-webui
CORS_ORIGIN=https://librewebui.example
BASE_URL=https://librewebui.example
JWT_SECRET=replace-with-a-long-random-secret
ENCRYPTION_KEY=replace-with-64-hex-characters
ENABLE_SIGNUP=false
OLLAMA_BASE_URL=http://ollama:11434
OLLAMA_TIMEOUT=300000
OLLAMA_LONG_OPERATION_TIMEOUT=900000
OLLAMA_MAX_CONTEXT=32768
TURNSTILE_SITE_KEY=...
TURNSTILE_SECRET_KEY=...
TURNSTILE_EXPECTED_HOSTNAME=librewebui.example