1. 项目简介

Open WebUI 是一个开源的自托管 Web 用户界面，专为大型语言模型（LLM）交互而设计。该项目提供了一个现代化、功能丰富的 Web 界面，让用户能够轻松地与本地部署的 Ollama 模型或其他兼容的 LLM API 进行交互。

项目支持多种安装方式，包括 pip 包安装和 Docker 容器化部署，并提供了丰富的功能集，涵盖对话管理、RAG（检索增强生成）、图像生成、语音模式、代码解释器等高级特性。

核心目标：为本地 LLM 提供一个类似 ChatGPT 的流畅、直观的 Web 交互体验，同时保持数据的私密性和本地化处理。

资料来源：README.md:1-20

概述

Open WebUI 是一个功能丰富的 Web 用户界面，专为大型语言模型（LLM）交互设计。该项目采用前后端分离的现代化架构，后端基于 FastAPI 构建 Python REST API 与 WebSocket 服务，前端使用 SvelteKit 框架实现响应式单页应用。

系统支持多模型并行对话、检索增强生成（RAG）、代码解释器执行、语音模式等高级功能，同时提供灵活的数据库与存储选项（SQLite、PostgreSQL、S3 等）。

资料来源：backend/open_webui/main.py:1-50

整体架构图

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）模式。主要组件包括：

#### 前端 API 端点配置

前端通过 constants.ts 中定义的常量与后端通信：

// 资料来源：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 框架，按照功能模块划分为多个路由组件：

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 路由体系

路由模块一览

资料来源：backend/open_webui/main.py:30-50

配置系统

环境配置架构

# 资料来源：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          # 项目根目录

关键配置项

资料来源：backend/open_webui/env.py:1-50

任务配置模板

系统支持可配置的提示词模板：

# 资料来源：backend/open_webui/config.py:1-30
CODE_INTERPRETER_PROMPT = """
代码解释器允许 AI 在沙箱环境中执行 Python 代码...
"""

中间件处理

响应处理管道

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

内容处理功能

中间件提供以下核心处理功能：

)

