agentic_huge_data_base / wiki
页面 Open WebUI · 17.1 开发环境设置·DeepWiki 中文全文译文
DeepWiki 中文译文 / Open WebUI / 17.1

17.1 · 开发环境设置（Development Environment Setup）

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

项目Open WebUI 章节17.1 状态全文译文 模块测试、发布与运维、系统架构、工具、记忆与模型调用、接口与服务契约
项目要点页2.5 参考项目 项目章节目录Open WebUI DeepWiki 原始章节Development Environment Setup 上一章17 下一章17.2
源码线索
  • CHANGELOG.md
  • CODE_OF_CONDUCT.md
  • backend/dev.sh
  • backend/open_webui/retrieval/web/testdata/brave.json
  • backend/start.sh
  • package-lock.json
  • package.json
  • run-ollama-docker.sh
  • run.sh
  • src/app.css
模块标签
  • 测试、发布与运维
  • 系统架构
  • 工具、记忆与模型调用
  • 接口与服务契约
  • 界面与交互

中文译文

开发环境设置（中文译文）

原始 DeepWiki 页面：https://deepwiki.com/open-webui/open-webui/17.1-development-environment-setup
翻译时间：2026-06-09T16:11:59.106Z
翻译模型：deepseek-chat
原文字符数：7426
项目：Open WebUI (open-webui)

---

开发环境搭建

相关源文件

以下文件用于生成此 Wiki 页面：

  • .env.example
  • CHANGELOG.md
  • CODE_OF_CONDUCT.md
  • Dockerfile
  • backend/dev.sh
  • backend/open_webui/retrieval/web/testdata/brave.json
  • backend/start.sh
  • backend/start_windows.bat
  • package-lock.json
  • package.json
  • run-ollama-docker.sh
  • run.sh
  • src/app.css
  • src/lib/components/admin/Settings/Interface/Banners.svelte
  • src/lib/components/admin/Settings/Models/ModelList.svelte
  • src/lib/components/common/RichTextInput.svelte
  • src/lib/components/common/Textarea.svelte
  • src/lib/constants.ts
  • src/routes/+layout.js
  • svelte.config.js

目的与范围

本文档指导开发者搭建 Open WebUI 的本地开发环境。内容涵盖前提条件、前后端依赖管理、环境变量配置以及开发服务器的启动。Open WebUI 是一个基于 SvelteKit 和 FastAPI 的 AI 界面，支持 RAG、协作笔记和多模型聊天 package.json:2-4。

前提条件

Open WebUI 需要特定版本的 Python 和 Node.js，以确保与其庞大的 AI 和 Web 依赖库兼容。

系统要求
  • Python：主要目标版本为 3.11.x Dockerfile:46。
  • Node.js：前端构建流水线使用版本 22（Alpine 3.20 或同等环境）Dockerfile:27。支持范围为 >=18.13.0 <=22.x.x package.json:159。
  • Git：用于版本控制和构建元数据 Dockerfile:36。
推荐开发工具
  • uv：快速的 Python 包安装器和解析器，用于管理复杂的依赖树 Dockerfile:142。
  • Playwright：如果在 RAG 中使用 playwright 引擎进行网页抓取，则需要安装 backend/start.sh:7-12。
  • Docker：用于容器化测试和运行辅助服务 run.sh:8-12。

后端开发环境搭建

后端是一个 FastAPI 应用程序，负责 AI 模型编排、RAG 流水线和实时通信。

架构与数据流
graph TD
    subgraph "入口点"
        main["open_webui.main:app"]
        start["backend/start.sh"]
        dev["backend/dev.sh"]
    end

    subgraph "请求处理"
        uvicorn["uvicorn"]
        fastapi["FastAPI 应用核心"]
    end

    subgraph "外部集成"
        ollama["Ollama API"]
        openai["OpenAI API"]
    end

    start --> uvicorn
    dev --> uvicorn
    uvicorn --> main
    main --> fastapi
    fastapi --> ollama
    fastapi --> openai

