2 · 架构总览（Architecture Overview）

架构总览（中文译文）

原始 DeepWiki 页面：https://deepwiki.com/open-webui/open-webui/2-architecture-overview

翻译时间：2026-06-09T16:07:27.642Z

翻译模型：deepseek-chat

原文字符数：12688

项目：Open WebUI (open-webui)

---

架构概览

相关源文件

本 Wiki 页面基于以下源文件生成：

• backend/open_webui/config.py
• backend/open_webui/env.py
• backend/open_webui/main.py
• backend/open_webui/routers/auths.py
• backend/open_webui/socket/main.py
• backend/open_webui/socket/utils.py
• backend/open_webui/tasks.py
• backend/open_webui/test/util/test_redis.py
• backend/open_webui/utils/auth.py
• backend/open_webui/utils/oauth.py
• backend/open_webui/utils/rate_limit.py
• backend/open_webui/utils/redis.py
• src/lib/apis/index.ts
• src/lib/stores/index.ts
• src/routes/+layout.svelte

目的与范围

本文档全面概述了 Open WebUI 的系统架构、设计模式及组件关系，描述了代码库的高层结构、主要子系统之间的交互，以及塑造应用程序的架构决策。

各子系统详情请参见：

• 系统组件与数据流：系统组件与数据流
• 前端组件与 UI 结构：前端架构
• 后端 API 与服务层：后端架构
• 数据持久化与存储：数据与存储层
• 实时通信：实时通信架构

---

系统架构与技术栈

Open WebUI 采用客户端-服务器架构，前端展示层与后端服务层之间界限清晰。系统设计为模块化、可扩展的平台，集成了多种 AI 服务、存储后端和外部工具。

高层架构

系统采用三层架构：前端（SvelteKit）、后端（FastAPI）和持久化层。组件重要性通过代码变更频率和功能中心性来衡量。

系统架构图

graph TB
    subgraph Client["客户端层 (SvelteKit)"]
        Browser["Web 浏览器 / 移动端 PWA"]
        ChatUI["Chat.svelte<br/>主 UI 编排器"]
        MessageInput["MessageInput.svelte<br/>输入处理"]
        ResponseMsg["ResponseMessage.svelte<br/>AI 响应渲染"]
    end

    subgraph Comm["实时通信 (Socket.IO)"]
        SocketIOClient["socket.io-client<br/>事件处理器"]
        SocketIOServer["socket/main.py<br/>sio = AsyncServer()"]
        Redis["Redis<br/>get_redis_connection()"]
    end

    subgraph Backend["后端 API 层 (FastAPI)"]
        MainApp["main.py<br/>FastAPI(lifespan)"]
        RoutersGroup["API 路由:<br/>chats.py, retrieval.py<br/>auths.py, images.py"]
        TasksSystem["tasks.py<br/>create_task() / stop_task()"]
        ConfigSystem["config.py<br/>PersistentConfig"]
    end

    subgraph AI["AI 与 RAG 层"]
        RAGSystem["retrieval/utils.py<br/>query_doc_with_hybrid_search()<br/>get_ef() / get_rf()"]
        ToolExec["utils/tools.py<br/>get_tools() / get_builtin_tools()"]
        LLMIntegration["routers/openai.py<br/>routers/ollama.py"]
    end

    subgraph Data["数据持久化"]
        SQLDB[("SQL 数据库<br/>models/users.py<br/>models/chats.py")]
        VectorDBs[("VECTOR_DB_CLIENT<br/>retrieval/vector/factory.py")]
        StorageProvider["Storage.factory()<br/>storage/provider.py"]
    end

    Browser --> ChatUI
    ChatUI --> MessageInput
    ChatUI --> ResponseMsg

    ChatUI --> SocketIOClient
    SocketIOClient --> SocketIOServer
    SocketIOServer --> Redis

    ChatUI --> MainApp
    MainApp --> RoutersGroup
    MainApp --> ConfigSystem
    RoutersGroup --> TasksSystem

    RoutersGroup --> RAGSystem
    RoutersGroup --> ToolExec
    RoutersGroup --> LLMIntegration

    MainApp --> SQLDB
    RAGSystem --> VectorDBs
    RoutersGroup --> StorageProvider
    MainApp --> Redis