• 推理链渲染：将模型的思维过程渲染为可折叠的 `'

## 前端响应处理

### 内容处理流程

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]()

### 响应清理函数

// 资料来源：src/lib/utils/index.ts:1-30 export const sanitizeResponseContent = (content: string) => { return content .replace(/<\|[a-z]*$/, '') .replace(/<\|[a-z]+\|$/, '') .replace(/<$/, '') .replaceAll('<', '&lt;') .replaceAll('>', '&gt;') .replaceAll(/<\|[a-z]+\|>/g, ' ') .trim(); };

## 代码语法高亮

### 文件类型映射配置

// 资料来源：src/lib/utils/codeHighlight.ts:1-50 const EXT_OVERRIDE: Record<string, string> = { 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 部署模式

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

### 离线模式支持

系统支持完全离线运行，通过设置以下环境变量禁用所有网络请求：

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]()

1. 概述

Open WebUI 的后端采用 FastAPI 框架构建，提供了完整的 RESTful API 接口层。系统通过模块化的路由设计，将不同功能域的 API 逻辑分离到独立的路由器（Router）中，实现了代码的高内聚低耦合。

1.1 架构设计原则

后端 API 层遵循以下核心设计原则：

1.2 核心路由模块

系统的主要路由模块位于 backend/open_webui/routers/ 目录下：

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/

概述

Open WebUI 的数据模型层是整个系统的核心基础设施，负责管理和持久化所有业务数据。该层采用了分层架构设计，将数据访问逻辑、业务模型定义和数据库交互分离到不同的模块中，以实现高内聚、低耦合的代码结构。

数据模型层的主要职责包括：

• 用户认证与授权：管理用户账户信息、权限配置和会话状态
• 对话历史管理：存储和检索聊天记录，支持消息的增删改查操作
• 文件与媒体处理：管理上传文件、元数据和访问控制
• 工具与函数集成：维护可扩展的工具和函数定义
• 知识库管理：支持向量化的知识检索和文档管理

资料来源：backend/open_webui/internal/db.py:1-50

架构设计

整体架构图

graph TB
    subgraph "表现层 (API Routes)"
        A[API 路由层]
    end
    
    subgraph "服务层 (Services)"
        B[业务逻辑服务]
    end
    
    subgraph "数据模型层 (Models)"
        C[用户模型<br/>users.py]
        D[对话模型<br/>chats.py]
        E[消息模型<br/>messages.py]
        F[文件模型<br/>files.py]
        G[函数模型<br/>functions.py]
        H[工具模型<br/>tools.py]
        I[知识模型<br/>knowledge.py]
    end
    
    subgraph "数据访问层 (Internal)"
        J[数据库连接<br/>db.py]
        K[数据仓库<br/>Repositories]
    end
    
    subgraph "存储层 (Storage)"
        L[(SQLite/MySQL<br/>PostgreSQL)]
        M[(文件存储<br/>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

模块职责划分

资料来源：backend/open_webui/internal/db.py:1-30

核心数据模型详解

1. 用户模型 (User Model)

用户模型是系统的基础实体，包含了用户身份验证和授权所需的所有信息。

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
    }

主要字段说明：

资料来源：backend/open_webui/models/users.py:1-100

2. 对话模型 (Chat Model)

对话模型采用扁平化的 JSON 结构存储聊天会话，包含完整的对话历史和元数据。

graph LR
    A[ChatModel] --> B["chat: Dict"]
    B --> C["history: Dict"]
    C --> D["messages: Dict<br/>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)

消息是对话的原子单位，每条消息包含发送者、内容、附件和时间戳等完整信息。

资料来源：backend/open_webui/models/messages.py:1-80

4. 文件模型 (File Model)

文件模型管理用户上传的所有文件，包括图片、文档、音频等。

stateDiagram-v2
    [*] --> Uploaded: 用户上传
    Uploaded --> Processing: 开始处理
    Processing --> Ready: 处理完成
    Processing --> Failed: 处理失败
    Failed --> [*]
    Ready --> Deleted: 用户删除
    Ready --> [*]

文件类型支持：

资料来源：backend/open_webui/models/files.py:1-100

5. 函数与工具模型

函数和工具模型为系统提供了扩展能力，允许用户和开发者自定义功能。

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)

知识库模型支持向量化的文档存储和语义检索。

资料来源：backend/open_webui/models/knowledge.py:1-80

数据库交互层

数据库连接管理

db.py 模块负责建立和管理数据库连接，支持多种数据库后端：

# 核心配置参数
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', '')

支持的数据库类型：

资料来源：backend/open_webui/internal/db.py:30-80

数据仓库模式

系统采用 Repository 模式封装数据访问逻辑，提供统一的 CRUD 操作接口：

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

数据清理与安全

消息内容在存入数据库前会经过严格的安全处理：

def sanitize_text_for_db(text: str) -> str:
    """移除可能导致数据库问题的特殊字符"""
    # 移除空字符和其他控制字符
    return text.replace('\x00', '')

安全措施包括：

• 移除空字符 (\x00)
• 转义 HTML 特殊字符
• 验证字符串长度
• 类型检查和类型转换

资料来源：backend/open_webui/models/chats.py:40-60

数据流程与生命周期

消息创建流程

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 读取（兼容旧数据）

flowchart TD
    A[get_messages_map] --> B{chat_message表存在?}
    B -->|是| C[快速查询<br/>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

配置与环境变量

数据模型层的行为受以下环境变量控制：

资料来源：backend/open_webui/env.py:1-60

扩展与自定义

添加新数据模型

在 Open WebUI 中添加新的数据模型需要遵循以下步骤：

1. 在 backend/open_webui/models/ 目录创建新的模型文件
2. 定义 Pydantic 模型类继承基础类
3. 在 db.py 中注册新的数据库表
4. 实现 CRUD 操作方法

# 示例：新模型结构
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. 事务管理：相关操作使用数据库事务保证一致性

性能优化建议

相关文档

• API 路由层
• 服务层架构
• 存储配置
• 安全机制

概述

Open WebUI 的认证与安全系统是一套完整的多层防护机制，支持多种认证方式，包括本地账号认证、OAuth 2.0 单点登录、API Key 认证以及 SCIM 用户管理协议。该系统采用基于角色的访问控制（RBAC）模型，确保不同权限级别的用户只能访问其授权范围内的资源。安全架构的核心设计理念是将认证逻辑与业务逻辑分离，通过中间件统一处理身份验证和授权检查。

整个认证体系构建在 FastAPI 框架之上，利用 Python 的异步特性实现高性能的请求处理。密码存储采用行业标准的加密算法，用户凭证在传输过程中全程使用 HTTPS 加密保护。系统还提供了细粒度的权限控制机制，支持对知识库、提示词、模型等资源进行独立的读写权限配置。

认证方式

本地账号认证

本地账号认证是 Open WebUI 的基础认证方式，用户通过用户名和密码注册和登录系统。注册时系统会验证邮箱格式并确保用户名唯一性，密码则通过 bcrypt 算法进行加盐哈希存储，确保即使数据库泄露也无法直接还原用户密码。

登录流程中，系统首先根据用户名查找用户记录，验证密码哈希是否匹配。认证成功后，系统生成 JWT（JSON Web Token）格式的访问令牌，令牌中包含用户 ID、角色和过期时间等信息。令牌的有效期默认为 24 小时，用户可以在此期间无需重新登录访问系统资源。

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 资料来源：backend/open_webui/models/users.py:1-150

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）用于验证令牌签名。

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

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

SCIM 用户管理

Open WebUI 实现了 SCIM（System for Cross-domain Identity Management）2.0 协议，支持与企业身份管理系统（如 Okta、Azure AD、OneLogin）集成进行用户自动化配置和生命周期管理。SCIM 接口允许外部系统推送用户创建、更新和禁用操作，实现用户账号的集中管理。

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

令牌与会话管理

JWT 令牌机制

Open WebUI 使用 JWT（JSON Web Token）作为主要的会话令牌格式。JWT 包含三个部分：头部（Header）、载荷（Payload）和签名（Signature）。令牌在用户登录成功后生成，包含用户 ID、用户名、角色、权限范围和过期时间等声明。签名使用 HS256 算法，确保令牌内容不可被篡改。

令牌的有效期通过配置管理，默认设置为 24 小时。系统在每个请求中验证令牌的签名和过期时间，过期令牌将被拒绝并返回 401 未授权响应。用户可以通过设置中的"记住我"功能延长令牌有效期，延长后的有效期可达 30 天。

{
  "id": "user-uuid",
  "name": "username",
  "email": "[email protected]",
  "role": "user",
  "exp": 1699999999,
  "iat": 1699913599
}

令牌刷新机制允许用户在令牌即将过期时获取新令牌，无需重新输入密码。刷新令牌通过独立的端点交换，系统会验证原令牌的有效性后颁发新令牌并使旧令牌失效。这种机制在保持安全性的同时提供了流畅的用户体验。

资料来源：backend/open_webui/utils/auth.py:50-150

Cookie 与 Header 认证

系统支持两种令牌传输方式：通过 HTTP Cookie 或 Authorization Header。Cookie 方式适用于浏览器环境，令牌自动随请求发送并在浏览器关闭后清除。Header 方式则需要客户端手动在请求头中添加 Authorization: Bearer <token>，适用于 API 客户端和程序化访问。

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

基于角色的访问控制

角色定义

Open WebUI 实现了三级角色体系，每种角色对应不同的权限级别：

管理员拥有系统的完全控制权，可以创建和删除用户、修改系统配置、管理 Ollama 模型和知识库。普通用户可以正常使用对话功能，创建个人知识库和提示词，但无法访问管理功能。待审核用户是注册后等待管理员审批的临时状态，此状态下用户只能登录无法使用任何功能。

默认情况下，管理员需要在用户管理界面手动审核新注册用户。但系统也支持配置为自动批准模式，新用户注册后自动获得普通用户角色，立即可以使用系统全部基础功能。

资料来源：src/lib/constants/permissions.ts:1-100 资料来源：backend/open_webui/models/users.py:50-120

资源权限授予

除了基于角色的粗粒度控制，系统还支持对特定资源进行细粒度的权限授予。资源类型包括知识库（knowledge）、提示词（prompt）、文件（file）等，每种资源可以独立设置读（read）、写（write）和删除（delete）权限。

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

安全中间件

请求认证中间件

ASGI 中间件是请求处理流程的第一道关卡，负责从 HTTP 请求中提取并验证认证凭证。该中间件实现了统一的认证逻辑，封装在 FastAPI 的请求处理管道中，对所有路由生效。

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

CSRF 保护

系统实现了 CSRF（跨站请求伪造）保护机制，防止恶意网站诱导已登录用户发起非预期请求。CSRF 防护通过验证请求头中的自定义字段实现，敏感操作（如表单提交、状态变更）必须携带有效的 CSRF 令牌。

Web 界面在发起跨域请求前会自动获取并附加 CSRF 令牌，确保用户操作的合法性。API 客户端则需要在请求头中手动添加令牌，或使用 Cookie 认证方式（Cookie 请求会自动携带同源策略保护）。

环境配置

认证相关环境变量

Open WebUI 通过环境变量配置认证和安全相关的各项参数。这些变量在服务启动时读取，决定了系统的安全行为。

管理员邮箱和密码在首次启动时用于创建初始管理员账号。如果未设置，系统会在控制台输出随机生成的初始密码。生产环境中强烈建议设置强密码并妥善保管凭证。

资料来源：backend/open_webui/env.py:30-100

OAuth 提供商配置

OAuth 认证需要配置提供商的详细信息。以下是常见的 OAuth 提供商配置示例：

# 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

安全最佳实践

部署建议

在生产环境中部署 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 协议的多重支持，系统可以适应各种使用场景和安全需求。基于角色的访问控制与细粒度资源权限的结合，确保了权限管理的精确性和灵活性。管理员应根据实际需求选择合适的认证方式，并遵循安全最佳实践进行部署和运维。

概述

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 的核心功能之一，主要由以下组件构成：

#### 消息处理流程

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 是工作区中的重要组件，负责模型管理和配置界面：

graph LR
    A[模型列表] --> B[模型选择器]
    B --> C[配置面板]
    C --> D[参数调整]
    D --> E[模型切换]
    E --> A

工作区组件与后端 API 通过统一的接口层进行通信，支持模型的动态加载和配置管理。

管理面板组件

管理面板通过 Settings.svelte 组件实现用户设置和系统配置功能：

状态管理

Store 架构

Open WebUI 使用 Svelte 的 writable store 模式实现全局状态管理。核心状态存储定义在 src/lib/stores/index.ts 中：

// 关键状态定义示例
export const settings: Writable<Settings> = writable({});
export const chatRequestQueues: Writable<Record<string, { id: string; prompt: string; files: any[] }[]>> = writable({});
export const showSidebar = writable(false);
export const showSettings = writable(false);

#### 状态分类表

响应式数据流

graph LR
    A[用户操作] --> B[Store 更新]
    B --> C[响应式订阅]
    C --> D[组件重渲染]
    D --> E[UI 更新]

国际化支持

i18n 模块

国际化系统位于 src/lib/i18n/ 目录，支持多语言切换功能：

• 语言检测与自动切换
• 实时翻译文本替换
• 聊天历史上下文保留

国际化配置通过后端 backend/open_webui/config.py 中的配置项管理：

VOICE_MODE_PROMPT_TEMPLATE = PersistentConfig(...)
ENABLE_VOICE_MODE_PROMPT = PersistentConfig(...)

工具函数库

核心工具模块

src/lib/utils/index.ts 提供了丰富的前端工具函数：

#### 内容处理流程

graph TD
    A[原始内容] --> B[移除特殊标记]
    B --> C[中文处理processChineseContent]
    C --> D[代码块提取]
    D --> E[清理敏感字符]
    E --> F[最终输出]

响应内容清理

系统通过 sanitizeResponseContent 函数处理模型输出：

export const sanitizeResponseContent = (content: string) => {
    return content
        .replace(/<\|[a-z]*$/, '')
        .replace(/<\|[a-z]+\|$/, '')
        .replace(/<$/, '')
        .replaceAll('<', '&lt;')
        .replaceAll('>', '&gt;')
        .replaceAll(/<\|[a-z]+\|>/g, ' ')
        .trim();
};

常量与配置

前端常量定义

src/lib/constants.ts 定义了应用级别的常量：

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';

#### 支持的文件类型

API 端点常量

数据流转架构

消息流转

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 中定义了主题切换的基础样式：

html.dark #splash-screen {
    background: #000;
}

html.her #splash-screen {
    background: #983724;
}

加载屏幕

应用启动时显示统一的加载界面，包含 Logo、进度条等元素，通过 CSS 控制显示与隐藏。

技术栈总结

本页面详细介绍了 Open WebUI 前端组件的组织结构、核心组件功能、状态管理机制以及数据流转方式，为开发者理解和扩展前端功能提供了系统性参考。

概述

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 的映射关系

核心组件说明

布局组件 (`+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 路由：

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：

