mirror of
https://github.com/open-webui/open-webui.git
synced 2025-12-12 20:35:19 +00:00
feat:补充local setuo
This commit is contained in:
sylarchen1389
parent
ecbf88ee2a
commit
e2eb06d5da
1 changed files with 514 additions and 0 deletions
514
docs/LOCAL_SETUP.md
Normal file
514
docs/LOCAL_SETUP.md
Normal file
|
|
@ -0,0 +1,514 @@
|
|||
# Open WebUI 本地开发环境搭建指南
|
||||
|
||||
本指南提供 Open WebUI 项目的本地开发环境配置和运行步骤。
|
||||
|
||||
## 系统要求
|
||||
|
||||
- **Node.js**: v22.x 或更高版本
|
||||
- **Python**: 3.11+ / 3.12.x (推荐使用 pyenv 管理)
|
||||
- **数据库**: PostgreSQL 15+（必需）
|
||||
- **npm**: 10.8.2 或更高版本
|
||||
- **操作系统**: macOS / Linux / Windows
|
||||
|
||||
## 技术栈
|
||||
|
||||
### 前端
|
||||
- **框架**: SvelteKit 4 + TypeScript
|
||||
- **构建工具**: Vite 5
|
||||
- **样式**: Tailwind CSS 4
|
||||
|
||||
### 后端
|
||||
- **语言**: Python 3.11+ / 3.12
|
||||
- **框架**: FastAPI
|
||||
- **数据库**: PostgreSQL 15+
|
||||
- **ORM**: SQLAlchemy
|
||||
- **迁移工具**: Alembic
|
||||
|
||||
## 环境准备
|
||||
|
||||
### 1. 安装 Node.js 22
|
||||
|
||||
```bash
|
||||
# macOS (使用 Homebrew)
|
||||
brew install node@22
|
||||
|
||||
# 或使用 nvm
|
||||
nvm install 22
|
||||
nvm use 22
|
||||
|
||||
# 验证安装
|
||||
node --version # 应显示 v22.x.x
|
||||
npm --version
|
||||
```
|
||||
|
||||
### 2. 安装 PostgreSQL 15+
|
||||
|
||||
```bash
|
||||
# macOS (使用 Homebrew)
|
||||
brew install postgresql@15
|
||||
brew services start postgresql@15
|
||||
|
||||
# 创建数据库
|
||||
createdb openwebui_dev
|
||||
|
||||
# 验证安装
|
||||
psql --version # 应显示 15.x
|
||||
```
|
||||
|
||||
**或者使用 Docker 运行 PostgreSQL**:
|
||||
```bash
|
||||
docker run -d \
|
||||
--name postgres-openwebui \
|
||||
-e POSTGRES_PASSWORD=postgres \
|
||||
-e POSTGRES_DB=openwebui_dev \
|
||||
-p 5432:5432 \
|
||||
postgres:15
|
||||
```
|
||||
|
||||
### 3. 安装 Python 3.11/3.12
|
||||
|
||||
```bash
|
||||
# macOS (使用 Homebrew)
|
||||
brew install python@3.12
|
||||
|
||||
# 或使用 pyenv
|
||||
pyenv install 3.12
|
||||
pyenv local 3.12
|
||||
|
||||
# 验证安装
|
||||
python3 --version # 应显示 3.12.x
|
||||
```
|
||||
|
||||
## 安装依赖
|
||||
|
||||
### 前端依赖
|
||||
|
||||
```bash
|
||||
# 在项目根目录执行
|
||||
npm install
|
||||
```
|
||||
|
||||
### 后端依赖
|
||||
|
||||
```bash
|
||||
# 进入后端目录
|
||||
cd backend
|
||||
|
||||
# 创建 Python 虚拟环境
|
||||
python3 -m venv venv
|
||||
|
||||
# 激活虚拟环境
|
||||
source venv/bin/activate # macOS/Linux
|
||||
# 或
|
||||
venv\Scripts\activate # Windows
|
||||
|
||||
# 升级 pip
|
||||
pip install --upgrade pip
|
||||
|
||||
# 安装依赖
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
|
||||
## 配置数据库
|
||||
|
||||
创建 `backend/.env` 文件:
|
||||
|
||||
```bash
|
||||
# PostgreSQL 连接（必需）
|
||||
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/openwebui_dev
|
||||
```
|
||||
|
||||
### 初始化数据库
|
||||
|
||||
```bash
|
||||
cd backend
|
||||
source venv/bin/activate
|
||||
|
||||
# 方式1: 启动应用自动迁移 (推荐)
|
||||
python -m uvicorn open_webui.main:app --reload --port 8080
|
||||
# 应用启动时会自动执行 alembic upgrade head
|
||||
|
||||
# 方式2: 手动执行迁移
|
||||
cd open_webui
|
||||
python -m alembic upgrade head
|
||||
```
|
||||
|
||||
## 运行开发服务器
|
||||
|
||||
### 启动后端服务 (端口 8080)
|
||||
|
||||
```bash
|
||||
# 在 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 upgrade head)
|
||||
- ✅ 初始化数据库表结构
|
||||
- ✅ 配置向量数据库 (ChromaDB)
|
||||
|
||||
### 启动前端服务 (端口 5050)
|
||||
|
||||
```bash
|
||||
# 在项目根目录
|
||||
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
|
||||
```
|
||||
|
||||
### 常用开发命令
|
||||
|
||||
#### 前端
|
||||
|
||||
```bash
|
||||
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 # 解析并更新翻译文件
|
||||
```
|
||||
|
||||
#### 后端
|
||||
|
||||
```bash
|
||||
# 在 backend 目录下,激活虚拟环境后
|
||||
|
||||
# 启动开发服务器 (自动重载)
|
||||
python -m uvicorn open_webui.main:app --reload --port 8080
|
||||
|
||||
# 代码格式化
|
||||
black .
|
||||
|
||||
# 数据库迁移 (详见下方"数据库迁移管理"章节)
|
||||
./scripts/migrate.sh current # 查看当前版本
|
||||
./scripts/migrate.sh upgrade # 升级到最新
|
||||
./scripts/check-status.sh # 检查一致性
|
||||
```
|
||||
|
||||
### 热重载
|
||||
|
||||
- **前端**: Vite 自动检测文件变化并热重载
|
||||
- **后端**: uvicorn 的 `--reload` 参数自动检测 Python 代码变化并重启
|
||||
|
||||
---
|
||||
|
||||
## 数据库迁移管理
|
||||
|
||||
### 自动迁移机制
|
||||
|
||||
**✅ 应用启动时自动执行迁移**
|
||||
|
||||
项目已配置自动迁移机制 (`backend/open_webui/config.py`):
|
||||
- 每次应用启动自动执行 `alembic upgrade head`
|
||||
- 开发和生产环境使用相同机制
|
||||
- 幂等性设计，重复执行安全
|
||||
|
||||
**这意味着**:
|
||||
- ✅ 拉取代码后重启应用即可自动同步数据库
|
||||
- ✅ 无需手动执行迁移命令
|
||||
- ✅ 开发环境和生产环境数据库始终一致
|
||||
|
||||
### 快速命令
|
||||
|
||||
```bash
|
||||
# 查看当前迁移版本
|
||||
./scripts/migrate.sh current
|
||||
|
||||
# 检查数据库与代码一致性
|
||||
./scripts/check-status.sh
|
||||
|
||||
# 查看迁移历史
|
||||
./scripts/migrate.sh history
|
||||
|
||||
# 手动升级 (通常不需要,应用启动会自动执行)
|
||||
./scripts/migrate.sh upgrade
|
||||
```
|
||||
|
||||
### 创建新迁移
|
||||
|
||||
**场景1: 添加新表或字段**
|
||||
|
||||
```bash
|
||||
cd backend/open_webui
|
||||
|
||||
# 1. 创建迁移脚本
|
||||
python -m alembic revision -m "add_user_credits_table"
|
||||
|
||||
# 2. 编辑生成的文件
|
||||
vim migrations/versions/xxxx_add_user_credits_table.py
|
||||
|
||||
# 3. 测试迁移
|
||||
python -m alembic upgrade head # 升级
|
||||
python -m alembic downgrade -1 # 降级测试
|
||||
python -m alembic upgrade head # 重新升级
|
||||
|
||||
# 4. 提交代码
|
||||
git add migrations/versions/xxxx_add_user_credits_table.py
|
||||
git commit -m "feat: add user credits table"
|
||||
```
|
||||
|
||||
**场景2: 修改现有表**
|
||||
|
||||
```python
|
||||
# 迁移脚本示例
|
||||
def upgrade():
|
||||
from sqlalchemy.dialects import postgresql
|
||||
|
||||
op.add_column('user',
|
||||
sa.Column('balance', postgresql.NUMERIC(20, 6),
|
||||
server_default='0', nullable=False))
|
||||
|
||||
def downgrade():
|
||||
op.drop_column('user', 'balance')
|
||||
```
|
||||
|
||||
### 多人协作
|
||||
|
||||
**处理迁移冲突**:
|
||||
|
||||
```bash
|
||||
# 发现多个 head
|
||||
python -m alembic heads
|
||||
# 输出: abc123 (head), def456 (head)
|
||||
|
||||
# 合并迁移
|
||||
python -m alembic merge -m "merge_branches" heads
|
||||
|
||||
# 应用合并
|
||||
python -m alembic upgrade head
|
||||
```
|
||||
|
||||
### 完整指南
|
||||
|
||||
详细的 Alembic 使用攻略请参考:
|
||||
- **[Alembic 使用攻略](./ALEMBIC_GUIDE.md)** - 开发协作和生产环境迁移
|
||||
- **[数据库一致性保证指南](./DATABASE_CONSISTENCY_GUIDE.md)** - 完整的方案和最佳实践
|
||||
|
||||
## 常见问题
|
||||
|
||||
### 1. npm install 失败
|
||||
|
||||
**问题**: 依赖版本冲突
|
||||
|
||||
**解决方案**:
|
||||
```bash
|
||||
npm install --legacy-peer-deps
|
||||
```
|
||||
|
||||
### 2. 后端 Python 版本不兼容
|
||||
|
||||
**问题**: `unstructured` 包不支持 Python 3.13+
|
||||
|
||||
**解决方案**: 使用 Python 3.12:
|
||||
```bash
|
||||
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 端口已被使用
|
||||
|
||||
**解决方案**:
|
||||
```bash
|
||||
# 查找占用端口的进程
|
||||
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 迁移失败
|
||||
|
||||
**解决方案**:
|
||||
```bash
|
||||
# 删除数据库并重新创建
|
||||
dropdb openwebui_dev
|
||||
createdb openwebui_dev
|
||||
|
||||
# 重启应用（自动执行迁移）
|
||||
python -m uvicorn open_webui.main:app --reload --port 8080
|
||||
```
|
||||
|
||||
### 6. PostgreSQL 连接失败
|
||||
|
||||
**问题**: 无法连接到 PostgreSQL
|
||||
|
||||
**解决方案**:
|
||||
```bash
|
||||
# 检查 PostgreSQL 是否运行
|
||||
brew services list | grep postgresql
|
||||
|
||||
# 启动 PostgreSQL
|
||||
brew services start postgresql@15
|
||||
|
||||
# 测试连接
|
||||
psql -U postgres -d openwebui_dev
|
||||
|
||||
# 检查环境变量
|
||||
cat backend/.env | grep DATABASE_URL
|
||||
```
|
||||
|
||||
## 环境变量配置
|
||||
|
||||
创建 `backend/.env` 文件:
|
||||
|
||||
```bash
|
||||
# 数据库（必需 PostgreSQL）
|
||||
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/openwebui_dev
|
||||
|
||||
# 向量数据库
|
||||
VECTOR_DB=chroma
|
||||
EMBEDDING_MODEL=sentence-transformers/all-MiniLM-L6-v2
|
||||
|
||||
# CORS (开发环境)
|
||||
CORS_ALLOW_ORIGIN=*
|
||||
|
||||
# 日志级别
|
||||
LOG_LEVEL=INFO
|
||||
|
||||
# Redis (可选，用于 Session)
|
||||
# REDIS_URL=redis://localhost:6379/0
|
||||
```
|
||||
|
||||
## 生产部署
|
||||
|
||||
生产环境使用 Docker 部署,详见项目根目录的 `Dockerfile` 和 `docker-compose.yaml`。
|
||||
|
||||
```bash
|
||||
# 构建镜像
|
||||
docker build -t open-webui .
|
||||
|
||||
# 运行容器
|
||||
docker run -d -p 8080:8080 -v open-webui:/app/backend/data open-webui
|
||||
```
|
||||
|
||||
## 更多资源
|
||||
|
||||
### 项目文档
|
||||
- **[CLAUDE.md](./CLAUDE.md)** - 项目架构和开发指南
|
||||
- **[ALEMBIC_GUIDE.md](./ALEMBIC_GUIDE.md)** - Alembic 使用攻略
|
||||
- **[DATABASE_CONSISTENCY_GUIDE.md](./DATABASE_CONSISTENCY_GUIDE.md)** - 数据库一致性保证完整方案
|
||||
|
||||
### 在线文档
|
||||
- **API 文档**: http://localhost:8080/docs (启动后端后访问)
|
||||
- **Swagger UI**: http://localhost:8080/redoc
|
||||
- **官方仓库**: https://github.com/open-webui/open-webui
|
||||
|
||||
## 贡献指南
|
||||
|
||||
1. Fork 项目
|
||||
2. 创建功能分支 (`git checkout -b feature/AmazingFeature`)
|
||||
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
|
||||
4. 推送到分支 (`git push origin feature/AmazingFeature`)
|
||||
5. 创建 Pull Request
|
||||
|
||||
---
|
||||
|
||||
## 快速参考
|
||||
|
||||
### 启动开发环境
|
||||
|
||||
```bash
|
||||
# 终端1: 启动后端
|
||||
cd backend
|
||||
source venv/bin/activate
|
||||
python -m uvicorn open_webui.main:app --reload --port 8080
|
||||
|
||||
# 终端2: 启动前端
|
||||
npm run dev:5050
|
||||
|
||||
# 浏览器访问
|
||||
# http://localhost:5050
|
||||
```
|
||||
|
||||
### 数据库操作
|
||||
|
||||
```bash
|
||||
# 查看迁移状态
|
||||
./scripts/check-status.sh
|
||||
|
||||
# 查看当前版本
|
||||
./scripts/migrate.sh current
|
||||
|
||||
# 连接数据库
|
||||
psql -U postgres -d openwebui_dev
|
||||
```
|
||||
|
||||
### 代码格式化
|
||||
|
||||
```bash
|
||||
# 前端
|
||||
npm run format
|
||||
|
||||
# 后端
|
||||
cd backend
|
||||
source venv/bin/activate
|
||||
black .
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**最后更新**: 2025-12-06
|
||||
**版本**: v2.0 (Node 22 + PostgreSQL)
|
||||
Loading…
Reference in a new issue