环境变量
本页列出当前 Libre WebUI 后端、前端和维护脚本读取的、面向操作员的受支持环境变量。有意省略仅供内部测试的探针。
后端服务器
| 变量 | 默认值 | 用途 |
|---|---|---|
NODE_ENV | development | 运行模式 |
PORT | 开发环境 3001，生产环境 8080 | 后端 HTTP 端口 |
TRUST_PROXY | 未设置（Helm 中为 0） | 用于推导客户端地址的确切可信反向代理跳数 |
CORS_ORIGIN | 本地开发源 | 允许的浏览器源，逗号分隔 |
SERVE_FRONTEND | 未设置 | 为 true 时由后端提供构建后的前端 |
DOCKER_ENV | 未设置 | 为 true 时启用 Docker 专用行为 |
DATA_DIR | backend/data；打包 CLI 中为 ~/.libre-webui | 持久数据目录 |
PLATFORM_PREFLIGHT_TMP_DIR | backend/temp/preflight；打包 CLI 使用用户缓存 | 私有 DB/WAL 启动检查副本的临时空间；容量应覆盖数据库和 WAL |
PLUGIN_UPLOAD_TEMP_DIR | 操作系统临时目录下的 libre-webui-plugin-uploads | 正在上传插件的临时空间 |
PLUGINS_DIR | $DATA_DIR/plugins | 已安装/自定义插件的可写目录 |
BASE_URL | http://localhost:3001 | OAuth 回调默认使用的基础 URL |
LOG_LEVEL | info（测试中为 warn） | 后端日志级别 |
LOG_FORMAT | text | json 切换为带时间戳、关联 ID 和脱敏的单行结构化日志 |
OTEL_EXPORTER_OTLP_ENDPOINT | 未设置 | 可选 OTLP/HTTP JSON 遥测导出；未设置时遥测不离开进程 |
OTEL_EXPORTER_OTLP_HEADERS | 未设置 | 发往 OTLP 收集器的逗号分隔 key=value 标头（例如身份验证） |
OTEL_SERVICE_NAME | libre-webui | 导出遥测中的 service.name 资源属性 |
WEBUI_HOST | 环回；Docker 中为 0.0.0.0 | 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 锚定到后端目录，不受 shell 当前目录影响。未设置 DATA_DIR 或使用新源码示例 DATA_DIR=./data 时，根目录和后端工作区命令都使用 backend/data。为兼容性，已有 DATA_DIR=./backend/data 配置继续选择 backend/backend/data；只能在停止服务、主动备份和迁移时更改。未设置的源码配置在 backend/backend/data 是唯一已有持久存储时也继续使用它。若两个位置都有状态且未选择路径，启动会安全失败，而不会猜测、复制或合并。
npx、全局 npm 和交互式 Homebrew 启动器则将数据保存在 ~/.libre-webui。显式相对 DATA_DIR 从调用者工作目录解析，并在后端启动前转为绝对路径。显式相对 PLUGINS_DIR 采用同一规则；未设置时，可写插件仍在 $DATA_DIR/plugins。检查临时空间默认使用数据目录外的用户可写缓存：macOS 为 ~/Library/Caches/libre-webui，Windows 为 %LOCALAPPDATA%\libre-webui，其他系统为 ${XDG_CACHE_HOME:-~/.cache}/libre-webui。Homebrew 服务固定同一主目录数据路径，并使用 Homebrew 的 var/libre-webui/preflight。缓存无法容纳数据库和 WAL 时应显式设置 PLATFORM_PREFLIGHT_TMP_DIR。内置 Docker 和 Helm 部署使用独立挂载支持的绝对路径 /app/backend/data 和 /app/backend/temp/preflight。
平台基础
默认 solo 配置使用 SQLite、本地加密 Blob、加密嵌入向量、本地协调和内置持久 Worker。team 配置使用 PostgreSQL、私有 S3 兼容 Blob、PGVector、Redis 和外部 Worker。团队配置安全失败：必须同时选择所有共享依赖。
| 变量 | 默认值 | 用途 |
|---|---|---|
LIBRE_PLATFORM_MODE | solo | 选择一致的 solo 或 team 配置 |
DATABASE_BACKEND | sqlite | 选择 sqlite 或 postgres |
DATABASE_URL | 未设置 | PostgreSQL 连接 URL，使用 postgres 时必需 |
DATABASE_SSL_MODE | verify-full | PostgreSQL TLS 策略：disable、require 或验证主机名的 verify-full |
POSTGRES_MIGRATION_MODE | apply | 在 Leader 锁下运行兼容迁移，或使用 validate 只读检查架构 |
POSTGRES_POOL_MAX | 10 | 每个应用或 Worker 进程的 PostgreSQL 最大连接数（1-100） |
POSTGRES_CONNECT_TIMEOUT_MS | 5000 | PostgreSQL 连接超时（1-60000 ms） |
POSTGRES_IDLE_TIMEOUT_MS | 30000 | PostgreSQL 空闲连接超时（1-600000 ms） |
POSTGRES_STATEMENT_TIMEOUT_MS | 30000 | PostgreSQL 语句超时（1-600000 ms） |
POSTGRES_MIGRATION_LOCK_TIMEOUT_MS | 60000 | 等待迁移 Leader 锁的时间（1-600000 ms） |
BLOB_STORE_BACKEND | local | 选择加密 local 存储或私有 s3 |
VECTOR_STORE_BACKEND | SQLite 使用 embedded | 选择加密 embedded 向量或 pgvector |
COORDINATION_BACKEND | solo 为 local；team 为 redis | 选择进程本地或 Redis 协调 |
REDIS_URL | 未设置 | redis: 或 rediss: URL，Redis 协调时必需 |
REDIS_KEY_PREFIX | libre | Libre 协调键的 1–64 字符命名空间 |
REDIS_CONNECT_TIMEOUT_MS | 5000 | 初始 Redis 连接超时，上限 60 秒 |
JOB_WORKER_MODE | solo 为 embedded；team 为 external | 在应用或独立共享 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 密钥映射；目前必须含与 ENCRYPTION_KEY 匹配的 legacy |
STORAGE_ENCRYPTION_ACTIVE_KEY_ID | 未设置 | 新本地 Blob 和嵌入向量写入使用的密钥 ID |
BLOB_QUOTA_BYTES_PER_USER | 10737418240 | 每位所有者持久明文 Blob 字节上限（正安全整数） |
BLOB_QUOTA_RESERVATION_TTL_MS | 3600000 | 废弃流式配额预留的寿命（至少 60000 ms） |
S3_BUCKET | 未设置 | 私有 S3 兼容 Bucket，使用 s3 时必需 |
S3_REGION | 未设置 | S3 区域，使用 s3 时必需 |
S3_ENDPOINT | 提供商默认值 | MinIO 或其他兼容服务的可选绝对 HTTP(S) 端点 |
S3_ACCESS_KEY_ID | SDK 凭据链 | 可选显式 S3 访问密钥 |
S3_SECRET_ACCESS_KEY | SDK 凭据链 | 设置显式访问密钥时必需 |
S3_SESSION_TOKEN | 未设置 | 与显式 S3 凭据一起使用的可选令牌 |
S3_FORCE_PATH_STYLE | false | 要求路径样式寻址的服务设为 true |
S3_BLOB_PREFIX | libre/blobs | Libre 所有的不透明 Bucket 键前缀 |
没有版本化存储密钥映射时，存储适配器使用现有 ENCRYPTION_KEY，密钥 ID 为 legacy；若也不存在，则读取现有 ${DATA_DIR}/.encryption_key，不生成或修改。显式配置必须与持久文件一致。引入版本化映射且已有旧密钥时，应在所有对象和向量重写或重封并验证前，以确切 ID legacy 保留。冲突、不安全文件权限、符号链接和已配置密钥缺失都会安全失败。
Redis 用于协调，不是规范持久存储。仅选择 Redis 不会使 SQLite、本地文件或其他进程所有状态可安全跨副本。在团队模式中，HTTP 速率限制、Chat/WebSocket 连接、STT/TTS/音频提供商工作、存档导入和 Work 终端使用 Redis 支持的共享准入。容量应用于所有副本，而不是每进程一次。准入和可续许可失败会返回 503 或中止正在进行的操作；Libre 绝不回退到独立本地计数器。参阅平台基础。
内置团队 Compose 配置和 Helm Chart 将以上所有团队平台选择器和调节值同时转发给应用和外部 Worker。在 Helm 中，非机密选择器位于 env 下；连接或密钥材料使用 secrets.redisUrl、secrets.databaseUrl 和 secrets.storageEncryptionKeys。PostgreSQL 连接池限制按进程应用：数据库至少需预留 (replicaCount + worker.replicaCount) * POSTGRES_POOL_MAX 个连接，以及运营和迁移余量。远程或托管 PostgreSQL 保持 DATABASE_SSL_MODE=verify-full。只有内置团队 Compose 配置选择 disable，因为其监听器隔离在私有项目网络。团队 Helm 还要求稳定 secrets.jwtSecret 并把同一 Secret 键挂载到所有应用和 Worker Pod；省略会导致各进程生成本地签名材料。S3 接收不透明键和密文；Bucket URL 与提供商 URL 不存入应用元数据。
集成的 solo 和 team 存档在签名加密保护配置中保留 PostgreSQL 连接池与超时、Redis 连接超时、两个 Blob 配额设置、平台选择器和 S3 寻址设置。干净恢复可发布重建对应部署所需的运营值，而无需把它们放入明文存档元数据。
内置团队 Compose 和 Helm 应用/外部 Worker 对接收相同解析后的 OLLAMA_BASE_URL、OLLAMA_TIMEOUT、OLLAMA_LONG_OPERATION_TIMEOUT 和 OLLAMA_MAX_CONTEXT。文档嵌入、持久聊天和 Work 运行的提供商调用在 Worker 中执行，因此进程间不能不同。两个服务器入口点在创建本地状态或连接共享状态前，将三个数值解析为完整的十进制正整数。300000ms 等部分值、指数/十六进制表示、超范围值，或长操作超时低于标准超时都会使启动失败。
Helm 将 TRUST_PROXY 限制为 0 到 16 的确切整数跳数，并只转发到 HTTP 应用 Pod。直连流量保持默认 0。为 Ingress/负载均衡链设置确切固定数，绝不使用运行时无限制 true。错误计数会把客户端归到代理地址用于共享速率限制，或信任客户端可提供的地址。
PostgreSQL 架构兼容要求完全相同版本。Helm 应用和 Worker 使用 Recreate；团队升级前排空并终止所有旧 Pod，再由一个新进程在 advisory leader 锁下迁移。不要运行混合二进制版本，也不要宣称零停机架构发布。回滚意味着在启动匹配旧二进制前，将升级前已验证团队存档恢复到干净 PostgreSQL/S3 目标。
活跃团队应用需要 worker.replicaCount >= 1；Helm 拒绝没有持久 Worker 的实时应用，而不会等到就绪失败。完整暂停时把应用和 Worker 数量都设为零。应用为零、Worker 为正是主动的仅 Worker 排空或恢复模式，会继续处理队列作业但不提供 Web 流量。
私有备份辅助程序
这些变量配置 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 | 恢复时必需 | 已审核的不可变 Libre 映像 ID 或摘要 |
LIBRE_WEBUI_RESTORE_CONFIG_DIR | /etc/libre-webui/restored 下每卷路径 | 恢复配置的新目录 |
systemd 单元从可选、root 所有的 /etc/libre-webui/backup.env 加载备份覆盖。设为模式 0600。堆栈目录、保留期、容器名和备份密钥目录可直接在其中设置。单元文件系统沙盒只允许在默认备份目录下写入。自定义 LIBRE_WEBUI_BACKUP_DIR 还要求在服务 ReadWritePaths= drop-in 中加入确切的预创建目录；参阅私有远程部署。
身份验证与安全
| 变量 | 默认值 | 用途 |
|---|---|---|
ENABLE_SIGNUP | false | 首位本地管理员后允许注册 |
JWT_SECRET | 开发环境生成/回退值 | JWT 签名密钥；生产环境显式设置 |
JWT_EXPIRES_IN | 7d | 会话令牌寿命 |
ENCRYPTION_KEY | 自动生成 | 加密值使用的 64 字符十六进制密钥 |
DEBUG_ENCRYPTION | 未设置 | 设置时记录加密调试输出 |
TURNSTILE_SITE_KEY | 未设置 | 登录和注册的 Cloudflare Turnstile 站点密钥 |
TURNSTILE_SECRET_KEY | 未设置 | 后端验证用 Cloudflare Turnstile 密钥 |
TURNSTILE_EXPECTED_HOSTNAME | BASE_URL 的主机名 | Cloudflare 验证响应中要求的主机名 |
MFA_REQUIRED_MODE | 未设置（管理员开关，optional） | 将双重验证策略固定为 optional 或 required |
WEBAUTHN_RP_ID | 请求主机名 | 多主机名后通行密钥的固定依赖方 ID |
VAPID_PUBLIC_KEY | 生成并加密存储 | 固定 Web Push VAPID 公钥（Base64URL P-256 点） |
VAPID_PRIVATE_KEY | 生成并加密存储 | 固定 Web Push VAPID 私钥（Base64URL 标量） |
VAPID_SUBJECT | mailto:admin@localhost | 已签名 Web Push 授权中的联系声明 |
只有两个 Turnstile 密钥同时存在时才启用 Turnstile。
ENABLE_SIGNUP=false 仍允许在空数据库中创建首位本地管理员，之后阻止额外本地和 OAuth 账户。首次启动前，请使用外部身份边界保护远程可访问的引导路由。
每个已签发 JWT 都绑定服务器端会话（sid 声明），因此退出或从设置 → 会话撤销会立即在所有副本使令牌失效，并关闭活跃 WebSocket。安全审计保留期可配置：
| 变量 | 默认值 | 用途 |
|---|---|---|
AUDIT_RETENTION_DAYS | 180 | 安全审计事件日志行的保留天数 |
通用 OIDC 单点登录
任何具有发现文档的 OpenID Connect 提供商都可用于登录。流程使用 PKCE（S256）、CSRF 状态，以及在签名已验证 ID 令牌中验证的 nonce。身份通过稳定 sub 声明关联。
| 变量 | 默认值 | 用途 |
|---|---|---|
OIDC_ISSUER_URL | 未设置 | 发行方基础 URL；从 <issuer>/.well-known/openid-configuration 获取发现 |
OIDC_CLIENT_ID | 未设置 | 在提供商注册的 OAuth 客户端 ID |
OIDC_CLIENT_SECRET | 未设置 | OAuth 客户端密钥 |
OIDC_DISPLAY_NAME | Single Sign-On | 登录按钮显示标签 |
OIDC_SCOPES | openid profile email | 请求范围 |
OIDC_CALLBACK_URL | BASE_URL + OIDC 回调路由 | 在提供商注册的重定向 URI |
OIDC_ALLOWED_EMAIL_DOMAINS | 未设置 | 逗号列表；要求邮箱已验证且属于其中一个域 |
OIDC_GROUP_CLAIM | groups | 保存组名的 ID 令牌声明 |
OIDC_ADMIN_GROUPS | 未设置 | 逗号列表；每次登录时管理员角色遵循声明成员身份 |
OIDC_SYNC_GROUPS | false | true 在每次登录时将 Libre 组成员与组声明协调 |
只有发行方 URL、客户端 ID 和客户端密钥全部存在时才启用 OIDC。已被未关联本地账户使用的邮箱会被拒绝，而不会悄然合并；账户创建仍遵守 ENABLE_SIGNUP。
可以调节 Chat WebSocket 准入，而不削弱身份验证：
| 变量 | 默认值 | 用途 |
|---|---|---|
CHAT_WS_MAX_PAYLOAD_BYTES | 10 MiB | 接受的 WebSocket 消息最大大小 |
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 | 一次性 Chat/Work 票据寿命，上限 60 秒 |
浏览器用普通 Authorization 标头换取不透明票据，只把短期值放入 WebSocket 升级 URL。票据一次性、绑定协议和会话，只存储哈希，从而避免持久会话令牌进入反向代理请求目标日志。配置 CORS_ORIGIN 或 BASE_URL 时，带 Origin 的浏览器升级必须匹配已配置源。远程部署至少设置一个；都未设置时，为兼容本地开发而宽松。Electron 和非浏览器客户端有意支持无源升级，但仍需有效一次性票据，并接受相同账户、Work 访问和任务检查。将票据视为身份验证边界，并通过 TLS、防火墙和反向代理限制非浏览器访问。
OAuth
| 变量 | 用途 |
|---|---|
GITHUB_CLIENT_ID | GitHub OAuth 客户端 ID |
GITHUB_CLIENT_SECRET | GitHub OAuth 客户端密钥 |
GITHUB_CALLBACK_URL | GitHub 回调 URL 覆盖 |
HUGGINGFACE_CLIENT_ID | Hugging Face OAuth 客户端 ID |
HUGGINGFACE_CLIENT_SECRET | Hugging Face OAuth 客户端密钥 |
HUGGINGFACE_CALLBACK_URL | Hugging Face 回调 URL 覆盖 |
未设置回调 URL 时，Libre WebUI 从 BASE_URL 构建默认值。
Ollama
| 变量 | 默认值 | 用途 |
|---|---|---|
OLLAMA_BASE_URL | http://localhost:11434 | Ollama API 基础 URL |
OLLAMA_TIMEOUT | 300000 | 标准 Ollama 请求超时（1,000-3,600,000 ms） |
OLLAMA_LONG_OPERATION_TIMEOUT | 900000 | 长操作超时（1,000-3,600,000 ms，且不短于 OLLAMA_TIMEOUT） |
OLLAMA_MAX_CONTEXT | 32768 | 自动采用的最大模型上下文（128-2,097,152 个令牌） |
Web 搜索
| 变量 | 默认值 | 用途 |
|---|---|---|
SEARXNG_URL | 未设置 | Web 搜索设置的默认 SearXNG 端点；管理员仍需在设置 > 搜索中启用 |
Libre Claw
| 变量 | 默认值 | 用途 |
|---|---|---|
LIBRE_CLAW_BASE_URL | http://127.0.0.1:8766 | 可选 Libre Claw 守护进程 URL |
LIBRE_CLAW_TIMEOUT_MS | 30000 | Libre Claw HTTP 请求超时 |
Work 运行时
这些变量配置运行 Libre WebUI 后端的计算机或 Kubernetes 集群上的 Work 执行。Docker 是默认运行时；设置 work.enabled=true 时 Helm Chart 选择 Kubernetes。
| 变量 | 默认值 | 用途 |
|---|---|---|
WORK_RUNTIME_IMAGE | node:22.22-bookworm@sha256:2d178f2785b96dfbf62a416ca2e40f50e30150b4ff3320d706f0d96e90600eb3 | Work 沙盒使用的固定映像 |
WORK_DOCKER_COMMAND | docker | 进程可用的 Docker 后端 CLI 可执行文件 |
WORK_COMMAND_TIMEOUT_MS | 120000 | 默认超时；工具可请求最多 600000 ms |
WORK_MAX_OUTPUT_CHARS | 50000 | 捕获 stdout/stderr 的上限，分别应用于每个流 |
WORK_MAX_AGENT_ROUNDS | 48 | 单次运行中与提供商无关的模型/工具轮次预算 |
WORK_STATUS_BLURB_MODEL | 1 | 设为 0 可跳过运行后为代理侧边栏状态行发出的模型请求 |
WORK_MEMORY_LIMIT | 2g | 每个 Work 容器的内存限制 |
WORK_CPU_LIMIT | 2 | 每个 Work 容器的 CPU 限制 |
WORK_PIDS_LIMIT | 256 | 每个 Work 容器的进程限制 |
WORK_PREVIEW_PORT | 4173 | 任务容器中预览服务器必须使用的端口 |
WORK_PREVIEW_BIND | 127.0.0.1 | 发布任务预览端口的宿主机接口；原生 Docker Engine 的 Compose 部署必须使用可访问的非公开网桥接口 |
WORK_DOCKER_PUBLISHED_HOST | 应用默认值：与 WORK_PREVIEW_BIND 相同；Compose 默认值：host.docker.internal | 后端访问 Docker 发布预览、屏幕和音频端口使用的主机/IP |
WORK_COMPUTER_SCREEN_PORT | 6080 | 启用 GUI 沙盒中 Work Computer 屏幕桥接（websockify）的容器端口 |
WORK_COMPUTER_AUDIO_PORT | 6081 | 启用 GUI 沙盒中音频桥接（websockify → PulseAudio monitor）的容器端口 |
WORK_MAX_ACTIVE_RUNTIMES_GLOBAL | 3 | 整个实例同时运行的运行时支持任务数 |
WORK_MAX_ACTIVE_RUNTIMES_PER_USER | 2 | 单用户同时运行的运行时支持任务数 |
WORK_MAX_TASKS_GLOBAL | 500 | 整个实例最大持久 Work 任务数 |
WORK_MAX_TASKS_PER_USER | 100 | 单管理员最大持久 Work 任务数 |
WORK_NETWORK_NAME | libre-webui-work | 网络任务使用的受管沙盒桥接网络 |
WORK_RUN_LEASE_WAIT_MS | 60000 | 运行等待任务共享运行时租约后报告副本冲突的时间（团队模式） |
WORK_RUNTIME_DNS | 未设置 | 强制应用于网络任务的解析器 IP，逗号分隔 |
WORK_DOCKER_SOCKET | DOCKER_HOST 为 unix:// 或 tcp:// 时使用它，否则 /var/run/docker.sock | 终端和诊断使用的 Docker Engine 端点 |
WORK_TERMINAL_MAX_SESSIONS_PER_TASK | 2 | 单任务同时附加的浏览器终端数 |
WORK_TERMINAL_IDLE_TIMEOUT_MS | 900000 | 终端会话因空闲而关闭前的超时 |
WORK_RUNTIME_IDLE_TIMEOUT_MS | 0（禁用） | 沙盒无活动达到此时间后停止（包括预览） |
WORK_HOST_WORKSPACES_ENABLED | false | 允许任务使用宿主机文件夹代替卷 |
WORK_HOST_WORKSPACE_ROOTS | 服务器用户主目录 | 宿主机工作区必须位于其中的 : 分隔根目录 |
WORK_RUNTIME_BACKEND | docker | 沙盒后端：docker 或 kubernetes |
WORK_K8S_NAMESPACE | libre-webui-work | 包含 Kubernetes 沙盒 Pod 和 PVC 的命名空间 |
WORK_K8S_STORAGE_CLASS | 集群默认值 | 工作区 PVC 使用的 StorageClass |
WORK_K8S_WORKSPACE_SIZE | 5Gi | 每任务工作区 PVC 大小（真实磁盘配额） |
WORK_K8S_POD_READY_TIMEOUT_MS | 900000 | 等待沙盒 Pod 到达 Running（包括拉取映像） |
WORK_K8S_POD_GONE_TIMEOUT_MS | 60000 | 等待已删除沙盒 Pod 消失 |
AGENT_CLI_MODELS_ENABLED | 未设置（管理员开关，关闭） | 固定 Agents 功能开关；未设置时由用户管理中的管理员开关决定，默认关闭 |
TOOLS_ACCESS_MODE | 未设置（管理员开关，仅管理员） | 将聊天工具固定为 admins 或 all-users，并锁定用户管理开关 |
STT_ACCESS_MODE | 未设置（管理员开关，所有用户） | 将语音转文字固定为 admins 或 all-users 并锁定开关 |
TTS_ACCESS_MODE | 未设置（管理员开关，所有用户） | 将文字转语音固定为 admins 或 all-users 并锁定开关 |
VOICE_MODE_ACCESS_MODE | 未设置（管理员开关，所有用户） | 将免手持语音模式固定为 admins 或 all-users 并锁定开关 |
VOICE_CLONING_ACCESS_MODE | 未设置（管理员开关，所有用户） | 将声音克隆固定为 admins 或 all-users 并锁定开关 |
TOOLS_PRIVATE_NETWORK_ALLOWLIST | 未设置 | 工具服务器和 Webhook 可解析到私有地址的确切主机名（逗号分隔），连接会固定 |
AGENT_CLI_TIMEOUT_MS | 600000 | Agent CLI 在被终止前的运行时间 |
CODEX_OAUTH_MODELS_ENABLED | true | 向管理员提供 Codex（ChatGPT）提供商 |
CODEX_HOME | ~/.codex | 读取 Codex CLI 登录文件（auth.json）的位置 |
Agent CLI 二进制和 Codex OAuth 凭据是节点本地的。它们只在单进程 solo 中受支持，此时发现和执行看到相同文件系统与环境。团队模式在外部 Worker 中执行持久聊天作业，因此要求 AGENT_CLI_MODELS_ENABLED=false 和 CODEX_OAUTH_MODELS_ENABLED=false；启动拒绝其他值，而不会公布可能只存在于一个应用副本的提供商。请使用 Ollama，或凭据和路由存储在共享 PostgreSQL 或以相同方式转发给每个应用与 Worker 的提供商插件。
在 Docker 后端中，宿主机工作区把真实目录绑定挂载到 /workspace，因此任务可直接读写文件，而不使用自身 Docker 卷。Kubernetes 拒绝宿主机文件夹工作区。这有意降低 Docker 沙盒强度：除非确实需要，否则关闭 WORK_HOST_WORKSPACES_ENABLED，并尽量缩小 WORK_HOST_WORKSPACE_ROOTS。请求路径在对照根目录检查前会解析符号链接；.ssh、.gnupg、.aws、.config 等文件夹直接拒绝。
Agent CLI 模型把服务器上已安装的编码代理（claude、codex）作为可选聊天模型，因此订阅代理无需 API 密钥也能回答。只有管理员可见；CLI 以 Libre WebUI 服务器用户运行，并继承该用户的代理凭据——应将其视为向这些代理授予 shell 访问。
在 Docker 上，网络 Work 任务连接到受管 WORK_NETWORK_NAME 桥接网络，该网络禁用容器间通信，防止一个沙盒访问另一个沙盒或部署自身容器。WORK_RUNTIME_DNS 是受支持的 Docker 出站策略挂钩：指向过滤解析器以应用基于名称的允许/拒绝列表。非 IPv4/IPv6 条目会被拒绝并记录。DNS 过滤不限制直接 IP 出站；需要时添加宿主机防火墙规则。Kubernetes 后端改用 Chart 默认拒绝 NetworkPolicy 和 work.networkPolicy.blockedEgressCidrs。
Docker 上的交互终端和系统诊断直接访问 Docker Engine API。若设置则遵循 WORK_DOCKER_SOCKET，否则遵循 DOCKER_HOST——unix:// 套接字或套接字代理等纯 HTTP tcp:// 端点（参阅 docker-compose.socket-proxy.yml）——否则使用 /var/run/docker.sock。此客户端不支持的 DOCKER_HOST（ssh://，或设置 DOCKER_TLS_VERIFY 的 tcp://）会报告终端和 Docker 诊断不可用；Work 其余部分继续通过可自行理解这些端点的 Docker CLI 运行。Kubernetes 上终端使用 Pod exec，不使用 Docker 端点。
Work 在后端启动时读取这些值。预览端口位于任务容器内部；Libre WebUI 将其发布到动态分配的环回端口，而不直接暴露在所有宿主机接口。
运行时映像应固定到已审核版本或摘要。提高并发或资源限制会增加一个或多个自主运行可消耗的容量。WORK_MAX_AGENT_ROUNDS 同等应用于 Ollama 和插件运行，没有更低的插件专属限制。工具调用安全预算为 max(128, WORK_MAX_AGENT_ROUNDS × 8)。运行耗尽轮次预算时，Work 请求模型进行最后一次无工具交接，并以终止状态 needs_input 结束，而不是返回原始轮次限制错误或声称成功。后续运行继续使用同一持久工作区。持久工具输出另有约 20,000 个源字符加截断标记的限制。
这些变量调节已可访问的 Work 运行时。仓库单实例 Compose 部署默认启用：映像包含 Docker CLI，Compose 文件挂载宿主机 Docker 套接字。两个 Compose 级变量控制连接：
| 变量 | 默认值 | 用途 |
|---|---|---|
DOCKER_GID | 0 | 宿主机 Docker 套接字组 ID，添加到容器用户 |
DOCKER_SOCKET | /var/run/docker.sock | 要挂载的宿主机 Docker 套接字路径 |
DOCKER_GID 必须是套接字 在容器内看到的 组；macOS 宿主机报告的值不同。团队 Compose 基础不挂载套接字，在添加 docker-compose.team.work.yml 前，基于 Docker 的 Work 不可用。该生产覆盖向应用和 Worker 提供相同内部过滤代理端点，绝不挂载套接字或套接字组。代理只允许运行时使用的 Docker API 部分，但创建容器仍是 Docker 宿主机控制凭据；更强边界请使用专用或无 root Work 守护进程。Helm Chart 绝不挂载节点运行时套接字；通过 work.enabled=true 启用原生 Pod/PVC Work 后端。
solo 配置因使用 SQLite、本地文件和进程本地协调，必须保持零或一个应用副本。Helm Chart 接受零作为主动暂停，拒绝更多 solo 副本或 solo 自动扩缩。完整 team 配置可使用多个应用副本和外部 Worker，因为 PostgreSQL、S3、PGVector 和 Redis 保存共享状态。两种配置中的 Work 沙盒 Pod 独立扩缩；团队模式外部 Worker 接收与应用 Pod 相同的 Kubernetes 运行时映像、StorageClass 和 work.env 限制。
仓库 Compose 文件还接受 WEBUI_BIND_ADDRESS（默认 127.0.0.1）和 WEBUI_PORT（默认 8080）。除非可信 LAN 或宿主机反向代理需要访问端口，否则保持环回默认值。
提供商模型发现
提供商模型目录缺失或过期时会自动重新发现，因此重新加载会反映当前提供的模型。以下变量调节周期：
| 变量 | 默认值 | 用途 |
|---|---|---|
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 | OpenAI 和 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 | Moonshot AI 的 Kimi Code |
GITHUB_API_KEY | GitHub Models |
HUGGINGFACE_API_KEY | 已配置的 Hugging Face API |
ELEVENLABS_API_KEY | ElevenLabs TTS |
COMFYUI_API_KEY | 需要 API 密钥的 ComfyUI 部署 |
用户也可在界面保存提供商凭据。环境密钥只用于未遮蔽内置定义的路由与身份验证投影。导入定义、复用内置 ID 的可写定义和管理员保存的自定义路由都需要该账户存储凭据。Libre WebUI 不会向这些路由附加环境密钥，也不会通过发现和可用性检查公开。信任来自每个发布清单的编译哈希，因此旧版和内置插件目录共享路径的容器布局仍受支持，但修改后的清单不会被视为内置。
用户保存的密钥绑定到有效提供商定义、源、身份验证契约和路由值。管理员更改目标后，用户必须重新保存密钥。升级前未绑定密钥只在使用内置路由的完全匹配发布定义上首次使用时接受并绑定。
源码启动时，相对 PLUGINS_DIR 从后端目录解析。打包启动器则在启动后端前把显式相对值转换为调用者绝对路径。为兼容性，Libre 也读取确定的 backend/plugins 目录和历史配置位置。请将这些定义移到 $DATA_DIR/plugins；恢复会把旧路径报告为外部状态，只要自定义定义仍在其中，就阻止仅卷快照。插件目录和 JSON 定义必须是实际普通条目；Libre 不跟随插件符号链接。
前端
| 变量 | 默认值 | 用途 |
|---|---|---|
VITE_API_BASE_URL | 同源开发代理或生产环境 API | 前端 API 基础 URL |
VITE_WS_BASE_URL | 从 API URL 推断 | Chat 和 Work 套接字的绝对 ws:/wss: 基础 |
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 覆盖 Chat 和 Work 终端的所有 WebSocket 回退。它可包含反向代理路径前缀，但必须是无凭据、查询或片段的绝对 ws: 或 wss: URL。未设置时，Electron file: 客户端使用 ws://localhost:3001；浏览器客户端依次从 VITE_API_BASE_URL、再到浏览器源推导基础地址。Vite 会将开发环境源代理到 3001 端口的后端。
维护脚本
| 变量 | 用途 |
|---|---|
CHANGELOG_AI | 设为 0 禁用 AI 辅助 Changelog 草稿 |
CHANGELOG_AI_MODEL | 生成版本/Changelog 使用的 Ollama 模型 |
CHANGELOG_AI_TIMEOUT_MS | AI Changelog 生成超时（毫秒） |
示例：
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