12.4 · 环境变量（Environment Variables）

环境变量（中文译文）

原始 DeepWiki 页面：https://deepwiki.com/open-webui/open-webui/12.4-environment-variables

翻译时间：2026-06-09T16:11:00.675Z

翻译模型：deepseek-chat

原文字符数：11909

项目：Open WebUI (open-webui)

---

环境变量

相关源文件

以下文件为本 wiki 页面的生成提供了上下文：

• .env.example
• Dockerfile
• backend/dev.sh
• backend/open_webui/config.py
• backend/open_webui/env.py
• backend/open_webui/main.py
• backend/open_webui/routers/auths.py
• backend/open_webui/utils/auth.py
• backend/open_webui/utils/oauth.py
• backend/start.sh
• backend/start_windows.bat
• src/lib/constants.ts

本页面提供了所有控制 Open WebUI 行为的环境变量的完整参考。环境变量是部署时配置系统的主要机制，可通过 shell 环境、Docker Compose 文件或容器编排平台进行设置。

关于环境变量在运行时的持久化和管理的详细信息，请参见持久化配置系统。关于允许管理员修改这些设置的用户界面，请参见设置 UI。

配置架构

Open WebUI 采用混合配置系统，结合了环境变量与数据库持久化设置。系统在启动时读取环境变量，并将其存储在 PersistentConfig 对象中，之后可通过管理界面更新这些对象，无需重启应用。

配置加载流程

graph TB
    EnvVars["环境变量<br/>(操作系统、Docker、.env)"]
    EnvModule["open_webui.env<br/>WEBUI_SECRET_KEY<br/>REDIS_URL<br/>DATABASE_URL"]
    ConfigModule["open_webui.config<br/>PersistentConfig 对象<br/>AppConfig 类"]
    Database["配置数据库表<br/>JSON 存储"]
    AppState["app.state.config<br/>运行时配置<br/>由路由访问"]

    EnvVars --> EnvModule
    EnvVars --> ConfigModule

    ConfigModule --> Database
    Database -.->|"启动时加载"| ConfigModule
    ConfigModule --> AppState
    EnvModule --> AppState

    AdminUI["管理界面变更"] -.->|"更新"| Database
    Database -.->|"重新加载"| AppState

    style EnvVars fill:none
    style Database fill:none
    style AppState fill:none

来源： backend/open_webui/env.py:21-165, backend/open_webui/config.py:114-141

配置系统分为三层：

1. 环境层：部署环境中定义的原始环境变量。
2. 持久化层：PersistentConfig 对象，可将值存储在数据库中。
3. 运行时层：app.state.config 提供对当前配置值的访问。

当 ENABLE_PERSISTENT_CONFIG=True（默认值）时，对于 PersistentConfig 条目，数据库中的值优先于环境变量。这使得管理员无需重新部署即可通过 UI 修改设置。

来源： backend/open_webui/config.py:211-231, backend/open_webui/utils/oauth.py:116-141

PersistentConfig 与直接环境变量

graph LR
    subgraph "持久化配置"
        PC1["ENABLE_SIGNUP<br/>PersistentConfig<br/>可通过 UI 更改"]
        PC2["OLLAMA_BASE_URLS<br/>PersistentConfig<br/>存储在数据库中"]
        PC3["RAG_EMBEDDING_MODEL<br/>PersistentConfig<br/>管理员可配置"]
    end

    subgraph "静态配置"
        ENV1["WEBUI_SECRET_KEY<br/>直接环境变量<br/>需要重启"]
        ENV2["DATABASE_URL<br/>直接环境变量<br/>基础设施级别"]
        ENV3["REDIS_URL<br/>直接环境变量<br/>运行时不可更改"]
    end

    PC1 --> DB[("数据库")]
    PC2 --> DB
    PC3 --> DB

    DB -.->|"热重载"| Runtime["app.state.config"]
    ENV1 --> Runtime
    ENV2 --> Runtime
    ENV3 --> Runtime

    style DB fill:none
    style Runtime fill:none