资料来源：src/lib/constants.ts:1-20

状态管理与数据流

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 响应：

export const sanitizeResponseContent = (content: string) => {
    return content
        .replace(/<\|[a-z]*$/, '')
        .replace(/<\|[a-z]+\|$/, '')
        .replace(/<$/, '')
        .replaceAll('<', '&lt;')
        .replaceAll('>', '&gt;')
        .replaceAll(/<\|[a-z]+\|>/g, ' ')
        .trim();
};

资料来源：src/lib/utils/index.ts:50-70

中文内容特殊处理

针对中文内容，框架进行了特殊处理以解决 Markdown/LaTeX 格式问题：

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 提供文件操作能力：

资料来源：src/lib/apis/terminal/index.ts:1-60

代码解释器集成

路由页面支持代码解释器功能，通过后端中间件处理 code_interpreter 类型消息：

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

代码执行引擎配置

资料来源：backend/open_webui/config.py:1-50

访问控制与权限

路由页面通过后端 RBAC 系统实现访问控制：

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 路由
• 前端工具函数
• 应用常量定义
• 知识库路由
• 终端 API

概述

Open WebUI 的模型集成与支持系统是整个平台的核心功能模块，负责管理与接入多种大语言模型（LLM）提供方。该系统通过统一的 API 网关架构，将 Ollama、OpenAI 兼容 API 等多种模型服务进行抽象封装，为用户提供无缝的模型切换与交互体验。

