agentic_huge_data_base / wiki
页面 Open WebUI · 3.3 环境配置·DeepWiki 中文全文译文
DeepWiki 中文译文 / Open WebUI / 3.3

3.3 · 环境配置（Environment Configuration）

多模型对话工作台与知识应用入口 · 本章是 Open WebUI DeepWiki 中文译文的独立章节页，保留原始链接、源码锚点、模块标签和章节层级。

项目Open WebUI 章节3.3 状态全文译文 模块工具、记忆与模型调用、检索、召回与知识系统、认证、权限与安全、接口与服务契约
项目要点页2.5 参考项目 项目章节目录Open WebUI DeepWiki 原始章节Environment Configuration 上一章3.2 下一章3.4
源码线索
  • 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
  • src/lib/constants.ts
  • env.py
模块标签
  • 工具、记忆与模型调用
  • 检索、召回与知识系统
  • 认证、权限与安全
  • 接口与服务契约
  • 界面与交互

中文译文

环境配置（中文译文）

原始 DeepWiki 页面：https://deepwiki.com/open-webui/open-webui/3.3-environment-configuration
翻译时间：2026-06-09T16:07:49.139Z
翻译模型：deepseek-chat
原文字符数：12248
项目：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 的环境配置系统，该系统通过 PersistentConfig 模式（定义于 backend/open_webui/config.py:214-252）将环境变量与数据库持久化配置合并。环境变量控制数据库连接、外部服务集成、认证方法、RAG 设置、音频/图像处理以及部署参数。

关键配置文件：

  • backend/open_webui/env.py:1-220 - 加载并解析环境变量，包含类型转换。
  • backend/open_webui/config.py:78-286 - 实现 PersistentConfig<T> 和 AppConfig 类。
  • backend/open_webui/main.py:127-263 - 定义配置常量和 PersistentConfig 实例。

关于安装特定说明，请参见 3.1 安装方法。关于 Docker 特定部署选项，请参见 3.2 Docker 部署选项。关于生产部署配置，请参见 3.4 反向代理设置。

配置系统架构

Open WebUI 实现了一个精密的配置系统，通过 PersistentConfig 模式将环境变量与数据库持久化值合并。这允许在运行时更新配置，同时保留环境变量默认值。

配置加载流程

graph TB
    DotenvFile[".env 文件"] --> LoadDotenv["load_dotenv()"]
    OsEnv["os.environ"] --> LoadDotenv

    LoadDotenv --> EnvPy["env.py<br/>解析环境变量"]

    EnvPy --> CreatePC["PersistentConfig.__init__<br/>(env_name, config_path, env_value)"]

    ConfigTable[("config 表<br/>列: data (JSON)")] --> GetConfigValue["get_config_value(config_path)"]

    GetConfigValue --> Priority{"self.config_value<br/>!= None?"}
    CreatePC --> EnvValue["self.env_value<br/>来自环境变量"]

    Priority -->|"是 & ENABLE_PERSISTENT_CONFIG"| UseDB["self.value = config_value"]
    Priority -->|否| UseEnv["self.value = env_value"]

    UseDB --> AppConfigInit["AppConfig.__init__<br/>app.state.config"]
    UseEnv --> AppConfigInit

    AppConfigInit --> SetAttrMethod["AppConfig.__setattr__<br/>更新时保存"]
    AppConfigInit --> GetAttrMethod["AppConfig.__getattr__<br/>读取时检查 Redis"]

    SetAttrMethod --> SaveToDB["save_to_db(CONFIG_DATA)"]
    SetAttrMethod --> RedisSet["redis.set(redis_key_prefix:config:key)"]
    GetAttrMethod --> RedisGet["redis.get(redis_key_prefix:config:key)"]

    SaveToDB --> ConfigTable
    RedisSet --> RedisCache[("Redis<br/>键: open-webui:config:*")]
    RedisGet --> RedisCache

    RedisCache -.->|"跨实例同步"| OtherInstances["FastAPI 工作进程 2-N"]

来源： backend/open_webui/config.py:214-286, backend/open_webui/env.py:22-43

关键组件

配置系统由三层组成：

  1. 环境变量层 (env.py)：使用 os.environ.get 加载并解析环境变量，包含默认值。
  2. 持久化层 (PersistentConfig)：为每个配置值包装数据库持久化功能，并通过注册表支持批量更新 backend/open_webui/config.py:172-231。
  3. 应用层 (AppConfig)：通过基于 Redis 的多节点同步（通过 get_redis_connection 实现）提供运行时访问 backend/open_webui/config.py:40。

