agentic_huge_data_base / wiki
页面 Open WebUI · 2.4 数据与存储层·DeepWiki 中文全文译文
DeepWiki 中文译文 / Open WebUI / 2.4

2.4 · 数据与存储层（Data and Storage Layer）

多模型对话工作台与知识应用入口 · 本章是 Open WebUI DeepWiki 中文译文的独立章节页，保留原始链接、源码锚点、模块标签和章节层级。

项目Open WebUI 章节2.4 状态全文译文 模块检索、召回与知识系统、系统架构、界面与交互、工具、记忆与模型调用
项目要点页2.5 参考项目 项目章节目录Open WebUI DeepWiki 原始章节Data and Storage Layer 上一章2.3 下一章2.5
源码线索
  • backend/open_webui/internal/db.py
  • backend/open_webui/migrations/env.py
  • backend/open_webui/models/chats.py
  • backend/open_webui/models/oauth_sessions.py
  • backend/open_webui/retrieval/loaders/mistral.py
  • backend/open_webui/retrieval/vector/dbs/chroma.py
  • backend/open_webui/retrieval/vector/dbs/elasticsearch.py
  • backend/open_webui/retrieval/vector/dbs/milvus.py
  • backend/open_webui/retrieval/vector/dbs/milvus_multitenancy.py
  • backend/open_webui/retrieval/vector/dbs/opensearch.py
模块标签
  • 检索、召回与知识系统
  • 系统架构
  • 界面与交互
  • 工具、记忆与模型调用
  • 接口与服务契约

中文译文

数据与存储层（中文译文）

原始 DeepWiki 页面：https://deepwiki.com/open-webui/open-webui/2.4-data-and-storage-layer
翻译时间：2026-06-09T16:07:26.974Z
翻译模型：deepseek-chat
原文字符数：12868
项目：Open WebUI (open-webui)

---

数据与存储层

相关源文件

以下文件为本 Wiki 页面的生成提供了上下文：

  • .github/workflows/integration-test.disabled
  • backend/open_webui/internal/db.py
  • backend/open_webui/migrations/env.py
  • backend/open_webui/models/chats.py
  • backend/open_webui/models/oauth_sessions.py
  • backend/open_webui/retrieval/loaders/mistral.py
  • backend/open_webui/retrieval/vector/dbs/chroma.py
  • backend/open_webui/retrieval/vector/dbs/elasticsearch.py
  • backend/open_webui/retrieval/vector/dbs/milvus.py
  • backend/open_webui/retrieval/vector/dbs/milvus_multitenancy.py
  • backend/open_webui/retrieval/vector/dbs/opensearch.py
  • backend/open_webui/retrieval/vector/dbs/oracle23ai.py
  • backend/open_webui/retrieval/vector/dbs/pgvector.py
  • backend/open_webui/retrieval/vector/dbs/pinecone.py
  • backend/open_webui/retrieval/vector/dbs/qdrant.py
  • backend/open_webui/retrieval/vector/dbs/qdrant_multitenancy.py
  • backend/open_webui/retrieval/vector/dbs/s3vector.py
  • backend/open_webui/retrieval/vector/dbs/weaviate.py
  • backend/open_webui/retrieval/vector/utils.py
  • backend/open_webui/retrieval/web/firecrawl.py
  • backend/open_webui/retrieval/web/utils.py
  • backend/open_webui/routers/chats.py
  • backend/open_webui/routers/configs.py
  • backend/open_webui/storage/provider.py
  • backend/open_webui/test/apps/webui/storage/test_provider.py
  • backend/open_webui/utils/webhook.py
  • backend/requirements-min.txt
  • backend/requirements.txt
  • docker-compose.playwright.yaml
  • pyproject.toml
  • src/lib/apis/chats/index.ts
  • src/lib/apis/configs/index.ts
  • src/lib/apis/tools/index.ts
  • src/lib/apis/users/index.ts
  • src/lib/components/chat/MessageInput/InputMenu.svelte
  • src/lib/components/chat/MessageInput/InputMenu/Chats.svelte
  • src/lib/components/chat/MessageInput/InputMenu/Knowledge.svelte
  • src/lib/components/chat/MessageInput/InputMenu/Notes.svelte
  • src/lib/components/chat/MessageInput/IntegrationsMenu.svelte
  • src/lib/components/chat/Settings/Interface/ManageFloatingActionButtonsModal.svelte
  • src/lib/components/chat/Settings/Interface/ManageImageCompressionModal.svelte
  • src/lib/components/chat/Settings/SyncStatsModal.svelte
  • src/lib/components/icons/PageEdit.svelte
  • src/lib/utils/onedrive-file-picker.ts
  • uv.lock