关键架构特性：

方面	实现方式
前端框架	SvelteKit，配合响应式 store（$config、$user、$models）
后端框架	FastAPI，全程使用 async/await
状态管理	前端：Svelte stores；后端：request.app.state 和 Redis
实时通信	Socket.IO，配合 Redis 实现多节点同步
配置管理	三层：环境变量 → 数据库 → Redis 缓存（PersistentConfig）
数据库 ORM	SQLAlchemy，用于迁移和作用域会话
向量存储	工厂模式，支持多种后端选项（VECTOR_DB_CLIENT）

来源： backend/open_webui/main.py:28-109、backend/open_webui/config.py:214-231、backend/open_webui/socket/main.py:65-96、src/lib/stores/index.ts:13-84、backend/open_webui/internal/db.py:120-120、backend/open_webui/tasks.py:104-124

---

技术栈

前端技术栈

层	技术	关键文件/导出	用途
框架	SvelteKit	src/routes/+layout.svelte	基于文件路由的 SSR/SPA
UI 库	Svelte 4	.svelte 组件	响应式组件框架
状态管理	Svelte Stores	src/lib/stores/index.ts	可写响应式 store
实时通信	Socket.IO 客户端	import { io } from 'socket.io-client'	WebSocket 通信
样式	TailwindCSS	tailwind.config.js	实用优先的 CSS
工作线程	Web Workers	PyodideWorker	通过 Pyodide 在客户端执行 Python

来源： src/lib/stores/index.ts:13-110、src/routes/+layout.svelte:2-41、src/routes/+layout.svelte:213-220

后端技术栈

层	技术	关键模块/类	用途
框架	FastAPI	main.py: FastAPI()	异步 ASGI Web 框架
ORM	SQLAlchemy	internal/db.py	SQL 持久化和迁移
数据库	SQLite/Postgres/MySQL	DATABASE_URL 环境变量	关系型存储
缓存	Redis	get_redis_connection()	分布式状态、会话存储和任务同步
实时通信	Python-SocketIO	socket/main.py	使用 AsyncRedisManager 的 WebSocket 服务器
验证	Pydantic	BaseModel 子类	请求/响应模式

来源： backend/open_webui/main.py:28-109、backend/open_webui/config.py:39-40、backend/open_webui/socket/main.py:65-84、backend/open_webui/internal/db.py:120-120、backend/open_webui/env.py:24-35

---

应用初始化与生命周期

后端初始化序列

FastAPI 负责启动编排，包括数据库迁移和挂载子应用（如 Socket.IO）。

后端启动序列图

sequenceDiagram
    participant Main as "main.py: FastAPI"
    participant Config as "config.py: run_migrations"
    participant DB as "internal/db.py: engine"
    participant Redis as "utils/redis.py: get_redis_connection()"
    participant Socket as "socket/main.py: sio"
    participant Tasks as "tasks.py: redis_task_command_listener"

    Main->>Config: run_migrations() (Alembic)
    Config->>DB: 将模式应用到 engine

    Main->>Redis: 初始化 Redis 连接
    Main->>Tasks: 启动 redis_task_command_listener

    Main->>Main: 注册路由（chats、retrieval、auths 等）

    Main->>Socket: socket_app 挂载到 /ws/socket.io

初始化细节：

• 配置加载：PersistentConfig 管理一个系统，其中环境变量优先，除非启用了持久化配置。backend/open_webui/config.py:214-231
• 迁移：如果设置了 ENABLE_DB_MIGRATIONS，Alembic 会在启动时处理模式升级。backend/open_webui/config.py:57-75
• 分布式任务：redis_task_command_listener 允许多个后端实例协调任务取消（例如，停止聊天生成）。backend/open_webui/tasks.py:25-42
• Socket.IO 挂载：将 Socket.IO ASGI 应用附加到主 FastAPI 实例，支持基于 Redis 的扩展。backend/open_webui/socket/main.py:65-84、backend/open_webui/main.py:69-71

