12 · 设置与配置（Settings and Configuration）

设置与配置（中文译文）

原始 DeepWiki 页面：https://deepwiki.com/open-webui/open-webui/12-settings-and-configuration

翻译时间：2026-06-09T16:10:39.273Z

翻译模型：deepseek-chat

原文字符数：8847

项目：Open WebUI (open-webui)

---

设置与配置

相关源文件

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

• 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
• src/lib/components/chat/Settings/Interface.svelte
• src/lib/components/chat/SettingsModal.svelte
• src/lib/components/common/Modal.svelte
• src/routes/(app)/+layout.svelte/+layout.svelte)
• src/routes/(app)/+page.svelte/+page.svelte)
• [src/routes/(app)/c/[id]/+page.svelte](src/routes/(app)/c/[id]/+page.svelte)

本文档记录了 Open WebUI 中全面的设置与配置系统。该系统同时管理后端服务器配置和前端用户偏好，支持环境变量、数据库持久化以及分布式配置更新。

有关特定子系统的详细信息，请参阅以下子页面：

• 应用生命周期与布局 — 应用初始化与全局状态设置。
• PersistentConfig 系统 — 支持数据库持久化的后端配置。
• 设置界面 — SettingsModal 组件与用户偏好分类。
• 环境变量 — 所有系统环境变量的完整参考。

配置系统概述

Open WebUI 采用双层配置系统，以平衡静态部署需求与动态运行时灵活性：

1. 后端配置：通过环境变量管理的服务器级设置，可选数据库持久化。在分布式部署中，通过 Redis 在多个实例间同步。
2. 用户设置：存储在数据库中并通过前端设置模态框管理的每用户偏好（UI 主题、语言、默认模型）。

后端配置在应用启动时初始化 backend/open_webui/config.py:158，并可在运行时通过管理端点更新，无需重启服务器。

---

后端配置架构

PersistentConfig 系统

PersistentConfig 类 backend/open_webui/config.py:214-231 提供了一种混合机制，优先使用数据库存储的值而非环境变量。这使得管理员可以通过 UI 更改设置，而无需修改环境变量或重启容器。

配置流程示意图

graph TD
    subgraph "数据源"
        EnvVars["环境变量<br/>(os.environ)"]
        ConfigDB["SQL 数据库<br/>'config' 表"]
    end

    subgraph "核心逻辑"
        PersistentConfig["PersistentConfig[T]<br/>(open_webui/config.py:214)"]
        CONFIG_DATA["CONFIG_DATA<br/>(open_webui/config.py:158)"]
    end

    subgraph "同步"
        Redis["Redis Pub/Sub<br/>(open_webui/utils/redis.py)"]
    end

    EnvVars -->|初始值| PersistentConfig
    ConfigDB -->|覆盖值| PersistentConfig
    PersistentConfig -->|注册到| PERSISTENT_CONFIG_REGISTRY["PERSISTENT_CONFIG_REGISTRY<br/>(config.py:172)"]

    PERSISTENT_CONFIG_REGISTRY -->|触发更新| CONFIG_DATA
    CONFIG_DATA -->|广播| Redis

    FastAPI["FastAPI app.state.config<br/>(open_webui/main.py:127)"]
    CONFIG_DATA -->|注入到| FastAPI

来源：backend/open_webui/config.py:152-172，backend/open_webui/config.py:214-231，backend/open_webui/main.py:127

数据库持久化与更新

系统使用 SQLAlchemy 在 config 表中持久化配置状态 backend/open_webui/config.py:78-85。

• 初始化：配置从环境变量加载，然后被数据库 config 表中找到的任何值覆盖 backend/open_webui/config.py:152-158。
• 运行时更新：当调用 async_save_config 时 backend/open_webui/config.py:192-206，它会更新数据库并触发所有已注册 PersistentConfig 实例的 update() 方法。

详细信息请参阅 PersistentConfig 系统。

---

配置分类

应用与功能开关

核心应用行为由大量标志控制。这些标志决定了以下功能的可见性：

