Open WebUI 必备核心 (Essentials)
您已经完成了 Open WebUI 的安装、连接了模型服务商，并进行了第一次 AI 对话。本页面涵盖了六大核心要素，能将一个基础的聊天 UI 升级为一套非常契合日常高频工作流的高效系统。这些要素虽然都不是强制要求的，但绝大多数用户在第一周内都会陆续用到它们。
您可以按顺序阅读，或直接跳转到您感兴趣的章节：
- 工具调用 (Tool calling)
- 插件生态 (Plugins)
- 任务模型 (Task models)
- 上下文管理 (Context management)
- 基础检索增强生成 (Basic RAG)
- 打开终端 (Open Terminal)
- 常见故障排除 (Troubleshooting)
如果您正在为多用户团队搭建 Open WebUI，请同步阅读 大规模扩展 Open WebUI 指南。该指南涵盖了基础设施层面的决策（如 PostgreSQL 数据库、Redis 缓存、外部向量数据库、共享存储等），这与本页面侧重于功能层面的核心要素是相辅相成的。这两份指南相得益彰——阅读本篇以掌握日常使用的核心功能，阅读扩展指南以构建多用户基础设施。
工具调用 (Tool calling)
如果没有工具，大语言模型（LLM）就只能生成纯文本。而一旦赋予工具，它就能查阅实时信息、执行代码并代您执行操作。您只需将一个 Tool (工具) 绑定到对话（或模型）中，模型在响应过程中就会自主决定何时调用它、以及传入什么参数。Open WebUI 会代为执行该工具调用，将运行结果反馈给模型，模型随后结合这些新获取的 信息继续生成回答。
工具调用是把聊天模型升级为智能 Agent（代理）的关键钥匙。搞定这一步，将解锁本页面后续涵盖的大部分高级特性。
在起步阶段，有两点非常值得提前了解。
1. 理解工具调用模式 (Tool-calling modes)
Open WebUI 提供了两种将模型与工具连接的方式。这里最容易让人感到困惑的是：被标记为“Default（默认）”的模式，反而并不是绝大多数人应该使用的模式。一旦您了解了发展历史和 Open WebUI 的设计哲学，其命名就非常合乎逻辑了。
Default Mode 是历史遗留方案，旨在提供最广泛的兼容性。如果您的模型本身支持函数调用/工具调用（几乎所有现代大模型均原生支持），Native Mode 是远比其优秀的绝佳选择。请参阅下文了解如何进行切换。
Open WebUI 的一个核心目标是提供最广泛的模型兼容性，从前沿的闭源商业 API 到运行在 树莓派 (Raspberry Pi) 上的微型量化本地模型全线支持。在 Open WebUI 首次引入工具调用时，绝大多数模型还没有提供内置的函数调用（Function-calling）API。当时给模型赋予工具的唯一方法，是在系统提示词（System Prompt）中用纯文本向其描述这些工具，然后通过解析模型输出的文本，来人肉判断模型想要调用哪个工具。这种基于提示词引导的方案在 Open WebUI 中被称为 Default Mode。它是最初的（也是在当时唯一的）实现方案，现在被视为老旧的遗留机制。它之所以依然是系统默认值，是因为它代表了“最低通用标准”：任何只要能够遵循系统提示词指令的模型都能使用它，完全不需要 API 层面的特殊支持。
此后，几乎所有的主流模型服务商都加入了原生的函数调用支持。Open WebUI 将此称为 Native Mode。在这种模式下，工具的定义会作为 API 请求中结构化的一部分发送给模型，模型则在其响应中返回结构化的工具调用参数。这种方式速度更快、准确度极高、能完美保留 KV 缓存，并且是 Open WebUI 所有内置系统级工具（如记忆 Memory、便签 Notes、知识库 Knowledge、网页搜索 Web Search、图像生成 Image Gen、代码解释器 Code Interpreter）的硬性要求 。所有开发的新型工具调用功能均只针对 Native Mode。不过它仅适用于那些真正暴露了函数调用 API 的模型，这也就是为什么它无法被设为一刀切的通用默认值。
在实际使用中，绝大多数用户都应该开启 Native Mode。当前所有的主流模型（OpenAI, Anthropic, Gemini, Llama 3.1+, Qwen 2.5+, DeepSeek, GLM 等）都原生支持它。您只需一步即可为全站实例进行全局配置：
管理员面板 (Admin Panel) > 设置 (Settings) > 模型 (Models) → 点击模型列表右上方的 设置 (Settings) 按钮 → 将 Function Calling (函数调用) 设为 Native → 保存。从此，当前及未来新增的所有模型都将默认继承这一设置。
- 针对单个模型配置： 管理员面板 > 设置 > 模型 > [您的模型] > 模型参数 (Model Parameters) > Function Calling = Native
- 针对单个对话配置： 在对话的**右侧边栏（Chat Controls 聊天控制）**中进行勾选。
如果您运行的是较老的本地模型，或是没有暴露函数调 用 API 的特定微调模型，请将该特定模型保持在 Default Mode。除此之外的绝大多数场景，选择 Native Mode 都是明智之举。
2. 选择并启用工具
很多用户苦苦寻找的工具，其实早就已经内置在 Open WebUI 中了，只需在后台一键开启即可：网页搜索、代码执行、图片生成、记忆以及知识库检索均已开箱即用，无需安装任何插件。一旦开启，它们在 Native Mode 下会自动作为系统工具呈现给模型。
其中大部分工具仅需极为简单的配置（选择服务商、填入 API 密钥或开启开关）。以下是常用工具的配置指南：
- 网页搜索 (Web Search) — 连接搜索服务商（Google, Brave, DuckDuckGo, SearXNG 等），让模型可以联网查阅实时信息。
- 图像生成 (Image Generation) — 连接图片服务商（OpenAI DALL-E, ComfyUI, Automatic1111 等）在对话中直接作图。
- 代码执行 (Code Execution) — 直接在对话中运行代码块（默认在浏览器中运行 Pyodide，或连接 Jupyter 在服务器端执行）。
- 记忆 (Memory) — 让模型在跨越不同的对话时，依然能够记住关于您的偏好与事实。
对于系统没有内置的定制化功 能，非常推荐到 Open WebUI Community 官方社区网站 上浏览淘金。以下是部分已有的热门分类，以供参考：
- 可观测性与成本追踪：Langfuse, OpenLit, Portkey。将每一次对话的交互、Token 使用量和响应延迟无损记录到您自己的技术栈中。
- 智能家居与自动化：连接 Home Assistant 工具，让大模型能直接控制家中的智能设备、场景和自动化流水线。
- 学术科研：arXiv, PubMed, Semantic Scholar, Wolfram Alpha。提供带真实权威文献引用的结构化科研结果。
- 工单管理与协同沟通：Jira, Linear, GitHub Issues, Slack, Discord, Email 等。
- 数据库与 API 交互：针对您自有的数据库执行只读 SQL 查询，或直接调用您的内部 API 接口。
- 生活娱乐：天气查询、股票行情、加密货币、快递追踪、菜谱搜索等等。
工具会呈现在输入框的 + 菜单中。模型仅能看到并使用您为该次对话所启用了的工具。
Open WebUI Community 社区 托管了数以千计的由全球开发者贡献的实用插件。在您决定自己动手手写代码之前，不妨先去社区检索一下：按热度排序、按分类过滤，翻阅几页。绝大多数时候，早就有人已经帮您写好了您所需要的工具（或者其代码已经十分接近，您可以直接 Fork 过来微调）。
更多参考详情：
插件生态 (Plugins)
Open WebUI 开箱即提供了非常丰富的功能，但其真正的魅力在于强大的可扩展性。很多让人惊叹的高级演示功能（例如自动双语翻译、Token/成本费用精准监控、自定义响应后处理、特定云端服务商连接等），其实都是基于平台底层的插件 (Plugins) 架构实现的。理解插件生态，是新用户快速玩转平台的终极钥匙。
插件主要分为两大核心家族：Tools (工具) 和 Functions (函数)。
Tools 赋予模型在生成回答时可以主动调用的外部能力：
| 来源分类 | 核心作用 | 典型 示例 |
|---|---|---|
| 内置系统工具 | Open WebUI 自带的系统工具，只需在管理员面板启用即可，无需安装 | 网页搜索 (Web Search)、代码解释器 (Code Interpreter)、图像生成 (Image Generation)、记忆 (Memory)、便签 (Notes)、知识库检索 |
| 自定义插件 | ||
| ↳ 自定义 Tool | 您自己手写或从 社区官方网站 一键安装的 Python 代码。在 工作区 (Workspace) > 工具 (Tools) 中进行管理 | Langfuse / OpenLit 链路追踪监控、连接 Home Assistant 智能家居、arXiv / PubMed 学术检索、Wolfram Alpha 复杂计算、Jira / Linear 工单系统、执行 SQL 查询等 |
| ↳ 外部工具服务器 | 通过 MCP (Model Context Protocol) 或 OpenAPI 接入的外部微服务。在 管理员面板 > 设置 > 工具 中进行连接 | 您自有的微服务接口、第三方 API、现有的 MCP 服务器 |
Functions 则运行在平台系统级层面，可以直接干预并改变 Open WebUI 自身的交互行为。它包含三种形态：
| 类型 | 核心作用 | 典型示例 |
|---|---|---|
| Pipes (管道) | 在模型选择下拉菜单中注册一个全新的虚拟“模型”，其背后由自定义的 Python 代码驱动 | 根据提示词复杂度智能选择路由（简单句用便宜模型，复杂句路由给昂贵旗舰模型）、多步骤智能 Agent 环路、接入自定义 LLM 后端 |
| Filters (过滤器) | 在每一次请求发送给大模型前、以及大模型响应返回给用户时进行自动过滤拦截（对每一次对话轮次静默生效） | 自动剔除上下文过长历史、敏感信息脱敏（PII Scrubbing）、Token 数量与 API 开销计量、Langfuse 链路观测、输出格式强制重写 |
| Actions (动作按钮) | 在每一条消息的正下方新增一个自定义的动作按钮，供用户点击触发执行特定 Python 脚本 | “一键生成后续追问”、“一键翻译该条回答”、“一键置顶本条消息”、“一键保存至知识库” |
无论是 Tools 还是 Functions，您都可以非常方便地在 Open WebUI Community 社区网站 上一键预览和安装。您也可以直接在管理员面板里从零编写自己的插件代码。
如何安装插件
Open WebUI Community 社区网站 为 Tools 和 Functions 提供了一键安装目录。只需挑选您中意的插件，点击 "Get"，将其代码复制并粘贴进您的 Open WebUI 管理员面板，开启它，并配置好其对应的 Valves (阀门，即该插件的配置 项) 即可。
当您脑海中冒出“要是 Open WebUI 能实现某个功能就好了”的想法时，通常早就有开发者通过插件实现了这一功能。社区里有数以千计的高质量插件，您需要的往往就在那里。即便没有百分之百匹配的，您也可以在管理员面板里直接一键 Fork 最接近的插件代码，通常只需微调个 20 来行代码就能完全契合您的专属诉求。
深入阅读参考：
任务模型 (Task models)
在默认情况下，系统后台的一些杂务（如生成对话标题、打标签、自动补全等）会调用您的当前主聊天模型。配置一个专属的轻量级任务模型，是提升响应速度并大幅削减不必要 API 费用的最简单有效手段。
每当 Open WebUI 需要为网页 UI 界面执行一些辅助性的微型“思考”任务（例如在左侧边栏为新对话起一个简短的标题、生成分类标签、推荐后续追问问题、或是支持输入框中的提示词自动补全）时，它都会调用一个 Task Model (任务模型)。默认情况下，这个任务模型就是您当前正在对话的主模型，这意味着：
- 每次您开启新对话，仅仅为了在侧边栏生成“买菜清单”这四个字，就会调用您昂贵的商业旗舰大模型。
- 在运行较慢的本地模型时，每一次键盘敲击都会感觉卡顿，因为自动补全功能正在焦急等待一个 30B 参数的模型给出响应。
- 像 o1, r1 或开启了深度思考（extended thinking）的 Claude 模型，可能会在花五秒钟深度思考后，才生产出三个字的简短标题。
由于这些任务全部在后台默默运行，极易被忽略。配置一个专属的任务模型是一笔极为划算且能带来明显丝滑体验的微调。
修复方案： 在 管理员面板 > 设置 > 界面 (Interface) 中，配置专属的 Task Model。这里有两个输入框，因为最合理的选择取决于您聊天的主模型是云端还是本地：
- Task Model (External) 云端任务模型：设为一个响应极快、资费极低且不需要推理思考的云端轻量模型，例如
gpt-5-nano、gemini-2.5-flash-lite或llama-3.1-8b-instant。 - Task Model (Local) 本地任务模型：设为一个极小尺寸的本地模型，例如
qwen3:1b、gemma3:1b或llama3.2:3b。
这样，您的主聊天体验不会受到任何影响，而后台的杂务任务将瞬间变得轻盈流畅，不再拖累系统。
在界面设置（Interface Settings）页面中，如果您在一台配置较低的机器上运行，或者单纯不想使用这些辅助特性，您也可以选择将这些后台任务彻底关闭。每一项都在该页面配有对应的管理员开关（Admin Toggle），也可以通过系统环境变量进行一刀切控制：
| 后台任 务 | 界面开关 (设置 > 界面) | 系统环境变量 |
|---|---|---|
| 自动提示词补全 (在每次键盘敲击时触发) | Autocomplete Generation | ENABLE_AUTOCOMPLETE_GENERATION=False |
| 后续问题追问生成 | Follow-up Generation | ENABLE_FOLLOW_UP_GENERATION=False |
| 对话标题自动生成 | Title Generation | ENABLE_TITLE_GENERATION=False |
| 对话分类标签自动生成 | Tags Generation | ENABLE_TAGS_GENERATION=False |
在配置较低的本地硬件上，“自动提示词补全”是影响系统响应灵敏度单一大诱因。因为它会在您每次敲击键盘时频繁触发，一个缓慢的任务模型会让整个提示词输入框变得像糖稀一样粘滞卡顿。如果感觉 UI 界面响应不灵敏，请第一时间将此功能关闭。
更多性能调优详情请参阅：性能与显存调优：配置专属任务模型。
上下文管理 (Context management)
随着长对话的持续深入，您最终必定会遇到如下报错：
The prompt is too long: 207601, model maximum context length: 202751
该报错源自您的模型服务商，而不是 Open WebUI 平台。每次您发送新消息时，整场对话的全部内容（包括系统提示词、之前所有的来回对话、附加的本地文件、工具调用返回的结果以及您的最新消息）都会作为整体被打包成“Prompt（提示词）”发送给大模型。当总字数超过了该模型的上下文窗 口（Context Window）极限时，服务商就会拒绝该请求。
Open WebUI 在系统设计上没有内置一刀切的自动裁剪器，因为：
- 每个模型都使用完全不同的分词器（Tokenizer）（GPT、Claude、Gemini、GLM、Llama 的分词算法千差万别）。
- 每个模型的上下文窗口上限也完全不同（从 8k 到 1M+ 不等）。
- 每个不同的部署业务都需要完全不同的裁剪策略（有的希望按 Token 数裁剪，有的希望按对话轮数裁剪，有的希望优先丢弃大附件，有的希望对历史消息自动总结等）。
这里并没有单一的黄金标准。官方支持的优雅解决之道是：安装一个裁剪功能的过滤器函数（Filter Function），以完全契合您业务的规则去自动裁剪上下文。
社区中早就存在针对各种裁剪策略的一键安装过滤器。如果觉得不完全契合，其代码也极其简短，非常容易复制并自行修改。请参阅我们包含“仅保留最新 N 轮对话”超轻量过滤器的完整排障指南：排障指南：上下文窗口/提示词超长解决方案。
基础检索增强生成 (Basic RAG)
RAG (检索增强生成) 是一项极其强大的技术，能让您直接对大模型说：“这是一份 400 页的 PDF，请帮我回答关于它的问题”，而无需让大模型在每次对话轮次中都傻傻地通读整本书。Open WebUI 会聪明地把您上传的文档切割成小块，将其向量化（Embeds），存储在向量数据库中。在聊天时，系统仅提取与您提问最相关的几个小块提供给大模型，从而实现精准的高效回答。
系统提供了两种使用 RAG 的方式，按简易度排序：
- 即时聊天附件：直接将一个或多个本地文件拖入任何对话的输入框并提问。文件会被自动切割和向量化，且仅对该次对话生效。
- 企业级知识库：对于您想在不同对话中反复复用的文档（如员工手册、产品源码库、科研文献库、用户操作指南等），请前往 工作区 (Workspace) > 知识库 (Knowledge) 创建知识库。您可以在聊天时通过在输入框中输入
#快捷键将整个知识库绑定到对话中，或者在 工作区 > 模型 里将知识库直接绑定到特定模型上，让该模型在每一次对话中都默认拥有这些知识背景。
对于起步阶段，系统默认的参数是完全够用的。当您的文档规模扩大、默认参数无法满足要求时，以下三个核心配置将变得至关重要：
- Embedding 向量模型引擎：默认在本地 CPU 上运行轻量级的 SentenceTransformers（
all-MiniLM-L6-v2模型），这会在每个 Worker 进程中消耗大约 500 MB 的 RAM 内存。对于多用户生产部署，极其推荐通过RAG_EMBEDDING_ENGINE环境变量，将向量化工作指向外部的 API（例如 OpenAI，或在本地 Ollama 中运行nomic-embed-text）。 - 文本提取引擎：系统默认使用
pypdf，在处理大规模高频文档导入时容易发生内存泄漏。若需要处理更复杂的企业级文档，建议通过CONTENT_EXTRACTION_ENGINE环境变量切换为更健壮的 Tika 或 Docling 引擎。 - 向量数据库 (Vector Database)：默认自带的 ChromaDB（基于本地 SQLite 文件存储）不支持多 Worker/多副本（multi-replica）的并发写入。一旦进入生产级规模，PGVector 是唯一由 Open WebUI 官方团队直接支持、维护并推荐的向量数据库。尽管系统也提供了 Milvus, Qdrant 和 MariaDB Vector 的接口，但这三者目前均属于社区维护（Community-maintained），在系统升级时存在兼容性风险，且排障高度依赖社区回馈。配置详情请参阅 环境变量参考配置手册 以及各服务商的社区免责声明。
如果只是“单个用户使用，偶尔上传几份 PDF”，您完全不需要担心上述任何优化。当您的系统拥有 100 份以上的常驻文档，或者有 10 个以上的用户在并发访问时，这些优化才会开始展现其非凡的价值。
官方推荐的基础 RAG 优化配置
如果您希望知识库和文档对话在开箱即用时就拥有极佳的表现，以下配置是一套非常扎实、通用的黄金起点。虽然它们并非针对每个细分场景都进行了微调，但对于绝大多数常见的文档类型，它们所产生的召回效果将明显优于系统的初始默认配置。
请前往 管理员面板 (Admin Panel) > 设置 (Settings) > 文档 (Documents) 进行如下配置：
| 核心配置项 | 官方推荐推荐值 | 系统默认初始值 | 推荐原因分析 |
|---|---|---|---|
| 文本分割器 (Text Splitter) | token | character | 基于 Token 数的切割，在跨越不同格式的文档时，能产生更稳定、大小更均匀的段落切片 |
| Markdown 标题关联分割 | 开启 (On) | 开启 | 尊重文档原有的逻辑大纲结构，优先在标题级别（Heading）进行切割，保持章节语意的高连贯性 |
| 切片尺寸 (Chunk Size) | 2000 | 1000 | 更大的切片尺寸能为每次召回提供更丰富的上下文信息背景 |
| 切片重叠量 (Chunk Overlap) | 200 | 100 | 更大的重叠区间能极大避免一个关键核心长句在分割时被生硬切断的尴尬情况 |
| 最相关提取量 (Top K) | 15 | 3 | 检索并提取出更多候选切片，为大模型提供更全面相关的知识背景。如果您使用的是上下文窗口极其狭窄的本地微型大模型，建议将此调低至 5，以防向量切片把模型的上下文窗口塞满 |
| 向量模型 (Embedding Model) | 外部 API (OpenAI 或 Ollama) | all-MiniLM-L6-v2 (本地 CPU) | 默认模型只适合单人起步，每个 Worker 进程会吃掉约 500 MB 内存。对于多用户生产环境，建议完全委托给外部高并发向量 API |
默认的 SentenceTransformers 模型在本地 CPU 上跑，适合个人玩票起步。对于任何正式的部署，将其指向外部的高并发向量 API 才是正道：设置 RAG_EMBEDDING_ENGINE=openai 并填入 OpenAI API 密钥，或者设置 RAG_EMBEDDING_ENGINE=ollama 并使用任何高并发 Ollama 向量模型（如 nomic-embed-text）。这能瞬间卸载本地 CPU 的计算压力并释放大量的物理 RAM 内存。
RAG 深度阅读参考：
- RAG 检索增强生成架构指南
- 知识库工作区管理
- 如何调优 RAG 性能
- 扩展部署：切换为外部向量数据库 — 多 Worker 及多 Replica 并发集群部署的硬性要求
- 扩展部署：优化文本解析与向量化 — 彻底解决生产环境下的内存泄漏痛点
打开终端 (Open Terminal)
如果仅仅是在沙盒里“运行几行 Python 代码”对您而言还不够过瘾，如果您渴望让大模型真正像一位高级程序员那样在您的真实系统上干重活（例如：自动克隆 GitHub 代码仓库、在终端自动安装软件包、自动运行测试用例集、在本地自动拉起一个网页的实时预览服务、或是直接针对您的真实本地 CSV 数据表格进行多轮复杂的交互分析），这正是 Open Terminal 诞生的伟大意义。它能将一个真实的终端 Shell（默认安全地沙箱隔离在 Docker 容器中运行，若您有需求也可以直接以裸机特权运行）作为一个 Tool 绑定给大模型。同时还配套了极具生产力的对话内文件浏览器、网页实时预览以及自定义技能（Skills）定义。
一旦您跨越了基础的聊天阶段，这绝对是最能让您发出“哇”赞叹的核心亮点！它彻底将 Open WebUI 从一个简单的聊天前端，升华为一个让大模型真正为您干脏活累活的“自动构建港湾”。如果开启了 Native Mode 且赋予了大模型一个具有特权的终端，试着命令它：“帮我写一个小程序并在终端跑起来，或者分析这整个文件夹里的杂乱文件”，然后静静地坐下来，看着它自动在终端里狂飙！
更多参考详情：
接下来该怎么做
您完全不需要在第一天就急于把上述所有配置全部配齐。对于一个新安装的系统，以下是一条非常舒适的渐进式旅程建议：
- 第一天：挑选一个优秀的主模型作为默认，进行几次畅快的聊天，熟悉一下网页 UI 的各个交互区域。
- 第一天之后首要的事：配置好一个轻量级的 Task Model (任务模型)，并仔细挑选您真正需要保留的辅助后台任务。这是能瞬间让系统反应速度“脱胎换骨”且立竿见影砍掉隐形 API 支出的最佳优化。
- 在第一周内：在管理员面板全局一键开启 Native Mode，并安装一两个与您日常工作高度契合的 Tools (工具) 插件。
- 在您遭遇瓶颈时：当您第一次看到“提示词上下文太长”的报错时，别慌，花五分钟安装一个上下文自动裁剪过滤器（Filter Function）。
- 在您需要沉淀知识时：当您第一次希望大模型同时理解您的多份本地文档并进行交叉回答时，去 Workspace 里 创建一个 Knowledge (知识库)。
- 当您准备好见证奇迹时：将 Open Terminal 赋予您的模型，见证大模型在您的终端里为您自动构建现实世界的应用程序。
- 当您的系统规模扩大时：一旦系统接入了更多的并发用户，回过头来，认真阅读 RAG 向量数据库与文本分析引擎的生产级集群配置章节。
至于其他更高级的课题（如企业级单点登录 SSO、多节点高可用 HA 部署、Redis 状态共享、全局 OpenTelemetry 日志审计等），当您真正面临对应生产环境挑战时，再去阅读 进阶主题 与 故障排除 即可。
常见故障排除 (Troubleshooting)
一旦系统遇到状况，从这里开始排查往往事半功倍：
| 故障现象描述 | 官方推荐推荐排障指南 |
|---|---|
| 连接被拒绝、401 身份校验失败、CORS 跨域报错、WebSocket 断连 | 排障：连接错误处理 |
| “Prompt is too long” 提示词上下文超长报错 | 排障：上下文超长解决方案 |
| RAG 知识库检索不相关、文档上传失败、知识库配置异常 | 排障：RAG 检索问题排查 |
| 网页搜索（联网搜索）不工作或检索质量低下 | 排障：网页搜索排查 |
| 图像生成失败或图像服务商接入异常 | 排障：图像生成排查 |
| 语音输入（STT）、语音朗读（TTS）或音频播放异常 | 排障：音频语音排查 |
| 单点登录 SSO、OAuth 2.0 或 LDAP 认证登录失败 | 排障：SSO 与三方登录排查 |
| 物理内存吃紧、大模型响应极为缓慢或 Worker 进程频繁崩溃 | 排障：性能与内存优化 · 集群扩展指南 |
| 多节点高可用集群中，发生无限登录循环、配置漂移或数据库死锁 | 排障：多副本与高可用排查 · 集群扩展指南 |
| 管理员（Admin）账号忘记密码被锁死在外面 | 运维：重置管理员密码 |
| 使用了企业内部自签 CA 证书导致 TLS 握手失败 | 安全：自签 CA 证书信任配置 |
| 数据库 Alembic 迁移报错或需要手动执行 SQL 迁移 Schema | 运维：数据库手动迁移与修复 |
还有疑问？
本页面是必备知识的极简浓缩版，完整的官方文档库对此有极为广博和深邃的探索。如果您没有在此找到所需的解答，非常推荐通过以下渠道获取支持：
- 检索官方文档库：善用页面顶部的全局搜索框。文档库里涵盖的技术细节要远远多于本篇必备知识的篇幅。
- 在 GitHub Discussions 讨论区提问：最适合探讨开放式课题、新特性论证以及“如何用 Open WebUI 实现某某奇思妙想”的话题。讨论区完全公开可检索，能持续造福后来的社区伙伴。
- 加入 Discord 官方群组提问：这里拥有全网最活跃的技术讨论氛围。可以前往
#questions频道寻求解答；那里还配备了一台深度学习了全套官方文档及 Issue 知识背景的 AI 机器人，通常能在几秒钟内给出极其精准的排障策略。 - 在 Reddit 社区交流：适合探讨宏观生态、展示您的 炫酷部署方案或浏览社区的优秀应用案例。
- 提交一个 Bug 报告 (Issue)：仅当您百分之百确认这属于代码 Bug 且可以在最新版本上稳定复现时才进行提交（请务必按模板提供详尽的重现步骤和排障日志）。空洞无物的报告会被自动关闭，而带有“清晰复现步骤、附带报错日志”的高质量报告将被迅速定位并修复。