系统支持多模型并发对话、模型热度管理、角色权限控制等功能，并提供完整的模型生命周期管理，包括模型的发现、拉取、配置与删除操作。资料来源：backend/open_webui/main.py:48

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 端点分布在多个路由器中，形成统一的接口体系。

资料来源：backend/open_webui/main.py:48-54

服务地址配置

前端通过 src/lib/constants.ts 集中管理所有 API 服务地址，支持开发环境与生产环境的动态切换。

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 是聊天界面中的模型选择器组件，提供直观的模型切换交互界面。该组件支持以下功能：

• 模型搜索与过滤
• 模型热度排序
• 快捷键切换模型
• 模型图标与描述显示

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

配置选项

环境变量配置

系统通过环境变量和配置文件管理模型相关的设置。主要配置项包括：

资料来源：backend/open_webui/config.py

运行时配置

系统支持通过管理员界面动态调整模型配置，包括：

• 模型调用参数（温度、最大 token 等）
• API 超时设置
• 重试策略配置
• 代理设置

多模型对话支持

Open WebUI 支持在单一对话中使用多个模型，通过并行调用不同模型获取响应，实现更优的回答质量。

多模型对话流程

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 官方文档
• OpenAI API 文档
• Open WebUI 安装指南
• 管理员配置手册