• 认证：WEBUI_AUTH、ENABLE_OAUTH_SIGNUP、ENABLE_LDAP。
• 图像生成：ENABLE_IMAGE_GENERATION、IMAGE_GENERATION_ENGINE。
• 音频：AUDIO_STT_ENGINE、AUDIO_TTS_ENGINE。

来源：backend/open_webui/main.py:129-212，backend/open_webui/config.py:48-56

RAG 与文档处理

检索增强生成（RAG）系统高度可配置，允许选择不同的嵌入和重排序引擎。

组件	关键代码实体 / 设置
嵌入	RAG_EMBEDDING_ENGINE、RAG_EMBEDDING_MODEL、get_embedding_function()
重排序	RAG_RERANKING_ENGINE、RAG_RERANKING_MODEL、get_reranking_function()
网络搜索	WEB_LOADER_ENGINE、FIRECRAWL_API_KEY、PLAYWRIGHT_WS_URL

来源：backend/open_webui/main.py:240-264，backend/open_webui/main.py:111-116

---

前端设置架构

SettingsModal 与用户偏好

SettingsModal.svelte 组件管理用户特定的偏好。这些设置存储在用户配置文件中，并通过 Svelte store 进行管理 src/lib/components/chat/SettingsModal.svelte:4-5。

设置界面层级结构

graph TD
    SettingsModal["SettingsModal.svelte<br/>(src/lib/components/chat/SettingsModal.svelte)"]
    SettingsStore["settings Store<br/>($lib/stores)"]
    UpdateAPI["updateUserSettings<br/>($lib/apis/users)"]

    subgraph "分类标签"
        General["General.svelte"]
        Interface["Interface.svelte"]
        Personalization["Personalization.svelte"]
        Connections["Connections.svelte"]
        Integrations["Integrations.svelte"]
        Audio["Audio.svelte"]
        Account["Account.svelte"]
    end

    SettingsModal --> General
    SettingsModal --> Interface
    SettingsModal --> Personalization
    SettingsModal --> Connections
    SettingsModal --> Integrations
    SettingsModal --> Audio
    SettingsModal --> Account

    Category_Tabs --> SettingsStore
    SettingsStore -->|持久化| UpdateAPI

SettingsModal.svelte 组件定义了不同设置分类的多个标签页，每个标签页由专用的 Svelte 组件处理 src/lib/components/chat/SettingsModal.svelte:10-16。allSettings 数组 src/lib/components/chat/SettingsModal.svelte:53-275 定义了可用的标签页及其用于设置搜索功能的关键词。

界面自定义

用户可以通过 Interface.svelte 子组件自定义体验，该组件管理 chatBubble、widescreenMode、richTextInput 和 textScale 等设置 src/lib/components/chat/Settings/Interface.svelte:27-105。 来源：src/lib/components/chat/Settings/Interface.svelte:177-182，src/lib/components/chat/SettingsModal.svelte:87-212

---

应用生命周期

初始化顺序确保在 UI 渲染之前环境已准备就绪：

1. 用户验证：+layout.svelte 确保存在有效的用户会话 src/routes/(app)/+layout.svelte:196-199。
2. 状态加载：应用通过 getUserSettings 获取用户设置 src/routes/(app)/+layout.svelte:89-93，并填充 models、tools 和 banners 的全局 store src/routes/(app)/+layout.svelte:205-215。
3. 动态配置：布局组件根据当前设置处理工具服务器和终端连接的初始化 src/routes/(app)/+layout.svelte:122-183。

详细信息请参阅 应用生命周期与布局。

---

环境变量

Open WebUI 支持广泛的环境变量，用于对部署进行精细控制。这些变量主要在 env.py 和 config.py 中定义和加载。

• 核心路径：DATA_DIR、OPEN_WEBUI_DIR、BACKEND_DIR backend/open_webui/env.py:26-35。
• 数据库：DATABASE_URL、ENABLE_DB_MIGRATIONS backend/open_webui/env.py:159。
• 日志：GLOBAL_LOG_LEVEL、LOG_FORMAT backend/open_webui/env.py:107-109。

完整列表请参阅 环境变量。 来源：backend/open_webui/env.py:129-158，backend/open_webui/config.py:22-37