Змінні середовища
На цій сторінці перелічено змінні для операторів, які читають поточні сервер, фронтенд і сценарії обслуговування Libre WebUI. Внутрішні тестові canary навмисно пропущено.
Серверна частина
| Змінна | Типово | Призначення |
|---|---|---|
NODE_ENV | development | Режим виконання |
PORT | 3001 у розробці, 8080 у промисловому середовищі | HTTP-порт сервера |
TRUST_PROXY | не задано (0 у Helm) | Точна кількість довірених переходів reverse proxy |
CORS_ORIGIN | локальні походження розробки | Дозволені походження браузера через кому |
SERVE_FRONTEND | не задано | true обслуговує зібраний фронтенд сервером |
DOCKER_ENV | не задано | true вмикає поведінку Docker |
DATA_DIR | backend/data; ~/.libre-webui у CLI | Постійний каталог даних |
PLATFORM_PREFLIGHT_TMP_DIR | backend/temp/preflight; кеш користувача в CLI | Тимчасова копія бази/WAL для перевірки запуску |
PLUGIN_UPLOAD_TEMP_DIR | libre-webui-plugin-uploads у тимчасовому каталозі ОС | Тимчасове місце завантажень плагінів |
PLUGINS_DIR | $DATA_DIR/plugins | Записуваний каталог установлених плагінів |
BASE_URL | http://localhost:3001 | Базовий URL для типових OAuth callback |
LOG_LEVEL | info (warn у тестах) | Рівень журналу сервера |
LOG_FORMAT | text | json вмикає структуровані однорядкові журнали |
OTEL_EXPORTER_OTLP_ENDPOINT | не задано | Добровільний експорт OTLP/HTTP JSON |
OTEL_EXPORTER_OTLP_HEADERS | не задано | Заголовки key=value колектора через кому |
OTEL_SERVICE_NAME | libre-webui | Атрибут service.name телеметрії |
WEBUI_HOST | loopback; 0.0.0.0 у Docker | Адреса прослуховування HTTP |
OPEN_BROWSER | true під час обслуговування фронтенду | false не відкриває браузер автоматично |
FULL_DOCUMENT_CONTEXT_MAX_TOKENS | 32000 | Захист контексту повного документа, 1000–2000000 |
GALLERY_RETENTION_DAYS | не задано, зберігати завжди | Видаляти старі медіа планувальником |
RECOVERY_DRILL_INTERVAL_HOURS | не задано, перевірки вимкнено | Автоматична перевірка відновлення кожні N годин у solo |
RECOVERY_DRILL_HISTORY | 60 | Кількість збережених перевірок |
Запуск із джерел прив’язує відносні DATA_DIR, PLUGINS_DIR і PLATFORM_PREFLIGHT_TMP_DIR до каталогу сервера незалежно від оболонки. DATA_DIR=./data вибирає backend/data, а історичне DATA_DIR=./backend/data — backend/backend/data; змінюйте лише після зупинки, резервування й свідомої міграції. Якщо обидва місця мають стан без явного вибору, запуск безпечно відмовляє замість вгадування, копіювання або злиття.
npx, глобальний npm і Homebrew зберігають дані в ~/.libre-webui; явні відносні шляхи визначаються від каталогу виклику й стають абсолютними. Типовий кеш перевірки: ~/Library/Caches/libre-webui на macOS, %LOCALAPPDATA%\libre-webui у Windows або ${XDG_CACHE_HOME:-~/.cache}/libre-webui в інших системах; Homebrew використовує var/libre-webui/preflight, Docker/Helm — /app/backend/data і /app/backend/temp/preflight. Задайте PLATFORM_PREFLIGHT_TMP_DIR, якщо кеш не вміщує базу разом із WAL.
Основа платформи
Профіль solo використовує SQLite, локальні зашифровані blob і вектори, локальну координацію та вбудований worker. team використовує PostgreSQL, приватне S3-сумісне сховище, PGVector, Redis і зовнішній worker. Неповне поєднання спільних залежностей безпечно відхиляється.
| Змінна | Типово | Призначення |
|---|---|---|
LIBRE_PLATFORM_MODE | solo | Узгоджений профіль solo або team |
DATABASE_BACKEND | sqlite | sqlite або postgres |
DATABASE_URL | не задано | URL PostgreSQL, потрібний для postgres |
DATABASE_SSL_MODE | verify-full | disable, require або verify-full |
POSTGRES_MIGRATION_MODE | apply | Міграція під блокуванням або validate лише для перевірки |
POSTGRES_POOL_MAX | 10 | Підключення PostgreSQL на процес, 1–100 |
POSTGRES_CONNECT_TIMEOUT_MS | 5000 | Тайм-аут підключення, 1–60000 ms |
POSTGRES_IDLE_TIMEOUT_MS | 30000 | Тайм-аут бездіяльного підключення, 1–600000 ms |
POSTGRES_STATEMENT_TIMEOUT_MS | 30000 | Тайм-аут оператора, 1–600000 ms |
POSTGRES_MIGRATION_LOCK_TIMEOUT_MS | 60000 | Очікування блокування міграції, 1–600000 ms |
BLOB_STORE_BACKEND | local | Зашифроване local або приватне s3 |
VECTOR_STORE_BACKEND | embedded із SQLite | embedded або pgvector |
COORDINATION_BACKEND | local у solo, redis у team | Локальна або Redis-координація |
REDIS_URL | не задано | URL redis: або rediss: |
REDIS_KEY_PREFIX | libre | Простір ключів 1–64 символи |
REDIS_CONNECT_TIMEOUT_MS | 5000 | Початковий тайм-аут Redis до 60 секунд |
JOB_WORKER_MODE | embedded у solo, external у team | Обробники в застосунку або окремому worker |
RESOURCE_LEASE_TTL_MS | 30000 | TTL оренди ресурсу 5000–300000 |
JOB_WORKER_CONCURRENCY | 4 | Одночасні постійні завдання worker, 1–32 |
CHAT_STREAM_EVENT_RETENTION_HOURS | 24 | Години зберігання фрагментів потоку чату |
PLATFORM_EVENT_RETENTION_DAYS | 30 | Дні зберігання постійних подій |
PLATFORM_JOB_RETENTION_DAYS | 30 | Дні зберігання завершених задач |
LIBRE_SKIP_STARTUP_INTEGRITY_SCAN | не задано | 1 один раз пропускає глибоке сканування старих шифротекстів |
STORAGE_ENCRYPTION_KEYS | не задано | Секретна JSON-карта з legacy, що дорівнює ENCRYPTION_KEY |
STORAGE_ENCRYPTION_ACTIVE_KEY_ID | не задано | ID ключа нових локальних blob і векторів |
BLOB_QUOTA_BYTES_PER_USER | 10737418240 | Максимум відкритих байтів blob на власника |
BLOB_QUOTA_RESERVATION_TTL_MS | 3600000 | Життя покинутої потокової резервації, мінімум 60000 ms |
S3_BUCKET | не задано | Приватний S3 bucket |
S3_REGION | не задано | Регіон S3 |
S3_ENDPOINT | типове значення провайдера | Необов’язкова абсолютна HTTP(S)-точка MinIO або сумісної служби |
S3_ACCESS_KEY_ID | ланцюг облікових даних SDK | Необов’язковий явний ключ доступу |
S3_SECRET_ACCESS_KEY | ланцюг облікових даних SDK | Потрібний з явним ключем доступу |
S3_SESSION_TOKEN | не задано | Необов’язковий токен S3 |
S3_FORCE_PATH_STYLE | false | true для адресації в стилі шляхів |
S3_BLOB_PREFIX | libre/blobs | Непрозорий префікс ключів bucket |
Без карти адаптери використовують ENCRYPTION_KEY як ID legacy, а якщо його немає — читають ${DATA_DIR}/.encryption_key, нічого не створюючи й не змінюючи. Явна конфігурація та файл мають збігатися. Після запровадження карти зберігайте старий ключ під точним ID legacy, доки всі об’єкти й вектори не переписано або не перепаковано й перевірено. Конфлікти, небезпечні права, symlink і відсутні ключі безпечно блокують запуск.
Redis — координація, не канонічне сховище. Сам вибір Redis не робить SQLite або локальні файли безпечними для реплік. У team спільний допуск HTTP, Chat/WebSocket, STT/TTS/audio, імпорту архівів і терміналів діє на всі репліки. Помилка повертає 503 або перериває операцію; локального резерву немає. Див. Основу платформи.
Team Compose і Helm передають усі селектори й налаштування застосунку та worker. У Helm несекретні значення містяться в env, а secrets.redisUrl, secrets.databaseUrl, secrets.storageEncryptionKeys — секретні. Плануйте щонайменше (replicaCount + worker.replicaCount) * POSTGRES_POOL_MAX підключень плюс запас. Для віддаленого PostgreSQL залишайте DATABASE_SSL_MODE=verify-full; приватний Compose використовує disable. Team Helm також потребує одного стабільного secrets.jwtSecret для всіх Pod. S3 отримує непрозорі ключі й шифротекст.
Інтегровані архіви зберігають параметри пулу й тайм-аутів PostgreSQL, Redis, обидві blob-квоти, селектори платформи та адресацію S3 у підписаній зашифрованій конфігурації.
Застосунок і worker отримують однакові OLLAMA_BASE_URL, OLLAMA_TIMEOUT, OLLAMA_LONG_OPERATION_TIMEOUT, OLLAMA_MAX_CONTEXT. Серверні точки приймають лише повні додатні десяткові числа; 300000ms, експонента, hex, значення поза межами або довгий тайм-аут менший за звичайний зупиняють запуск.
Helm обмежує TRUST_PROXY точним цілим від 0 до 16 і передає лише HTTP Pod. Залишайте 0 для прямого трафіку; задавайте точну кількість переходів проксі, ніколи необмежене true.
Сумісність схеми PostgreSQL точна. Застосунок і worker використовують Recreate; перед оновленням завершіть усі старі Pod, потім одна нова версія мігрує під advisory lock. Не запускайте змішані двійкові версії та не заявляйте оновлення без простою. Відкат означає відновлення перевіреного архіву в чисті PostgreSQL/S3 до запуску старої версії.
Активний team потребує worker.replicaCount >= 1. Для повного призупинення задайте нуль і застосунку, і worker. Нуль застосунку з додатним worker — режим дренування або відновлення, що продовжує чергу без вебтрафіку.
Помічник приватних резервних копій
Ці змінні читає сценарій deploy/private/libre-webui-backup, а не процес застосунку:
| Змінна | Типово | Призначення |
|---|---|---|
LIBRE_WEBUI_STACK_DIR | /opt/libre-webui | Каталог Compose |
LIBRE_WEBUI_BACKUP_DIR | /var/backups/libre-webui | Каталог копій |
LIBRE_WEBUI_BACKUP_RETENTION_DAYS | 14 | Дні зберігання |
LIBRE_WEBUI_CONTAINER_NAME | libre-webui | Ім’я контейнера |
LIBRE_WEBUI_BACKUP_KEY_DIR | /etc/libre-webui/backup-keys | Каталог ключів |
LIBRE_WEBUI_RESTORE_IMAGE | обов’язкова | Image для відновлення |
LIBRE_WEBUI_RESTORE_CONFIG_DIR | /etc/libre-webui/restored | Відновлена конфігурація |
Модуль systemd необов’язково читає /etc/libre-webui/backup.env, що має належати root і мати режим 0600; він не читає .env застосунку. Власний каталог копій також потребує точного ReadWritePaths= у додатковому файлі служби. Див. Приватне розгортання.
Автентифікація та безпека
Необов’язкова політика другого фактора позначається optional, а обов’язкова — required. Контакт Web Push типово mailto:admin@localhost; VAPID_PUBLIC_KEY, VAPID_PRIVATE_KEY, VAPID_SUBJECT налаштовують push. TURNSTILE_SITE_KEY, TURNSTILE_SECRET_KEY, TURNSTILE_EXPECTED_HOSTNAME налаштовують Turnstile.
Основні значення: ENABLE_SIGNUP типово false, JWT_SECRET, JWT_EXPIRES_IN типово 7d, ENCRYPTION_KEY, DEBUG_ENCRYPTION, ключі Turnstile, MFA_REQUIRED_MODE, WEBAUTHN_RP_ID, VAPID. ENABLE_SIGNUP=false усе одно дозволяє першого адміністратора. JWT прив’язаний до sid. AUDIT_RETENTION_DAYS типово 180. Режим TLS може бути require; тестовий рівень журналу — warn.
Загальний єдиний вхід OIDC
Стабільний ID користувача береться з claim sub, а групи типово з groups. OIDC_GROUP_CLAIM і OIDC_SYNC_GROUPS керують синхронізацією. OIDC_CALLBACK_URL, OIDC_ALLOWED_EMAIL_DOMAINS, OIDC_ADMIN_GROUPS задають callback, домени й адміністративні групи.
Потрібні OIDC_ISSUER_URL з <issuer>/.well-known/openid-configuration, OIDC_CLIENT_ID, OIDC_CLIENT_SECRET; OIDC_DISPLAY_NAME типово Single Sign-On, OIDC_SCOPES — openid profile email. Header Origin має збігатися.
WebSocket: CHAT_WS_MAX_PAYLOAD_BYTES — 10 MiB, CHAT_WS_MAX_MESSAGES_PER_MINUTE — 120, CHAT_WS_MAX_ACTIVE_GENERATIONS_PER_USER — 4, CHAT_WS_MAX_CONNECTIONS_PER_USER — 5, WEBSOCKET_TICKET_TTL_MS — 30000. Квиток одноразовий, походження перевіряється.
OAuth
GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET, GITHUB_CALLBACK_URL, HUGGINGFACE_CLIENT_ID, HUGGINGFACE_CLIENT_SECRET, HUGGINGFACE_CALLBACK_URL; резервні callback використовують BASE_URL.
Ollama
OLLAMA_BASE_URL типово http://localhost:11434, OLLAMA_TIMEOUT — 300000, OLLAMA_LONG_OPERATION_TIMEOUT — 900000, OLLAMA_MAX_CONTEXT — 32768.
Веб-пошук
SEARXNG_URL попередньо задає кінцеву точку; адміністратор усе одно окремо вмикає пошук.
Libre Claw
LIBRE_CLAW_BASE_URL типово http://127.0.0.1:8766, LIBRE_CLAW_TIMEOUT_MS — 30000.
Середовище Work
Домашній каталог Codex типово ~/.codex. Типовий образ — node:22.22-bookworm@sha256:2d178f2785b96dfbf62a416ca2e40f50e30150b4ff3320d706f0d96e90600eb3, а мережа й простір імен — libre-webui-work. Команда й сервер типово docker. У team обов’язкові AGENT_CLI_MODELS_ENABLED=false та CODEX_OAUTH_MODELS_ENABLED=false.
Тайм-аут команди типово 120000; інші типові значення містять 2, 2, 2, верхню межу пулу 100, а також 256, 2g, 3, 4173, 48, 500, 50000, 5Gi, 6080, 6081.
Повний перелік змінних Work: WORK_RUNTIME_IMAGE, WORK_DOCKER_COMMAND, WORK_COMMAND_TIMEOUT_MS, WORK_MAX_OUTPUT_CHARS, WORK_MAX_AGENT_ROUNDS, WORK_STATUS_BLURB_MODEL, WORK_MEMORY_LIMIT, WORK_CPU_LIMIT, WORK_PIDS_LIMIT, WORK_PREVIEW_PORT, WORK_PREVIEW_BIND, WORK_DOCKER_PUBLISHED_HOST, WORK_COMPUTER_SCREEN_PORT, WORK_COMPUTER_AUDIO_PORT, WORK_MAX_ACTIVE_RUNTIMES_GLOBAL, WORK_MAX_ACTIVE_RUNTIMES_PER_USER, WORK_MAX_TASKS_GLOBAL, WORK_MAX_TASKS_PER_USER, WORK_NETWORK_NAME, WORK_RUN_LEASE_WAIT_MS, WORK_RUNTIME_DNS, WORK_DOCKER_SOCKET, WORK_TERMINAL_MAX_SESSIONS_PER_TASK, WORK_TERMINAL_IDLE_TIMEOUT_MS, WORK_RUNTIME_IDLE_TIMEOUT_MS, WORK_HOST_WORKSPACES_ENABLED, WORK_HOST_WORKSPACE_ROOTS, WORK_RUNTIME_BACKEND, WORK_K8S_NAMESPACE, WORK_K8S_STORAGE_CLASS, WORK_K8S_WORKSPACE_SIZE, WORK_K8S_POD_READY_TIMEOUT_MS, WORK_K8S_POD_GONE_TIMEOUT_MS, AGENT_CLI_MODELS_ENABLED, TOOLS_ACCESS_MODE, STT_ACCESS_MODE, TTS_ACCESS_MODE, VOICE_MODE_ACCESS_MODE, VOICE_CLONING_ACCESS_MODE, TOOLS_PRIVATE_NETWORK_ALLOWLIST, AGENT_CLI_TIMEOUT_MS, CODEX_OAUTH_MODELS_ENABLED, CODEX_HOME.
Корені хоста розділяються :. Режими доступу можуть бути admins, admins, admins, all-users, all-users, all-users, all-users, all-users. Сервер може бути kubernetes, Codex читає auth.json. Agent CLI/Codex підтримуються лише в solo; team вимагає false. Папки монтуються в /workspace, а .ssh, .gnupg, .aws, .config відхиляються. Моделі claude і codex доступні лише адміністраторам.
Мережа Docker використовує WORK_NETWORK_NAME, DNS — WORK_RUNTIME_DNS, Kubernetes — work.networkPolicy.blockedEgressCidrs. Термінал використовує WORK_DOCKER_SOCKET, потім DOCKER_HOST (unix://, tcp://, docker-compose.socket-proxy.yml) і /var/run/docker.sock; ssh:// та DOCKER_TLS_VERIFY роблять термінал недоступним. Helm передає work.env. Бюджет інструментів — max(128, WORK_MAX_AGENT_ROUNDS × 8), завершення — needs_input, збережений вивід — приблизно 20 000 символів.
Compose використовує DOCKER_GID типово 0, DOCKER_SOCKET типово /var/run/docker.sock; team вмикається docker-compose.team.work.yml, Helm — work.enabled=true. WEBUI_BIND_ADDRESS типово 127.0.0.1, WEBUI_PORT — 8080. solo допускає нуль або одну репліку застосунку; повний team — кілька реплік із PostgreSQL, S3, PGVector і Redis, а зовнішній worker отримує ту саму image, StorageClass і ліміти work.env. У самому застосунку типове значення WORK_DOCKER_PUBLISHED_HOST збігається з WORK_PREVIEW_BIND, а у файлах Compose воно дорівнює host.docker.internal; розгортання Compose на нативному Docker Engine мають задати WORK_PREVIEW_BIND на доступний непублічний інтерфейс мосту.
Виявлення моделей провайдерів
| Змінна | Типово | Призначення |
|---|---|---|
PLUGIN_MODEL_DISCOVERY_TTL_MS | 21600000 (6 h) | Вік каталогу до автоматичного оновлення |
PLUGIN_MODEL_DISCOVERY_RETRY_MS | 600000 (10 min) | Мінімальна пауза між невдалими спробами |
PLUGIN_MODEL_DISCOVERY_REFRESH_DEADLINE_MS | 3000 | Очікування оновлення відповіддю списку |
Явне Оновити моделі завжди звертається до провайдера й ігнорує інтервал; запізнілий результат видно в наступному запиті.
Ключі плагінів провайдерів
OPENAI_API_KEY, ANTHROPIC_API_KEY, GROQ_API_KEY, GEMINI_API_KEY, MISTRAL_API_KEY, OPENROUTER_API_KEY, KIMI_API_KEY, GITHUB_API_KEY, HUGGINGFACE_API_KEY, ELEVENLABS_API_KEY, COMFYUI_API_KEY задають типові ключі відповідних провайдерів.
Ключ середовища використовується лише з маршрутом і автентифікацією незатіненого вбудованого визначення. Імпортоване, записуване з повторним вбудованим ID або власний маршрут адміністратора потребує ключа того самого користувача; Libre не підставляє секрет у ці маршрути чи виявлення. Довіра походить зі скомпільованого хешу маніфесту.
Ключ користувача прив’язаний до ефективного визначення, джерела, контракту й маршруту; після зміни його треба зберегти знову. Старі неприв’язані ключі приймаються й прив’язуються при першому використанні лише на точному вбудованому маршруті.
Відносний PLUGINS_DIR із джерел визначається від сервера, а пакетний запуск перетворює його на абсолютний від виклику. Для сумісності читаються backend/plugins та історичні місця. Перенесіть визначення в $DATA_DIR/plugins; звіт відновлення вважає старі місця зовнішнім станом і блокує копію лише тому. Каталоги й JSON мають бути фізичними звичайними записами; symlink не переходяться.
Фронтенд
| Змінна | Типово | Призначення |
|---|---|---|
VITE_API_BASE_URL | проксі розробки того самого походження або продакшн API | Базовий URL API |
VITE_WS_BASE_URL | визначається з API | Абсолютна основа ws:/wss: Chat і Work |
VITE_APP_VERSION | версія пакета з Vite | Показана версія застосунку |
VITE_DEMO_MODE | false | true вмикає демонстраційні імітації |
VITE_API_TIMEOUT | 300000 | Тайм-аут API у мілісекундах |
VITE_BACKEND_URL | http://localhost:3001 | Деякі помічники автентифікації |
VITE_DEBUG_VERBOSE | не задано | Докладні журнали розробки |
VITE_LOG_LEVEL | не задано | Рівень журналу фронтенду |
ELECTRON_BUILD | не задано | true вмикає поведінку Electron Vite |
VITE_WS_BASE_URL перевизначає всі резервні WebSocket для Chat і термінала Work. Може містити префікс reverse proxy, але має бути абсолютним ws:/wss: без облікових даних, query чи fragment. Без значення клієнти Electron file: використовують ws://localhost:3001; браузерні клієнти визначають основу спочатку з VITE_API_BASE_URL, потім з походження браузера. Vite проксіює середовище розробки до бекенда на порту 3001.
Сценарії обслуговування
| Змінна | Призначення |
|---|---|
CHANGELOG_AI | 0 вимикає чернетки журналу змін ШІ |
CHANGELOG_AI_MODEL | Модель Ollama для випуску й журналу |
CHANGELOG_AI_TIMEOUT_MS | Тайм-аут генерації в мілісекундах |
Приклад:
CHANGELOG_AI_MODEL=glm-5.2:cloud npm run changelog
CHANGELOG_AI=0 npm run release:minor
Приклад промислового середовища
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