来源： backend/open_webui/config.py:214-232, backend/open_webui/env.py:21-40

核心系统变量

这些环境变量控制着系统的基本行为，必须在应用启动前设置。

基础设施

变量	类型	默认值	描述
ENV	string	"dev"	环境模式："dev" 或 "prod"。backend/open_webui/env.py:141
WEBUI_SECRET_KEY	string	自动生成	用于 JWT 令牌签名的密钥。backend/start.sh:25-36
DATABASE_URL	string	SQLite	数据库连接字符串。backend/open_webui/env.py:24
PORT	integer	8080	应用监听的 HTTP 端口。backend/start.sh:23
HOST	string	"0.0.0.0"	绑定的网络接口。backend/start.sh:24
DOCKER	boolean	false	如果在 Docker 内运行，设置为 true。backend/open_webui/env.py:44
REDIS_URL	string	None	用于会话存储和发布/订阅的 Redis 连接 URL。backend/open_webui/env.py:27

来源： backend/open_webui/env.py:24-141, backend/start.sh:17-46

日志与结构化数据

Open WebUI 支持生产环境的结构化 JSON 日志。

变量	类型	默认值	描述
GLOBAL_LOG_LEVEL	string	"INFO"	日志级别：DEBUG、INFO、WARNING、ERROR、CRITICAL。backend/open_webui/env.py:118
LOG_FORMAT	string	""	设置为 "json" 以启用结构化日志。backend/open_webui/env.py:107

来源： backend/open_webui/env.py:78-128

认证与安全变量

核心认证

变量	类型	默认值	描述
WEBUI_AUTH	boolean	true	启用认证系统。backend/open_webui/env.py:34
JWT_EXPIRES_IN	string	"4w"	JWT 令牌过期时间。backend/open_webui/utils/oauth.py:136
ENABLE_OAUTH_SIGNUP	boolean	false	允许新用户通过 OAuth 注册。backend/open_webui/utils/oauth.py:118
OAUTH_MERGE_ACCOUNTS_BY_EMAIL	boolean	false	通过电子邮件将 OAuth 账户与现有账户合并。backend/open_webui/utils/oauth.py:120

来源： backend/open_webui/routers/auths.py:33-55, backend/open_webui/utils/oauth.py:116-141

OAuth 2.1 配置

Open WebUI 实现了复杂的 OAuth 管理系统，并对敏感客户端信息进行加密。

变量	类型	默认值	描述
OAUTH_CLIENT_INFO_ENCRYPTION_KEY	string	必需	用于加密数据库中 OAuth 客户端密钥的密钥。backend/open_webui/env.py:77
OAUTH_MAX_SESSIONS_PER_USER	integer	10	限制每个用户的并发 OAuth 会话数。backend/open_webui/env.py:78
ENABLE_OAUTH_ID_TOKEN_COOKIE	boolean	true	将 OAuth ID 令牌存储在 Cookie 中。backend/open_webui/env.py:75

来源： backend/open_webui/utils/oauth.py:180-191, backend/open_webui/env.py:75-78

受信任标头认证

适用于上游代理处理认证的环境。

变量	类型	默认值	描述
WEBUI_AUTH_TRUSTED_EMAIL_HEADER	string	None	包含已认证电子邮件的标头。backend/open_webui/env.py:35
WEBUI_AUTH_TRUSTED_NAME_HEADER	string	None	包含已认证名称的标头。backend/open_webui/env.py:36
WEBUI_AUTH_TRUSTED_GROUPS_HEADER	string	None	包含组成员身份的标头。backend/open_webui/env.py:37
WEBUI_AUTH_TRUSTED_ROLE_HEADER	string	None	包含用户角色的标头。backend/open_webui/env.py:38

来源： backend/open_webui/routers/auths.py:33-44, backend/open_webui/env.py:35-38