概述

检索增强生成（Retrieval-Augmented Generation，简称 RAG）是一种将信息检索与语言模型生成相结合的技术架构。在 Open WebUI 项目中，RAG 模块负责从外部知识库、文档集合或网络资源中检索相关内容，并将检索结果注入到大语言模型（LLM）的上下文窗口中，从而提升模型回答的准确性、时效性和可信度。

Open WebUI 的 RAG 系统支持多种文档格式、多种向量存储后端以及多种网络搜索提供者，形成了完整的文档处理 → 向量化 → 存储 → 检索 → 上下文注入链路。

核心架构

RAG 系统在整体上分为三大子模块：

1. 文档加载与处理（Loaders）：负责从各类文件格式中提取文本内容
2. 向量存储与检索（Vector Stores）：负责文本的向量化、存储和相似度检索
3. 网络搜索（Web Retrieval）：支持通过外部搜索引擎获取实时信息

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）：

加载器实现

文档加载器的核心实现在 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）

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）：

向量存储与检索

向量存储后端

Open WebUI 支持多种向量数据库作为存储后端，通过工厂模式（Factory Pattern）进行统一管理（资料来源：backend/open_webui/retrieval/vector/factory.py）：

检索流程

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）：

网络搜索

支持的搜索提供者

Open WebUI 集成了超过 15 种网络搜索提供者，可在 RAG 流程中注入实时网络信息（资料来源：README.md）：

搜索结果处理

搜索结果经过标准化处理后返回统一的 SearchResult 数据结构（资料来源：backend/open_webui/retrieval/web/ydc.py）：

@dataclass
class SearchResult:
    link: str          # 结果链接
    title: str         # 结果标题
    snippet: str       # 摘要内容

对于不同的搜索 API，Open WebUI 进行了结果格式统一，包括：

• 标题提取与清理
• 摘要/片段（Snippet）的合并构建
• URL 解析与规范化
• 评分与排序

知识库管理

知识库 API

知识库管理功能提供了完整的 CRUD 操作（资料来源：backend/open_webui/routers/knowledge.py）：

知识库数据模型

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 对话中：

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）
• 引用标注：在回答中标注信息来源

配置管理

环境变量配置

RAG 系统的核心配置通过环境变量管理：

使用场景

