跳到主要内容

开发 OPL 数据空间

从源码运行 OPL 数据空间，用于开发与测试。

这份指南介绍如何建立一个本地开发环境，让前端（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

前置要求​

RequirementVersion
Python3.11+
Node.js22.10+
Git任意较新的版本
分离开发与生产数据

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

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

创建并激活虚拟环境：

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

# Option 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 在构建过程中内存不足。先提高 heap：

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

同时尽量保证机器至少有 4 GB 可用内存。

端口冲突​

如果 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 包含前端地址。详见 CORS 配置。

热更新失效​

  1. 确认两个 dev server 都在正常运行
  2. 浏览器做强制刷新
  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。