# https://github.com/open-webui/open-webui 项目说明书
生成时间：2026-05-11 06:57:26 UTC
## 目录
- [项目概述](#page-overview)
- [系统架构](#page-architecture)
- [后端路由与 API](#page-backend-routers)
- [数据模型层](#page-backend-models)
- [认证与安全](#page-auth-security)
- [前端组件结构](#page-frontend-structure)
- [前端路由页面](#page-frontend-routes)
- [模型集成与支持](#page-model-integration)
- [检索增强生成 (RAG)](#page-retrieval-rag)
- [工具与函数系统](#page-tools-functions)
## 项目概述
### 相关页面
相关主题：[系统架构](#page-architecture)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/open-webui/open-webui/blob/main/README.md)
- [src/lib/constants.ts](https://github.com/open-webui/open-webui/blob/main/src/lib/constants.ts)
- [backend/open_webui/config.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/config.py)
- [backend/open_webui/env.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/env.py)
- [backend/open_webui/retrieval/utils.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/retrieval/utils.py)
- [backend/open_webui/routers/knowledge.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/routers/knowledge.py)
- [src/lib/utils/index.ts](https://github.com/open-webui/open-webui/blob/main/src/lib/utils/index.ts)
# 项目概述
## 1. 项目简介
Open WebUI 是一个开源的自托管 Web 用户界面，专为大型语言模型（LLM）交互而设计。该项目提供了一个现代化、功能丰富的 Web 界面，让用户能够轻松地与本地部署的 Ollama 模型或其他兼容的 LLM API 进行交互。
项目支持多种安装方式，包括 pip 包安装和 Docker 容器化部署，并提供了丰富的功能集，涵盖对话管理、RAG（检索增强生成）、图像生成、语音模式、代码解释器等高级特性。
**核心目标**：为本地 LLM 提供一个类似 ChatGPT 的流畅、直观的 Web 交互体验，同时保持数据的私密性和本地化处理。
资料来源：[README.md:1-20](https://github.com/open-webui/open-webui/blob/main/README.md)
---
## 2. 技术架构
### 2.1 整体架构
Open WebUI 采用前后端分离的架构设计：
```mermaid
graph TD
subgraph 前端层["前端层 (SvelteKit)"]
A[Web UI] --> B[API 客户端]
B --> C[状态管理]
end
subgraph 后端层["后端层 (Python/FastAPI)"]
D[API 路由] --> E[业务逻辑]
E --> F[数据访问层]
F --> G[(SQLite/PostgreSQL)]
end
subgraph 外部服务["外部服务集成"]
H[Ollama]
I[RAG 检索器]
J[图像生成引擎]
K[语音服务]
end
A --> D
C --> E
E --> H
E --> I
E --> J
E --> K
```
### 2.2 目录结构
```
open-webui/
├── backend/
│ └── open_webui/
│ ├── __init__.py
│ ├── config.py # 配置管理
│ ├── env.py # 环境变量
│ ├── constants.py # 常量定义
│ ├── routers/ # API 路由
│ │ └── knowledge.py # 知识库路由
│ ├── retrieval/ # RAG 检索模块
│ │ ├── utils.py # 文档处理工具
│ │ └── loaders/ # 文档加载器
│ └── utils/ # 工具函数
│ └── middleware.py # 中间件处理
└── src/
├── lib/
│ ├── constants.ts # 前端常量
│ ├── utils/ # 前端工具
│ └── apis/ # API 客户端
└── app.html # 主 HTML 模板
```
资料来源：[backend/open_webui/env.py:1-50](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/env.py)
### 2.3 环境配置
后端通过 `env.py` 模块管理环境配置，支持从 `.env` 文件加载配置：
```python
# 目录定义
ENV_FILE_PATH = Path(__file__).resolve()
OPEN_WEBUI_DIR = ENV_FILE_PATH.parent # open_webui/
BACKEND_DIR = OPEN_WEBUI_DIR.parent # backend/
BASE_DIR = BACKEND_DIR.parent # 项目根目录
```
支持的设备类型：
| 设备类型 | 说明 | 配置值 |
|---------|------|--------|
| CPU | 默认模式，兼容所有系统 | `USE_CUDA_DOCKER=false` |
| CUDA | NVIDIA GPU 加速 | `USE_CUDA_DOCKER=true` |
| MPS | Apple Silicon 加速 | 自动检测 |
资料来源：[backend/open_webui/env.py:30-45](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/env.py)
---
## 3. 核心功能特性
### 3.1 功能总览
Open WebUI 提供以下核心功能模块：
| 功能模块 | 描述 | 支持范围 |
|---------|------|---------|
| **对话管理** | 多模型并行对话、对话历史管理 | Ollama、OpenAI 兼容 API |
| **RAG 检索** | 文档解析、向量检索、上下文注入 | 15+ 搜索提供商 |
| **Web 搜索** | 实时网络搜索增强回答 | SearXNG、Google PSE、Bing 等 |
| **图像生成** | DALL-E、Gemini、ComfyUI、AUTOMATIC1111 | 本地/云端引擎 |
| **语音模式** | 语音输入输出交互 | TTS/ASR 集成 |
| **代码解释器** | Python 代码执行与结果展示 | Pyodide/Jupyter |
| **多模型对话** | 同时调用多个模型协作回答 | 任意支持的模型 |
资料来源：[README.md:60-100](https://github.com/open-webui/open-webui/blob/main/README.md)
### 3.2 RAG 检索系统
检索系统支持多种文档格式和加载器：
```mermaid
graph LR
A[用户上传文档] --> B[文档解析器]
B --> C[文本提取]
C --> D[向量存储]
E[用户查询] --> F[向量检索]
F --> G[上下文组装]
G --> H[LLM 生成回答]
D --> F
```
**支持的文档类型**：
| 格式 | MIME 类型 |
|-----|----------|
| PDF | `application/pdf` |
| EPUB | `application/epub+zip` |
| Markdown | `text/markdown` |
| Word | `application/vnd.openxmlformats-officedocument.wordprocessingml.document` |
| 纯文本 | `text/plain` |
| CSV | `text/csv` |
| HTML | `text/html` |
| Python | `text/x-python` |
| CSS | `text/css` |
| JavaScript | `application/x-javascript` |
| 音频 | `audio/mpeg`, `audio/wav` |
**支持的 OCR 和文档处理服务**：
- TIKA Server
- Docling
- Mistral OCR
- PaddleOCR VL
- MinerU
- Azure Document Intelligence
资料来源：[src/lib/constants.ts:20-40](https://github.com/open-webui/open-webui/blob/main/src/lib/constants.ts)
资料来源：[backend/open_webui/retrieval/utils.py:1-50](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/retrieval/utils.py)
### 3.3 Web 搜索提供商
| 提供商 | 配置标识 |
|-------|---------|
| SearXNG | `searxng` |
| Google PSE | `google PSE` |
| Brave Search | `brave` |
| Bing | `bing` |
| DuckDuckGo | `duckduckgo` |
| Tavily | `tavily` |
| Perplexity | `perplexity` |
| Jina | `jina` |
| Exa | `exa` |
| Ollama Cloud | `ollama` |
| Azure AI Search | `azure` |
资料来源：[README.md:70-80](https://github.com/open-webui/open-webui/blob/main/README.md)
---
## 4. API 架构
### 4.1 API 端点结构
```mermaid
graph TD
A[WebUI API] --> B[/api/v1/*]
A --> C[/ollama/*]
A --> D[/openai/*]
B --> E[音频处理]
B --> F[图像处理]
B --> G[检索服务]
B --> H[知识库管理]
```
**基础 API 路径**：
| 服务 | 路径 |
|-----|------|
| WebUI API | `/api/v1` |
| Ollama | `/ollama` |
| OpenAI | `/openai` |
| 音频 | `/api/v1/audio` |
| 图像 | `/api/v1/images` |
| 检索 | `/api/v1/retrieval` |
资料来源：[src/lib/constants.ts:8-15](https://github.com/open-webui/open-webui/blob/main/src/lib/constants.ts)
### 4.2 知识库 API
知识库模块提供完整的 CRUD 操作：
| 端点 | 方法 | 描述 |
|-----|------|------|
| `/knowledge/create` | POST | 创建知识库 |
| `/knowledge/` | GET | 获取知识库列表 |
| `/knowledge/{id}` | GET | 获取知识库详情 |
| `/knowledge/{id}/file/add` | POST | 添加文件到知识库 |
| `/knowledge/{id}/files/search` | GET | 搜索知识库文件 |
**访问控制**：
- 管理员（`admin`）拥有完全访问权限
- 知识库创建者拥有完全访问权限
- 其他用户需要通过访问授权（`AccessGrants`）获得读取权限
资料来源：[backend/open_webui/routers/knowledge.py:1-80](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/routers/knowledge.py)
资料来源：[src/lib/apis/knowledge/index.ts:1-60](https://github.com/open-webui/open-webui/blob/main/src/lib/apis/knowledge/index.ts)
---
## 5. 安装与部署
### 5.1 安装方式对比
| 安装方式 | 适用场景 | Python 版本要求 |
|---------|---------|----------------|
| pip 安装 | 本地开发、快速体验 | Python 3.11+ |
| Docker | 生产环境、跨平台部署 | 无 |
| 开发分支 | 测试最新功能 | 无 |
### 5.2 pip 安装
```bash
# 安装
pip install open-webui
# 启动服务
open-webui serve
# 访问地址：http://localhost:8080
```
### 5.3 Docker 部署
```bash
# 标准部署
docker run -d -p 3000:8080 \
-v open-webui:/app/backend/data \
--name open-webui \
--add-host=host.docker.internal:host-gateway \
--restart always \
ghcr.io/open-webui/open-webui:main
# CUDA 加速版本
docker run -d -p 3000:8080 \
-v open-webui:/app/backend/data \
--gpus all \
--name open-webui \
ghcr.io/open-webui/open-webui:cuda
# Ollama 集成版本
docker run -d -p 3000:8080 \
-v open-webui:/app/backend/data \
--name open-webui \
ghcr.io/open-webui/open-webui:ollama
```
> [!WARNING]
> Docker 部署时必须挂载数据卷 `-v open-webui:/app/backend/data`，否则数据库数据将在容器重建时丢失。
> [!NOTE]
> 离线环境可设置 `HF_HUB_OFFLINE=1` 环境变量阻止模型下载。
资料来源：[README.md:25-120](https://github.com/open-webui/open-webui/blob/main/README.md)
---
## 6. 配置与定制
### 6.1 系统常量配置
前端通过 `src/lib/constants.ts` 定义系统级常量：
```typescript
export const APP_NAME = 'Open WebUI';
export const WEBUI_VERSION = APP_VERSION;
export const WEBUI_BUILD_HASH = APP_BUILD_HASH;
export const REQUIRED_OLLAMA_VERSION = '0.1.16';
```
### 6.2 内容处理管道
前端对 LLM 输出进行标准化处理：
```mermaid
graph LR
A[原始输出] --> B[sanitizeResponseContent]
B --> C[processChineseContent]
C --> D[Markdown 渲染]
```
**处理功能**：
- 移除未闭合的 tokenizer 标记（`<|...`）
- HTML 实体转义
- 中文内容特殊格式优化
- Markdown/LaTeX 格式标准化
资料来源：[src/lib/utils/index.ts:1-50](https://github.com/open-webui/open-webui/blob/main/src/lib/utils/index.ts)
### 6.3 代码解释器配置
代码解释器支持两种执行引擎：
| 引擎 | 执行环境 | 提示词追加 |
|-----|---------|-----------|
| Jupyter | 服务器端 | 无 |
| Pyodide | 浏览器端 | Pyodide 环境提示 |
**关键配置参数**：
- 允许使用多种数据处理、可视化、API 调用库
- 强制使用 `` XML 标签包裹代码
- 输出结果需显式打印
资料来源：[backend/open_webui/config.py:200-280](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/config.py)
---
## 7. 安全特性
### 7.1 角色权限控制
| 角色 | Ollama 访问 | 模型拉取 | 模型创建 | 知识库管理 |
|-----|------------|---------|---------|-----------|
| 管理员 | ✅ 完全 | ✅ | ✅ | ✅ |
| 普通用户 | 受限 | ❌ | ❌ | 受限 |
| 访客 | 受限 | ❌ | ❌ | ❌ |
### 7.2 访问授权机制
知识库使用 `AccessGrants` 系统控制资源访问：
```python
await AccessGrants.has_access(
user_id=user.id,
resource_type='knowledge',
resource_id=knowledge.id,
permission='read',
db=db,
)
```
资料来源：[backend/open_webui/routers/knowledge.py:40-60](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/routers/knowledge.py)
---
## 8. 版本与依赖
### 8.1 版本要求
| 组件 | 最低版本 |
|-----|---------|
| Python | 3.11 |
| Ollama | 0.1.16 |
### 8.2 数据存储
支持多种数据库后端：
| 数据库 | 特点 | 加密支持 |
|-------|------|---------|
| SQLite | 默认、轻量 | ✅ 可选 |
| PostgreSQL | 生产级、高并发 | ❌ |
资料来源：[README.md:100-110](https://github.com/open-webui/open-webui/blob/main/README.md)
---
## 9. 相关资源
- **官方文档**：https://docs.openwebui.com/
- **更新指南**：https://docs.openwebui.com/getting-started/updating
- **路线图**：https://docs.openwebui.com/roadmap/
- **许可证**：项目采用 Open WebUI License，需保留品牌标识
资料来源：[README.md:140-160](https://github.com/open-webui/open-webui/blob/main/README.md)
---
## 系统架构
### 相关页面
相关主题：[后端路由与 API](#page-backend-routers), [前端组件结构](#page-frontend-structure)
相关源码文件
以下源码文件用于生成本页说明：
- [backend/open_webui/main.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/main.py)
- [backend/open_webui/config.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/config.py)
- [backend/open_webui/env.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/env.py)
- [src/lib/constants.ts](https://github.com/open-webui/open-webui/blob/main/src/lib/constants.ts)
- [src/lib/utils/index.ts](https://github.com/open-webui/open-webui/blob/main/src/lib/utils/index.ts)
- [backend/open_webui/utils/middleware.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/utils/middleware.py)
# 系统架构
## 概述
Open WebUI 是一个功能丰富的 Web 用户界面，专为大型语言模型（LLM）交互设计。该项目采用前后端分离的现代化架构，后端基于 FastAPI 构建 Python REST API 与 WebSocket 服务，前端使用 SvelteKit 框架实现响应式单页应用。
系统支持多模型并行对话、检索增强生成（RAG）、代码解释器执行、语音模式等高级功能，同时提供灵活的数据库与存储选项（SQLite、PostgreSQL、S3 等）。
资料来源：[backend/open_webui/main.py:1-50]()
## 整体架构图
```mermaid
graph TB
subgraph 前端层["前端层 (SvelteKit)"]
UI[用户界面]
WS_CLIENT[WebSocket 客户端]
API_CLIENT[API 客户端]
end
subgraph 后端层["后端层 (FastAPI)"]
API_GATEWAY[API 网关]
subgraph API路由["API 路由模块"]
TASKS[tasks 路由]
IMAGES[images 路由]
AUDIO[audio 路由]
RETRIEVAL[retrieval 路由]
CONFIGS[configs 路由]
AUTHS[auths 路由]
USERS[users 路由]
CHANNELS[channels 路由]
CHATS[chats 路由]
NOTES[notes 路由]
MODELS[models 路由]
KNOWLEDGE[knowledge 路由]
PROMPTS[prompts 路由]
TOOLS[tools 路由]
SKILLS[skills 路由]
MEMORIES[memories 路由]
FOLDERS[folders 路由]
GROUPS[groups 路由]
FILES[files 路由]
end
WS_SERVER[WebSocket 服务]
MIDDLEWARE[中间件处理]
end
subgraph 外部服务["外部服务"]
OLLAMA[Ollama API]
OPENAI[OpenAI API]
DOCLING[Docling OCR]
TIKA[Tika Server]
end
UI --> WS_CLIENT
UI --> API_CLIENT
WS_CLIENT --> WS_SERVER
API_CLIENT --> API_GATEWAY
API_GATEWAY --> API路由
MIDDLEWARE --> API路由
WS_SERVER --> MIDDLEWARE
API_GATEWAY --> OLLAMA
API_GATEWAY --> OPENAI
API路由 --> DOCLING
API路由 --> TIKA
```
资料来源：[backend/open_webui/main.py:1-50]()
## 核心组件架构
### 前端架构
前端基于 SvelteKit 框架构建，采用单页应用（SPA）模式。主要组件包括：
| 组件路径 | 功能描述 |
|---------|---------|
| `src/app.html` | 应用主 HTML 模板，包含启动画面和主题样式 |
| `src/lib/constants.ts` | 前端常量定义，包含 API 端点配置 |
| `src/lib/utils/index.ts` | 响应内容处理工具函数 |
| `src/lib/utils/codeHighlight.ts` | 代码语法高亮映射配置 |
#### 前端 API 端点配置
前端通过 `constants.ts` 中定义的常量与后端通信：
```typescript
// 资料来源：src/lib/constants.ts:1-20
export const WEBUI_BASE_URL = browser ? (dev ? `http://${WEBUI_HOSTNAME}` : ``) : ``;
export const WEBUI_API_BASE_URL = `${WEBUI_BASE_URL}/api/v1`;
export const OLLAMA_API_BASE_URL = `${WEBUI_BASE_URL}/ollama`;
export const OPENAI_API_BASE_URL = `${WEBUI_BASE_URL}/openai`;
export const AUDIO_API_BASE_URL = `${WEBUI_BASE_URL}/api/v1/audio`;
export const IMAGES_API_BASE_URL = `${WEBUI_BASE_URL}/api/v1/images`;
export const RETRIEVAL_API_BASE_URL = `${WEBUI_BASE_URL}/api/v1/retrieval`;
```
### 后端架构
后端采用 FastAPI 框架，按照功能模块划分为多个路由组件：
```mermaid
graph LR
subgraph REST_API["REST API (/api/v1/*)"]
TASKS_API[任务 API]
FILE_API[文件 API]
CHAT_API[聊天 API]
MODEL_API[模型 API]
RAG_API[RAG 检索 API]
end
subgraph WEBSOCKET["WebSocket (/ws)"]
STREAM[流式响应]
REALTIME[实时事件]
end
subgraph MIDDLEWARE["中间件"]
AUTH[身份验证]
SANITIZE[内容清理]
PIPELINE[管道处理]
end
```
资料来源：[backend/open_webui/main.py:1-50]()
## API 路由体系
### 路由模块一览
| 前缀路径 | 路由模块 | 标签 | 功能 |
|---------|---------|------|------|
| `/api/v1/tasks` | tasks | tasks | 异步任务管理 |
| `/api/v1/images` | images | images | 图片处理与生成 |
| `/api/v1/audio` | audio | audio | 音频处理 |
| `/api/v1/retrieval` | retrieval | retrieval | RAG 检索功能 |
| `/api/v1/configs` | configs | configs | 系统配置 |
| `/api/v1/auths` | auths | auths | 身份认证 |
| `/api/v1/users` | users | users | 用户管理 |
| `/api/v1/channels` | channels | channels | 通道管理 |
| `/api/v1/chats` | chats | chats | 对话管理 |
| `/api/v1/notes` | notes | notes | 笔记功能 |
| `/api/v1/models` | models | models | 模型管理 |
| `/api/v1/knowledge` | knowledge | knowledge | 知识库 |
| `/api/v1/prompts` | prompts | prompts | 提示词管理 |
| `/api/v1/tools` | tools | tools | 工具扩展 |
| `/api/v1/skills` | skills | skills | 技能管理 |
| `/api/v1/memories` | memories | memories | 记忆功能 |
| `/api/v1/folders` | folders | folders | 文件夹组织 |
| `/api/v1/groups` | groups | groups | 分组管理 |
| `/api/v1/files` | files | files | 文件存储 |
资料来源：[backend/open_webui/main.py:30-50]()
## 配置系统
### 环境配置架构
```python
# 资料来源：backend/open_webui/env.py:1-50
OPEN_WEBUI_DIR = ENV_FILE_PATH.parent # open_webui/
BACKEND_DIR = OPEN_WEBUI_DIR.parent # backend/
BASE_DIR = BACKEND_DIR.parent # 项目根目录
```
### 关键配置项
| 配置项 | 环境变量 | 默认值 | 说明 |
|-------|---------|-------|------|
| Docker 模式 | `DOCKER` | `'False'` | 是否运行在 Docker 容器中 |
| CUDA 支持 | `USE_CUDA_DOCKER` | `'false'` | 是否启用 NVIDIA GPU 加速 |
| 设备类型 | `DEVICE_TYPE` | `'cpu'` | 嵌入模型运行设备 |
| 版本哈希 | `APP_VERSION` | - | 构建版本标识 |
| 构建哈希 | `APP_BUILD_HASH` | - | Git 提交哈希 |
资料来源：[backend/open_webui/env.py:1-50]()
### 任务配置模板
系统支持可配置的提示词模板：
```python
# 资料来源：backend/open_webui/config.py:1-30
CODE_INTERPRETER_PROMPT = """
代码解释器允许 AI 在沙箱环境中执行 Python 代码...
"""
```
## 中间件处理
### 响应处理管道
```mermaid
graph TD
LLM_Response[LLM 响应] --> STREAM[流式响应处理]
STREAM --> REASONING[推理内容检测]
REASONING --> CODE_INTERPRETER{代码解释器?}
CODE_INTERPRETER -->|是| SANITIZE[内容清理]
CODE_INTERPRETER -->|否| FORMAT[格式处理]
SANITIZE --> HTML[HTML 渲染]
FORMAT --> HTML
HTML --> FINAL[最终响应]
```
资料来源：[backend/open_webui/utils/middleware.py:1-50]()
### 内容处理功能
中间件提供以下核心处理功能：
- **推理链渲染**：将模型的思维过程渲染为可折叠的 `` HTML 元素
- **代码解释器集成**：识别并执行代码块，渲染执行结果
- **HTML 转义**：对非信任内容进行安全转义
- **Markdown 处理**：支持 Markdown 格式解析
```python
# 资料来源：backend/open_webui/utils/middleware.py:1-30
if item_type == 'reasoning':
if duration is not None or not is_last_item:
parts.append(
f'\nThought for {duration or 0} seconds
\n{display}\n '
)
```
## 前端响应处理
### 内容处理流程
```mermaid
graph LR
RAW[原始响应] --> PROCESS[processResponseContent]
PROCESS --> CHINESE{包含中文?}
CHINESE -->|是| CHINESE_PROC[中文内容处理]
CHINESE -->|否| SANITIZE[内容清理]
CHINESE_PROC --> SANITIZE
SANITIZE --> HTML_ESCAPE[HTML 转义]
HTML_ESCAPE --> OUTPUT[最终输出]
```
资料来源：[src/lib/utils/index.ts:1-50]()
### 响应清理函数
```typescript
// 资料来源：src/lib/utils/index.ts:1-30
export const sanitizeResponseContent = (content: string) => {
return content
.replace(/<\|[a-z]*$/, '')
.replace(/<\|[a-z]+\|$/, '')
.replace(/<$/, '')
.replaceAll('<', '<')
.replaceAll('>', '>')
.replaceAll(/<\|[a-z]+\|>/g, ' ')
.trim();
};
```
## 代码语法高亮
### 文件类型映射配置
```typescript
// 资料来源：src/lib/utils/codeHighlight.ts:1-50
const EXT_OVERRIDE: Record = {
py: 'python',
js: 'javascript',
ts: 'typescript',
jsx: 'jsx',
tsx: 'tsx',
rb: 'ruby',
rs: 'rust',
yml: 'yaml',
md: 'markdown',
dockerfile: 'dockerfile',
proto: 'proto',
graphql: 'graphql',
gql: 'graphql',
};
```
支持的语言标识符集合包含超过 50 种编程语言和配置格式，确保前端代码展示的准确性。
## 部署架构
### Docker 部署模式
```mermaid
graph TB
USER[用户] --> BROWSER[浏览器]
BROWSER --> DOCKER[Docker 容器]
subgraph DOCKER[Docker 容器]
NGINX[反向代理]
FASTAPI[FastAPI 后端]
SVELTE[构建静态文件]
end
FASTAPI --> OLLAMA[(Ollama 服务)]
FASTAPI --> DATA[数据卷 /app/backend/data]
subgraph OLLAMA[(Ollama 服务)]
MODEL1[模型 1]
MODEL2[模型 2]
MODEL_N[模型 N]
end
```
### 离线模式支持
系统支持完全离线运行，通过设置以下环境变量禁用所有网络请求：
```bash
export HF_HUB_OFFLINE=1
```
资料来源：[README.md](https://github.com/open-webui/open-webui/blob/main/README.md)
## 技术栈总结
| 层级 | 技术选型 | 说明 |
|-----|---------|------|
| 前端框架 | SvelteKit | 现代化响应式框架 |
| 后端框架 | FastAPI | 高性能 Python ASGI 框架 |
| 数据库 | SQLite (默认) / PostgreSQL | 灵活的数据存储选项 |
| 存储 | S3 / GCS / Azure Blob | 云端对象存储支持 |
| LLM 运行时 | Ollama / OpenAI API | 多模型支持 |
| 文档处理 | Tika / Docling / Mistral OCR | 多格式文档解析 |
| WebSocket | 原生 FastAPI WebSocket | 实时双向通信 |
资料来源：[README.md](https://github.com/open-webui/open-webui/blob/main/README.md), [backend/open_webui/env.py:1-50]()
---
## 后端路由与 API
### 相关页面
相关主题：[系统架构](#page-architecture), [认证与安全](#page-auth-security), [模型集成与支持](#page-model-integration)
相关源码文件
以下源码文件用于生成本页说明：
- [backend/open_webui/routers/chats.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/routers/chats.py)
- [backend/open_webui/routers/auths.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/routers/auths.py)
- [backend/open_webui/routers/models.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/routers/models.py)
- [backend/open_webui/routers/ollama.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/routers/ollama.py)
- [backend/open_webui/routers/openai.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/routers/openai.py)
- [backend/open_webui/routers/retrieval.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/routers/retrieval.py)
- [backend/open_webui/routers/tasks.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/routers/tasks.py)
# 后端路由与 API
## 1. 概述
Open WebUI 的后端采用 FastAPI 框架构建，提供了完整的 RESTful API 接口层。系统通过模块化的路由设计，将不同功能域的 API 逻辑分离到独立的路由器（Router）中，实现了代码的高内聚低耦合。
### 1.1 架构设计原则
后端 API 层遵循以下核心设计原则：
| 设计原则 | 说明 |
|---------|------|
| **分层架构** | 路由层 → 服务层 → 数据访问层分离 |
| **依赖注入** | 使用 FastAPI 的 Depends 机制管理依赖 |
| **异步优先** | 全面采用 AsyncIO 异步编程模型 |
| **权限控制** | 基于角色的访问控制（RBAC） |
| **统一响应** | 标准化的响应格式和错误处理 |
### 1.2 核心路由模块
系统的主要路由模块位于 `backend/open_webui/routers/` 目录下：
```mermaid
graph TD
A[客户端请求] --> B[API 网关层]
B --> C[认证路由 auths]
B --> D[聊天路由 chats]
B --> E[模型路由 models]
B --> F[知识库路由 knowledge]
B --> G[检索路由 retrieval]
B --> H[任务路由 tasks]
B --> I[外部集成 ollama/openai]
C --> K[用户认证服务]
D --> L[对话管理服务]
E --> M[模型配置服务]
F --> N[文档处理服务]
G --> O[向量检索服务]
H --> P[异步任务服务]
```
资料来源：[backend/open_webui/routers/](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/routers/)
---
## 2. 认证与授权系统
### 2.1 认证路由（auths）
认证路由负责处理用户身份验证、会话管理和访问授权。
资料来源：[backend/open_webui/routers/auths.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/routers/auths.py)
#### 2.1.1 主要 API 端点
| 端点 | 方法 | 描述 |
|------|------|------|
| `/api/auth/login` | POST | 用户登录 |
| `/api/auth/logout` | POST | 用户登出 |
| `/api/auth/user` | GET | 获取当前用户信息 |
| `/api/auth/modelfiles` | GET | 获取用户自定义模型文件 |
#### 2.1.2 认证流程
```mermaid
sequenceDiagram
participant Client as 客户端
participant API as 认证 API
participant DB as 数据库
participant Session as 会话管理
Client->>API: POST /api/auth/login
API->>DB: 验证用户凭据
DB-->>API: 用户信息
API->>Session: 创建会话
Session-->>API: 会话令牌
API-->>Client: 返回认证令牌
```
### 2.2 访问控制机制
系统通过 `AccessGrants` 模块实现细粒度的资源访问控制：
```python
if not (
user.role == 'admin'
or knowledge.user_id == user.id
or await AccessGrants.has_access(
user_id=user.id,
resource_type='knowledge',
resource_id=knowledge.id,
permission='read',
db=db,
)
):
raise HTTPException(
status_code=status.HTTP_400_BAD_REQUEST,
detail=ERROR_MESSAGES.ACCESS_PROHIBITED,
)
```
资料来源：[backend/open_webui/routers/knowledge.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/routers/knowledge.py)
---
## 3. 对话管理 API
### 3.1 聊天路由（chats）
聊天路由是系统的核心模块，负责处理所有与对话相关的功能，包括消息发送、对话历史管理和对话状态维护。
资料来源：[backend/open_webui/routers/chats.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/routers/chats.py)
#### 3.1.1 核心功能
| 功能 | 描述 |
|------|------|
| 创建对话 | 初始化新的聊天会话 |
| 发送消息 | 向对话中添加用户消息和助手回复 |
| 获取历史 | 检索指定对话的消息历史 |
| 删除对话 | 删除整个对话及其关联数据 |
| 分享对话 | 将对话导出为可分享格式 |
#### 3.1.2 消息处理流程
```mermaid
graph TD
A[用户发送消息] --> B[消息验证]
B --> C{工具调用检测}
C -->|是| D[执行工具函数]
C -->|否| E[模型推理]
D --> F[返回工具结果]
E --> G[生成回复]
F --> G
G --> H[保存消息]
H --> I[流式返回]
```
### 3.2 消息处理工具函数
系统提供了丰富的消息处理工具函数：
| 函数名 | 功能 |
|--------|------|
| `get_message_list` | 获取消息列表 |
| `add_or_update_system_message` | 添加/更新系统消息 |
| `add_or_update_user_message` | 添加/更新用户消息 |
| `get_last_user_message` | 获取最后用户消息 |
| `get_last_assistant_message` | 获取最后助手消息 |
| `replace_system_message_content` | 替换系统消息内容 |
资料来源：[backend/open_webui/utils/chat.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/utils/chat.py)
---
## 4. 模型管理 API
### 4.1 模型路由（models）
模型路由负责管理系统中的大语言模型配置，包括模型列表管理、配置更新和模型选择。
资料来源：[backend/open_webui/routers/models.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/routers/models.py)
#### 4.1.1 配置参数
| 参数 | 类型 | 说明 |
|------|------|------|
| `title` | string | 模型显示名称 |
| `base_url` | string | 模型服务地址 |
| `api_key` | string | API 密钥 |
| `max_tokens` | int | 最大生成 token 数 |
| `temperature` | float | 生成温度参数 |
| `stream` | boolean | 是否启用流式输出 |
### 4.2 外部模型集成
系统支持多种外部模型服务的集成，通过统一的适配器接口实现。
---
## 5. 外部服务集成
### 5.1 Ollama 集成
Ollama 路由提供了与本地 Ollama 服务通信的接口。
资料来源：[backend/open_webui/routers/ollama.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/routers/ollama.py)
```mermaid
graph LR
A[Open WebUI] -->|API 请求| B[Ollama 适配层]
B --> C[Ollama 服务]
C -->|模型响应| B
B -->|标准化响应| A
```
#### 5.1.1 Ollama API 端点映射
| Open WebUI 端点 | Ollama API |
|----------------|-----------|
| `/ollama/chat` | `/api/chat` |
| `/ollama/models` | `/api/tags` |
| `/ollama/generate` | `/api/generate` |
| `/ollama/embeddings` | `/api/embeddings` |
### 5.2 OpenAI 兼容 API
OpenAI 路由实现了与 OpenAI API 兼容的接口，支持使用 OpenAI SDK 的应用无缝接入。
资料来源：[backend/open_webui/routers/openai.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/routers/openai.py)
#### 5.2.1 支持的端点
| 端点 | 描述 |
|------|------|
| `/openai/v1/chat/completions` | 聊天补全 |
| `/openai/v1/completions` | 文本补全 |
| `/openai/v1/embeddings` | 向量嵌入 |
| `/openai/v1/models` | 模型列表 |
---
## 6. 知识库与检索系统
### 6.1 知识库路由
知识库路由负责文档上传、内容处理和知识库管理。
资料来源：[backend/open_webui/routers/knowledge.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/routers/knowledge.py)
#### 6.1.1 文件操作 API
| 端点 | 方法 | 描述 |
|------|------|------|
| `/{id}/files` | GET | 列出知识库文件 |
| `/{id}/file/add` | POST | 添加文件到知识库 |
| `/{id}/file/delete` | DELETE | 删除知识库文件 |
| `/{id}/search` | POST | 搜索知识库内容 |
#### 6.1.2 访问控制流程
```mermaid
graph TD
A[请求访问知识库] --> B{用户角色检查}
B -->|管理员| C[允许访问]
B -->|普通用户| D{是否为所有者}
D -->|是| C
D -->|否| E{检查访问权限}
E -->|有读权限| C
E -->|无权限| F[拒绝访问 400]
```
### 6.2 检索路由
检索路由提供了向量检索和全文搜索功能。
资料来源：[backend/open_webui/routers/retrieval.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/routers/retrieval.py)
#### 6.2.1 检索处理流程
```mermaid
graph TD
A[用户查询] --> B[查询预处理]
B --> C[向量嵌入]
C --> D[向量数据库检索]
D --> E[结果重排序]
E --> F[格式化输出]
F --> G[返回检索结果]
```
---
## 7. 异步任务系统
### 7.1 任务路由
任务路由管理系统中的异步任务，包括任务创建、状态查询和结果获取。
资料来源：[backend/open_webui/routers/tasks.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/routers/tasks.py)
#### 7.1.1 任务类型
| 任务类型 | 描述 |
|---------|------|
| `chat` | 聊天消息生成任务 |
| `title` | 对话标题生成任务 |
| `summarize` | 消息摘要任务 |
| `rerank` | 检索结果重排序任务 |
#### 7.1.2 任务状态流转
```mermaid
stateDiagram-v2
[*] --> Pending: 创建任务
Pending --> Processing: 开始执行
Processing --> Completed: 执行成功
Processing --> Failed: 执行失败
Completed --> [*]
Failed --> [*]
```
### 7.2 任务处理配置
系统通过配置文件管理任务处理参数：
| 配置项 | 说明 | 默认值 |
|--------|------|--------|
| `TASK_MODEL` | 任务处理模型 | auto |
| `TASK_MODEL_EXTERNAL` | 外部任务模型 | - |
资料来源：[backend/open_webui/config.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/config.py)
---
## 8. 代码执行系统
### 8.1 代码解释器配置
系统支持在聊天中执行代码，提供强大的动态执行能力。
资料来源：[backend/open_webui/config.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/config.py)
#### 8.1.1 配置参数
| 配置项 | 类型 | 说明 |
|--------|------|------|
| `ENABLE_CODE_EXECUTION` | boolean | 启用代码执行 |
| `CODE_EXECUTION_ENGINE` | string | 执行引擎 (pyodide) |
| `CODE_EXECUTION_JUPYTER_URL` | string | Jupyter 服务地址 |
| `CODE_EXECUTION_JUPYTER_AUTH` | string | Jupyter 认证信息 |
#### 8.1.2 架构设计
```mermaid
graph TD
A[代码块检测] --> B{启用代码执行}
B -->|是| C[隔离执行环境]
C --> D[Pyodide/Jupyter]
B -->|否| E[普通代码展示]
D --> F[执行结果捕获]
F --> G[格式化返回]
```
---
## 9. 工具系统
### 9.1 工具函数管理
系统提供灵活的函数调用机制，支持自定义工具扩展。
资料来源：[backend/open_webui/utils/tools.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/utils/tools.py)
| 函数 | 功能 |
|------|------|
| `get_tools` | 获取可用工具列表 |
| `get_updated_tool_function` | 获取更新后的工具定义 |
| `get_terminal_tools` | 获取终端级工具 |
### 9.2 工具调用处理
```mermaid
graph TD
A[模型输出] --> B{检测工具调用}
B -->|function_call| C[解析工具名和参数]
C --> D[加载工具模块]
D --> E[执行工具函数]
E --> F[返回执行结果]
F --> G[模型生成最终回复]
```
---
## 10. 流水线处理
### 10.1 管道过滤器
系统支持在请求处理流程中插入自定义过滤器，实现功能的灵活扩展。
资料来源：[backend/open_webui/routers/pipelines.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/routers/pipelines.py)
| 处理阶段 | 描述 |
|---------|------|
| `pipeline_inlet_filter` | 请求预处理过滤器 |
| `pipeline_outlet_filter` | 响应后处理过滤器 |
### 10.2 处理流程
```mermaid
graph LR
A[用户请求] --> B[输入过滤器]
B --> C[核心业务处理]
C --> D[输出过滤器]
D --> E[返回响应]
```
---
## 11. API 响应格式规范
### 11.1 统一响应结构
| 字段 | 类型 | 说明 |
|------|------|------|
| `id` | string | 资源唯一标识符 |
| `object` | string | 对象类型 |
| `created` | int | 创建时间戳 |
| `model` | string | 使用的模型 |
| `choices` | array | 生成选项列表 |
| `usage` | object | Token 使用统计 |
### 11.2 错误响应
| 状态码 | 说明 |
|--------|------|
| 400 | 请求参数错误 |
| 401 | 认证失败 |
| 403 | 权限不足 |
| 404 | 资源不存在 |
| 500 | 服务器内部错误 |
---
## 12. 总结
Open WebUI 的后端 API 系统采用模块化设计，通过清晰的路由划分实现了功能的有效分离。系统提供了完整的用户认证、对话管理、模型配置、知识库管理和异步任务处理能力，同时支持与 Ollama、OpenAI 等外部服务的高效集成。
该架构的核心优势包括：
- **可扩展性**：通过流水线过滤器支持自定义扩展
- **安全性**：基于角色的访问控制和细粒度的资源权限管理
- **性能**：全面采用异步编程模型，支持高并发处理
- **兼容性**：提供 OpenAI 兼容接口，无缝对接现有生态系统
---
## 数据模型层
### 相关页面
相关主题：[后端路由与 API](#page-backend-routers)
相关源码文件
以下源码文件用于生成本页说明：
- [backend/open_webui/models/users.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/models/users.py)
- [backend/open_webui/models/chats.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/models/chats.py)
- [backend/open_webui/models/messages.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/models/messages.py)
- [backend/open_webui/models/files.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/models/files.py)
- [backend/open_webui/models/functions.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/models/functions.py)
- [backend/open_webui/models/tools.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/models/tools.py)
- [backend/open_webui/models/knowledge.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/models/knowledge.py)
- [backend/open_webui/internal/db.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/internal/db.py)
# 数据模型层
## 概述
Open WebUI 的数据模型层是整个系统的核心基础设施，负责管理和持久化所有业务数据。该层采用了**分层架构设计**，将数据访问逻辑、业务模型定义和数据库交互分离到不同的模块中，以实现高内聚、低耦合的代码结构。
数据模型层的主要职责包括：
- **用户认证与授权**：管理用户账户信息、权限配置和会话状态
- **对话历史管理**：存储和检索聊天记录，支持消息的增删改查操作
- **文件与媒体处理**：管理上传文件、元数据和访问控制
- **工具与函数集成**：维护可扩展的工具和函数定义
- **知识库管理**：支持向量化的知识检索和文档管理
资料来源：[backend/open_webui/internal/db.py:1-50]()
## 架构设计
### 整体架构图
```mermaid
graph TB
subgraph "表现层 (API Routes)"
A[API 路由层]
end
subgraph "服务层 (Services)"
B[业务逻辑服务]
end
subgraph "数据模型层 (Models)"
C[用户模型
users.py]
D[对话模型
chats.py]
E[消息模型
messages.py]
F[文件模型
files.py]
G[函数模型
functions.py]
H[工具模型
tools.py]
I[知识模型
knowledge.py]
end
subgraph "数据访问层 (Internal)"
J[数据库连接
db.py]
K[数据仓库
Repositories]
end
subgraph "存储层 (Storage)"
L[(SQLite/MySQL
PostgreSQL)]
M[(文件存储
S3/本地)]
end
A --> B
B --> C
B --> D
B --> E
B --> F
B --> G
B --> H
B --> I
C --> J
D --> J
E --> J
F --> J
G --> J
H --> J
I --> J
J --> K
K --> L
K --> M
```
### 模块职责划分
| 模块文件 | 主要职责 | 核心数据结构 |
|---------|---------|-------------|
| `users.py` | 用户账户、认证、权限 | UserModel |
| `chats.py` | 对话会话、聊天历史 | ChatModel |
| `messages.py` | 单条消息、消息内容 | MessageModel |
| `files.py` | 文件上传、元数据管理 | FileModel |
| `functions.py` | 可调用函数定义 | FunctionModel |
| `tools.py` | 外部工具集成 | ToolModel |
| `knowledge.py` | 知识库、向量存储 | KnowledgeModel |
| `db.py` | 数据库连接、查询构建 | Database Connection |
资料来源：[backend/open_webui/internal/db.py:1-30]()
## 核心数据模型详解
### 1. 用户模型 (User Model)
用户模型是系统的基础实体，包含了用户身份验证和授权所需的所有信息。
```mermaid
classDiagram
class UserModel {
+str id
+str email
+str name
+str password_hash
+str role
+datetime created_at
+datetime updated_at
+dict settings
+dict preferences
}
class UserSettings {
+str theme
+str language
+list allowed_models
+bool consent_analytics
}
```
**主要字段说明：**
| 字段名 | 类型 | 说明 | 必填 |
|-------|------|------|-----|
| `id` | str | 唯一标识符 (UUID) | 是 |
| `email` | str | 用户邮箱地址 | 是 |
| `name` | str | 显示名称 | 是 |
| `password_hash` | str | 密码哈希值 (bcrypt) | 是 |
| `role` | str | 角色 (admin/user/guest) | 是 |
| `created_at` | datetime | 创建时间戳 | 自动 |
| `updated_at` | datetime | 更新时间戳 | 自动 |
| `settings` | dict | 用户偏好设置 | 否 |
资料来源：[backend/open_webui/models/users.py:1-100]()
### 2. 对话模型 (Chat Model)
对话模型采用扁平化的 JSON 结构存储聊天会话，包含完整的对话历史和元数据。
```mermaid
graph LR
A[ChatModel] --> B["chat: Dict"]
B --> C["history: Dict"]
C --> D["messages: Dict
message_id → message"]
C --> E["metadata: Dict"]
B --> F["share_id: str"]
B --> G["archived: bool"]
B --> H["pinned: bool"]
```
**关键特性：**
- **消息存储方式**：对话消息存储在 `chat.history.messages` 字典中，以 `message_id` 为键
- **双轨存储**：支持从独立的 `chat_message` 表快速查询，同时保持向后兼容的 JSON blob 存储
- **自动清理**：对消息内容进行特殊字符清理，防止数据库存储问题
资料来源：[backend/open_webui/models/chats.py:1-50]()
### 3. 消息模型 (Message Model)
消息是对话的原子单位，每条消息包含发送者、内容、附件和时间戳等完整信息。
| 字段 | 类型 | 说明 |
|------|------|------|
| `id` | str | 消息唯一标识 |
| `chat_id` | str | 所属对话 ID |
| `role` | str | 发送者角色 (user/assistant/system) |
| `content` | str | 消息文本内容 |
| `attachments` | list | 附件列表 |
| `metadata` | dict | 额外元数据 |
| `created_at` | datetime | 创建时间 |
资料来源：[backend/open_webui/models/messages.py:1-80]()
### 4. 文件模型 (File Model)
文件模型管理用户上传的所有文件，包括图片、文档、音频等。
```mermaid
stateDiagram-v2
[*] --> Uploaded: 用户上传
Uploaded --> Processing: 开始处理
Processing --> Ready: 处理完成
Processing --> Failed: 处理失败
Failed --> [*]
Ready --> Deleted: 用户删除
Ready --> [*]
```
**文件类型支持：**
| 类型 | 说明 | 存储方式 |
|------|------|---------|
| `image` | 图片文件 | 对象存储 |
| `document` | 文档 (PDF, DOCX等) | 对象存储 |
| `audio` | 音频文件 | 对象存储 |
| `video` | 视频文件 | 对象存储 |
| `html` | HTML 内容 | 内联存储 |
资料来源：[backend/open_webui/models/files.py:1-100]()
### 5. 函数与工具模型
函数和工具模型为系统提供了扩展能力，允许用户和开发者自定义功能。
```mermaid
graph TD
A[FunctionModel/ToolModel] --> B["id: str"]
A --> C["name: str"]
A --> D["description: str"]
A --> E["parameters: dict"]
A --> F["source_code: str"]
A --> G["enabled: bool"]
H[函数调用流程] --> I[解析参数]
H --> J[执行函数]
H --> K[返回结果]
```
资料来源：[backend/open_webui/models/functions.py:1-60]()
### 6. 知识库模型 (Knowledge Model)
知识库模型支持向量化的文档存储和语义检索。
| 字段 | 类型 | 说明 |
|------|------|------|
| `id` | str | 知识库唯一标识 |
| `name` | str | 知识库名称 |
| `description` | str | 描述信息 |
| `documents` | list | 文档列表 |
| `embeddings` | list | 向量化数据 |
| `created_by` | str | 创建者 ID |
资料来源：[backend/open_webui/models/knowledge.py:1-80]()
## 数据库交互层
### 数据库连接管理
`db.py` 模块负责建立和管理数据库连接，支持多种数据库后端：
```python
# 核心配置参数
DB_HOST = os.environ.get('DB_HOST', 'localhost')
DB_PORT = os.environ.get('DB_PORT', '5432')
DB_NAME = os.environ.get('DB_NAME', 'openwebui')
DB_USER = os.environ.get('DB_USER', 'postgres')
DB_PASSWORD = os.environ.get('DB_PASSWORD', '')
```
**支持的数据库类型：**
| 数据库 | 配置项 | 说明 |
|-------|-------|------|
| SQLite | 默认 | 轻量级开发环境 |
| PostgreSQL | `DATABASE_URL` | 生产环境推荐 |
| MySQL | `DATABASE_URL` | 兼容模式支持 |
资料来源：[backend/open_webui/internal/db.py:30-80]()
### 数据仓库模式
系统采用 Repository 模式封装数据访问逻辑，提供统一的 CRUD 操作接口：
```mermaid
graph TB
A[Service Layer] --> B[Repository Interface]
B --> C[UserRepository]
B --> D[ChatRepository]
B --> E[MessageRepository]
B --> F[FileRepository]
C --> G[(Database)]
D --> G
E --> G
F --> G
```
### 数据清理与安全
消息内容在存入数据库前会经过严格的安全处理：
```python
def sanitize_text_for_db(text: str) -> str:
"""移除可能导致数据库问题的特殊字符"""
# 移除空字符和其他控制字符
return text.replace('\x00', '')
```
**安全措施包括：**
- 移除空字符 (`\x00`)
- 转义 HTML 特殊字符
- 验证字符串长度
- 类型检查和类型转换
资料来源：[backend/open_webui/models/chats.py:40-60]()
## 数据流程与生命周期
### 消息创建流程
```mermaid
sequenceDiagram
participant U as 用户
participant API as API路由
participant S as 服务层
participant M as MessageModel
participant D as 数据库
U->>API: 发送消息
API->>S: create_message()
S->>M: 构建消息对象
M->>D: sanitize_text_for_db()
D-->>M: 清理后的文本
M->>D: INSERT INTO messages
D-->>M: 返回插入结果
M-->>S: MessageModel
S-->>API: 响应
API-->>U: 返回消息
```
### 对话历史查询流程
系统采用两级缓存策略优化查询性能：
1. **优先路径**：从 `chat_message` 表直接查询（推荐）
2. **回退路径**：从 `chat.chat.history.messages` JSON blob 读取（兼容旧数据）
```mermaid
flowchart TD
A[get_messages_map] --> B{chat_message表存在?}
B -->|是| C[快速查询
ChatMessages.get_messages_map_by_chat_id]
B -->|否| D[查询Chat表]
D --> E{Chat存在?}
E -->|是| F[解析chat.history.messages]
E -->|否| G[返回None]
C --> H[返回消息映射]
F --> H
```
资料来源：[backend/open_webui/models/chats.py:15-35]()
## 配置与环境变量
数据模型层的行为受以下环境变量控制：
| 环境变量 | 默认值 | 说明 |
|---------|-------|------|
| `DATABASE_URL` | sqlite | 数据库连接字符串 |
| `DB_HOST` | localhost | 数据库主机 |
| `DB_PORT` | 5432 | 数据库端口 |
| `DB_NAME` | openwebui | 数据库名称 |
| `DB_USER` | postgres | 数据库用户 |
| `DEVICE_TYPE` | cpu | 嵌入模型设备类型 |
| `USE_CUDA_DOCKER` | false | 是否使用GPU加速 |
资料来源：[backend/open_webui/env.py:1-60]()
## 扩展与自定义
### 添加新数据模型
在 Open WebUI 中添加新的数据模型需要遵循以下步骤：
1. 在 `backend/open_webui/models/` 目录创建新的模型文件
2. 定义 Pydantic 模型类继承基础类
3. 在 `db.py` 中注册新的数据库表
4. 实现 CRUD 操作方法
```python
# 示例：新模型结构
from pydantic import BaseModel
from typing import Optional
from datetime import datetime
class NewModel(BaseModel):
id: str
name: str
description: Optional[str] = None
created_at: datetime
updated_at: datetime
```
### 数据迁移策略
系统支持平滑的数据迁移，确保向后兼容性：
- 新字段添加使用默认值
- 旧数据结构在读取时自动转换
- 迁移脚本支持批量更新历史数据
## 最佳实践
### 数据访问规范
1. **始终使用模型方法**：通过模型层访问数据，不要直接操作数据库
2. **处理空值情况**：使用 `Optional` 类型注解，明确空值处理逻辑
3. **批量操作优化**：对于大量数据使用批量插入和查询
4. **事务管理**：相关操作使用数据库事务保证一致性
### 性能优化建议
| 场景 | 优化方案 |
|------|---------|
| 频繁读取对话 | 使用 `get_messages_map_by_chat_id` 快速路径 |
| 大量文件存储 | 配置对象存储而非数据库 |
| 向量检索 | 使用专门的向量数据库后端 |
| 复杂查询 | 添加适当的数据库索引 |
## 相关文档
- [API 路由层](../api/routes)
- [服务层架构](../services)
- [存储配置](../storage)
- [安全机制](../security)
---
## 认证与安全
### 相关页面
相关主题：[后端路由与 API](#page-backend-routers), [数据模型层](#page-backend-models)
相关源码文件
以下源码文件用于生成本页说明：
- [backend/open_webui/utils/auth.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/utils/auth.py)
- [backend/open_webui/utils/oauth.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/utils/oauth.py)
- [backend/open_webui/routers/auths.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/routers/auths.py)
- [backend/open_webui/models/users.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/models/users.py)
- [backend/open_webui/routers/scim.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/routers/scim.py)
- [src/lib/constants/permissions.ts](https://github.com/open-webui/open-webui/blob/main/src/lib/constants/permissions.ts)
- [backend/open_webui/utils/asgi_middleware.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/utils/asgi_middleware.py)
- [backend/open_webui/env.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/env.py)
# 认证与安全
## 概述
Open WebUI 的认证与安全系统是一套完整的多层防护机制，支持多种认证方式，包括本地账号认证、OAuth 2.0 单点登录、API Key 认证以及 SCIM 用户管理协议。该系统采用基于角色的访问控制（RBAC）模型，确保不同权限级别的用户只能访问其授权范围内的资源。安全架构的核心设计理念是将认证逻辑与业务逻辑分离，通过中间件统一处理身份验证和授权检查。
整个认证体系构建在 FastAPI 框架之上，利用 Python 的异步特性实现高性能的请求处理。密码存储采用行业标准的加密算法，用户凭证在传输过程中全程使用 HTTPS 加密保护。系统还提供了细粒度的权限控制机制，支持对知识库、提示词、模型等资源进行独立的读写权限配置。
## 认证方式
### 本地账号认证
本地账号认证是 Open WebUI 的基础认证方式，用户通过用户名和密码注册和登录系统。注册时系统会验证邮箱格式并确保用户名唯一性，密码则通过 bcrypt 算法进行加盐哈希存储，确保即使数据库泄露也无法直接还原用户密码。
登录流程中，系统首先根据用户名查找用户记录，验证密码哈希是否匹配。认证成功后，系统生成 JWT（JSON Web Token）格式的访问令牌，令牌中包含用户 ID、角色和过期时间等信息。令牌的有效期默认为 24 小时，用户可以在此期间无需重新登录访问系统资源。
```mermaid
sequenceDiagram
participant 用户
participant 前端 as 前端应用
participant API as 认证 API
participant 数据库 as 用户数据库
用户->>前端: 输入用户名和密码
前端->>API: POST /auth/login
API->>数据库: 查询用户信息
数据库-->>API: 用户记录
API->>API: 验证密码哈希
API->>API: 生成 JWT Token
API-->>前端: 返回 Token 和用户信息
前端->>前端: 存储 Token 到本地
前端-->>用户: 登录成功
```
用户注册功能默认启用，但管理员可通过配置禁用注册或将系统设置为只读模式。在只读模式下，新用户注册将被阻止，但现有用户仍可正常登录使用系统。密码修改功能允许用户随时更新密码，系统会要求输入当前密码以确认身份。
资料来源：[backend/open_webui/routers/auths.py:1-100](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/routers/auths.py)
资料来源：[backend/open_webui/models/users.py:1-150](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/models/users.py)
### OAuth 2.0 单点登录
Open WebUI 支持通过 OAuth 2.0 协议与企业身份提供商集成，实现单点登录（SSO）。系统目前支持 OIDC（OpenID Connect）标准，能够与主流的身份服务如 Keycloak、Authentik、Okta、Auth0 等无缝对接。OAuth 认证流程遵循标准授权码模式，用户首先被重定向到身份提供商进行身份验证，验证成功后返回授权码，再由后端交换为访问令牌和用户信息。
OAuth 配置通过环境变量进行管理，主要配置项包括提供商类型、客户端 ID、客户端密钥和授权端点 URL。系统会自动发现 OIDC 提供商的配置元数据，包括令牌颁发者地址、用户信息端点和 JWKS（JSON Web Key Set）用于验证令牌签名。
```mermaid
graph TD
A[用户访问 Open WebUI] --> B{是否已登录}
B -->|否| C[点击 OAuth 登录]
C --> D[重定向到身份提供商]
D --> E[用户输入凭证]
E --> F{身份验证成功}
F -->|是| G[返回授权码]
F -->|否| H[显示错误信息]
G --> I[后端交换授权码]
I --> J[获取访问令牌]
J --> K[获取用户信息]
K --> L[创建或更新本地用户]
L --> M[生成 JWT 会话]
M --> N[用户登录成功]
B -->|是| O[直接访问受保护资源]
```
用户首次通过 OAuth 登录时，系统会自动创建本地用户记录，将 OAuth 提供商返回的用户信息映射到本地用户模型。后续登录时，系统会识别已有用户并更新其信息，实现用户数据的同步。管理员可以为不同用户分配不同的角色，或将 OAuth 用户自动映射到特定角色组。
资料来源：[backend/open_webui/utils/oauth.py:1-200](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/utils/oauth.py)
### API Key 认证
对于程序化访问场景，Open WebUI 提供了 API Key 认证方式，允许外部应用或服务使用 API Key 访问系统接口。API Key 通过自定义 HTTP 头传输，默认头名称为 `x-api-key`，可在配置中修改以适应不同的反向代理环境。
API Key 的创建和管理完全由管理员控制，每个 API Key 可以关联到特定用户或配置为全局密钥。全局密钥绕过用户关联，适用于服务间通信或系统集成场景。API Key 采用一次性哈希存储，后端仅保存密钥的 SHA-256 摘要，用户创建后无法再次查看完整密钥，必须保存后妥善保管。
当 API Key 通过中间件验证时，系统会将其映射到关联的用户身份，后续的权限检查逻辑与普通用户登录完全一致。这意味着 API Key 持有者受到与普通用户相同的 RBAC 约束，确保程序化访问不会绕过安全策略。
资料来源：[backend/open_webui/utils/asgi_middleware.py:1-80](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/utils/asgi_middleware.py)
### SCIM 用户管理
Open WebUI 实现了 SCIM（System for Cross-domain Identity Management）2.0 协议，支持与企业身份管理系统（如 Okta、Azure AD、OneLogin）集成进行用户自动化配置和生命周期管理。SCIM 接口允许外部系统推送用户创建、更新和禁用操作，实现用户账号的集中管理。
```mermaid
graph LR
A[身份管理系统] -->|POST /Users| B[创建用户]
A -->|PUT /Users/:id| C[更新用户]
A -->|PATCH /Users/:id| D[修改用户属性]
A -->|DELETE /Users/:id| E[禁用用户]
A -->|GET /Users| F[查询用户列表]
B --> G{验证数据}
G -->|通过| H[创建本地用户]
G -->|失败| I[返回错误]
H --> J[分配默认角色]
J --> K[返回用户信息]
```
SCIM 端点位于 `/scim/v2` 路径下，支持标准的 RESTful 操作。创建用户时，系统会验证请求体的 schema 合规性，提取用户名、邮箱、姓名和活跃状态等核心属性。成功创建的用户会被分配默认角色，并生成对应的本地账号。用户更新操作会同步修改本地用户记录，包括角色变更和状态切换。
资料来源：[backend/open_webui/routers/scim.py:1-300](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/routers/scim.py)
## 令牌与会话管理
### JWT 令牌机制
Open WebUI 使用 JWT（JSON Web Token）作为主要的会话令牌格式。JWT 包含三个部分：头部（Header）、载荷（Payload）和签名（Signature）。令牌在用户登录成功后生成，包含用户 ID、用户名、角色、权限范围和过期时间等声明。签名使用 HS256 算法，确保令牌内容不可被篡改。
令牌的有效期通过配置管理，默认设置为 24 小时。系统在每个请求中验证令牌的签名和过期时间，过期令牌将被拒绝并返回 401 未授权响应。用户可以通过设置中的"记住我"功能延长令牌有效期，延长后的有效期可达 30 天。
```json
{
"id": "user-uuid",
"name": "username",
"email": "user@example.com",
"role": "user",
"exp": 1699999999,
"iat": 1699913599
}
```
令牌刷新机制允许用户在令牌即将过期时获取新令牌，无需重新输入密码。刷新令牌通过独立的端点交换，系统会验证原令牌的有效性后颁发新令牌并使旧令牌失效。这种机制在保持安全性的同时提供了流畅的用户体验。
资料来源：[backend/open_webui/utils/auth.py:50-150](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/utils/auth.py)
### Cookie 与 Header 认证
系统支持两种令牌传输方式：通过 HTTP Cookie 或 Authorization Header。Cookie 方式适用于浏览器环境，令牌自动随请求发送并在浏览器关闭后清除。Header 方式则需要客户端手动在请求头中添加 `Authorization: Bearer `，适用于 API 客户端和程序化访问。
```mermaid
graph TD
A[收到 HTTP 请求] --> B{检查 Authorization 头}
B -->|存在| C[提取 Bearer Token]
B -->|不存在| D{检查 Cookie}
D -->|存在| E[提取 token Cookie]
D -->|不存在| F{检查 API Key 头}
F -->|存在| G[验证 API Key]
F -->|不存在| H[返回 401]
C --> I[验证 JWT 签名]
E --> I
G --> J{API Key 有效}
J -->|是| K[获取关联用户]
J -->|否| H
I --> L{JWT 有效}
L -->|是| M[设置请求状态]
L -->|否| H
K --> M
```
中间件优先检查 Authorization 头，若不存在则回退到 Cookie，最后才检查 API Key。这种优先级设计确保了最佳的安全性：Bearer Token 提供了最细粒度的控制，而 Cookie 认证则为 Web 界面提供了便利。
资料来源：[backend/open_webui/utils/asgi_middleware.py:20-100](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/utils/asgi_middleware.py)
## 基于角色的访问控制
### 角色定义
Open WebUI 实现了三级角色体系，每种角色对应不同的权限级别：
| 角色 | 描述 | 主要权限 |
|------|------|----------|
| admin | 管理员 | 全部功能、用户管理、系统配置、模型管理 |
| user | 普通用户 | 聊天、创建知识库、使用提示词 |
| pending | 待审核用户 | 仅登录，无功能权限 |
管理员拥有系统的完全控制权，可以创建和删除用户、修改系统配置、管理 Ollama 模型和知识库。普通用户可以正常使用对话功能，创建个人知识库和提示词，但无法访问管理功能。待审核用户是注册后等待管理员审批的临时状态，此状态下用户只能登录无法使用任何功能。
默认情况下，管理员需要在用户管理界面手动审核新注册用户。但系统也支持配置为自动批准模式，新用户注册后自动获得普通用户角色，立即可以使用系统全部基础功能。
资料来源：[src/lib/constants/permissions.ts:1-100](https://github.com/open-webui/open-webui/blob/main/src/lib/constants/permissions.ts)
资料来源：[backend/open_webui/models/users.py:50-120](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/models/users.py)
### 资源权限授予
除了基于角色的粗粒度控制，系统还支持对特定资源进行细粒度的权限授予。资源类型包括知识库（knowledge）、提示词（prompt）、文件（file）等，每种资源可以独立设置读（read）、写（write）和删除（delete）权限。
```mermaid
graph TD
A[用户请求访问资源] --> B[获取资源信息]
B --> C{用户是管理员?}
C -->|是| D[允许访问]
C -->|否| E{用户是资源所有者?}
E -->|是| D
E -->|否| F[查询访问授权表]
F --> G{存在匹配授权?}
G -->|是| H{授权类型匹配请求?}
H -->|是| D
H -->|否| I[拒绝访问]
G -->|否| I[拒绝访问]
```
访问授权表（Access Grants）存储用户与资源之间的权限关系。授权可以针对个人用户或用户组设置，支持灵活的权限继承和覆盖机制。管理员可以授予其他用户访问自己创建的知识库的权限，实现团队协作。
资源级别的权限检查贯穿于各个路由处理函数。系统在处理请求前首先验证用户身份，然后在执行业务逻辑前检查用户是否具有相应资源的访问权限。若权限不足，请求将被拒绝并返回 403 Forbidden 响应。
资料来源：[backend/open_webui/routers/knowledge.py:50-150](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/routers/knowledge.py)
## 安全中间件
### 请求认证中间件
ASGI 中间件是请求处理流程的第一道关卡，负责从 HTTP 请求中提取并验证认证凭证。该中间件实现了统一的认证逻辑，封装在 FastAPI 的请求处理管道中，对所有路由生效。
```python
async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
# 仅处理 HTTP 请求
if scope['type'] != 'http':
await self.app(scope, receive, send)
return
request = Request(scope)
# 尝试多种认证方式
token = self._extract_bearer_token(request)
if not token:
token = self._extract_cookie_token(request)
if not token:
token = self._extract_api_key(request)
# 将认证结果存入请求状态
request.state.token = token
request.state.enable_api_keys = self._snapshot_config()
```
中间件按优先级依次尝试 Bearer Token、Cookie Token 和 API Key 三种认证方式。一旦找到有效凭证，中间件会将用户信息和权限快照存入 `request.state`，供后续处理函数使用。这种设计使得业务逻辑可以专注于权限检查，无需关心认证细节。
中间件还会添加响应头 `X-Process-Time`，记录请求处理耗时，便于监控和性能分析。处理时间会被记录但不会影响正常响应，主要用于调试和运维目的。
资料来源：[backend/open_webui/utils/asgi_middleware.py:1-150](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/utils/asgi_middleware.py)
### CSRF 保护
系统实现了 CSRF（跨站请求伪造）保护机制，防止恶意网站诱导已登录用户发起非预期请求。CSRF 防护通过验证请求头中的自定义字段实现，敏感操作（如表单提交、状态变更）必须携带有效的 CSRF 令牌。
Web 界面在发起跨域请求前会自动获取并附加 CSRF 令牌，确保用户操作的合法性。API 客户端则需要在请求头中手动添加令牌，或使用 Cookie 认证方式（Cookie 请求会自动携带同源策略保护）。
## 环境配置
### 认证相关环境变量
Open WebUI 通过环境变量配置认证和安全相关的各项参数。这些变量在服务启动时读取，决定了系统的安全行为。
| 环境变量 | 默认值 | 描述 |
|----------|--------|------|
| WEBUI_AUTH | True | 是否启用认证（False 为公开访问） |
| ADMIN_USER_EMAIL | - | 管理员邮箱（首次启动时创建） |
| ADMIN_USER_PASSWORD | - | 管理员密码 |
| JWT_EXPIRY | 24h | JWT 令牌有效期 |
| OIDC_CLIENT_ID | - | OAuth 客户端 ID |
| OIDC_CLIENT_SECRET | - | OAuth 客户端密钥 |
| OIDC_PROVIDER_URL | - | OIDC 提供商 URL |
| CUSTOM_API_KEY_HEADER | x-api-key | API Key 传输头名称 |
| SCIM_AUTH_HEADER | - | SCIM 认证头 |
管理员邮箱和密码在首次启动时用于创建初始管理员账号。如果未设置，系统会在控制台输出随机生成的初始密码。生产环境中强烈建议设置强密码并妥善保管凭证。
资料来源：[backend/open_webui/env.py:30-100](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/env.py)
### OAuth 提供商配置
OAuth 认证需要配置提供商的详细信息。以下是常见的 OAuth 提供商配置示例：
```bash
# Keycloak 配置示例
OIDC_PROVIDER_URL=https://keycloak.example.com/realms/myrealm
OIDC_CLIENT_ID=open-webui
OIDC_CLIENT_SECRET=your-client-secret
# Authentik 配置示例
OIDC_PROVIDER_URL=https://authentik.example.com/application/oauth2/open-webui
OIDC_CLIENT_ID=open-webui
OIDC_CLIENT_SECRET=your-client-secret
# 通用 OIDC 配置（系统自动发现元数据）
OIDC_PROVIDER_URL=https://provider.example.com
OIDC_CLIENT_ID=open-webui
OIDC_CLIENT_SECRET=your-client-secret
```
配置完成后，管理员需要在 OAuth 提供商的应用注册中设置回调 URL，格式为 `{WEBUI_URL}/auth/oidc/callback`。用户点击登录页的 SSO 按钮后将自动跳转到提供商进行身份验证。
资料来源：[backend/open_webui/utils/oauth.py:100-250](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/utils/oauth.py)
## 安全最佳实践
### 部署建议
在生产环境中部署 Open WebUI 时，应遵循以下安全最佳实践：
- **启用 HTTPS**：所有生产部署必须使用 HTTPS，确保传输层加密。使用反向代理（如 Nginx、Caddy）终止 TLS 连接并转发 HTTP 请求到后端。
- **配置强管理员密码**：首次部署时使用包含大小写字母、数字和特殊字符的强密码。定期更换密码，建议周期为 90 天。
- **限制 API Key 访问**：API Key 适合机器对机器通信，应限制其访问范围，优先使用最小权限原则。
- **启用审计日志**：配置日志记录所有认证事件和敏感操作，便于安全审计和异常检测。
- **定期更新**：保持 Open WebUI 和所有依赖项为最新版本，及时应用安全补丁。
### 常见安全威胁防护
系统内置了针对常见 Web 安全威胁的防护机制：
- **SQL 注入防护**：使用参数化查询处理所有数据库操作，阻止恶意 SQL 代码注入。
- **XSS 防护**：前端对用户输入进行转义处理，防止跨站脚本执行。
- **CSRF 防护**：敏感操作需要有效的 CSRF 令牌，防止跨站请求伪造。
- **暴力破解防护**：登录失败后实施渐进式延迟，阻止自动化暴力猜测攻击。
## 总结
Open WebUI 的认证与安全系统提供了全面而灵活的访问控制能力，支持从简单的单用户部署到复杂的企业级 SSO 集成。通过 JWT 令牌、OAuth 2.0、API Key 和 SCIM 协议的多重支持，系统可以适应各种使用场景和安全需求。基于角色的访问控制与细粒度资源权限的结合，确保了权限管理的精确性和灵活性。管理员应根据实际需求选择合适的认证方式，并遵循安全最佳实践进行部署和运维。
---
## 前端组件结构
### 相关页面
相关主题：[系统架构](#page-architecture), [前端路由页面](#page-frontend-routes)
相关源码文件
以下源码文件用于生成本页说明：
- [src/lib/components/chat/Chat.svelte](https://github.com/open-webui/open-webui/blob/main/src/lib/components/chat/Chat.svelte)
- [src/lib/components/chat/Messages.svelte](https://github.com/open-webui/open-webui/blob/main/src/lib/components/chat/Messages.svelte)
- [src/lib/components/workspace/Models.svelte](https://github.com/open-webui/open-webui/blob/main/src/lib/components/workspace/Models.svelte)
- [src/lib/components/admin/Settings.svelte](https://github.com/open-webui/open-webui/blob/main/src/lib/components/admin/Settings.svelte)
- [src/lib/stores/index.ts](https://github.com/open-webui/open-webui/blob/main/src/lib/stores/index.ts)
- [src/lib/i18n/index.ts](https://github.com/open-webui/open-webui/blob/main/src/lib/i18n/index.ts)
# 前端组件结构
## 概述
Open WebUI 的前端采用现代化的 SvelteKit 框架构建，采用组件化架构设计。前端代码位于 `src/` 目录下，主要包含组件（components）、状态管理（stores）、工具函数（utils）、国际化（i18n）等核心模块。整个前端架构遵循高内聚低耦合的设计原则，通过 Svelte 的响应式系统和 Store 模式实现状态共享与组件通信。
## 目录结构
```
src/
├── lib/
│ ├── components/ # UI 组件目录
│ │ ├── chat/ # 聊天相关组件
│ │ ├── workspace/ # 工作区组件
│ │ ├── admin/ # 管理面板组件
│ │ └── ...
│ ├── stores/ # Svelte 状态存储
│ ├── utils/ # 工具函数
│ ├── i18n/ # 国际化模块
│ └── constants.ts # 常量定义
├── app.html # 应用主模板
└── routes/ # 页面路由
```
## 核心组件架构
### 聊天组件体系
聊天模块是 Open WebUI 的核心功能之一，主要由以下组件构成：
| 组件名称 | 文件路径 | 功能描述 |
|---------|---------|---------|
| Chat.svelte | src/lib/components/chat/ | 聊天主容器组件，处理用户输入和消息流 |
| Messages.svelte | src/lib/components/chat/ | 消息展示组件，负责渲染对话内容 |
| Collapsible | - | 可折叠容器，用于渲染思考过程和代码解释器 |
#### 消息处理流程
```mermaid
graph TD
A[用户输入] --> B[Chat.svelte]
B --> C[验证输入]
C --> D[发送API请求]
D --> E[流式响应]
E --> F[Messages.svelte]
F --> G[内容处理sanitizeResponseContent]
G --> H[渲染消息]
H --> I[显示完成状态]
J[代码块] --> K[Collapsible组件]
K --> L[代码解释器执行]
L --> M[展示执行结果]
```
聊天组件通过 Store 模式实现与全局状态的同步，支持流式输出和多模态交互。
### 工作区组件
Models.svelte 是工作区中的重要组件，负责模型管理和配置界面：
```mermaid
graph LR
A[模型列表] --> B[模型选择器]
B --> C[配置面板]
C --> D[参数调整]
D --> E[模型切换]
E --> A
```
工作区组件与后端 API 通过统一的接口层进行通信，支持模型的动态加载和配置管理。
### 管理面板组件
管理面板通过 Settings.svelte 组件实现用户设置和系统配置功能：
| 配置类别 | 功能模块 |
|---------|---------|
| 用户设置 | 主题切换、语言选择、音频配置 |
| 系统设置 | API 配置、数据库连接、存储后端 |
| 安全设置 | RBAC 权限管理、访问控制 |
## 状态管理
### Store 架构
Open WebUI 使用 Svelte 的 writable store 模式实现全局状态管理。核心状态存储定义在 `src/lib/stores/index.ts` 中：
```typescript
// 关键状态定义示例
export const settings: Writable = writable({});
export const chatRequestQueues: Writable> = writable({});
export const showSidebar = writable(false);
export const showSettings = writable(false);
```
#### 状态分类表
| 状态类型 | 变量名 | 用途 |
|---------|-------|------|
| 用户界面 | showSidebar, showSettings | 控制面板显示/隐藏 |
| 聊天状态 | chatRequestQueues | 管理请求队列 |
| 全局配置 | settings | 存储用户偏好设置 |
| 临时状态 | temporaryChatEnabled | 临时会话标记 |
### 响应式数据流
```mermaid
graph LR
A[用户操作] --> B[Store 更新]
B --> C[响应式订阅]
C --> D[组件重渲染]
D --> E[UI 更新]
```
## 国际化支持
### i18n 模块
国际化系统位于 `src/lib/i18n/` 目录，支持多语言切换功能：
- 语言检测与自动切换
- 实时翻译文本替换
- 聊天历史上下文保留
国际化配置通过后端 `backend/open_webui/config.py` 中的配置项管理：
```python
VOICE_MODE_PROMPT_TEMPLATE = PersistentConfig(...)
ENABLE_VOICE_MODE_PROMPT = PersistentConfig(...)
```
## 工具函数库
### 核心工具模块
`src/lib/utils/index.ts` 提供了丰富的前端工具函数：
| 函数名称 | 功能描述 |
|---------|---------|
| sanitizeResponseContent | 清理响应内容，移除特殊标记 |
| processResponseContent | 处理中文内容显示 |
| extractSentences | 提取音频用句子 |
| extractParagraphsForAudio | 提取音频用段落 |
| extractCodeBlocks | 提取并处理代码块 |
#### 内容处理流程
```mermaid
graph TD
A[原始内容] --> B[移除特殊标记]
B --> C[中文处理processChineseContent]
C --> D[代码块提取]
D --> E[清理敏感字符]
E --> F[最终输出]
```
### 响应内容清理
系统通过 `sanitizeResponseContent` 函数处理模型输出：
```typescript
export const sanitizeResponseContent = (content: string) => {
return content
.replace(/<\|[a-z]*$/, '')
.replace(/<\|[a-z]+\|$/, '')
.replace(/<$/, '')
.replaceAll('<', '<')
.replaceAll('>', '>')
.replaceAll(/<\|[a-z]+\|>/g, ' ')
.trim();
};
```
## 常量与配置
### 前端常量定义
`src/lib/constants.ts` 定义了应用级别的常量：
```typescript
export const APP_NAME = 'Open WebUI';
export const WEBUI_API_BASE_URL = `${WEBUI_BASE_URL}/api/v1`;
export const REQUIRED_OLLAMA_VERSION = '0.1.16';
```
#### 支持的文件类型
| 类型分类 | 文件格式 |
|---------|---------|
| 文档 | PDF, EPUB, DOCX, Markdown |
| 代码 | Python, JavaScript, CSS, XML |
| 音频 | MPEG, WAV |
| 其他 | CSV, HTML, Plain Text |
### API 端点常量
| 常量名称 | 用途 |
|---------|------|
| OLLAMA_API_BASE_URL | Ollama 模型 API |
| OPENAI_API_BASE_URL | OpenAI 兼容 API |
| AUDIO_API_BASE_URL | 音频处理 API |
| IMAGES_API_BASE_URL | 图像生成 API |
| RETRIEVAL_API_BASE_URL | 检索增强 API |
## 数据流转架构
### 消息流转
```mermaid
sequenceDiagram
participant U as 用户
participant C as Chat.svelte
participant S as Stores
participant M as Messages.svelte
participant API as Backend API
U->>C: 发送消息
C->>API: POST /api/v1/chat
API-->>C: 流式响应
C->>S: 更新状态
S->>M: 触发响应式更新
M-->>U: 渲染消息内容
```
### 状态同步机制
组件间通过 Svelte 的响应式系统实现高效状态同步，无需手动订阅和取消订阅。
## 组件通信模式
### 父子组件通信
- Props 传递：父组件向子组件传递数据和回调函数
- 事件分发：子组件通过 `createEventDispatcher` 触发事件
### 跨组件通信
- Store 共享：多个组件订阅同一 Store 实现状态共享
- Context API：深层嵌套组件间的数据传递
## 样式与主题
### 主题系统
`src/app.html` 中定义了主题切换的基础样式：
```css
html.dark #splash-screen {
background: #000;
}
html.her #splash-screen {
background: #983724;
}
```
### 加载屏幕
应用启动时显示统一的加载界面，包含 Logo、进度条等元素，通过 CSS 控制显示与隐藏。
## 技术栈总结
| 层级 | 技术选型 | 说明 |
|-----|---------|------|
| 框架 | SvelteKit | 现代化的 Svelte 框架 |
| 状态管理 | Svelte Stores | 轻量级响应式状态管理 |
| 路由 | SvelteKit Routes | 基于文件的路由系统 |
| 构建工具 | Vite | 快速开发与构建 |
| 样式 | CSS + Custom Properties | 原生 CSS 变量支持主题 |
| 国际化 | 自定义 i18n 模块 | 多语言支持 |
本页面详细介绍了 Open WebUI 前端组件的组织结构、核心组件功能、状态管理机制以及数据流转方式，为开发者理解和扩展前端功能提供了系统性参考。
---
## 前端路由页面
### 相关页面
相关主题：[前端组件结构](#page-frontend-structure), [系统架构](#page-architecture)
相关源码文件
以下源码文件用于生成本页说明：
- [src/routes/(app)/+page.svelte](https://github.com/open-webui/open-webui/blob/main/src/routes/(app)/+page.svelte) *(未在当前上下文中提供)*
- [src/routes/(app)/+layout.svelte](https://github.com/open-webui/open-webui/blob/main/src/routes/(app)/+layout.svelte) *(未在当前上下文中提供)*
- [src/routes/(app)/admin/+page.svelte](https://github.com/open-webui/open-webui/blob/main/src/routes/(app)/admin/+page.svelte) *(未在当前上下文中提供)*
- [src/routes/(app)/workspace/+page.svelte](https://github.com/open-webui/open-webui/blob/main/src/routes/(app)/workspace/+page.svelte) *(未在当前上下文中提供)*
- [src/routes/(app)/c/[id]/+page.svelte](https://github.com/open-webui/open-webui/blob/main/src/routes/(app)/c/[id]/+page.svelte) *(未在当前上下文中提供)*
- [src/lib/constants.ts](https://github.com/open-webui/open-webui/blob/main/src/lib/constants.ts)
- [src/lib/utils/index.ts](https://github.com/open-webui/open-webui/blob/main/src/lib/utils/index.ts)
- [src/lib/apis/terminal/index.ts](https://github.com/open-webui/open-webui/blob/main/src/lib/apis/terminal/index.ts)
- [backend/open_webui/main.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/main.py)
- [backend/open_webui/routers/knowledge.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/routers/knowledge.py)
- [backend/open_webui/config.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/config.py)
# 前端路由页面
## 概述
Open WebUI 的前端采用 **SvelteKit** 作为核心框架，通过文件路由系统（File-based Routing）组织页面结构。路由系统遵循 SvelteKit 的约定式路由规范，使用 `(app)` 路由组来封装应用的主要功能页面。
前端路由页面的主要职责包括：
- 提供用户交互的主界面（聊天、对话管理）
- 实现管理员控制台
- 支持工作区功能
- 处理动态路由参数（如对话 ID）
## 路由架构
### 路由目录结构
```
src/routes/
├── (app)/
│ ├── +layout.svelte # 应用布局组件
│ ├── +page.svelte # 首页/主聊天页面
│ ├── admin/
│ │ └── +page.svelte # 管理后台页面
│ ├── workspace/
│ │ └── +page.svelte # 工作区页面
│ └── c/
│ └── [id]/
│ └── +page.svelte # 动态对话详情页
```
### 路由与后端 API 的映射关系
| 前端路由 | 后端 API 前缀 | 功能描述 |
|----------|---------------|----------|
| `(app)/+page.svelte` | `/api/v1/chats` | 聊天列表与主界面 |
| `(app)/admin/+page.svelte` | `/api/v1/*` | 系统管理与配置 |
| `(app)/workspace/+page.svelte` | `/api/v1/knowledge` | 知识库与 RAG 工作区 |
| `(app)/c/[id]/+page.svelte` | `/api/v1/chats/{id}` | 特定对话详情与消息 |
## 核心组件说明
### 布局组件 (`+layout.svelte`)
`(app)/+layout.svelte` 作为全局布局，包裹所有 `(app)` 路由组下的页面。主要功能包括：
- 初始化全局状态管理
- 配置应用级导航栏
- 加载用户会话信息
- 设置主题与语言偏好
### 主页面 (`+page.svelte`)
`(app)/+page.svelte` 是用户首次访问时的默认页面，提供：
- 对话列表展示
- 新建对话入口
- 模型选择器
- 聊天消息输入框
### 管理员页面
`(app)/admin/+page.svelte` 提供系统管理功能：
- 用户管理 (RBAC)
- 模型配置
- 系统设置
- 日志与审计
资料来源：[backend/open_webui/main.py:1-50]()
### 工作区页面
`(app)/workspace/+page.svelte` 面向知识管理场景：
- 知识库文件上传与管理
- RAG 配置
- 文档处理状态监控
资料来源：[backend/open_webui/routers/knowledge.py:1-50]()
### 动态对话页面
`(app)/c/[id]/+page.svelte` 处理动态路由参数 `[id]`，该页面用于：
- 加载特定对话的消息历史
- 渲染对话流内容
- 处理代码解释器等特殊消息类型
资料来源：[src/lib/utils/index.ts:1-80]()
## API 路由集成
### 后端 FastAPI 路由注册
Open WebUI 后端使用 FastAPI 的.include_router()方法注册所有 API 路由：
```python
app.include_router(chats.router, prefix='/api/v1/chats', tags=['chats'])
app.include_router(knowledge.router, prefix='/api/v1/knowledge', tags=['knowledge'])
app.include_router(models.router, prefix='/api/v1/models', tags=['models'])
app.include_router(files.router, prefix='/api/v1/files', tags=['files'])
```
资料来源：[backend/open_webui/main.py:50-80]()
### 前端 API 端点常量
前端通过 `src/lib/constants.ts` 定义 API 基础 URL：
| 常量名 | 值 | 用途 |
|--------|-----|------|
| `WEBUI_API_BASE_URL` | `/api/v1` | 主 API 端点 |
| `AUDIO_API_BASE_URL` | `/api/v1/audio` | 音频处理 |
| `IMAGES_API_BASE_URL` | `/api/v1/images` | 图像处理 |
| `RETRIEVAL_API_BASE_URL` | `/api/v1/retrieval` | RAG 检索 |
资料来源：[src/lib/constants.ts:1-20]()
## 状态管理与数据流
```mermaid
graph TD
A[用户交互] --> B[SvelteKit 路由]
B --> C{页面组件}
C --> D[加载对话数据]
C --> E[管理知识库]
C --> F[管理员操作]
D --> G[调用 /api/v1/chats]
E --> H[调用 /api/v1/knowledge]
F --> I[调用 /api/v1/users, /api/v1/configs]
G --> J[后端 Chat 路由处理器]
H --> K[后端 Knowledge 路由处理器]
I --> L[后端 Admin 路由处理器]
J --> M[(SQLite/PostgreSQL)]
K --> N[(向量数据库)]
L --> M
```
## 消息内容处理
前端路由页面使用 `sanitizeResponseContent` 和 `processResponseContent` 函数处理 AI 响应：
```typescript
export const sanitizeResponseContent = (content: string) => {
return content
.replace(/<\|[a-z]*$/, '')
.replace(/<\|[a-z]+\|$/, '')
.replace(/<$/, '')
.replaceAll('<', '<')
.replaceAll('>', '>')
.replaceAll(/<\|[a-z]+\|>/g, ' ')
.trim();
};
```
资料来源：[src/lib/utils/index.ts:50-70]()
### 中文内容特殊处理
针对中文内容，框架进行了特殊处理以解决 Markdown/LaTeX 格式问题：
```typescript
function processChineseContent(content: string): string {
if (!/[\u4e00-\u9fa5]/.test(content)) return content;
// 中文内容处理逻辑
}
```
资料来源：[src/lib/utils/index.ts:75-90]()
## 文件 API 与终端集成
前端通过 `src/lib/apis/terminal/index.ts` 提供文件操作能力：
| 函数 | 功能 |
|------|------|
| `listFiles` | 列出目录中的文件 |
| `readFile` | 读取文件内容 |
| `downloadFileBlob` | 下载文件为 Blob |
资料来源：[src/lib/apis/terminal/index.ts:1-60]()
## 代码解释器集成
路由页面支持代码解释器功能，通过后端中间件处理 `code_interpreter` 类型消息：
```python
elif item_type == 'open_webui:code_interpreter':
# 代码解释器消息处理
code = item.get('code', '').strip()
lang = item.get('lang', 'python')
status = item.get('status', 'in_progress')
```
资料来源：[backend/open_webui/utils/middleware.py:1-50]()
### 代码执行引擎配置
| 配置项 | 默认值 | 说明 |
|--------|--------|------|
| `ENABLE_CODE_EXECUTION` | True | 是否启用代码执行 |
| `CODE_EXECUTION_ENGINE` | pyodide | 执行引擎 (pyodide/jupyter) |
| `CODE_EXECUTION_JUPYTER_URL` | - | Jupyter 服务地址 |
| `CODE_EXECUTION_JUPYTER_AUTH` | - | Jupyter 认证信息 |
资料来源：[backend/open_webui/config.py:1-50]()
## 访问控制与权限
路由页面通过后端 RBAC 系统实现访问控制：
```python
if not (
user.role == 'admin'
or knowledge.user_id == user.id
or await AccessGrants.has_access(...)
):
raise HTTPException(status_code=400, detail=ERROR_MESSAGES.ACCESS_PROHIBITED)
```
资料来源：[backend/open_webui/routers/knowledge.py:50-80]()
## 相关页面
- [后端 API 路由](backend/open_webui/main.py)
- [前端工具函数](src/lib/utils/index.ts)
- [应用常量定义](src/lib/constants.ts)
- [知识库路由](backend/open_webui/routers/knowledge.py)
- [终端 API](src/lib/apis/terminal/index.ts)
---
## 模型集成与支持
### 相关页面
相关主题：[检索增强生成 (RAG)](#page-retrieval-rag), [工具与函数系统](#page-tools-functions)
相关源码文件
以下源码文件用于生成本页说明：
- [backend/open_webui/main.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/main.py)
- [backend/open_webui/routers/models.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/routers/models.py)
- [backend/open_webui/routers/ollama.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/routers/ollama.py)
- [backend/open_webui/routers/openai.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/routers/openai.py)
- [backend/open_webui/utils/models.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/utils/models.py)
- [backend/open_webui/models/models.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/models/models.py)
- [backend/open_webui/config.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/config.py)
- [src/lib/constants.ts](https://github.com/open-webui/open-webui/blob/main/src/lib/constants.ts)
- [src/lib/components/chat/ModelSelector.svelte](https://github.com/open-webui/open-webui/blob/main/src/lib/components/chat/ModelSelector.svelte)
- [src/lib/components/workspace/Models.svelte](https://github.com/open-webui/open-webui/blob/main/src/lib/components/workspace/Models.svelte)
# 模型集成与支持
## 概述
Open WebUI 的模型集成与支持系统是整个平台的核心功能模块，负责管理与接入多种大语言模型（LLM）提供方。该系统通过统一的 API 网关架构，将 Ollama、OpenAI 兼容 API 等多种模型服务进行抽象封装，为用户提供无缝的模型切换与交互体验。
系统支持多模型并发对话、模型热度管理、角色权限控制等功能，并提供完整的模型生命周期管理，包括模型的发现、拉取、配置与删除操作。资料来源：[backend/open_webui/main.py:48]()
```mermaid
graph TD
A[用户界面] --> B[前端 ModelSelector]
B --> C[API 网关层]
C --> D[Ollama 路由器]
C --> E[OpenAI 路由器]
C --> F[Models 路由器]
D --> G[Ollama 服务]
E --> H[OpenAI 兼容服务]
F --> I[模型数据库]
G --> I
H --> I
```
## 架构设计
### API 端点结构
Open WebUI 采用 FastAPI 框架构建后端服务，通过路由器（Router）模式组织 API 端点。模型相关的 API 端点分布在多个路由器中，形成统一的接口体系。
| 路由器 | 前缀路径 | 标签 | 功能描述 |
|--------|----------|------|----------|
| models | `/api/v1/models` | models | 模型 CRUD 操作 |
| ollama | `/api/v1/ollama` | ollama | Ollama 专属 API |
| openai | `/api/v1/openai` | openai | OpenAI 兼容 API |
| functions | `/api/v1/functions` | functions | 函数调用管理 |
资料来源：[backend/open_webui/main.py:48-54]()
### 服务地址配置
前端通过 `src/lib/constants.ts` 集中管理所有 API 服务地址，支持开发环境与生产环境的动态切换。
```typescript
export const WEBUI_HOSTNAME = browser ? (dev ? `${location.hostname}:8080` : ``) : '';
export const WEBUI_BASE_URL = browser ? (dev ? `http://${WEBUI_HOSTNAME}` : ``) : ``;
export const WEBUI_API_BASE_URL = `${WEBUI_BASE_URL}/api/v1`;
export const OLLAMA_API_BASE_URL = `${WEBUI_BASE_URL}/ollama`;
export const OPENAI_API_BASE_URL = `${WEBUI_BASE_URL}/openai`;
```
资料来源：[src/lib/constants.ts:4-11]()
## 支持的模型类型
### Ollama 模型
Ollama 是 Open WebUI 的核心本地模型运行引擎，支持在本地部署和运行各类开源大语言模型。系统通过 Ollama API 进行模型管理，支持超过 1000 种开源模型。
支持的模型类型包括：
- **对话模型**：Llama 2/3、Mistral、Qwen 等
- **嵌入模型**：用于向量检索和语义搜索
- **多模态模型**：支持图像理解和分析的模型
### OpenAI 兼容模型
Open WebUI 通过 OpenAI 兼容层支持接入任何符合 OpenAI API 规范的服务提供方，包括：
- OpenAI 官方 API（GPT-4、GPT-3.5-turbo）
- Azure OpenAI Service
- 自定义 OpenAI 兼容 API 服务器
- 云端模型服务（如 Groq、Perplexity 等）
资料来源：[src/lib/apis/openai/index.ts:1-10]()
## 前端模型选择组件
### ModelSelector 组件
`ModelSelector.svelte` 是聊天界面中的模型选择器组件，提供直观的模型切换交互界面。该组件支持以下功能：
- 模型搜索与过滤
- 模型热度排序
- 快捷键切换模型
- 模型图标与描述显示
```mermaid
graph LR
A[用户点击选择器] --> B[展开模型列表]
B --> C[搜索/过滤模型]
C --> D[选择目标模型]
D --> E[更新会话上下文]
E --> F[发送请求至后端]
```
资料来源：[src/lib/components/chat/ModelSelector.svelte]()
### Workspace Models 组件
`Models.svelte` 是工作区中的模型管理界面，提供更全面的模型管理功能，包括：
- 模型列表展示与排序
- 模型添加与配置
- 模型删除与禁用
- 模型使用统计
资料来源：[src/lib/components/workspace/Models.svelte]()
## 模型管理 API
### 获取模型列表
```
GET /api/v1/models
```
返回系统中所有已配置的模型列表，包括模型的元数据、状态和配置信息。
### 获取模型详情
```
GET /api/v1/models/{model_id}
```
获取指定模型的详细信息，包括：
- 模型 ID 和名称
- 模型类型和提供者
- 上下文长度
- 支持的功能（函数调用、视觉等）
### 创建模型配置
```
POST /api/v1/models
```
创建新的模型配置，支持配置模型参数和连接信息。
### 更新模型配置
```
PUT /api/v1/models/{model_id}
```
更新现有模型的配置参数。
### 删除模型
```
DELETE /api/v1/models/{model_id}
```
从系统中移除指定的模型配置。
资料来源：[backend/open_webui/main.py:48]()
## 配置选项
### 环境变量配置
系统通过环境变量和配置文件管理模型相关的设置。主要配置项包括：
| 配置项 | 说明 | 默认值 |
|--------|------|--------|
| `OLLAMA_API_BASE_URL` | Ollama API 地址 | `/ollama` |
| `OPENAI_API_BASE_URL` | OpenAI API 地址 | `/openai` |
| `OPENAI_API_KEY` | OpenAI API 密钥 | - |
| `ENABLE_OPENAI_API` | 启用 OpenAI API | True |
| `DEFAULT_MODEL` | 默认模型 | - |
资料来源：[backend/open_webui/config.py]()
### 运行时配置
系统支持通过管理员界面动态调整模型配置，包括：
- 模型调用参数（温度、最大 token 等）
- API 超时设置
- 重试策略配置
- 代理设置
## 多模型对话支持
Open WebUI 支持在单一对话中使用多个模型，通过并行调用不同模型获取响应，实现更优的回答质量。
### 多模型对话流程
```mermaid
sequenceDiagram
participant U as 用户
participant F as 前端
participant B as 后端
participant M1 as 模型A
participant M2 as 模型B
U->>F: 发送消息
F->>B: 转发请求
B->>M1: 并发请求模型A
B->>M2: 并发请求模型B
M1-->>B: 返回响应A
M2-->>B: 返回响应B
B-->>F: 合并响应
F-->>U: 展示结果
```
### 模型选择策略
系统支持多种模型选择策略：
1. **自动选择**：根据请求类型自动选择最合适的模型
2. **手动选择**：用户显式指定使用的模型
3. **智能路由**：基于模型能力与请求特征的动态路由
资料来源：[src/lib/components/chat/ModelSelector.svelte]()
## 角色权限控制
Open WebUI 实现基于角色的访问控制（RBAC），模型访问权限与用户角色挂钩：
| 角色 | 权限级别 | 可用功能 |
|------|----------|----------|
| 管理员 | 完全权限 | 所有模型操作 |
| 普通用户 | 受限权限 | 使用已授权模型 |
| 访客 | 最小权限 | 仅使用公开模型 |
资料来源：[README.md]()
## 最佳实践
### 模型选择建议
1. **性能优先场景**：选择量化模型或较小的模型以降低延迟
2. **质量优先场景**：使用较大的基础模型或 GPT-4 系列
3. **成本敏感场景**：优先使用本地 Ollama 模型
4. **多模态场景**：选择支持视觉的模型（如 Llava）
### 安全配置
- 生产环境务必配置 API 密钥
- 启用模型访问审计日志
- 定期轮换 API 密钥
- 限制敏感模型的访问权限
## 相关文档
- [Ollama 官方文档](https://github.com/ollama/ollama)
- [OpenAI API 文档](https://platform.openai.com/docs/api-reference)
- [Open WebUI 安装指南](./installation.md)
- [管理员配置手册](./admin-guide.md)
---
## 检索增强生成 (RAG)
### 相关页面
相关主题：[模型集成与支持](#page-model-integration)
相关源码文件
以下源码文件用于生成本页说明：
- [backend/open_webui/retrieval/vector/factory.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/retrieval/vector/factory.py)
- [backend/open_webui/retrieval/loaders/main.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/retrieval/loaders/main.py)
- [backend/open_webui/retrieval/web/main.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/retrieval/web/main.py)
- [backend/open_webui/routers/knowledge.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/routers/knowledge.py)
- [backend/open_webui/routers/retrieval.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/routers/retrieval.py)
# 检索增强生成 (RAG)
## 概述
检索增强生成（Retrieval-Augmented Generation，简称 RAG）是一种将信息检索与语言模型生成相结合的技术架构。在 Open WebUI 项目中，RAG 模块负责从外部知识库、文档集合或网络资源中检索相关内容，并将检索结果注入到大语言模型（LLM）的上下文窗口中，从而提升模型回答的准确性、时效性和可信度。
Open WebUI 的 RAG 系统支持多种文档格式、多种向量存储后端以及多种网络搜索提供者，形成了完整的**文档处理 → 向量化 → 存储 → 检索 → 上下文注入**链路。
## 核心架构
RAG 系统在整体上分为三大子模块：
1. **文档加载与处理（Loaders）**：负责从各类文件格式中提取文本内容
2. **向量存储与检索（Vector Stores）**：负责文本的向量化、存储和相似度检索
3. **网络搜索（Web Retrieval）**：支持通过外部搜索引擎获取实时信息
```mermaid
graph TD
A[用户查询] --> B[检索模块]
B --> C{检索类型}
C -->|知识库检索| D[向量存储检索]
C -->|网络搜索| E[Web Search Providers]
D --> F[文档加载器]
F --> G[文本分块]
G --> H[向量化]
H --> I[向量数据库]
I --> J[相似度检索]
J --> K[上下文构建]
E --> L[搜索结果处理]
L --> K
K --> M[LLM 生成响应]
```
## 文档加载与处理
### 支持的文件格式
文档加载模块支持以下文件类型（资料来源：[src/lib/constants.ts](src/lib/constants.ts)）：
| 文件类型 | MIME 类型 |
|---------|-----------|
| PDF | `application/pdf` |
| EPUB | `application/epub+zip` |
| Word 文档 | `application/vnd.openxmlformats-officedocument.wordprocessingml.document` |
| 纯文本 | `text/plain` |
| CSV | `text/csv` |
| XML | `text/xml` |
| HTML | `text/html` |
| Markdown | `text/markdown` |
| Python 代码 | `text/x-python` |
| CSS | `text/css` |
| JavaScript | `application/x-javascript` |
| 音频 | `audio/mpeg`, `audio/wav` |
### 加载器实现
文档加载器的核心实现在 `backend/open_webui/retrieval/loaders/` 目录下。加载器采用统一的接口设计，主要包括：
- **PDF 处理**：支持多种 PDF 解析后端，包括 Tika、DOCLING、文档智能（Document Intelligence）、Mistral OCR、PaddleOCR VL、MinerU 等
- **图片 OCR**：通过 PaddleOCR VL 等引擎从图片中提取文字（资料来源：[backend/open_webui/retrieval/loaders/paddleocr_vl.py](backend/open_webui/retrieval/loaders/paddleocr_vl.py)）
```mermaid
graph LR
A[上传文件] --> B{文件类型判断}
B -->|PDF| C[PDF Loader]
B -->|图片| D[OCR Engine]
B -->|文本| E[Text Loader]
C --> F[文本提取]
D --> G[OCR 识别]
E --> H[直接读取]
F --> I[Document 对象]
G --> I
H --> I
I --> J[分块处理]
J --> K[元数据附加]
K --> L[输出片段列表]
```
### 配置参数
文档处理支持以下关键配置（资料来源：[backend/open_webui/retrieval/utils.py](backend/open_webui/retrieval/utils.py)）：
| 参数名 | 说明 |
|-------|------|
| `EXTERNAL_DOCUMENT_LOADER_URL` | 外部文档加载器服务地址 |
| `TIKA_SERVER_URL` | Apache Tika 服务器地址 |
| `DOCLING_SERVER_URL` | DOCLING 服务地址 |
| `DOCLING_API_KEY` | DOCLING API 密钥 |
| `PDF_EXTRACT_IMAGES` | 是否从 PDF 提取图片 |
| `PDF_LOADER_MODE` | PDF 加载模式 |
| `DOCUMENT_INTELLIGENCE_ENDPOINT` | Azure 文档智能端点 |
| `MISTRAL_OCR_API_BASE_URL` | Mistral OCR API 地址 |
| `PADDLEOCR_VL_BASE_URL` | PaddleOCR VL 服务地址 |
| `MINERU_API_URL` | MinerU API 地址 |
## 向量存储与检索
### 向量存储后端
Open WebUI 支持多种向量数据库作为存储后端，通过工厂模式（Factory Pattern）进行统一管理（资料来源：[backend/open_webui/retrieval/vector/factory.py](backend/open_webui/retrieval/vector/factory.py)）：
| 向量存储 | 说明 |
|---------|------|
| Chroma | 本地向量数据库 |
| FAISS | Facebook AI 相似度搜索 |
| Qdrant | 高性能向量数据库 |
| Milvus | 分布式向量数据库 |
| Weaviate | 云原生向量搜索引擎 |
| Pinecone | 云端向量数据库 |
| Elasticsearch | 混合搜索能力 |
| Chroma Legacy | 向后兼容模式 |
### 检索流程
```mermaid
sequenceDiagram
participant U as 用户
participant A as API 路由
participant R as 检索路由器
participant V as 向量存储
participant L as LLM
U->>A: 发送查询请求
A->>R: 转发查询
R->>V: 执行相似度搜索
V-->>R: 返回 Top-K 相关片段
R->>L: 构建提示词上下文
L-->>U: 生成增强响应
```
### 检索 API
检索功能通过 RESTful API 暴露，主要端点包括（资料来源：[backend/open_webui/routers/retrieval.py](backend/open-webui/routers/retrieval.py)）：
| 端点 | 方法 | 功能 |
|------|------|------|
| `/api/v1/retrieval/search` | POST | 执行知识库检索 |
| `/api/v1/retrieval/process` | POST | 处理并索引文档 |
| `/api/v1/retrieval/config` | GET | 获取检索配置 |
## 网络搜索
### 支持的搜索提供者
Open WebUI 集成了超过 15 种网络搜索提供者，可在 RAG 流程中注入实时网络信息（资料来源：[README.md](README.md)）：
| 提供者 | 说明 |
|-------|------|
| SearXNG | 开源自托管元搜索引擎 |
| Google PSE | Google Programmable Search Engine |
| Brave Search | Brave 浏览器搜索 API |
| Kagi | 高质量搜索服务 |
| Mojeek | 独立搜索索引 |
| Tavily | AI 优化的搜索 API |
| Perplexity | AI 搜索服务 |
| DuckDuckGo | 隐私导向搜索 |
| Bing | Microsoft 搜索 API |
| Jina | AI 驱动的搜索与摘要 |
| Exa | 语义搜索 API |
| Azure AI Search | Azure 云搜索服务 |
| Ollama Cloud | Ollama 云端服务 |
### 搜索结果处理
搜索结果经过标准化处理后返回统一的 `SearchResult` 数据结构（资料来源：[backend/open_webui/retrieval/web/ydc.py](backend/open_webui/retrieval/web/ydc.py)）：
```python
@dataclass
class SearchResult:
link: str # 结果链接
title: str # 结果标题
snippet: str # 摘要内容
```
对于不同的搜索 API，Open WebUI 进行了结果格式统一，包括：
- 标题提取与清理
- 摘要/片段（Snippet）的合并构建
- URL 解析与规范化
- 评分与排序
## 知识库管理
### 知识库 API
知识库管理功能提供了完整的 CRUD 操作（资料来源：[backend/open_webui/routers/knowledge.py](backend/open-webui/routers/knowledge.py)）：
| 端点 | 方法 | 功能 |
|------|------|------|
| `/api/v1/knowledge` | GET | 列出所有知识库 |
| `/api/v1/knowledge` | POST | 创建新知识库 |
| `/api/v1/knowledge/{id}` | GET | 获取知识库详情 |
| `/api/v1/knowledge/{id}` | PUT | 更新知识库配置 |
| `/api/v1/knowledge/{id}` | DELETE | 删除知识库 |
| `/api/v1/knowledge/{id}/file` | POST | 上传文件到知识库 |
| `/api/v1/knowledge/{id}/file/{file_id}` | DELETE | 从知识库删除文件 |
### 知识库数据模型
```
Knowledge {
id: string # 唯一标识符
name: string # 知识库名称
description: string # 描述信息
user_id: string # 所有者 ID
created_at: timestamp # 创建时间
updated_at: timestamp # 更新时间
settings: {
embeddings: object # 嵌入模型配置
chunk_size: int # 分块大小
chunk_overlap: int # 分块重叠
}
}
```
## RAG 与 LLM 集成
### 上下文注入流程
RAG 检索结果通过以下方式注入到 LLM 对话中：
```mermaid
graph LR
A[用户消息] --> B[检索查询生成]
B --> C[并行执行]
C --> D[向量检索]
C --> E[网络搜索]
D --> F[结果合并]
E --> F
F --> G[上下文构建]
G --> H[提示词组装]
H --> I[LLM 生成]
I --> J[响应输出]
```
### 提示词模板
RAG 系统使用专门的提示词模板来引导模型正确利用检索到的上下文：
- **默认检索模板**：通用问答场景
- **中文内容处理**：针对中文文档的特殊格式化处理（资料来源：[src/lib/utils/index.ts](src/lib/utils/index.ts)）
- **引用标注**：在回答中标注信息来源
## 配置管理
### 环境变量配置
RAG 系统的核心配置通过环境变量管理：
| 变量名 | 默认值 | 说明 |
|-------|-------|------|
| `ENABLE_RAG_WEB` | `True` | 启用网络搜索 RAG |
| `RAG_TOP_K` | `5` | 检索返回的 Top-K 结果数 |
| `RAG_EMBEDDING_MODEL` | - | 嵌入模型选择 |
| `RAG_VECTOR_DB` | `chroma` | 向量数据库选择 |
| `WEB_SEARCH_API_KEY` | - | 搜索 API 密钥 |
| `SEARXNG_QUERY_URL` | - | SearXNG 实例地址 |
## 使用场景
1. **私有知识问答**：上传内部文档创建私有知识库
2. **实时信息补充**：通过网络搜索获取最新资讯
3. **多模态文档理解**：处理 PDF、图片混合文档
4. **跨语言检索**：支持多语言文档的统一检索
## 最佳实践
- **分块策略**：根据文档类型选择合适的分块大小，代码类文档建议较小分块
- **向量模型选择**：根据文档语言选择对应语言的嵌入模型
- **混合检索**：结合向量检索与关键词检索以平衡精确度与召回率
- **定期更新**：知识库内容变更后需重新索引
---
## 工具与函数系统
### 相关页面
相关主题：[模型集成与支持](#page-model-integration)
相关源码文件
以下源码文件用于生成本页说明：
- [backend/open_webui/main.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/main.py)
- [backend/open_webui/config.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/config.py)
- [src/lib/utils/index.ts](https://github.com/open-webui/open-webui/blob/main/src/lib/utils/index.ts)
- [backend/open_webui/utils/middleware.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/utils/middleware.py)
- [src/lib/constants.ts](https://github.com/open-webui/open-webui/blob/main/src/lib/constants.ts)
# 工具与函数系统
## 概述
Open WebUI 的工具与函数系统是平台的核心扩展机制之一，允许用户通过自定义工具和函数来增强 AI 助手的交互能力。该系统支持在对话过程中动态调用外部工具、执行代码、访问外部数据源，从而实现更丰富的智能助手体验。
系统通过 API 路由层统一管理工具的注册、调用和生命周期维护，支持多种工具类型，包括内置工具、用户自定义工具以及通过函数定义的工具。
## 系统架构
### 整体架构流程
```mermaid
graph TD
A[用户请求] --> B[API 路由层
routers/tools.py]
B --> C[工具注册表
tools/__init__.py]
C --> D{工具类型}
D --> E[内置工具
builtin.py]
D --> F[用户自定义函数
models/functions.py]
D --> G[外部工具]
E --> H[工具执行引擎]
F --> H
G --> H
H --> I[结果返回]
I --> J[前端展示
Tools.svelte]
```
### 组件层级
| 层级 | 组件 | 职责 |
|------|------|------|
| API 层 | routers/tools.py | HTTP 接口、请求验证、响应格式化 |
| 核心层 | tools/__init__.py | 工具注册表、调度逻辑、生命周期管理 |
| 内置工具层 | tools/builtin.py | 系统内置工具实现 |
| 数据模型层 | models/functions.py | 函数数据结构、序列化/反序列化 |
| 前端层 | Tools.svelte | 工具管理界面、用户交互 |
| 中间件层 | utils/middleware.py | 工具输出渲染、内容处理 |
## 工具注册与路由
### API 路由配置
工具系统通过 FastAPI 路由模块挂载到主应用，所有工具相关的 HTTP 接口均以 `/api/v1/tools` 为前缀。
```python
app.include_router(tools.router, prefix='/api/v1/tools', tags=['tools'])
```
资料来源：[backend/open_webui/main.py]()
### 路由端点
| 端点 | 方法 | 功能 |
|------|------|------|
| `/` | GET | 获取工具列表 |
| `/{tool_id}` | GET | 获取特定工具详情 |
| `/` | POST | 注册新工具 |
| `/{tool_id}` | PUT | 更新工具配置 |
| `/{tool_id}` | DELETE | 删除工具 |
## 函数数据模型
### 数据结构定义
函数（Function）是工具系统的核心数据结构，用于描述可调用的工具逻辑。
```python
class Function:
id: str # 唯一标识符
name: str # 函数名称
description: str # 函数描述
parameters: dict # 参数定义（JSON Schema）
return_type: str # 返回值类型
is_enabled: bool # 是否启用
created_at: datetime # 创建时间
updated_at: datetime # 更新时间
```
### 参数定义规范
函数参数采用 JSON Schema 格式定义，支持以下类型：
| 类型 | 描述 | 示例 |
|------|------|------|
| string | 字符串类型 | `"type": "string"` |
| integer | 整数类型 | `"type": "integer"` |
| number | 数字类型 | `"type": "number"` |
| boolean | 布尔类型 | `"type": "boolean"` |
| array | 数组类型 | `"type": "array", "items": {...}` |
| object | 对象类型 | `"type": "object", "properties": {...}` |
## 工具执行流程
### 执行时序
```mermaid
sequenceDiagram
participant U as 用户
participant A as API路由
participant T as 工具注册表
participant E as 执行引擎
participant R as 结果渲染器
U->>A: 调用工具请求
A->>T: 查询工具定义
T-->>A: 返回工具元数据
A->>E: 提交执行任务
E->>E: 执行工具逻辑
E-->>A: 返回执行结果
A->>R: 渲染结果内容
R-->>A: 格式化输出
A-->>U: 返回响应
```
### 内置工具类型
系统预置多种内置工具，覆盖常见的扩展场景：
| 工具类别 | 功能描述 |
|----------|----------|
| 搜索工具 | 集成 SearXNG、Google PSE、Brave Search 等搜索引擎 |
| 知识库工具 | 支持知识库检索、文档问答 |
| 计算工具 | 数学计算、公式求解 |
| 代码执行 | 代码解释器执行 Python 代码 |
| 图像生成 | 集成 DALL-E、Stable Diffusion 等图像生成服务 |
## 前端集成
### 工具管理界面
前端工具管理组件位于 `src/lib/components/workspace/Tools.svelte`，提供以下功能：
- **工具列表视图**：展示所有已注册工具，支持按名称、类型筛选
- **工具详情面板**：查看工具描述、参数说明、使用示例
- **工具调试控制台**：测试工具调用、查看执行结果
- **工具创建向导**：引导用户创建自定义工具
### 响应内容处理
前端通过 `sanitizeResponseContent` 函数处理工具执行后的响应内容，确保内容安全展示：
```typescript
export const sanitizeResponseContent = (content: string) => {
return content
.replace(/<\|[a-z]*$/, '')
.replace(/<\|[a-z]+\|$/, '')
.replace(/<$/, '')
.replaceAll('<', '<')
.replaceAll('>', '>')
.replaceAll(/<\|[a-z]+\|>/g, ' ')
.trim();
};
```
资料来源：[src/lib/utils/index.ts]()
## 中间件渲染
### 工具输出渲染机制
系统中间件负责将工具执行结果渲染为可展示的 HTML 格式，支持代码解释器等特殊工具类型：
```python
elif item_type == 'open_webui:code_interpreter':
# 代码解释器需要检查/修改先前的累积内容
# 去除尾部未闭合的代码块
content = '\n'.join(parts)
content_stripped, original_whitespace = split_content_and_whitespace(content)
if is_opening_code_block(content_stripped):
content = content_stripped.rstrip('`').rstrip() + original_whitespace
else:
content = content_stripped + original_whitespace
```
资料来源：[backend/open_webui/utils/middleware.py]()
### 渲染输出格式
| 工具类型 | 渲染格式 | 说明 |
|----------|----------|------|
| 通用工具 | `` | 折叠面板展示 |
| 代码解释器 | `` | 带执行状态 |
| 思考过程 | `` | 显示思考耗时 |
## 配置管理
### 环境变量配置
工具系统支持通过环境变量进行全局配置：
| 变量名 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| `TOOLS_ENABLED` | bool | true | 启用/禁用工具系统 |
| `TOOLS_LIMIT` | int | 10 | 单次对话最大工具调用数 |
| `CODE_INTERPRETER_ENABLED` | bool | true | 启用代码解释器 |
### 配置持久化
工具配置通过 `PersistentConfig` 类实现持久化存储：
```python
TOOLS_ENABLED = PersistentConfig(
'TOOLS_ENABLED',
'tools.enabled',
os.environ.get('TOOLS_ENABLED', 'True'),
)
```
资料来源：[backend/open_webui/config.py]()
## 安全机制
### 权限控制
工具系统集成基于角色的访问控制（RBAC）机制：
- **管理员**：可创建、编辑、删除所有工具
- **普通用户**：仅可使用已启用的工具
- **访客**：无法使用工具功能
### 代码执行沙箱
代码解释器工具使用 RestrictedPython 库限制可执行的代码范围：
```
RestrictedPython==8.1
```
资料来源：[backend/requirements-min.txt]()
## API 常量定义
### 前端 API 端点配置
| 常量名 | 值 | 用途 |
|--------|-----|------|
| `RETRIEVAL_API_BASE_URL` | `/api/v1/retrieval` | 检索工具 API |
| `WEBUI_API_BASE_URL` | `/api/v1` | 通用 API 基础地址 |
资料来源：[src/lib/constants.ts]()
## 扩展开发指南
### 创建自定义工具步骤
1. **定义工具元数据**：在 `models/functions.py` 中添加函数定义
2. **实现工具逻辑**：在 `tools/` 目录下创建工具实现文件
3. **注册工具**：在 `tools/__init__.py` 中注册工具
4. **挂载路由**：确保路由在 `routers/tools.py` 中可用
5. **前端集成**：在 `Tools.svelte` 中添加工具管理界面
### 工具接口规范
所有自定义工具需遵循统一接口规范：
```python
class BaseTool:
name: str # 工具名称（唯一）
description: str # 工具描述
parameters: dict # JSON Schema 参数定义
async def execute(self, **kwargs) -> dict:
"""执行工具逻辑"""
raise NotImplementedError
```
## 总结
Open WebUI 的工具与函数系统为平台提供了强大的扩展能力，通过标准化的 API 路由、数据模型和前端组件，实现了工具的注册、调用、管理全流程支持。系统架构清晰，安全机制完善，支持从内置工具到用户自定义工具的多种场景，是构建智能助手生态的重要基础设施。
---
---
## Doramagic 踩坑日志
项目：open-webui/open-webui
摘要：发现 6 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：能力坑 - 能力判断依赖假设。
## 1. 能力坑 · 能力判断依赖假设
- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 建议检查：将假设转成下游验证清单。
- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
- 证据：capability.assumptions | github_repo:701547123 | https://github.com/open-webui/open-webui | README/documentation is current enough for a first validation pass.
## 2. 维护坑 · 维护活跃度未知
- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
- 证据：evidence.maintainer_signals | github_repo:701547123 | https://github.com/open-webui/open-webui | last_activity_observed missing
## 3. 安全/权限坑 · 下游验证发现风险项
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：下游已经要求复核，不能在页面中弱化。
- 建议检查：进入安全/权限治理复核队列。
- 防护动作：下游风险存在时必须保持 review/recommendation 降级。
- 证据：downstream_validation.risk_items | github_repo:701547123 | https://github.com/open-webui/open-webui | no_demo; severity=medium
## 4. 安全/权限坑 · 存在评分风险
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 建议检查：把风险写入边界卡，并确认是否需要人工复核。
- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
- 证据：risks.scoring_risks | github_repo:701547123 | https://github.com/open-webui/open-webui | no_demo; severity=medium
## 5. 维护坑 · issue/PR 响应质量未知
- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
- 防护动作：issue/PR 响应未知时，必须提示维护风险。
- 证据：evidence.maintainer_signals | github_repo:701547123 | https://github.com/open-webui/open-webui | issue_or_pr_quality=unknown
## 6. 维护坑 · 发布节奏不明确
- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
- 证据：evidence.maintainer_signals | github_repo:701547123 | https://github.com/open-webui/open-webui | release_recency=unknown