16.3 · 构建系统与包管理（Build System and Package Management）

构建系统与包管理（中文译文）

原始 DeepWiki 页面：https://deepwiki.com/open-webui/open-webui/16.3-build-system-and-package-management

翻译时间：2026-06-09T16:11:58.441Z

翻译模型：deepseek-chat

原文字符数：11819

项目：Open WebUI (open-webui)

---

构建系统与包管理

相关源文件

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

• .github/workflows/build-release.yml
• .github/workflows/docker-build.yaml
• .github/workflows/format-backend.yaml
• .github/workflows/format-build-frontend.yaml
• .github/workflows/integration-test.disabled
• .github/workflows/lint-backend.disabled
• .github/workflows/lint-frontend.disabled
• .github/workflows/release-pypi.yml
• CHANGELOG.md
• backend/open_webui/retrieval/web/firecrawl.py
• backend/open_webui/retrieval/web/utils.py
• backend/open_webui/storage/provider.py
• backend/open_webui/test/apps/webui/storage/test_provider.py
• backend/requirements-min.txt
• backend/requirements.txt
• docker-compose.playwright.yaml
• hatch_build.py
• package-lock.json
• package.json
• pyproject.toml
• src/app.css
• src/lib/components/common/RichTextInput.svelte
• uv.lock
• vite.config.ts

本文档描述了 Open WebUI 的构建系统和包管理配置。内容涵盖基于 pyproject.toml 并使用 Hatchling 的构建系统、依赖层级结构、Vite/SvelteKit 前端编译，以及将后端 Python 代码和前端资源作为统一包进行分发的机制。

构建系统架构

Open WebUI 采用基于 PEP 621（pyproject.toml）的现代 Python 构建系统，并使用 Hatchling 作为构建后端。构建过程将 FastAPI 后端和编译后的 SvelteKit 前端整合为一个可分发的 Python 包。

Hatchling 构建配置

构建系统在 pyproject.toml:178-180 中配置为使用 Hatchling：

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

Hatchling 提供以下功能：

• 符合 PEP 517/PEP 660 标准的构建后端。
• 通过 hatch_build.py pyproject.toml:193 提供自定义构建钩子。
• 从 package.json pyproject.toml:189-191 动态提取版本号。
• 灵活的 wheel 分发包文件包含/排除规则 pyproject.toml:195-208。

构建流程

标题：从源码到制品的构建流水线

graph TB
    PackageJSON["package.json<br/>(版本: '0.9.2')"]
    PyprojectToml["pyproject.toml<br/>(Hatchling 配置)"]
    HatchBuildPy["hatch_build.py<br/>(构建钩子)"]
    BackendSrc["backend/<br/>(Python 模块)"]
    FrontendSrc["src/<br/>(SvelteKit/Vite)"]

    ViteBuild["npm run build<br/>(Vite/SvelteKit)"]
    HatchlingBuild["Hatchling 构建过程"]

    StaticAssets["build/<br/>(静态前端资源)"]
    WheelOutput["open_webui-*.whl<br/>(可分发包)"]

    FrontendSrc --> ViteBuild
    ViteBuild --> StaticAssets

    PackageJSON -->|"版本提取<br/>[pyproject.toml:189-191]()"| HatchlingBuild
    PyprojectToml -->|"配置"| HatchlingBuild
    HatchBuildPy -->|"自定义钩子<br/>[pyproject.toml:193]()"| HatchlingBuild
    BackendSrc -->|"sources=['backend']<br/>[pyproject.toml:196]()"| HatchlingBuild
    StaticAssets -->|"强制包含<br/>[pyproject.toml:208]()"| HatchlingBuild

    HatchlingBuild --> WheelOutput

来源：pyproject.toml:178-208, package.json:3, hatch_build.py:1-21

构建系统执行以下关键操作：

1. 前端编译：通过 npm run build package.json:8 使用 Vite 构建 SvelteKit 前端。该脚本依次触发 pyodide:fetch 和 vite build package.json:8。
2. 版本提取：使用正则表达式从 package.json 动态读取版本号 pyproject.toml:189-191。
3. 源码收集：从 backend/ 目录收集 Python 源码 pyproject.toml:196。
4. 资源包含：强制将 build/ 目录中编译后的前端资源包含到包的 open_webui/frontend 路径下 pyproject.toml:208。
5. 文件过滤：从最终的 wheel 包中排除开发文件和数据库文件，如 .webui_secret_key、webui.db 和 chroma.sqlite3 pyproject.toml:197-207。

来源：pyproject.toml:178-208, package.json:8, 22, hatch_build.py:18-21

依赖管理结构

需求文件层级

Open WebUI 为不同环境维护了多个依赖规格说明：

文件	用途	关键内容
backend/requirements.txt	完整生产依赖	Docker 构建的完整依赖列表 backend/requirements.txt:1-161
backend/requirements-min.txt	最小运行时依赖	核心框架和必要的 AI 库 backend/requirements-min.txt:1-60
pyproject.toml	标准安装与扩展	定义 [project.dependencies] 和 [project.optional-dependencies] pyproject.toml:8-172

来源：backend/requirements.txt:1-161, backend/requirements-min.txt:1-60, pyproject.toml:8-172

依赖分类

依赖按功能领域组织，以支持模块化架构：

核心 Web 框架

应用核心依赖 FastAPI 和 Uvicorn 实现高性能异步服务。

• fastapi==0.135.1 backend/requirements.txt:1
• uvicorn[standard]==0.41.0 backend/requirements.txt:2
• pydantic==2.12.5 backend/requirements.txt:3

AI 与 LLM 集成

支持多种模型提供商和模型上下文协议（MCP）。

