跳到主要内容

开发 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 或 3.12(见下方说明;暂不支持 3.13)
Node.js22.10+
Git任意较新版本
Python 版本兼容性

Open WebUI 支持 Python 3.11 与 3.12暂不支持 3.13 —— 我们的部分依赖还需要发布兼容 3.13 的版本,在此之前,在 3.13 上安装会失败或在运行时出错。

  • 生产环境请使用 Docker 镜像最新的 Python 3.11。这是我们测试最充分的组合。
  • 3.12 也可以工作,但我们在 3.12 上收到过极个别、尚未在 3.11 上复现的异常行为报告。如果你在 3.12 上遇到难以解释的问题,先降到最新的 3.11 是首选排查步骤。
将开发数据与生产数据分开

不要在开发环境与生产环境之间共享数据库或数据目录。开发构建可能包含向后不兼容的数据库迁移。


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 可用内存。

端口冲突

如果端口 51738080 已被占用,请先找出冲突进程:

# 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 配置

热重载不工作

  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. 以清晰的标题和描述向 dev 分支提交拉取请求(pull request)

贡献规范请参见 Contributing

本内容仅供参考,不构成任何保证、担保或合同承诺。Open WebUI 按“现状”提供。请参阅您的许可协议 以了解适用条款。