1. 私有知识问答：上传内部文档创建私有知识库
2. 实时信息补充：通过网络搜索获取最新资讯
3. 多模态文档理解：处理 PDF、图片混合文档
4. 跨语言检索：支持多语言文档的统一检索

最佳实践

• 分块策略：根据文档类型选择合适的分块大小，代码类文档建议较小分块
• 向量模型选择：根据文档语言选择对应语言的嵌入模型
• 混合检索：结合向量检索与关键词检索以平衡精确度与召回率
• 定期更新：知识库内容变更后需重新索引

概述

Open WebUI 的工具与函数系统是平台的核心扩展机制之一，允许用户通过自定义工具和函数来增强 AI 助手的交互能力。该系统支持在对话过程中动态调用外部工具、执行代码、访问外部数据源，从而实现更丰富的智能助手体验。

系统通过 API 路由层统一管理工具的注册、调用和生命周期维护，支持多种工具类型，包括内置工具、用户自定义工具以及通过函数定义的工具。

系统架构

整体架构流程

graph TD
    A[用户请求] --> B[API 路由层<br/>routers/tools.py]
    B --> C[工具注册表<br/>tools/__init__.py]
    C --> D{工具类型}
    D --> E[内置工具<br/>builtin.py]
    D --> F[用户自定义函数<br/>models/functions.py]
    D --> G[外部工具]
    E --> H[工具执行引擎]
    F --> H
    G --> H
    H --> I[结果返回]
    I --> J[前端展示<br/>Tools.svelte]

组件层级

工具注册与路由

API 路由配置

工具系统通过 FastAPI 路由模块挂载到主应用，所有工具相关的 HTTP 接口均以 /api/v1/tools 为前缀。

app.include_router(tools.router, prefix='/api/v1/tools', tags=['tools'])

资料来源：backend/open_webui/main.py

路由端点

函数数据模型

数据结构定义

函数（Function）是工具系统的核心数据结构，用于描述可调用的工具逻辑。

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 格式定义，支持以下类型：

工具执行流程

执行时序

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: 返回响应

内置工具类型

系统预置多种内置工具，覆盖常见的扩展场景：

前端集成

工具管理界面

前端工具管理组件位于 src/lib/components/workspace/Tools.svelte，提供以下功能：

• 工具列表视图：展示所有已注册工具，支持按名称、类型筛选
• 工具详情面板：查看工具描述、参数说明、使用示例
• 工具调试控制台：测试工具调用、查看执行结果
• 工具创建向导：引导用户创建自定义工具

响应内容处理

前端通过 sanitizeResponseContent 函数处理工具执行后的响应内容，确保内容安全展示：

export const sanitizeResponseContent = (content: string) => {
	return content
		.replace(/<\|[a-z]*$/, '')
		.replace(/<\|[a-z]+\|$/, '')
		.replace(/<$/, '')
		.replaceAll('<', '&lt;')
		.replaceAll('>', '&gt;')
		.replaceAll(/<\|[a-z]+\|>/g, ' ')
		.trim();
};

资料来源：src/lib/utils/index.ts

中间件渲染

工具输出渲染机制

系统中间件负责将工具执行结果渲染为可展示的 HTML 格式，支持代码解释器等特殊工具类型：

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

渲染输出格式

配置管理

环境变量配置

工具系统支持通过环境变量进行全局配置：

配置持久化

工具配置通过 PersistentConfig 类实现持久化存储：

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 端点配置

资料来源：src/lib/constants.ts

扩展开发指南

创建自定义工具步骤

1. 定义工具元数据：在 models/functions.py 中添加函数定义
2. 实现工具逻辑：在 tools/ 目录下创建工具实现文件
3. 注册工具：在 tools/__init__.py 中注册工具
4. 挂载路由：确保路由在 routers/tools.py 中可用
5. 前端集成：在 Tools.svelte 中添加工具管理界面

工具接口规范

所有自定义工具需遵循统一接口规范：

class BaseTool:
    name: str                          # 工具名称（唯一）
    description: str                   # 工具描述
    parameters: dict                   # JSON Schema 参数定义
    
    async def execute(self, **kwargs) -> dict:
        """执行工具逻辑"""
        raise NotImplementedError

总结

Open WebUI 的工具与函数系统为平台提供了强大的扩展能力，通过标准化的 API 路由、数据模型和前端组件，实现了工具的注册、调用、管理全流程支持。系统架构清晰，安全机制完善，支持从内置工具到用户自定义工具的多种场景，是构建智能助手生态的重要基础设施。

Pitfall Log / 踩坑日志

项目：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