目的与范围

本文档描述了 Open WebUI 的数据持久化架构，该架构由三个主要层次组成：用于结构化数据的关系型数据库（PostgreSQL、MySQL 或 SQLite）、用于缓存和分布式状态管理的 Redis，以及用于语义搜索能力的向量数据库。此外，系统还实现了一个文件存储抽象层，支持本地文件系统和多种云存储提供商。

持久化层基于 SQLAlchemy 实现 ORM backend/open_webui/internal/db.py:11，使用 Peewee 处理遗留迁移 backend/open_webui/internal/db.py:31，并采用基于提供商的架构来管理外部存储服务 backend/open_webui/storage/provider.py:40。

---

系统架构概览

多层存储架构
graph TB
    subgraph "应用层"
        ["FastAPI 应用"] -- "backend/open_webui/main.py" --> FastAPI
        ["Socket.IO 服务器"] -- "backend/open_webui/socket/main.py" --> SocketIO
    end

    subgraph "数据访问层"
        ["AsyncSession"] -- "backend/open_webui/internal/db.py" --> Session
        ["VectorDBBase"] -- "backend/open_webui/retrieval/vector/main.py" --> VectorClient
        ["StorageProvider"] -- "backend/open_webui/storage/provider.py" --> StorageProviderNode["StorageProvider"]
    end

    subgraph "主数据库"
        PostgreSQL[("PostgreSQL<br/>(psycopg[binary])")]
        MySQL[("MySQL/MariaDB")]
        SQLite[("SQLite<br/>(aiosqlite)")]
    end

    subgraph "向量数据库"
        ChromaDB[("ChromaDB")]
        Milvus[("MilvusClient")]
        Qdrant[("QdrantClient")]
        PGVector[("PgvectorClient")]
        Oracle[("Oracle23aiClient")]
        ES[("Elasticsearch")]
    end

    subgraph "文件存储"
        LocalFS["LocalStorageProvider<br/>UPLOAD_DIR"]
        S3["S3StorageProvider<br/>boto3"]
        GCS["GCSStorageProvider"]
        Azure["AzureStorageProvider"]
    end

    FastAPI --> Session
    FastAPI --> VectorClient
    FastAPI --> StorageProviderNode

    Session --> PostgreSQL
    Session --> MySQL
    Session --> SQLite

    VectorClient --> ChromaDB
    VectorClient --> Milvus
    VectorClient --> Qdrant
    VectorClient --> PGVector
    VectorClient --> Oracle
    VectorClient --> ES

    StorageProviderNode --> LocalFS
    StorageProviderNode --> S3
    StorageProviderNode --> GCS
    StorageProviderNode --> Azure

来源： backend/open_webui/storage/provider.py:40-56, backend/open_webui/internal/db.py:27-31, backend/requirements.txt:27-32, backend/requirements.txt:128-133

---

主数据库系统

数据库连接管理

Open WebUI 使用 SQLAlchemy 作为主要 ORM 层。数据库引擎在 backend/open_webui/internal/db.py 中初始化。它通过 sqlalchemy[asyncio] 和 aiosqlite 支持异步操作 backend/requirements.txt:27-28。

数据库实体与连接流程

graph LR
    subgraph "配置"
        DATABASE_URL["DATABASE_URL<br/>internal/db.py"]
    end

    subgraph "SQLAlchemy 核心"
        Base["Base (Declarative)<br/>internal/db.py:11"]
        get_async_session["get_async_session()<br/>internal/db.py:30"]
    end

    subgraph "模型"
        Chat["Chat<br/>models/chats.py:40"]
        ChatMessage["ChatMessage<br/>models/chat_messages.py"]
        Folders["Folders<br/>models/folders.py"]
        AutomationRun["AutomationRun<br/>models/automations.py"]
    end

    DATABASE_URL --> get_async_session
    get_async_session --> Base
    Base --> Chat
    Base --> ChatMessage
    Base --> Folders
    Base --> AutomationRun