来源： backend/start.sh:83-87、backend/dev.sh:1-3、src/lib/constants.ts:10-11

依赖安装

项目通过 requirements.txt 和 package.json 管理依赖。

  1. 初始化虚拟环境：
   cd backend
   python -m venv venv
   source venv/bin/activate
  1. 使用 uv 安装：
   pip install uv
   uv pip install -r requirements.txt

*注意：对于 ARM64/QEMU 构建，设置 UV_LINK_MODE=copy 以防止 0 字节文件损坏* Dockerfile:139。

后端依赖分类
类别包文件引用
Web 核心fastapi、uvicornbackend/start.sh:83、backend/dev.sh:3
数据库psycopg (v3)CHANGELOG.md:30, 49
实时通信python-socketio、redisCHANGELOG.md:45
AI/MLtorch、sentence-transformers、faster-whisperDockerfile:146-150

来源： Dockerfile:141-165、CHANGELOG.md:30-49

前端开发环境搭建

前端是一个 SvelteKit 应用程序，使用 Vite 进行打包和热模块替换（HMR）。

安装与构建
  1. 安装依赖：
   npm ci --force

构建流水线中使用 --force 标志以确保干净安装 Dockerfile:39。

  1. 启动开发服务器：
   npm run dev

该命令在获取 Pyodide 资源后执行 vite dev --host package.json:6。

关键前端实体
实体角色文件引用
RichTextInput.svelte基于 TipTap 的聊天和笔记编辑器src/lib/components/common/RichTextInput.svelte:130-153
Textarea.svelte自动调整大小的输入组件src/lib/components/common/Textarea.svelte:36-50
constants.ts前端常量和 API 路由src/lib/constants.ts:4-19

来源： package.json:5-22、src/lib/constants.ts:1-40

配置与环境

Open WebUI 使用环境变量实现灵活部署。

关键环境变量
变量默认值用途
PORT8080后端端口 backend/start.sh:23
WEBUI_SECRET_KEY(自动生成)用于 JWT 签名。存储在 .webui_secret_key 文件中 backend/start.sh:31-35
OLLAMA_BASE_URL/ollama本地 Ollama 实例的端点 Dockerfile:76
WEB_LOADER_ENGINElink_reader网页抓取引擎（设置为 playwright 以支持 JavaScript）backend/start.sh:7-10
CUSTOM_API_KEY_HEADERnull可配置的 API 密钥认证请求头 CHANGELOG.md:15

来源： backend/start.sh:17-46、Dockerfile:63-106、CHANGELOG.md:12-23

开发工作流

启动服务器

后端（带热重载）：

cd backend
sh dev.sh

dev.sh 脚本为本地开发配置 CORS_ALLOW_ORIGIN，并使用 --reload 参数启动 uvicorn backend/dev.sh:1-3。

前端：

npm run dev
前后端交互
sequenceDiagram
    participant Browser as "SvelteKit 前端"
    participant Vite as "Vite 开发服务器 (5173)"
    participant FastAPI as "Uvicorn 后端 (8080)"

    Browser->>Vite: 加载资源 / HMR
    Browser->>FastAPI: API 请求（通过 WEBUI_API_BASE_URL）
    FastAPI-->>Browser: JSON 响应 / 流式响应

来源： src/lib/constants.ts:6-9、backend/dev.sh:1-3

测试与质量保证

代码质量工具
工具用途命令
eslint前端代码检查npm run lint:frontend package.json:14
pylint后端代码检查npm run lint:backend package.json:16
prettier代码格式化npm run format package.json:17
ruff后端格式化npm run format:backend package.json:18
svelte-check类型检查npm run check package.json:11
自动化测试
  • 前端：使用 vitest 进行单元测试 package.json:21。
  • 端到端：使用 cypress 进行集成测试 package.json:20。

来源： package.json:5-23、CHANGELOG.md:21-22