配置层与代码实体

graph LR
    subgraph EnvPy["env.py - 环境层"]
        OLLAMA_BASE_URL["OLLAMA_BASE_URL<br/>os.environ.get()"]
        DATABASE_URL["DATABASE_URL<br/>由各组件构建"]
        REDIS_URL["REDIS_URL<br/>os.environ.get()"]
        RAG_EMBEDDING_MODEL["RAG_EMBEDDING_MODEL<br/>默认: all-MiniLM-L6-v2"]
    end

    subgraph ConfigPy["config.py - 持久化层"]
        PC_Ollama["PersistentConfig<br/>('ENABLE_OLLAMA_API',<br/>'ollama.enable', ENABLE_OLLAMA_API)"]
        PC_RAG["PersistentConfig<br/>('RAG_EMBEDDING_MODEL',<br/>'rag.embedding.model', RAG_EMBEDDING_MODEL)"]
        ConfigTable[("Config 表<br/>id | data | version | created_at")]
        Registry["PERSISTENT_CONFIG_REGISTRY[]"]
    end

    subgraph MainPy["main.py - 应用层"]
        AppState["app.state.config<br/>AppConfig 实例"]
        RedisClient["app.state.redis<br/>get_redis_connection()"]
    end

    OLLAMA_BASE_URL --> PC_Ollama
    RAG_EMBEDDING_MODEL --> PC_RAG

    PC_Ollama --> Registry
    PC_RAG --> Registry
    Registry --> ConfigTable

    ConfigTable --> AppState
    AppState <--> RedisClient

来源： backend/open_webui/config.py:172-286, backend/open_webui/env.py:22-160, backend/open_webui/main.py:127-263

按类别划分的核心环境变量

数据库配置
变量默认值描述
DATABASE_URLsqlite:///{DATA_DIR}/webui.db完整数据库连接字符串。覆盖各个组件 backend/open_webui/env.py:24。
DATABASE_TYPENone数据库类型：sqlite、postgresql、mysql
DATABASE_USERNone数据库用户名
DATABASE_PASSWORDNone数据库密码
DATABASE_HOSTNone数据库主机
DATABASE_PORTNone数据库端口
DATABASE_NAMENone数据库名称
DATABASE_SCHEMANonePostgreSQL 模式名称
ENABLE_DB_MIGRATIONSTrue启用自动 Alembic 迁移 backend/open_webui/env.py:159。

env.py 中的 DATABASE_URL 构建过程

graph TB
    ExplicitURL["os.environ.get('DATABASE_URL')"] --> CheckExplicit{"值存在？"}

    CheckExplicit -->|是| UseDirect["DATABASE_URL = value"]
    CheckExplicit -->|否| CheckComponents{"所有组件<br/>环境变量已设置？"}

    DbType["DATABASE_TYPE<br/>(sqlite/postgresql/mysql)"] --> CheckComponents
    DbUser["DATABASE_USER"] --> CheckComponents
    DbPass["DATABASE_PASSWORD"] --> CheckComponents
    DbHost["DATABASE_HOST"] --> CheckComponents
    DbPort["DATABASE_PORT"] --> CheckComponents
    DbName["DATABASE_NAME"] --> CheckComponents

    CheckComponents -->|是| BuildURL["DATABASE_URL = f'{DATABASE_TYPE}://..."]

    CheckComponents -->|否| UseDefault["DATABASE_URL = f'sqlite:///{DATA_DIR}/webui.db'"]

    FinalURL["DATABASE_URL 常量"]
    UseDirect --> FinalURL
    BuildURL --> FinalURL
    UseDefault --> FinalURL

    FinalURL --> EngineInit["internal/db.py:<br/>engine = create_engine(DATABASE_URL)"]

来源： backend/open_webui/env.py:23-25, backend/open_webui/config.py:57-75

Redis 配置
变量默认值描述
REDIS_URL""Redis 连接 URL backend/open_webui/env.py:27。
REDIS_KEY_PREFIXopen-webui所有 Redis 键的前缀 backend/open_webui/env.py:28。
REDIS_SENTINEL_HOSTS""逗号分隔的 Sentinel 主机列表 backend/open_webui/env.py:29。
REDIS_SENTINEL_PORT26379Sentinel 端口 backend/open_webui/env.py:30。