数据库 URL 配置：

  • SQLite：默认引擎，使用 aiosqlite backend/requirements.txt:28。
  • PostgreSQL：支持 pgvector，用于集成向量存储 backend/requirements.txt:122。
  • JSON 支持：自定义 JSONField 处理 SQLite 和 PostgreSQL 的 JSON 序列化 backend/open_webui/internal/db.py:11。

来源： backend/open_webui/internal/db.py:11-30, backend/open_webui/models/chats.py:40-70, backend/requirements.txt:27-32

核心数据模型：聊天系统

聊天系统是最关键的数据结构，使用复杂的 JSON 字段存储消息历史记录和元数据。

模型表名用途关键字段
Chatchat存储对话历史id, user_id, title, chat (JSON), meta (JSON) backend/open_webui/models/chats.py:40-55
ChatFilechat_file将聊天与上传的文件关联chat_id, file_id, message_id backend/open_webui/models/chats.py:97-105
ChatMessagechat_message单条消息记录id, chat_id, role, content backend/open_webui/models/chats.py:14

来源： backend/open_webui/models/chats.py:40-110

---

向量数据库集成

Open WebUI 支持多种向量数据库，用于检索增强生成（RAG）。该集成支持对文档和记忆进行语义搜索。

专用向量客户端
  • PgvectorClient：使用 pgvector 扩展将嵌入向量存储在 PostgreSQL 中 backend/requirements.txt:122。
  • MilvusClient：支持高性能向量数据库 backend/requirements.txt:128。
  • QdrantClient：支持多租户和高级过滤 backend/requirements.txt:129。
  • Elasticsearch/OpenSearch：支持混合搜索（BM25 + 向量）backend/requirements.txt:60, 131。
  • Pinecone：云原生无服务器向量搜索 backend/requirements.txt:132。

来源： backend/requirements.txt:58-61, backend/requirements.txt:122-133

---

文件存储提供商

系统通过 StorageProvider 抽象基类实现了灵活的存储抽象 backend/open_webui/storage/provider.py:40。

提供商实现
提供商后端实现类
本地服务器文件系统LocalStorageProvider backend/open_webui/storage/provider.py:58
S3AWS S3 / MinIOS3StorageProvider backend/open_webui/storage/provider.py:101
GCSGoogle Cloud StorageGCSStorageProvider backend/open_webui/storage/provider.py:30
AzureAzure Blob StorageAzureStorageProvider backend/open_webui/storage/provider.py:34
S3 存储实现

S3StorageProvider 使用 boto3 进行通信。它包含用于清理 S3 标签的逻辑 backend/open_webui/storage/provider.py:137-140，并处理带有可选标签的对象上传 backend/open_webui/storage/provider.py:141-158。它通过默认凭据回退支持 IAM 角色 backend/open_webui/storage/provider.py:124-131。

来源： backend/open_webui/storage/provider.py:40-160, backend/requirements.txt:125

---

数据流：聊天与文件持久化

sequenceDiagram
    participant FE as 前端 (InputMenu.svelte)
    participant API as 聊天 API (routers/chats.py)
    participant DB as SQL 数据库 (models/chats.py)
    participant SP as StorageProvider (storage/provider.py)

    FE->>API: POST /chats/new {chat, folder_id}
    API->>DB: ChatForm 处理
    DB-->>API: ChatModel
    API-->>FE: 200 OK (ChatResponse)

    Note over FE, SP: 文件上传流程
    FE->>SP: upload_file(file, filename)
    SP->>SP: 本地/S3/Azure 逻辑
    SP-->>FE: file_path/s3_url
    FE->>API: 将文件链接到聊天 (ChatFile)

实现细节：

  • 输入菜单集成：前端 InputMenu.svelte 管理文件上传和模型选择的发起 src/lib/components/chat/MessageInput/InputMenu.svelte:33-46。
  • 聊天使用统计：系统跟踪实验性使用统计信息，包括平均响应时间和 token 数量 backend/open_webui/routers/chats.py:92-153。
  • 安全检查：网页抓取和 URL 处理包括 SSL 验证和速率限制 backend/open_webui/retrieval/web/utils.py:144-181。

来源： src/lib/components/chat/MessageInput/InputMenu.svelte:33-63, backend/open_webui/routers/chats.py:92-181, backend/open_webui/storage/provider.py:141-160, backend/open_webui/retrieval/web/utils.py:144-181