Proměnné prostředí
Stránka uvádí podporované proměnné pro operátory, které čte aktuální backend, frontend a skripty údržby Libre WebUI. Interní kanárkové hodnoty pouze pro testy jsou záměrně vynechané.
Server backendu
| Proměnná | Výchozí | Účel |
|---|---|---|
NODE_ENV | development | Režim runtime |
PORT | 3001 ve vývoji, 8080 v produkci | HTTP port backendu |
TRUST_PROXY | nenastaveno (0 v Helm) | Přesný počet důvěryhodných hopů reverse proxy pro adresu klienta |
CORS_ORIGIN | místní vývojové originy | Povolené originy prohlížeče oddělené čárkou |
SERVE_FRONTEND | nenastaveno | Podávat sestavený frontend z backendu při true |
DOCKER_ENV | nenastaveno | Zapnout chování zaměřené na Docker při true |
DATA_DIR | backend/data; ~/.libre-webui v baleném CLI | Trvalý datový adresář |
PLATFORM_PREFLIGHT_TMP_DIR | backend/temp/preflight; cache uživatele v baleném CLI | Pracovní prostor pro soukromou kontrolní kopii DB/WAL; dimenzujte na databázi plus WAL |
PLUGIN_UPLOAD_TEMP_DIR | libre-webui-plugin-uploads v dočasném adresáři OS | Pracovní prostor pro probíhající nahrávání pluginů |
PLUGINS_DIR | $DATA_DIR/plugins | Zapisovatelný adresář nainstalovaných/vlastních pluginů |
BASE_URL | http://localhost:3001 | Základní URL pro výchozí callback OAuth |
LOG_LEVEL | info (warn v testech) | Úroveň protokolu backendu |
LOG_FORMAT | text | json přepne na strukturované jednořádkové protokoly s časem, korelačním ID a maskováním |
OTEL_EXPORTER_OTLP_ENDPOINT | nenastaveno | Volitelný export telemetrie OTLP/HTTP JSON; bez hodnoty nic neopouští proces |
OTEL_EXPORTER_OTLP_HEADERS | nenastaveno | Headery key=value oddělené čárkou posílané kolektoru OTLP |
OTEL_SERVICE_NAME | libre-webui | Atribut prostředku service.name exportované telemetrie |
WEBUI_HOST | loopback; 0.0.0.0 v Dockeru | Naslouchací adresa HTTP |
OPEN_BROWSER | true při podávání frontendu | Nastavte false, chcete-li zabránit automatickému otevření prohlížeče |
FULL_DOCUMENT_CONTEXT_MAX_TOKENS | 32000 | Ochrana tokenů pro kontext celého dokumentu na chat (1000-2000000) |
GALLERY_RETENTION_DAYS | nenastaveno (uchovat navždy) | Smazat média galerie starší než tento počet dní průchodem plánovače |
RECOVERY_DRILL_INTERVAL_HOURS | nenastaveno (cvičení vypnuto) | Automaticky spouštět ověřené cvičení obnovy každých N hodin (solo) |
RECOVERY_DRILL_HISTORY | 60 | Zachované položky historie cvičení obnovy |
Spuštění ze zdroje ukotvuje relativní DATA_DIR, PLUGINS_DIR a PLATFORM_PREFLIGHT_TMP_DIR v adresáři backendu bez ohledu na pracovní adresář shellu. Bez DATA_DIR nebo s DATA_DIR=./data tedy kořenové a backendové příkazy používají backend/data. Pro kompatibilitu DATA_DIR=./backend/data nadále volí backend/backend/data; měňte jen během záměrné zastavené zálohy a migrace. Nenastavený profil také používá backend/backend/data, pokud je jediným trvalým úložištěm. Pokud oba umístění obsahují stav a cesta není vybraná, spuštění se bezpečně odmítne místo odhadu, kopie či sloučení.
Spouštěče npx, globální npm a interaktivní Homebrew uchovávají data v ~/.libre-webui. Výslovná relativní DATA_DIR se přeloží z pracovního adresáře volajícího a před startem převede na absolutní. Relativní PLUGINS_DIR používá stejné pravidlo; bez hodnoty zůstávají zapisovatelné pluginy v $DATA_DIR/plugins. Pracovní kontrolní prostor je výchozí zapisovatelná cache mimo data: ~/Library/Caches/libre-webui na macOS, %LOCALAPPDATA%\libre-webui na Windows nebo ${XDG_CACHE_HOME:-~/.cache}/libre-webui jinde. Homebrew používá stejný domov a var/libre-webui/preflight. Pokud cache nestačí na databázi a WAL, nastavte PLATFORM_PREFLIGHT_TMP_DIR. Nasazení Docker a Helm používají absolutní /app/backend/data a /app/backend/temp/preflight na samostatných připojeních.
Základ platformy
Výchozí profil solo používá SQLite, místní šifrované bloby, šifrované vložené vektory, místní koordinaci a vložený trvalý worker. team používá PostgreSQL, soukromé bloby kompatibilní s S3, PGVector, Redis a externí worker. Konfigurace team se bezpečně odmítne, pokud nejsou vybrané všechny sdílené závislosti.
| Proměnná | Výchozí | Účel |
|---|---|---|
LIBRE_PLATFORM_MODE | solo | Vybrat souvislý profil solo nebo team |
DATABASE_BACKEND | sqlite | Vybrat sqlite nebo postgres |
DATABASE_URL | nenastaveno | URL připojení PostgreSQL, povinná s postgres |
DATABASE_SSL_MODE | verify-full | Zásada TLS PostgreSQL: disable, require nebo verify-full ověřující hostitele |
POSTGRES_MIGRATION_MODE | apply | Spustit kompatibilní migrace pod zámkem lídra nebo validate pro kontrolu jen pro čtení |
POSTGRES_POOL_MAX | 10 | Nejvýše připojení PostgreSQL na proces aplikace či workeru (1-100) |
POSTGRES_CONNECT_TIMEOUT_MS | 5000 | Timeout připojení PostgreSQL (1-60000 ms) |
POSTGRES_IDLE_TIMEOUT_MS | 30000 | Timeout nečinného připojení PostgreSQL (1-600000 ms) |
POSTGRES_STATEMENT_TIMEOUT_MS | 30000 | Timeout příkazu PostgreSQL (1-600000 ms) |
POSTGRES_MIGRATION_LOCK_TIMEOUT_MS | 60000 | Čekání na zámek lídra migrace (1-600000 ms) |
BLOB_STORE_BACKEND | local | Vybrat šifrované local úložiště nebo soukromé s3 |
VECTOR_STORE_BACKEND | embedded se SQLite | Vybrat šifrované vektory embedded nebo pgvector |
COORDINATION_BACKEND | local v solo; redis v team | Vybrat procesní nebo Redis koordinaci |
REDIS_URL | nenastaveno | URL redis: nebo rediss:, povinná s Redis |
REDIS_KEY_PREFIX | libre | Namespace 1–64 znaků pro koordinační klíče Libre |
REDIS_CONNECT_TIMEOUT_MS | 5000 | Počáteční timeout Redis, nejvýše 60 sekund |
JOB_WORKER_MODE | embedded v solo; external v team | Spouštět obsluhu v aplikaci nebo samostatném sdíleném workeru |
RESOURCE_LEASE_TTL_MS | 30000 | TTL pronájmu pro prostředky trvalých jobů (5000-300000) |
JOB_WORKER_CONCURRENCY | 4 | Trvalé joby spuštěné jedním workerem současně (1-32) |
CHAT_STREAM_EVENT_RETENTION_HOURS | 24 | Hodiny uchování událostí streamu před hodinovým čištěním |
PLATFORM_EVENT_RETENTION_DAYS | 30 | Dny uchování trvalé události |
PLATFORM_JOB_RETENTION_DAYS | 30 | Dny uchování dokončených jobů mimo životní cyklus |
LIBRE_SKIP_STARTUP_INTEGRITY_SCAN | nenastaveno | 1 přeskočí hloubkový sken starších šifer při příštím startu |
STORAGE_ENCRYPTION_KEYS | nenastaveno | Tajná mapa klíčů JSON; musí obsahovat legacy shodné s ENCRYPTION_KEY |
STORAGE_ENCRYPTION_ACTIVE_KEY_ID | nenastaveno | ID klíče pro nové místní bloby a vložené vektory |
BLOB_QUOTA_BYTES_PER_USER | 10737418240 | Trvalé maximum bajtů blobu otevřeného textu na vlastníka |
BLOB_QUOTA_RESERVATION_TTL_MS | 3600000 | Životnost opuštěné rezervace streamovací kvóty (min. 60000 ms) |
S3_BUCKET | nenastaveno | Soukromý bucket kompatibilní s S3, povinný s s3 |
S3_REGION | nenastaveno | Oblast S3, povinná s s3 |
S3_ENDPOINT | výchozí poskytovatele | Volitelný absolutní endpoint HTTP(S) pro MinIO nebo kompatibilní službu |
S3_ACCESS_KEY_ID | řetězec údajů SDK | Volitelný výslovný přístupový klíč S3 |
S3_SECRET_ACCESS_KEY | řetězec údajů SDK | Povinný při výslovném přístupovém klíči |
S3_SESSION_TOKEN | nenastaveno | Volitelný token s výslovnými údaji S3 |
S3_FORCE_PATH_STYLE | false | Nastavte true pro služby vyžadující adresování podle cesty |
S3_BLOB_PREFIX | libre/blobs | Neprůhledný prefix klíče bucketu vlastněný Libre |
Bez verzované mapy klíčů používají adaptéry existující ENCRYPTION_KEY jako ID legacy; pokud chybí i ten, čtou ${DATA_DIR}/.encryption_key bez vytváření či změny. Výslovná konfigurace a trvalý soubor se musí shodovat. Při zavedení mapy se starým klíčem jej zachovejte pod přesným ID legacy, dokud se všechny objekty a vektory nepřepíší nebo znovu nezabalí a neověří. Konflikty, nebezpečná oprávnění, symlinky a chybějící klíče se bezpečně odmítnou.
Redis slouží ke koordinaci, ne kanonické perzistenci. Samotný Redis nečiní SQLite, místní soubory ani procesní stav bezpečný napříč replikami. V režimu team používají limity HTTP, spojení chatu/WebSocket, práce STT/TTS/zvuku, importy a terminály Work sdílené přijetí přes Redis. Kapacity platí přes všechny repliky. Chyby vracejí 503 nebo ruší běžící operaci; Libre se nikdy nevrací k nezávislému místnímu čítači.
Viz Základ platformy.
Přibalený team Compose a Helm předávají všechny volby a hodnoty aplikaci i externímu workeru. V Helm jsou netajné volby pod env; pro spojení a klíče nastavte secrets.redisUrl, secrets.databaseUrl a secrets.storageEncryptionKeys. Limity poolu PostgreSQL jsou na proces: rezervujte alespoň (replicaCount + worker.replicaCount) * POSTGRES_POOL_MAX spojení a rezervu. U spravovaného/vzdáleného PostgreSQL zachovejte DATABASE_SSL_MODE=verify-full. Pouze přibalený Compose volí disable, protože listener je izolovaný. Team Helm vyžaduje stabilní secrets.jwtSecret sdílený všemi Pody; jinak by vznikl procesní podpisový materiál. S3 přijímá neprůhledné klíče a šifru; URL bucketu a poskytovatele se v metadatech neukládají.
Integrované archivy solo/team zachovávají pooly a timeouty PostgreSQL, timeout Redis, obě blobové kvóty, volby platformy a adresování S3 v podepsané a šifrované konfiguraci. Čistá obnova tak může publikovat provozní hodnoty bez otevřeného textu v metadatech.
Páry aplikace/workeru Compose a Helm dostávají stejné vyřešené OLLAMA_BASE_URL, OLLAMA_TIMEOUT, OLLAMA_LONG_OPERATION_TIMEOUT a OLLAMA_MAX_CONTEXT. Volání pro vkládání, trvalé chaty a Work běží ve workeru, proto se hodnoty nesmí lišit. Serverové vstupy interpretují číselné hodnoty jako úplná kladná celá čísla základu 10 před vytvořením stavu. Částečné hodnoty jako 300000ms, exponent/hex, hodnoty mimo rozsah a dlouhý timeout pod standardním způsobí selhání startu.
Helm omezuje TRUST_PROXY na přesné celé číslo 0–16 a posílá jej jen HTTP Podům. Pro přímý provoz ponechte 0. Pro řetězec ingress/load balancer nastavte přesný pevný počet; nepoužívejte neomezené true. Chybný počet seskupí klienty pod proxy nebo důvěřuje adrese od klienta.
Kompatibilita schématu PostgreSQL vyžaduje přesnou verzi. Aplikace a worker Helm používají Recreate; před upgradem vyprázdněte a ukončete všechny staré Pody a nechte jeden nový proces migrovat pod poradním zámkem. Nespouštějte smíšené binární verze ani netvrďte nulový výpadek. Rollback obnoví ověřený archiv do čistých cílů PostgreSQL/S3 před spuštěním odpovídající starší binárky.
Aktivní team aplikace vyžaduje worker.replicaCount >= 1; Helm odmítne živou aplikaci bez trvalého workeru. Pro úplné pozastavení nastavte aplikaci i worker na nulu. Aplikace na nule s kladným workerem je záměrný režim vyprázdnění/obnovy, který zpracovává frontu bez webového provozu.
Pomocník soukromých záloh
Proměnné konfigurují deploy/private/libre-webui-backup a čte je skript údržby, nikoli proces aplikace:
| Proměnná | Výchozí | Účel |
|---|---|---|
LIBRE_WEBUI_STACK_DIR | /opt/libre-webui | Adresář se soukromým souborem Compose |
LIBRE_WEBUI_BACKUP_DIR | /var/backups/libre-webui | Chráněný adresář záloh a souboru zámku |
LIBRE_WEBUI_BACKUP_RETENTION_DAYS | 14 | Stáří, po kterém se dokončené zálohy smažou |
LIBRE_WEBUI_CONTAINER_NAME | libre-webui | Nasazený kontejner aplikace ke kontrole |
LIBRE_WEBUI_BACKUP_KEY_DIR | /etc/libre-webui/backup-keys | Soukromý adresář klíčů šifrování a podpisu archivu |
LIBRE_WEBUI_RESTORE_IMAGE | povinné pro obnovu | Zkontrolované neměnné ID nebo digest image Libre |
LIBRE_WEBUI_RESTORE_CONFIG_DIR | cesta na svazek pod /etc/libre-webui/restored | Nový adresář obnovené konfigurace |
Jednotka systemd načítá přepsání z volitelného souboru /etc/libre-webui/backup.env vlastněného rootem. Nastavte režim 0600. Adresář stacku, uchování, název kontejneru a adresář klíčů lze nastavit přímo. Sandbox systému souborů povoluje zápis jen pod výchozím adresářem. Vlastní LIBRE_WEBUI_BACKUP_DIR vyžaduje přesně předem vytvořený adresář v drop-in ReadWritePaths=; viz
Soukromé vzdálené nasazení.
Ověřování a zabezpečení
| Proměnná | Výchozí | Účel |
|---|---|---|
ENABLE_SIGNUP | false | Povolit registraci po prvním místním správci |
JWT_SECRET | vytvořená/záložní ve vývoji | Tajemství podpisu JWT; v produkci nastavte výslovně |
JWT_EXPIRES_IN | 7d | Životnost tokenu relace |
ENCRYPTION_KEY | vytvořen automaticky | Hex klíč o 64 znacích pro šifrované hodnoty |
DEBUG_ENCRYPTION | nenastaveno | Při nastavení logovat ladění šifrování |
TURNSTILE_SITE_KEY | nenastaveno | Klíč webu Turnstile pro přihlášení |
TURNSTILE_SECRET_KEY | nenastaveno | Tajný klíč Turnstile pro ověření backendem |
TURNSTILE_EXPECTED_HOSTNAME | hostitel z BASE_URL | Povinný hostitel v odpovědi Cloudflare |
MFA_REQUIRED_MODE | nenastaveno (optional) | Připnout dvoufaktorovou zásadu k optional nebo required |
WEBAUTHN_RP_ID | hostitel požadavku | Pevné relying-party ID pro passkeys za více hostiteli |
VAPID_PUBLIC_KEY | vytvořen a uložen šifrovaně | Připnout veřejný klíč VAPID Web Push |
VAPID_PRIVATE_KEY | vytvořen a uložen šifrovaně | Připnout soukromý klíč VAPID Web Push |
VAPID_SUBJECT | mailto:admin@localhost | Kontaktní claim v podepsaných oprávněních Web Push |
Turnstile se zapne jen při přítomnosti obou klíčů.
ENABLE_SIGNUP=false stále dovolí prvního místního správce v prázdné databázi a poté blokuje další účty. Vzdáleně dostupnou startovací trasu před prvním spuštěním chraňte vnější hranicí identity.
Každý JWT je svázaný se serverovou relací (claim sid), takže odhlášení nebo odvolání v Nastavení → Relace zneplatní token na všech replikách a zavře aktivní WebSocket. Uchování auditu lze konfigurovat:
| Proměnná | Výchozí | Účel |
|---|---|---|
AUDIT_RETENTION_DAYS | 180 | Dny uchování řádků bezpečnostního auditního protokolu |
Obecné jednotné přihlášení OIDC
K přihlášení lze použít každého poskytovatele OpenID Connect s dokumentem zjišťování. Tok používá PKCE (S256), stav CSRF a nonce ověřené v ID tokenu s kontrolou podpisu. Identity se propojují pomocí stabilního claimu sub.
| Proměnná | Výchozí | Účel |
|---|---|---|
OIDC_ISSUER_URL | nenastaveno | Základní URL vydavatele; dokument zjišťování se načítá z <issuer>/.well-known/openid-configuration |
OIDC_CLIENT_ID | nenastaveno | ID klienta OAuth zaregistrované u poskytovatele |
OIDC_CLIENT_SECRET | nenastaveno | Tajný klíč klienta OAuth |
OIDC_DISPLAY_NAME | Single Sign-On | Popisek zobrazený na přihlašovacím tlačítku |
OIDC_SCOPES | openid profile email | Požadované rozsahy |
OIDC_CALLBACK_URL | BASE_URL + callback trasa OIDC | URI přesměrování zaregistrované u poskytovatele |
OIDC_ALLOWED_EMAIL_DOMAINS | nenastaveno | Seznam oddělený čárkami; při nastavení je vyžadován ověřený e-mail v jedné z uvedených domén |
OIDC_GROUP_CLAIM | groups | Claim ID tokenu obsahující názvy skupin |
OIDC_ADMIN_GROUPS | nenastaveno | Seznam oddělený čárkami; při nastavení se role správce při každém přihlášení řídí členstvím uvedeným v claimu |
OIDC_SYNC_GROUPS | false | Hodnota true při každém přihlášení sladí členství ve skupinách Libre se skupinovým claimem |
OIDC se zapne jen tehdy, když jsou současně zadané URL vydavatele, ID klienta a tajný klíč klienta. E-mail, který už používá nepropojený místní účet, bude odmítnut namísto tichého sloučení a vytváření účtů se stále řídí nastavením ENABLE_SIGNUP.
Přijímání připojení Chat WebSocket lze vyladit bez oslabení ověřování:
| Proměnná | Výchozí | Účel |
|---|---|---|
CHAT_WS_MAX_PAYLOAD_BYTES | 10 MiB | Největší přijatelná velikost zprávy WebSocket |
CHAT_WS_MAX_MESSAGES_PER_MINUTE | 120 | Limit zpráv WebSocket za jedno připojení |
CHAT_WS_MAX_ACTIVE_GENERATIONS_PER_USER | 4 | Počet generování poskytovatele povolených pro jeden účet |
CHAT_WS_MAX_CONNECTIONS_PER_USER | 5 | Souběžné ověřené sockety na účet |
WEBSOCKET_TICKET_TTL_MS | 30000 | Životnost jednorázového lístku Chat/Work; nejvýše 60 sekund |
Prohlížeč vymění svůj běžný header Authorization za neprůhledný lístek a do URL upgradu WebSocket vloží pouze tuto krátkodobou hodnotu. Lístky jsou jednorázové, svázané s protokolem i relací a ukládají se pouze jako hashe. Trvalé tokeny relace se tak nedostanou do protokolů cílů požadavků reverse proxy.
Když je nakonfigurovaná proměnná CORS_ORIGIN nebo BASE_URL, musí se header Origin upgradu z prohlížeče shodovat s jedním z nakonfigurovaných originů. U vzdáleně dostupného nasazení nastavte alespoň jednu z nich; pokud není nastavená žádná, filtr Origin zůstává kvůli kompatibilitě s místním vývojem benevolentní.
Upgrady bez originu jsou záměrně podporované pro Electron a neprohlížečské klienty, kde není k dispozici kontrola Origin prováděná prohlížečem. Stále potřebují platný jednorázový lístek a podléhají stejným kontrolám aktuálního účtu, přístupu k Work a úloh. Považujte lístek za hranici ověřování a přístup neprohlížečských klientů omezte běžnými mechanismy TLS, firewallu a reverse proxy daného nasazení.
OAuth
| Proměnná | Účel |
|---|---|
GITHUB_CLIENT_ID | ID klienta GitHub OAuth |
GITHUB_CLIENT_SECRET | Tajný klíč klienta GitHub OAuth |
GITHUB_CALLBACK_URL | Přepsání callback URL GitHub |
HUGGINGFACE_CLIENT_ID | ID klienta Hugging Face OAuth |
HUGGINGFACE_CLIENT_SECRET | Tajný klíč klienta Hugging Face OAuth |
HUGGINGFACE_CALLBACK_URL | Přepsání callback URL Hugging Face |
Pokud callback URL nejsou nastavené, Libre WebUI vytvoří výchozí hodnoty z BASE_URL.
Ollama
| Proměnná | Výchozí | Účel |
|---|---|---|
OLLAMA_BASE_URL | http://localhost:11434 | Základní URL API Ollama |
OLLAMA_TIMEOUT | 300000 | Standardní timeout požadavku Ollama (1 000–3 600 000 ms) |
OLLAMA_LONG_OPERATION_TIMEOUT | 900000 | Timeout dlouhé operace (1 000–3 600 000 ms, ne kratší než OLLAMA_TIMEOUT) |
OLLAMA_MAX_CONTEXT | 32768 | Největší automaticky přijatý kontext modelu (128–2 097 152 tokenů) |
Vyhledávání na webu
| Proměnná | Výchozí | Účel |
|---|---|---|
SEARXNG_URL | nenastaveno | Výchozí endpoint SearXNG pro nastavení vyhledávání na webu; správce jej přesto musí zapnout v Nastavení > Vyhledávání |
Libre Claw
| Proměnná | Výchozí | Účel |
|---|---|---|
LIBRE_CLAW_BASE_URL | http://127.0.0.1:8766 | Volitelná URL démona Libre Claw |
LIBRE_CLAW_TIMEOUT_MS | 30000 | Timeout požadavku HTTP Libre Claw |
Runtime Work
Tyto proměnné nastavují spouštění Work na počítači nebo v clusteru Kubernetes, kde běží backend Libre WebUI. Výchozím runtimem je Docker; chart Helm vybere Kubernetes při work.enabled=true.
| Proměnná | Výchozí | Účel |
|---|---|---|
WORK_RUNTIME_IMAGE | node:22.22-bookworm@sha256:2d178f2785b96dfbf62a416ca2e40f50e30150b4ff3320d706f0d96e90600eb3 | Připnutý image používaný pro sandboxy Work |
WORK_DOCKER_COMMAND | docker | Spustitelný soubor CLI backendu Docker dostupný procesu |
WORK_COMMAND_TIMEOUT_MS | 120000 | Výchozí timeout; nástroj může požadovat až 600000 ms |
WORK_MAX_OUTPUT_CHARS | 50000 | Limit zachyceného stdout/stderr použitý samostatně na každý stream |
WORK_MAX_AGENT_ROUNDS | 48 | Rozpočet kol modelu a nástrojů pro jeden běh, nezávislý na poskytovateli |
WORK_STATUS_BLURB_MODEL | 1 | Nastavením 0 přeskočit jeden požadavek modelu, který po běhu zapíše stavový řádek agenta v postranním panelu |
WORK_MEMORY_LIMIT | 2g | Limit paměti předaný každému kontejneru Work |
WORK_CPU_LIMIT | 2 | Limit CPU předaný každému kontejneru Work |
WORK_PIDS_LIMIT | 256 | Limit procesů předaný každému kontejneru Work |
WORK_PREVIEW_PORT | 4173 | Port, který musí server náhledu používat uvnitř kontejneru úlohy |
WORK_PREVIEW_BIND | 127.0.0.1 | Rozhraní hostitele, na kterém se publikuje port náhledu úlohy; nasazení Compose na nativním Docker Engine musí použít dosažitelné neveřejné rozhraní mostu |
WORK_DOCKER_PUBLISHED_HOST | výchozí v aplikaci: stejné jako WORK_PREVIEW_BIND; výchozí v Compose: host.docker.internal | Hostitel/IP viditelný backendem pro porty náhledu, obrazovky a zvuku publikované Dockerem |
WORK_COMPUTER_SCREEN_PORT | 6080 | Port kontejneru pro most obrazovky Work Computer (websockify) v sandboxech s GUI |
WORK_COMPUTER_AUDIO_PORT | 6081 | Port kontejneru pro zvukový most Work Computer (websockify → monitor PulseAudio) v sandboxech s GUI |
WORK_MAX_ACTIVE_RUNTIMES_GLOBAL | 3 | Souběžné úlohy využívající runtime v celé instanci |
WORK_MAX_ACTIVE_RUNTIMES_PER_USER | 2 | Souběžné úlohy využívající runtime pro jednoho uživatele |
WORK_MAX_TASKS_GLOBAL | 500 | Nejvyšší počet trvale uložených úloh Work v celé instanci |
WORK_MAX_TASKS_PER_USER | 100 | Nejvyšší počet trvale uložených úloh Work pro jednoho správce |
WORK_NETWORK_NAME | libre-webui-work | Spravovaná síť typu bridge pro sandboxy síťových úloh |
WORK_RUN_LEASE_WAIT_MS | 60000 | Jak dlouho běh čeká na sdílený pronájem runtimu úlohy, než nahlásí konflikt repliky (režim team) |
WORK_RUNTIME_DNS | nenastaveno | IP resolverů oddělené čárkou, které se vynutí pro síťové úlohy |
WORK_DOCKER_SOCKET | DOCKER_HOST, pokud je unix:// nebo tcp://, jinak /var/run/docker.sock | Endpoint Docker Engine pro terminály a diagnostiku |
WORK_TERMINAL_MAX_SESSIONS_PER_TASK | 2 | Souběžné terminály prohlížeče připojené k jedné úloze |
WORK_TERMINAL_IDLE_TIMEOUT_MS | 900000 | Doba nečinnosti před zavřením terminálové relace |
WORK_RUNTIME_IDLE_TIMEOUT_MS | 0 (vypnuto) | Zastavit sandbox po této době nečinnosti (včetně náhledů) |
WORK_HOST_WORKSPACES_ENABLED | false | Povolit úloze použít složku hostitele namísto svazku |
WORK_HOST_WORKSPACE_ROOTS | domovský adresář uživatele serveru | Kořeny oddělené :, uvnitř kterých musí být pracovní prostor hostitele |
WORK_RUNTIME_BACKEND | docker | Backend sandboxu: docker nebo kubernetes |
WORK_K8S_NAMESPACE | libre-webui-work | Namespace obsahující Pody sandboxů Kubernetes a PVC |
WORK_K8S_STORAGE_CLASS | výchozí hodnota clusteru | StorageClass pro PVC pracovních prostorů |
WORK_K8S_WORKSPACE_SIZE | 5Gi | Velikost PVC pracovního prostoru na úlohu (skutečná disková kvóta) |
WORK_K8S_POD_READY_TIMEOUT_MS | 900000 | Čekání, než Pod sandboxu dosáhne stavu Running (zahrnuje stahování) |
WORK_K8S_POD_GONE_TIMEOUT_MS | 60000 | Čekání, než odstraněný Pod sandboxu zmizí |
AGENT_CLI_MODELS_ENABLED | nenastaveno (přepínač správce, vypnuto) | Připnout funkci Agenti jako zapnutou/vypnutou; bez hodnoty ji řídí přepínač správce ve Správě uživatelů (výchozí vypnuto) |
TOOLS_ACCESS_MODE | nenastaveno (přepínač správce, jen správci) | Připnout nástroje chatu na admins nebo all-users a uzamknout přepínač ve Správě uživatelů |
STT_ACCESS_MODE | nenastaveno (přepínač správce, všichni uživatelé) | Připnout převod řeči na text na admins nebo all-users a uzamknout přepínač ve Správě uživatelů |
TTS_ACCESS_MODE | nenastaveno (přepínač správce, všichni uživatelé) | Připnout převod textu na řeč na admins nebo all-users a uzamknout přepínač ve Správě uživatelů |
VOICE_MODE_ACCESS_MODE | nenastaveno (přepínač správce, všichni uživatelé) | Připnout hlasový režim bez použití rukou na admins nebo all-users a uzamknout přepínač ve Správě uživatelů |
VOICE_CLONING_ACCESS_MODE | nenastaveno (přepínač správce, všichni uživatelé) | Připnout klonování hlasu na admins nebo all-users a uzamknout přepínač ve Správě uživatelů |
TOOLS_PRIVATE_NETWORK_ALLOWLIST | nenastaveno | Přesné názvy hostitelů, na jejichž soukromé adresy se smějí překládat servery nástrojů a cíle webhooků (oddělené čárkou); připnuté |
AGENT_CLI_TIMEOUT_MS | 600000 | Doba, po kterou smí běžet CLI agenta, než je ukončeno |
CODEX_OAUTH_MODELS_ENABLED | true | Nabízet správcům poskytovatele Codex (ChatGPT) |
CODEX_HOME | ~/.codex | Místo, odkud se čtou přihlašovací údaje CLI Codex (auth.json) |
Binární soubory CLI agentů a přihlašovací údaje Codex OAuth jsou místní pro daný uzel. Podporují se pouze v procesu solo, kde zjišťování i spouštění vidí stejný souborový systém a prostředí. Režim team spouští trvalé chatové joby v externím workeru, a proto vyžaduje AGENT_CLI_MODELS_ENABLED=false i CODEX_OAUTH_MODELS_ENABLED=false; spuštění odmítne jakoukoli jinou hodnotu, místo aby inzerovalo poskytovatele, který může existovat jen na jedné replice aplikace. Použijte Ollama nebo plugin poskytovatele, jehož přihlašovací údaje a směrování jsou uložené ve sdíleném PostgreSQL nebo předané shodně každé aplikaci i workeru.
Na backendu Docker pracovní prostor hostitele připojí skutečný adresář do /workspace, takže úloha může tyto soubory přímo číst a zapisovat namísto práce ve vlastním svazku Docker. Kubernetes pracovní prostory se složkou hostitele odmítá. Jde o záměrné oslabení sandboxu Docker: ponechte WORK_HOST_WORKSPACES_ENABLED vypnuté, pokud tuto možnost nechcete, a hodnotu WORK_HOST_WORKSPACE_ROOTS nastavte co nejužší. Požadované cesty se před kontrolou vůči kořenům vyhodnotí přes symbolické odkazy a složky jako .ssh, .gnupg, .aws a .config jsou bezpodmínečně odmítnuté.
Modely CLI agentů zpřístupňují programovací agenty už nainstalované na serveru (claude, codex) jako volitelné chatové modely, takže agent s předplatným může odpovídat bez klíče API. Vidí je jen správci, CLI běží jako uživatel serveru Libre WebUI a dědí přihlašovací údaje agentů tohoto uživatele — zacházejte s tím stejně jako s udělením shellového přístupu těmto agentům.
V Dockeru se síťové úlohy Work připojují ke spravovanému bridge WORK_NETWORK_NAME, vytvořenému s vypnutou komunikací mezi kontejnery, aby žádný sandbox nemohl oslovit jiný sandbox ani vlastní kontejnery nasazení. WORK_RUNTIME_DNS je podporovaný bod zásady odchozího provozu Dockeru: nastavte jej na filtrovací resolver, který uplatňuje seznamy povolených a zakázaných názvů. Položky, které nejsou adresami IPv4/IPv6, se odmítnou a zaprotokolují. Filtrování DNS neomezuje odchozí provoz přímo na IP; pokud to nasazení vyžaduje, přidejte pravidla firewallu hostitele. Backend Kubernetes místo toho používá výchozí NetworkPolicies typu default-deny z chartu a hodnoty work.networkPolicy.blockedEgressCidrs.
V Dockeru komunikují interaktivní terminál a systémová diagnostika přímo s API Docker Engine. Při nastavení používají WORK_DOCKER_SOCKET, jinak DOCKER_HOST — buď socket unix://, nebo endpoint tcp:// přes prosté HTTP, například socket proxy (viz docker-compose.socket-proxy.yml) — a jinak /var/run/docker.sock. Hodnota DOCKER_HOST, se kterou tento klient neumí komunikovat (ssh:// nebo tcp:// s nastaveným DOCKER_TLS_VERIFY), označí terminál a diagnostiku Dockeru za nedostupné; zbytek Work nadále běží přes CLI Docker, které si s těmito endpointy poradí samo. V Kubernetes používá terminál dílčí prostředek exec Podu a endpoint Dockeru nepoužívá.
Work čte tyto hodnoty při spuštění backendu. Port náhledu je interní pro kontejner úlohy; Libre WebUI jej publikuje na dynamicky přiděleném portu loopback namísto přímého vystavení této hodnoty na všech rozhraních hostitele.
Image runtimu ponechte připnutý na prověřenou verzi nebo digest. Zvýšení souběžnosti či limitů prostředků zvětšuje kapacitu runtimu, kterou může spotřebovat jeden nebo více autonomních běhů. WORK_MAX_AGENT_ROUNDS platí stejně pro Ollama i běhy založené na pluginech; pro pluginy neexistuje nižší zvláštní omezení. Bezpečnostní rozpočet volání nástrojů je max(128, WORK_MAX_AGENT_ROUNDS × 8). Když běh vyčerpá rozpočet kol, Work požádá model o závěrečné předání bez nástrojů a skončí v terminálním stavu needs_input, místo aby vrátil surovou chybu limitu kol nebo tvrdil, že úspěšně skončil. Následný běh pokračuje ve stejném trvalém pracovním prostoru. Trvale uložený výstup nástrojů má samostatný limit přibližně 20,000 zdrojových znaků plus značku zkrácení.
Tyto proměnné ladí runtime Work, který už je dostupný. Nasazení Compose s jednou instancí z repozitáře jej zapínají ve výchozím nastavení: image obsahuje CLI Docker a tyto soubory Compose připojí socket Docker hostitele. Toto zapojení řídí dvě proměnné na úrovni Compose:
| Proměnná | Výchozí | Účel |
|---|---|---|
DOCKER_GID | 0 | ID skupiny socketu Docker hostitele přidané uživateli kontejneru |
DOCKER_SOCKET | /var/run/docker.sock | Cesta hostitele k připojovanému socketu Docker |
DOCKER_GID musí být skupina socketu tak, jak je vidět uvnitř kontejneru; hostitel s macOS hlásí jinou hodnotu. Základ Compose pro režim team nepřipojuje žádný socket a Work s backendem Docker zůstává nedostupný, dokud nepřidáte docker-compose.team.work.yml. Tento produkční overlay předá aplikaci i workeru stejný interní filtrovaný endpoint proxy, nikdy připojený socket ani jeho skupinu. Proxy povoluje jen ty části API Docker, které runtime používá, vytvoření kontejneru ale nadále představuje oprávnění k ovládání hostitele Docker; pro silnější hranici použijte vyhrazeného nebo rootless démona Work. Chart Helm nikdy nepřipojuje socket runtimu uzlu. Jeho nativní backend Work s Pody/PVC zapnete pomocí work.enabled=true.
Profil solo musí zůstat na nule nebo jedné replice aplikace, protože používá SQLite, místní soubory a koordinaci v rámci procesu. Chart Helm přijímá nulu pro záměrné pozastavení a odmítá větší počet replik solo i automatické škálování solo. Úplný profil team může používat více replik aplikace a externí worker, protože sdílený stav spravují PostgreSQL, S3, PGVector a Redis. Pody sandboxů Work se škálují nezávisle v obou profilech; v režimu team dostává externí worker stejný image runtimu Kubernetes, StorageClass a limity work.env jako Pody aplikace.
Soubory Compose v repozitáři přijímají také WEBUI_BIND_ADDRESS (výchozí 127.0.0.1) a WEBUI_PORT (výchozí 8080). Výchozí loopback ponechte, pokud port nemusí být dostupný důvěryhodné síti LAN nebo reverse proxy hostitele.
Zjišťování modelů poskytovatelů
Chybějící nebo zastaralý katalog modelů poskytovatele se automaticky znovu zjistí, takže nové načtení odráží modely, které poskytovatel právě nabízí. Tento cyklus řídí následující proměnné:
| Proměnná | Výchozí | Účel |
|---|---|---|
PLUGIN_MODEL_DISCOVERY_TTL_MS | 21600000 (6 h) | Stáří, při kterém se uložený katalog obnoví při příštím načtení seznamu pluginů |
PLUGIN_MODEL_DISCOVERY_RETRY_MS | 600000 (10 min) | Nejkratší odstup mezi pokusy, aby se chybující poskytovatel nekontroloval příliš často |
PLUGIN_MODEL_DISCOVERY_REFRESH_DEADLINE_MS | 3000 | Jak dlouho odpověď se seznamem pluginů čeká na obnovení |
Obnovení, které překročí časový limit, se přesto dokončí a jeho výsledek se použije při příštím požadavku. Výslovná volba Obnovit modely vždy kontaktuje poskytovatele a interval ignoruje.
Klíče pluginů poskytovatelů
Pluginy poskytovatelů mohou používat klíče prostředí jako výchozí hodnoty pro celé nasazení:
| Proměnná | Poskytovatel |
|---|---|
OPENAI_API_KEY | OpenAI a 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 od Moonshot AI |
GITHUB_API_KEY | Modely GitHub |
HUGGINGFACE_API_KEY | API Hugging Face tam, kde jsou nakonfigurovaná |
ELEVENLABS_API_KEY | ElevenLabs TTS |
COMFYUI_API_KEY | Nasazení ComfyUI vyžadující klíč API |
Pokud jsou vhodnější klíče jednotlivých uživatelů, mohou si uživatelé uložit přihlašovací údaje poskytovatelů také v uživatelském rozhraní. Klíče prostředí se používají pouze s projekcí směrování a ověřování nezastíněné přibalené definice. Importované definice, zapisovatelné definice znovu používající přibalené ID a vlastní trasy uložené správcem vyžadují přihlašovací údaj uložený daným účtem. Libre WebUI k těmto trasám nepřipojí klíč prostředí ani jej nezpřístupní prostřednictvím kontrol zjišťování a dostupnosti. Důvěra vychází ze zkompilovaného hashe každého dodaného manifestu, takže rozložení kontejnerů, kde starší a přibalený adresář pluginů sdílejí cestu, zůstávají podporovaná, aniž by se změněný manifest považoval za přibalený.
Klíče uložené uživatelem jsou svázané s výslednou definicí poskytovatele, zdrojem, smlouvou ověřování a hodnotami směrování. Po změně tohoto cíle správcem musí uživatel klíč uložit znovu. Nesvázané klíče z doby před upgradem se přijmou a při prvním použití svážou pouze pro přesnou dodanou definici využívající její přibalenou trasu.
Při spuštění ze zdroje se relativní hodnoty PLUGINS_DIR vyhodnocují z adresáře backendu. Balený spouštěč naopak před startem backendu převede výslovně nakonfigurovanou relativní hodnotu na absolutní cestu vůči volajícímu. Kvůli kompatibilitě čte Libre také deterministický adresář backend/plugins a historická umístění vybraná předchozími konfiguracemi. Přesuňte tyto definice do $DATA_DIR/plugins; obnova hlásí starší cesty jako externí stav a blokuje snímek pouze svazku, dokud tam vlastní definice zůstávají. Adresáře pluginů a definice JSON musí být fyzické běžné položky — Libre nenásleduje symbolické odkazy pluginů.
Frontend
| Proměnná | Výchozí | Účel |
|---|---|---|
VITE_API_BASE_URL | vývojová proxy stejného původu nebo produkční API | Základní URL API frontendu |
VITE_WS_BASE_URL | odvozeno z URL API | Absolutní základ ws:/wss: pro sockety Chat a Work |
VITE_APP_VERSION | verze balíčku vložená konfigurací Vite | Zobrazená verze aplikace |
VITE_DEMO_MODE | false | Při true zapne mocky demonstračního režimu |
VITE_API_TIMEOUT | 300000 | Timeout API frontendu v milisekundách |
VITE_BACKEND_URL | http://localhost:3001 | Používají některé pomocné komponenty ověřování |
VITE_DEBUG_VERBOSE | nenastaveno | Zapne podrobné ladicí protokoly frontendu ve vývoji |
VITE_LOG_LEVEL | nenastaveno | Přepíše úroveň protokolu frontendu |
ELECTRON_BUILD | nenastaveno | Při true zapne chování Vite specifické pro Electron |
VITE_WS_BASE_URL přepisuje všechny záložní hodnoty WebSocket pro Chat i terminál Work. Může obsahovat prefix cesty reverse proxy, musí však jít o absolutní URL ws: nebo wss: bez přihlašovacích údajů, dotazu či fragmentu. Pokud není nastavená, klienti Electron s file: používají ws://localhost:3001; klienti v prohlížeči odvodí základ z VITE_API_BASE_URL a následně z originu prohlížeče. Vite přesměrovává vývojový origin na backend na portu 3001.
Skripty údržby
| Proměnná | Účel |
|---|---|
CHANGELOG_AI | Nastavením na 0 vypnout koncepty přehledu změn s pomocí AI |
CHANGELOG_AI_MODEL | Model Ollama pro generování vydání/přehledu změn |
CHANGELOG_AI_TIMEOUT_MS | Timeout generování přehledu změn pomocí AI v milisekundách |
Příklad:
CHANGELOG_AI_MODEL=glm-5.2:cloud npm run changelog
CHANGELOG_AI=0 npm run release:minor
Produkční příklad
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