来源： backend/open_webui/main.py:69-109、backend/open_webui/config.py:57-75、backend/open_webui/tasks.py:25-42、backend/open_webui/config.py:214-231

前端初始化序列

根布局（+layout.svelte）编排前端初始化：

1. i18n 初始化：加载翻译并使用 initI18n 设置语言。src/routes/+layout.svelte:48-48
2. WebSocket 连接：建立带有 JWT 认证的 socket.io-client 连接。src/routes/+layout.svelte:115-125
3. 会话加载：通过 getSessionUser() 获取用户数据，通过 getBackendConfig() 获取系统配置。src/routes/+layout.svelte:54-55
4. Store 填充：填充模型、工具和用户设置的全局 store。src/lib/stores/index.ts:13-84

来源： src/routes/+layout.svelte:115-207、src/lib/stores/index.ts:13-84

---

设计模式与架构决策

1. 持久化配置模式

PersistentConfig 类实现了一种模式：设置从环境变量加载，但可以通过数据库在实例之间同步。 来源： backend/open_webui/config.py:214-231

2. 路由组织模式

API 端点被组织成模块化路由，注册到主应用中，分离了 retrieval、chats 和 auths 等关注点。 来源： backend/open_webui/main.py:78-109

3. 分布式任务管理

系统使用基于 Redis 的任务管理系统（tasks.py）来处理长时间运行的操作。这允许前端在分布式后端节点集群中取消任务（如 LLM 生成）。 来源： backend/open_webui/tasks.py:145-163

---

请求流模式

聊天与 RAG 流

聊天完成序列图

sequenceDiagram
    participant UI as "Chat.svelte"
    participant API as "apis/index.ts"
    participant Router as "routers/chats.py"
    participant Task as "tasks.py: create_task()"
    participant LLM as "routers/openai.py"

    UI->>API: chatCompleted()
    API->>Router: POST /api/chat/completed

    Router->>Task: create_task(coroutine)
    Task-->>Router: task_id

    Router->>LLM: 请求完成
    LLM-->>Router: response_stream
    Router-->>UI: 流式更新

管道中的关键函数：

• getModels：聚合来自后端 API 和 OPENAI_API_BASE_URLS 中定义直接提供者连接的模型。src/lib/apis/index.ts:9-160
• create_task：将后端操作包装在 asyncio.Task 中，并在全局注册表（以及 Redis，如果可用）中跟踪它们。backend/open_webui/tasks.py:104-124
• setupSocket：管理实时通信通道的生命周期，包括心跳监控。src/routes/+layout.svelte:115-207

来源： src/lib/apis/index.ts:9-160、backend/open_webui/tasks.py:104-124、src/routes/+layout.svelte:115-207

---

可扩展性与性能考量

• 分布式状态：Redis 用于多节点同步，确保 Socket.IO 事件和后台任务在服务器实例之间的一致性。backend/open_webui/socket/main.py:65-84、backend/open_webui/tasks.py:78-86
• 异步 I/O：后端利用 asyncio 和 FastAPI 实现非阻塞操作，这对流式响应和高并发至关重要。backend/open_webui/main.py:1-23
• 客户端执行：使用 Web Workers 和 Pyodide 将 Python 代码解释等繁重任务卸载到浏览器，节省服务器资源。src/routes/+layout.svelte:213-220
• 会话池：Socket.IO 管理一个 SESSION_POOL，并定期清理，以处理分布式环境中的孤立连接。backend/open_webui/socket/main.py:173-194

来源： backend/open_webui/socket/main.py:173-194、backend/open_webui/tasks.py:25-42、src/routes/+layout.svelte:213-220