环境变量配置
概览
OPL 数据空间 提供了大量环境变量，用来定制应用的认证、模型路由、存储、日志、检索、扩展能力等行为。本页是这些变量的中文化高频总览，重点先覆盖部署时最常会碰到的入口、通用 区块和容易踩坑的 PersistentConfig 机制。
如果你只是在找某一个具体设置，优先用浏览器搜索；如果你在做部署变更，建议先从下面的分类导航开始，而不是从头到尾顺序阅读整页。
本页当前优先覆盖高频配置路径与最常用变量，细分 provider / RAG / 存储 / observability 的全部条目会继续逐段补全。
快速导航
以下这些类别最适合先读：
- 身份、注册与管理员初始化：
WEBUI_URL、ENABLE_SIGNUP、WEBUI_ADMIN_EMAIL、OAuth / SCIM - 组织与混合作用域管理：
DEFAULT_ORGANIZATION_ID、ORGANIZATION_*配置映射 - 模型与 provider 连接：Ollama、OpenAI、direct connections、task models、图像 provider
- RAG 与检索：内容提取、embedding、rerank、向量数据库
- 存储与数据库：
DATABASE_URL、向量数据库、对象存储、Redis - 日志、审计与可观测性：audit logs、JSON logging、OpenTelemetry
本页会同时记录部分兼容别名与过时变量名。新部署应优先采用新的 canonical name；只有在维护老环境时，才建议继续使用 legacy alias。
关于 PersistentConfig
重要说明：PersistentConfig 环境变量
首次启动 OPL 数据空间 时，所有环境变量都一样对待，都会参与配置应用。
但对于被标记为 PersistentConfig 的变量，它们的值会被持久化存进数据库。之后如果你重启容器，这些变量就不再优先读取外部环境变量，而是优先采用数据库里已经保存的值。
普通环境变量则会在每次重启时继续从外部环境中读取并生效。
如果你想关闭这套行为，强制 OPL 数据空间 总是以环境变量为准，请设：
ENABLE_PERSISTENT_CONFIG=False重要警告： 当 ENABLE_PERSISTENT_CONFIG=False 时，你在 Admin UI 中修改这些设置，看起来仍然会暂时生效，但重启后会丢失，因为系统会重新回到环境变量定义的值。
环境变量改了却看起来没生效
最常见原因就是：这个设置已经被数据库中的 PersistentConfig 覆盖了。
有四种处理方式：
方式 1：临时关闭 PersistentConfig
ENABLE_PERSISTENT_CONFIG=False这样系统会强制从环境变量读取配置，但 UI 中修改不会持久化。
方式 2：直接在 Admin UI 中改（推荐）
对大多数场景，最安全的方式就是直接在 OPL 数据空间 的 管理员面板 里更新这些持久化配置。
方式 3：手改数据库（只在锁 死或无法进入 UI 时使用）
docker exec -it open-webui sqlite3 /app/backend/data/webui.db "UPDATE config SET data = json_set(data, '$.ENABLE_SIGNUP', json('true'));"方式 4：做真正的全新安装
- 停止容器
- 删除持久卷
- 重启容器
删除卷会清空用户数据、聊天记录和账号。
组织感知管理配置
启用了 组织 后，并不是所有管理员设置都还是“整个实例的一把总开关”。
- 有些值仍然是实例级全局的
- 有些值可以按当前选中的组织覆写
- 有些组织级覆写可以委派给 organization admin，有些则只能由 global admin 控制
如果某个设置在一个租户里看起来正确，在另一个租户里却不对，先确认 Admin switcher 当前选中的组织，再结合 Admin Scope 一起分析。
App / Backend
下面这些变量主要来自 backend/open_webui/config.py，控制 OPL 数据空间 的启动行为。
通用
WEBUI_URL
- 类型：
str - 默认值：
http://localhost:3000 - 说明：定义你的 OPL 数据空间 可被外部访问的 URL。OAuth / SSO、搜索引擎支持等能力都依赖它。
- 持久化：
PersistentConfig
在启用 OAuth / SSO 之前，必须先正确设置 WEBUI_URL。
ENABLE_SIGNUP
- 类型：
bool - 默认值：
True - 说明：控制是否允许注册 新用户
- 持久化：
PersistentConfig
ENABLE_INITIAL_ADMIN_SIGNUP
- 类型：
bool - 默认值：
False - 说明：旧式 first-admin bootstrap 开关。现在多数部署更推荐直接使用
WEBUI_ADMIN_EMAIL/WEBUI_ADMIN_PASSWORD
ENABLE_SIGNUP_PASSWORD_CONFIRMATION
- 类型：
bool - 默认值：
False - 说明：如果设为
True，注册页会额外出现 “Confirm Password” 字段
WEBUI_ADMIN_EMAIL
- 类型：
str - 默认值：空
- 说明：在数据库还没有任何用户时，用它自动创建管理员账号
这个变量适合自动化 / 容器化部署，只会在满足以下条件时生效：
- 数据库中还没有任何用户
- 同时配置了
WEBUI_ADMIN_EMAIL和WEBUI_ADMIN_PASSWORD
WEBUI_ADMIN_PASSWORD
- 类型：
str - 默认值：空
- 说明：与
WEBUI_ADMIN_EMAIL配合使用，定义自动创建管理员时的密码
生产环境请使用强密码，并优先通过 secrets manager 注入，不要把它硬编码进配置文件。
WEBUI_ADMIN_NAME
- 类型：
str - 默认值：
Admin - 说明：自动创 建管理员时使用的显示名
ENABLE_LOGIN_FORM
- 类型：
bool - 默认值：
True - 说明：控制登录页中的邮箱、密码和登录表单元素是否显示
- 持久化：
PersistentConfig
ENABLE_PASSWORD_CHANGE_FORM
- 类型：
bool - 默认值：
True - 说明：控制 设置 > Account 中是否显示密码修改 UI
- 持久化：
PersistentConfig
ENABLE_PASSWORD_AUTH
- 类型：
bool - 默认值：
True - 说明：控制是否允许密码登录。当你已经稳定启用 SSO，并把实例暴露到公网时，通常应改为
False
如果你是纯 SSO 登录环境，建议设为 False，避免密码登录入口成为额外攻击面。
只有当 OAuth / SSO 已经真的启用时，才应该关闭密码认证。否则你会把自己彻底锁在系统外面。
DEFAULT_LOCALE
- 类型：
str - 默认值：
en - 说明：设置应用默认语言
- 持久化：
PersistentConfig
DEFAULT_MODELS
- 类型：
str - 默认值：空
- 说明：设置默认语言模型
- 持久化：
PersistentConfig
DEFAULT_PINNED_MODELS
- 类型：
str - 默认值：空
- 说明：给新用户预先固定的模型列表，逗号分隔
- 持久化：
PersistentConfig
DEFAULT_MODEL_METADATA
- 类型：
dict（JSON） - 默认值：
{} - 说明：给所有模型提供全局默认 metadata / capabilities 基线
- 持久化：
PersistentConfig
DEFAULT_MODEL_PARAMS
- 类型：
dict（JSON） - 默认值：
{} - 说明：给所有模型提供默认推理参数，例如 temperature、top_p、max_tokens、function_calling
- 持久化：
PersistentConfig
DEFAULT_USER_ROLE
- 类型：
str - 可选值：
pending/user/admin - 默认值：
pending - 说明：定义新用户默认角色
- 持久化：
PersistentConfig
DEFAULT_ORGANIZATION_ID
- 类型：
str - 默认值：空字符串
- 说明：定义注册、OAuth 注册或 SCIM 在没有显式组织上下文时所落到的默认组织
- 持久化：
PersistentConfig
这在组织化部署里非常关键。修改它只会影响新用户将来落到哪里，不会改变已有用户当前所属组织。
DEFAULT_GROUP_ID
- 类型：
str - 默认值：空
- 说明：新用户注册后自动分配的默认组 ID
- 持久化：
PersistentConfig
DEFAULT_GROUP_SHARE_PERMISSION
- 类型：
str - 可选值：
members/true/false - 默认值：
members - 说明：定义新建组默认“谁可以向这个组共享”
ENABLE_CALENDAR
- 类型：
bool - 默认值：
True - 说明：是否启用日历
- 持久化：
PersistentConfig
ENABLE_CHANNELS
- 类型：
bool - 默认值：
False - 说明：是否启用频道
- 持久化：
PersistentConfig
ENABLE_FOLDERS
- 类型：
bool - 默认值：
True - 说明：是否启用聊天文件夹
- 持久化：
PersistentConfig
ENABLE_AUTOMATIONS
- 类型：
bool - 默认值：
True - 说明：是否全局启用自动化
- 持久化：
PersistentConfig
ENABLE_NOTES
- 类型：
bool - 默认值：
True - 说明：是否启用笔记
- 持久化：
PersistentConfig
ENABLE_MEMORIES
- 类型：
bool - 默认值：
True - 说明：是否启用记忆
- 持久化：
PersistentConfig
ENABLE_ADMIN_EXPORT
- 类型：
bool - 默认值：
True - 说明：控制管理员能否导出数据、聊天和数据库
ENABLE_ADMIN_CHAT_ACCESS
- 类型：
bool - 默认值：
True - 说明：控制管理员能否直接查看其他用户聊天
ENABLE_ADMIN_ANALYTICS
- 类型：
bool - 默认值：
True - 说明：控制 管理员面板 中是否显示分析
BYPASS_ADMIN_ACCESS_CONTROL
- 类型：
bool - 默认值：
True - 说明：为
True时，管理员默认可看见所有工作区资源；为False时，管理员也只会看见自己被显式授权的资源
ENV
- 类型：
str - 可选值：
dev/prod - 说明：定义运行环境。
dev会开放/docs，Docker 默认通常是prod
ENABLE_PERSISTENT_CONFIG
- 类型：
bool - 默认值：
True - 说明：控制系统是否优先读取数据库中的持久化配置
下一步建议
如果你当前的重点是：
- SSO / 注册 / 用户接入：继续读 认证与访问控制
- 组织与租户边界：继续读 组织
- 扩缩容 / 数据库 / Redis / 向量数据库：继续读 扩展 OPL 数据空间
- API / 文件上传 / RAG 接口：继续读 API 端点
后续我会继续把这份中文页往下扩展到：
- 日志
- Ollama / OpenAI / Tasks
- 直连
- 评测 / API Key 限制
- 存储 / RAG / 可观测性
兼容锚点速查
下面这些小节先用于承接中文站点里已经存在的高频跳转。当前阶段它们提供的是中文定位入口和最小解释；对应的完整变量说明会继续补到本页正文。
API Key 与认证
CUSTOM_API_KEY_HEADER
用于定义替代 Authorization 的自定义 API Key 请求头名称。常见于前置代理已经占用 Authorization 头的部署。
WEBUI_SECRET_KEY
多副本和 OAuth 场景中的关键共享密钥。未统一配置时，常见症状是登录循环、401 和会话不一致。
ENABLE_OAUTH_TOKEN_EXCHANGE
是否启用 OAuth token exchange 端点，允许外部应用把 IdP token 换成 OPL 数据空间 JWT。
权限与功能开关
USER_PERMISSIONS_FEATURES_CALENDAR
控制普通用户是否拥有日历功能权限。
USER_PERMISSIONS_FEATURES_AUTOMATIONS
控制普通用户是否拥有 Automations 功能权限。
USER_PERMISSIONS_FEATURES_FOLDERS
控制普通用户是否拥有 Folders 功能权限。
USER_PERMISSIONS_FEATURES_MEMORIES
控制普通用户是否拥有 Memories 功能权限。
自动化与日历
CALENDAR_ALERT_LOOKAHEAD_MINUTES
定义日历提醒预判窗口，单位为分钟。
SCHEDULER_POLL_INTERVAL
调度器轮询周期，统一影响自动化和日历提醒。
AUTOMATION_MAX_COUNT
限制普通用户可创建的自动化数量上限。
AUTOMATION_MIN_INTERVAL
限制普通用户自动化任务允许的最短重复间隔。
Tasks 与自动生成
TASK_MODEL
定义用于标题、标签、自动补全、追问等辅助任务的模型。
TASK_MODEL_EXTERNAL
定义外部辅助任务模型，在某些部署里用于把任务模型与主推理模型解耦。
ENABLE_AUTOCOMPLETE_GENERATION
控制是否启用输入自动补全生成。
ENABLE_REALTIME_CHAT_SAVE
控制聊天是否以更实时的方式落库，性能排障中经常会检查这个值。
ENABLE_BASE_MODELS_CACHE
控制基础模型列表缓存。
MODELS_CACHE_TTL
模型缓存 TTL，常用于排查模型列表刷新延迟。
ENABLE_QUERIES_CACHE
控制查询缓存。性能排障和高频请求优化时可能需要一起检查。
存储、数据库与扩缩容
DATABASE_URL
主数据库连接串。扩缩容时，SQLite 通常应迁移到 PostgreSQL。
DATABASE_POOL_SIZE
数据库连接池大小，高并发环境中常需要配合实例数一起调优。
DATABASE_ENABLE_SESSION_SHARING
控制数据库层的 session sharing 行为，多副本排障时可能涉及。
VECTOR_DB
向量数据库类型。多 worker / 多副本部署中通常不应继续使用默认本地 ChromaDB。
PGVECTOR_DB_URL
PGVector 的数据库连接串。
MARIADB_VECTOR_DB_URL
MariaDB Vector 的数据库连接串。
CHROMA_HTTP_HOST
独立 Chroma HTTP 服务的主机地址。
CHROMA_HTTP_PORT
独立 Chroma HTTP 服务的端口。
WEBSOCKET_MANAGER
WebSocket 状态管理方式。多副本部署常见配置是 redis。
ENABLE_WEBSOCKET_SUPPORT
是否启用 WebSocket 支持。
WEBSOCKET_REDIS_URL
当 WebSocket 通过 Redis 协调时使用的 Redis 地址。
CORS_ALLOW_ORIGIN
CORS 允许来源列表。反向代理和多域名排障时经常需要检查。
RAG 与内容处理
RAG_EMBEDDING_ENGINE
定义 embedding 引擎，例如 OpenAI、Ollama 等。
RAG_SYSTEM_CONTEXT
控制 RAG 拼装的系统上下文内容。
RAG_EMBEDDING_TIMEOUT
embedding 请求超时时间。
RAG_EMBEDDING_CONCURRENT_REQUESTS
embedding 并发请求数。
RAG_EMBEDDING_BATCH_SIZE
embedding 批大小。
ENABLE_ASYNC_EMBEDDING
是否启用异步 embedding。
CONTENT_EXTRACTION_ENGINE
定义文档内容提取引擎，例如 tika、docling 等。
FOLDER_MAX_FILE_COUNT
定义每个 folder 允许处理的文件数上限。
音频与图像
音频
音频相关设置总入口，包含 STT / TTS 与音频调用流程。
AUDIO_STT_ENGINE
定义语音转文本引擎。
BYPASS_PYDUB_PREPROCESSING
是否绕过 pydub 预处理。音频排障时常见。
ENABLE_IMAGE_GENERATION
是否启用图像生成能力。
网页搜索
网页搜索
网页搜索相关配置总入口，包含 provider、代理与网络行为。
WEB_SEARCH_TRUST_ENV
控制网页搜索请求是否信任环境中的代理等网络配置。
网络与超时
AIOHTTP_CLIENT_TIMEOUT_MODEL_LIST
模型列表拉取超时，模型连接故障时常被引用。
CHAT_RESPONSE_STREAM_DELTA_CHUNK_SIZE
流式输出 chunk 大小，性能与流式体验排障常见变量。
THREAD_POOL_SIZE
FastAPI / AnyIO 的线程池大小，大实例上经常需要显著调高。
插件与开发
WEBSOCKET_EVENT_CALLER_TIMEOUT
插件、工具开发与事件总线相关超时设置。
ENABLE_PIP_INSTALL_FRONTMATTER_REQUIREMENTS
是否允许根据 frontmatter requirement 自动安装 pip 依赖。插件开发文档常引用它。