• openai==2.29.0、anthropic==0.86.0、google-genai==1.66.0 backend/requirements.txt:48-50
• mcp==1.26.0 backend/requirements.txt:46
• langchain==1.2.10 backend/requirements.txt:52

RAG 与向量存储

广泛支持文档处理和向量数据库。

• chromadb==1.5.2 backend/requirements.txt:58
• sentence-transformers==5.4.0 backend/requirements.txt:63
• pypdf==6.7.5、docx2txt==0.9、python-pptx==1.0.2 backend/requirements.txt:70-74

实时与协作

• python-socketio==5.16.1 backend/requirements.txt:7
• pycrdt==0.12.47（用于 Yjs 协作编辑）backend/requirements.txt:34
• redis==7.4.0 backend/requirements.txt:35

来源：backend/requirements.txt:1-161, pyproject.toml:8-124

可选依赖与扩展

pyproject.toml 为特定数据库后端和扩展功能定义了可选依赖组：

标题：可选依赖映射

graph LR
    subgraph "pyproject.toml [project.optional-dependencies]"
        Postgres["postgres<br/>(psycopg2-binary, pgvector)"]
        MariaDB["mariadb<br/>(mariadb 库)"]
        Unstructured["unstructured<br/>(unstructured 库)"]
        All["all<br/>(完整向量数据库套件 + 测试)"]
    end

    Postgres -->|"通过以下方式启用"| InstallPG["pip install open-webui[postgres]"]
    MariaDB -->|"通过以下方式启用"| InstallDB["pip install open-webui[mariadb]"]
    Unstructured -->|"通过以下方式启用"| InstallUnstructured["pip install open-webui[unstructured]"]
    All -->|"通过以下方式启用"| InstallAll["pip install open-webui[all]"]

来源：pyproject.toml:138-172

• PostgreSQL：包含 psycopg2-binary==2.9.11 和 pgvector==0.4.2 pyproject.toml:139-142。
• MariaDB：包含 mariadb==1.1.14 pyproject.toml:143-145。
• Unstructured：包含 unstructured==0.18.31 pyproject.toml:146-148。
• All：聚合了企业级向量数据库（qdrant-client、pinecone、pymilvus、elasticsearch、weaviate-client）以及 playwright 和 pytest 等测试工具 pyproject.toml:150-172。

来源：pyproject.toml:138-172

存储提供程序集成

构建系统确保云存储提供程序作为可选或核心依赖可用。backend/open_webui/storage/provider.py 中的 StorageProvider 抽象允许在本地和云后端之间切换。

标题：存储提供程序实现层级

classDiagram
    class StorageProvider {
        <<接口>>
        +upload_file(file, filename, tags)
        +get_file(file_path)
        +delete_file(file_path)
    }
    class LocalStorageProvider {
        +upload_file()
        +get_file()
    }
    class S3StorageProvider {
        +s3_client
        +upload_file()
    }
    class GCSStorageProvider {
        +gcs_client
    }
    class AzureStorageProvider {
        +blob_service_client
    }
    StorageProvider <|-- LocalStorageProvider
    StorageProvider <|-- S3StorageProvider
    StorageProvider <|-- GCSStorageProvider
    StorageProvider <|-- AzureStorageProvider

来源：backend/open_webui/storage/provider.py:40-182

• 本地：LocalStorageProvider 中的默认实现 backend/open_webui/storage/provider.py:58-99。
• S3：S3StorageProvider 中使用 boto3 的实现 backend/open_webui/storage/provider.py:101-182。
• Azure：AzureStorageProvider 中使用 azure-identity 和 azure-storage-blob 的实现 backend/requirements.txt:107-108（依赖），backend/open_webui/storage/provider.py:33-35（实现）。
• GCS：GCSStorageProvider 中使用 google-cloud-storage 的实现 backend/requirements.txt:117-118（依赖），backend/open_webui/storage/provider.py:30（实现）。

来源：backend/open_webui/storage/provider.py:40-182, backend/requirements.txt:107-108, 117-118

版本同步与固定版本

某些依赖需要在技术栈中严格匹配版本：

1. Playwright：requirements.txt 中的版本（1.58.0）必须与 docker-compose.playwright.yaml 中的 Docker 镜像（v1.58.0-noble）匹配 backend/requirements.txt:130, docker-compose.playwright.yaml:3。
2. PyArrow：固定为 20.0.0，专门用于 Raspberry Pi 兼容性 backend/requirements.txt:65。
3. AioHTTP：固定为 3.13.5，因为 3.13.3 存在缺陷 backend/requirements.txt:16。
4. AV：固定为 14.0.1，以避免 FIPS 自检失败 backend/requirements.txt:135。

来源：backend/requirements.txt:16, 65, 130, 135, docker-compose.playwright.yaml:3-5

自动化构建与发布工作流

项目利用 GitHub Actions 自动化构建和分发过程。

Docker 构建工作流

• 使用 QEMU 构建多平台镜像（linux/amd64、linux/arm64）.github/workflows/docker-build.yaml:25-28, 49。
• 通过传递 USE_CUDA=true 构建参数支持专门的 CUDA 构建 .github/workflows/docker-build.yaml:206。
• 将镜像推送到 ghcr.io .github/workflows/docker-build.yaml:13-60。
• 在 Dockerfile 中设置 UV_LINK_MODE=copy 以解决 ARM64 可靠性问题 CHANGELOG.md:31。

PyPI 发布工作流

• 在推送到 main 分支或标签时触发 CHANGELOG.md:1-10。
• 使用 hatchling 作为构建后端生成 wheel 包 pyproject.toml:179。
• 动态版本控制直接从 package.json 提取版本号 pyproject.toml:189-191。

来源：.github/workflows/docker-build.yaml:1-207, pyproject.toml:178-191, CHANGELOG.md:31