RAG 与 Web 检索变量

Web 搜索集成

变量	类型	默认值	描述
WEB_LOADER_ENGINE	string	"playwright"	用于获取 Web 内容的引擎。backend/open_webui/main.py:230
PLAYWRIGHT_WS_URL	string	None	Playwright 的 WebSocket URL。backend/open_webui/main.py:225
PLAYWRIGHT_TIMEOUT	integer	60000	Playwright 操作的超时时间。backend/open_webui/main.py:226
FIRECRAWL_API_BASE_URL	string	None	Firecrawl API 的基础 URL。backend/open_webui/main.py:227
FIRECRAWL_API_KEY	string	None	Firecrawl 的 API 密钥。backend/open_webui/main.py:228
WEB_LOADER_CONCURRENT_REQUESTS	integer	5	Web 加载器的并发请求数。backend/open_webui/main.py:231
WEB_LOADER_TIMEOUT	integer	60000	Web 加载器操作的超时时间。backend/open_webui/main.py:232

来源： backend/open_webui/main.py:225-232, backend/start.sh:7-15

RAG 嵌入与重排序

变量	类型	默认值	描述
RAG_EMBEDDING_MODEL	string	"sentence-transformers/all-MiniLM-L6-v2"	用于生成嵌入的模型。Dockerfile:14
RAG_EMBEDDING_ENGINE	string	""	嵌入生成引擎（例如 ollama、openai）。backend/open_webui/main.py:255
RAG_RERANKING_MODEL	string	""	用于重排序的模型。Dockerfile:15
RAG_TOP_K	integer	4	检索的 top-k 结果数。backend/open_webui/main.py:259
RAG_TOP_K_RERANKER	integer	4	重排序器的 top-k 结果数。backend/open_webui/main.py:260
RAG_RELEVANCE_THRESHOLD	float	0.0	检索文档的最低相关性分数。backend/open_webui/main.py:261
RAG_HYBRID_BM25_WEIGHT	float	0.5	混合搜索中 BM25 的权重。backend/open_webui/main.py:262

来源： backend/open_webui/main.py:240-270, Dockerfile:14-17

文档处理

变量	类型	默认值	描述
RAG_ALLOWED_FILE_EXTENSIONS	string	".pdf,.txt,.md..."	RAG 允许的文件扩展名列表（逗号分隔）。backend/open_webui/main.py:263
WHISPER_MODEL	string	"base"	语音转文本模型。backend/open_webui/main.py:233
WHISPER_LANGUAGE	string	None	Whisper 转录的语言。backend/open_webui/main.py:235
TIKTOKEN_ENCODING_NAME	string	"cl100k_base"	分词器编码名称。Dockerfile:19

来源： backend/open_webui/main.py:233-239, Dockerfile:18-20

硬件加速

用于控制 Docker 环境中 GPU/CUDA 使用的变量。

变量	类型	默认值	描述
USE_CUDA_DOCKER	boolean	"false"	启用 NVIDIA GPU 加速。backend/open_webui/env.py:47
DEVICE_TYPE	string	"cpu"	计算出的设备类型（cpu、cuda 或 mps）。backend/open_webui/env.py:54-70

来源： backend/open_webui/env.py:46-72, Dockerfile:4-73

默认模型路径汇总

以下变量定义了容器内本地模型和缓存的存储位置。

变量	默认路径	描述
WHISPER_MODEL_DIR	/app/backend/data/cache/whisper/models	本地 Whisper 模型。Dockerfile:89
SENTENCE_TRANSFORMERS_HOME	/app/backend/data/cache/embedding/models	嵌入模型。Dockerfile:95
TIKTOKEN_CACHE_DIR	/app/backend/data/cache/tiktoken	分词器缓存。Dockerfile:99
HF_HOME	/app/backend/data/cache/embedding/models	Hugging Face 缓存。Dockerfile:102

来源： Dockerfile:86-107