跳到主要内容

开发 Open WebUI

从源码运行 Open WebUI 以进行开发和测试。

本指南介绍如何设置本地开发环境，使前端（SvelteKit）和后端（Python/FastAPI）同时运行。你需要开启两个终端会话，分别用于前端和后端。

不需要完整的开发环境？

你可以通过运行开发版（dev）的 Docker 镜像来测试最新的更改：docker run -d -p 3000:8080 -v open-webui-dev:/app/backend/data --name open-webui-dev ghcr.io/open-webui/open-webui:dev

前提条件​

需求版本
Python3.11+
Node.js22.10+
Git任何较新版本
隔离你的数据

切勿在开发环境和生产环境之间共享数据库或数据目录。开发版本可能包含不向下兼容的数据库迁移（database migrations）。

1. 克隆仓库​

git clone https://github.com/open-webui/open-webui.git
cd open-webui

2. 前端设置​

在第一个终端中，在项目根目录下执行：

cp -RPp .env.example .env
npm install
npm run build
npm run dev

npm run build 会编译前端并提早捕获构建时的错误。然后 npm run dev 会在 http://localhost:5173 启动开发服务器。在后端运行之前，前端会显示一个等待界面。

提示

如果 npm install 失败并提示兼容性警告，请运行 npm install --force。

3. 后端设置​

在第二个终端中：

cd backend

创建并激活虚拟环境（Conda 或 venv）：

# 选项 A: Conda
conda create --name open-webui python=3.11
conda activate open-webui

# 选项 B: venv
python3 -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

安装依赖并启动服务器：

pip install -r requirements.txt -U
sh dev.sh

后端将在 http://localhost:8080 启动。API 文档可在 http://localhost:8080/docs 查看。

刷新位于 http://localhost:5173 的前端页面，你应该就能看到完整的应用程序了。

从其他设备进行测试​

要从手机或同一网络中的其他计算机访问你的开发实例：

  1. 查找你的计算机的局域网 IP（例如 192.168.1.42）
  2. 在 backend/dev.sh 中将该来源添加到 CORS 允许列表中：
export CORS_ALLOW_ORIGIN="http://localhost:5173;http://localhost:8080;http://192.168.1.42:5173"
  1. 重启后端并浏览至 http://192.168.1.42:5173

故障排除​

"FATAL ERROR: Reached Heap Limit"​

在构建过程中 Node.js 内存不足。在运行前端命令之前增加堆内存大小：

export NODE_OPTIONS="--max-old-space-size=4096"
npm run dev

请确保至少有 4 GB 的可用 RAM。

端口冲突​

如果端口 5173 或 8080 已被占用，请找出冲突的进程：

# macOS/Linux
lsof -i :5173

# Windows (PowerShell)
Get-Process -Id (Get-NetTCPConnection -LocalPort 5173).OwningProcess

终止该进程，或者在 vite.config.js（前端）或 dev.sh（后端）中更改端口。

图标未加载 (CORS)​

如果静态资源加载失败，请在 backend/dev.sh 中配置 CORS_ALLOW_ORIGIN 以包含你的前端 URL。详情请参阅 CORS 配置。

热重载（Hot reload）不起作用​

  1. 验证两个开发服务器均在无错误运行
  2. 强制刷新浏览器 (Ctrl+Shift+R / Cmd+Shift+R)
  3. 重新安装前端依赖：rm -rf node_modules && npm install
  4. 后端更改可能需要手动重启 sh dev.sh

贡献工作流​

  1. 在编写代码之前，先在 GitHub Discussions 发起讨论
  2. 为你的工作从 dev 创建一个分支。切勿直接提交到 dev。
git checkout dev
git pull origin dev
git checkout -b my-feature-branch
  1. 定期从 dev 合并代码以保持你的分支同步
  2. 提交一个 Pull Request 到 dev 分支，并附上清晰的标题和描述

有关贡献指南，请参阅 贡献。

This content is for informational purposes only and does not constitute a warranty, guarantee, or contractual commitment. Open WebUI is provided "as is." See your license for applicable terms.