来源： backend/open_webui/env.py:27-30

认证与安全
变量默认值描述
WEBUI_AUTHTrue启用认证 backend/open_webui/env.py:34。
WEBUI_SECRET_KEY""JWT 令牌和会话的密钥 backend/open_webui/utils/auth.py:39。
JWT_EXPIRES_IN4wJWT 令牌过期时间 backend/open_webui/utils/oauth.py:66。
ENABLE_OAUTH_SIGNUPTrue允许通过 OAuth 注册新用户 backend/open_webui/utils/oauth.py:39。
ENABLE_LDAPFalse启用 LDAP 认证 backend/open_webui/routers/auths.py:52。
WEBUI_AUTH_TRUSTED_EMAIL_HEADERNone受信任电子邮件头名称（SSO） backend/open_webui/routers/auths.py:35。
WEBUI_AUTH_COOKIE_SECUREFalse要求 Cookie 使用 HTTPS backend/open_webui/routers/auths.py:40。

来源： backend/open_webui/env.py:34-40, backend/open_webui/routers/auths.py:33-56

LLM 提供商配置
Ollama 设置
变量默认值描述
ENABLE_OLLAMA_APITrue启用 Ollama 集成 backend/open_webui/main.py:129。
OLLAMA_BASE_URLS["/ollama"]Ollama API 基础 URL 列表 backend/open_webui/main.py:130。
OpenAI 设置
变量默认值描述
ENABLE_OPENAI_APITrue启用 OpenAI API 集成 backend/open_webui/main.py:133。
OPENAI_API_BASE_URLS[""]OpenAI API 基础 URL 列表 backend/open_webui/main.py:134。
OPENAI_API_KEYS[""]OpenAI API 密钥列表 backend/open_webui/main.py:135。

来源： backend/open_webui/main.py:129-136, Dockerfile:76-80

RAG 与检索配置
变量默认值描述
RAG_EMBEDDING_ENGINE""嵌入引擎（local、ollama、openai、azure_openai） backend/open_webui/main.py:255。
RAG_EMBEDDING_MODELsentence-transformers/all-MiniLM-L6-v2嵌入模型名称 backend/open_webui/main.py:244。
RAG_RERANKING_ENGINE""重排序引擎 backend/open_webui/main.py:247。
RAG_RERANKING_MODEL""重排序模型名称 backend/open_webui/main.py:248。

来源： backend/open_webui/main.py:240-265, Dockerfile:91-95

PersistentConfig 系统

PersistentConfig 系统允许通过管理界面在运行时更新配置，同时保留环境变量默认值。配置值存储在数据库的 config 表中 backend/open_webui/config.py:78-86。

AppConfig 实现

AppConfig 类提供基于属性的配置访问，具有自动持久化和 Redis 同步功能。它包装了 PersistentConfig 实例，并管理 _state 字典。

关键方法：

  • __setattr__：更新本地状态并触发 save_to_db backend/open_webui/config.py:93-104。
  • __getattr__：从本地状态检索值，如果可用则从 Redis 刷新以确保多节点一致性。
  • async_save_to_db：用于所有运行时配置持久化的异步版本 backend/open_webui/config.py:107-122。

来源： backend/open_webui/config.py:78-122, backend/open_webui/config.py:214-286

运行时配置更新

配置值通过后端逻辑更新，通常由管理 API 调用触发。当通过 AppConfig 更新值时，会触发数据库同步和注册表更新。

配置更新流程

sequenceDiagram
    participant UI as 管理设置
    participant API as FastAPI 路由
    participant AppState as app.state.config (AppConfig)
    participant PC as PersistentConfig 实例
    participant DB as 数据库 (config 表)
    participant Redis as Redis 缓存

    UI->>API: 提交配置更改
    API->>AppState: setattr(key, value)
    AppState->>PC: 更新实例中的值
    AppState->>DB: async_save_to_db(new_config_data)
    AppState->>Redis: set(redis_key, value)
    PC->>PC: 触发注册表更新()
    Note over PC: 更新本地实例状态
    API-->>UI: 200 OK

来源： backend/open_webui/config.py:192-206, backend/open_webui/config.py:107-122