mirror of
https://github.com/open-webui/open-webui.git
synced 2025-12-14 13:25:20 +00:00
6.3 KiB
6.3 KiB
Open WebUI 本地开发环境搭建指南
本指南提供 Open WebUI 项目的本地开发环境配置和运行步骤。
系统要求
- Node.js: v20.19.5 或更高版本
- Python: 3.12.x (推荐使用 pyenv 管理)
- npm: 10.8.2 或更高版本
- 操作系统: macOS / Linux / Windows
技术栈
前端
- 框架: SvelteKit 4 + TypeScript
- 构建工具: Vite 5
- 样式: Tailwind CSS 4
后端
- 语言: Python 3.12
- 框架: FastAPI
- 数据库: SQLite (开发环境) / PostgreSQL (生产环境)
- ORM: SQLAlchemy + Peewee
环境准备
1. 安装 pyenv (如果系统 Python 版本不是 3.12)
# macOS (使用 Homebrew)
brew install pyenv
# 配置 shell 环境变量 (添加到 ~/.zshrc 或 ~/.bash_profile)
export PATH="$HOME/.pyenv/bin:$PATH"
eval "$(pyenv init -)"
2. 安装 Python 3.12
# 使用 pyenv 安装 Python 3.12
pyenv install 3.12
# 验证安装
pyenv versions
安装依赖
前端依赖
# 在项目根目录执行
npm install --legacy-peer-deps
注意: 需要使用 --legacy-peer-deps 标志来解决 @tiptap 包的版本冲突问题。
后端依赖
# 进入后端目录
cd backend
# 创建 Python 3.12 虚拟环境
/Users/你的用户名/.pyenv/versions/3.12.12/bin/python3 -m venv venv
# 或者,如果系统 Python 已是 3.12
python3 -m venv venv
# 激活虚拟环境
source venv/bin/activate # macOS/Linux
# 或
venv\Scripts\activate # Windows
# 升级 pip
pip install --upgrade pip
# 安装依赖
pip install -r requirements.txt
运行开发服务器
启动后端服务 (端口 8080)
# 在 backend 目录下,激活虚拟环境后
cd backend
source venv/bin/activate
python -m uvicorn open_webui.main:app --reload --port 8080 --host 0.0.0.0
后端服务将运行在: http://localhost:8080
后端启动时会自动:
- 运行数据库迁移 (Alembic)
- 初始化 SQLite 数据库
- 配置向量数据库 (ChromaDB)
启动前端服务 (端口 5050)
# 在项目根目录
npm run dev:5050
前端服务将运行在: http://localhost:5050
首次启动时会自动:
- 下载 Pyodide 包 (浏览器内 Python 运行时)
- 预加载常用 Python 包 (numpy, pandas, matplotlib 等)
访问应用
打开浏览器访问: http://localhost:5050
前端会通过 Vite 代理将 API 请求转发到后端 (8080 端口)。
开发工作流
目录结构
open-webui-next/
├── src/ # 前端源码
│ ├── routes/ # SvelteKit 路由
│ ├── lib/
│ │ ├── apis/ # API 客户端
│ │ ├── components/ # Svelte 组件
│ │ ├── stores/ # 全局状态管理
│ │ └── i18n/ # 国际化
├── backend/ # 后端源码
│ ├── open_webui/
│ │ ├── main.py # FastAPI 入口
│ │ ├── routers/ # API 路由
│ │ ├── models/ # 数据模型
│ │ ├── utils/ # 工具函数
│ │ └── migrations/ # 数据库迁移
│ ├── requirements.txt
│ └── venv/ # Python 虚拟环境
└── package.json
常用开发命令
前端
npm run dev # 启动开发服务器 (默认端口 5173)
npm run dev:5050 # 启动开发服务器 (端口 5050)
npm run build # 构建生产版本
npm run lint # 代码检查
npm run format # 代码格式化
npm run test:frontend # 运行单元测试
npm run i18n:parse # 解析并更新翻译文件
后端
# 在 backend 目录下,激活虚拟环境后
# 启动开发服务器 (自动重载)
python -m uvicorn open_webui.main:app --reload --port 8080
# 代码格式化
black .
# 数据库迁移
cd backend
alembic revision --autogenerate -m "描述" # 生成迁移脚本
alembic upgrade head # 执行迁移
热重载
- 前端: Vite 自动检测文件变化并热重载
- 后端: uvicorn 的
--reload参数自动检测 Python 代码变化并重启
常见问题
1. npm install 失败
问题: 依赖版本冲突
解决方案:
npm install --legacy-peer-deps
2. 后端 Python 版本不兼容
问题: unstructured 包不支持 Python 3.13+
解决方案: 使用 Python 3.12:
pyenv install 3.12
cd backend
rm -rf venv
/Users/你的用户名/.pyenv/versions/3.12.12/bin/python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
3. 端口被占用
问题: 8080 或 5050 端口已被使用
解决方案:
# 查找占用端口的进程
lsof -i :8080
lsof -i :5050
# 终止进程
kill -9 <PID>
# 或者使用不同端口
# 前端:
npm run dev -- --port 3000
# 后端:
python -m uvicorn open_webui.main:app --reload --port 8000
4. 前端 Pyodide 下载慢
问题: 首次启动下载 Pyodide 包较慢
解决方案: 耐心等待,包会缓存在 node_modules 中,后续启动会很快。
5. 数据库迁移错误
问题: Alembic 迁移失败
解决方案:
# 删除数据库重新初始化 (仅开发环境)
rm backend/data/webui.db
python -m uvicorn open_webui.main:app --reload --port 8080
环境变量配置
后端可通过环境变量配置,创建 backend/.env 文件:
# 数据库
DATABASE_URL=sqlite:///data/webui.db
# 向量数据库
VECTOR_DB=chroma
EMBEDDING_MODEL=sentence-transformers/all-MiniLM-L6-v2
# CORS (开发环境)
CORS_ALLOW_ORIGIN=*
# 日志级别
LOG_LEVEL=INFO
生产部署
生产环境使用 Docker 部署,详见项目根目录的 Dockerfile 和 docker-compose.yaml。
# 构建镜像
docker build -t open-webui .
# 运行容器
docker run -d -p 8080:8080 -v open-webui:/app/backend/data open-webui
更多资源
- 项目文档: CLAUDE.md
- API 文档: http://localhost:8080/docs (启动后端后访问)
- 官方仓库: https://github.com/open-webui/open-webui
贡献指南
- Fork 项目
- 创建功能分支 (
git checkout -b feature/AmazingFeature) - 提交更改 (
git commit -m 'Add some AmazingFeature') - 推送到分支 (
git push origin feature/AmazingFeature) - 创建 Pull Request
最后更新: 2025-11-08