mirror of
https://github.com/open-webui/open-webui.git
synced 2025-12-14 05:15:18 +00:00
451 lines
10 KiB
Markdown
451 lines
10 KiB
Markdown
# Alembic 使用攻略 - Open WebUI
|
||
|
||
## 🚀 快速开始
|
||
|
||
### 当前项目配置
|
||
- **自动迁移**: 应用启动时自动执行 `alembic upgrade head`
|
||
- **位置**: `backend/open_webui/config.py:53-70`
|
||
- **结论**: 拉取代码后重启应用即可，无需手动执行迁移
|
||
|
||
### 工具脚本
|
||
```bash
|
||
./scripts/migrate.sh current # 查看当前版本
|
||
./scripts/migrate.sh upgrade # 手动升级
|
||
./scripts/check-status.sh # 检查数据库与代码一致性
|
||
```
|
||
|
||
---
|
||
|
||
## 📝 开发协作流程
|
||
|
||
### 场景1: 添加新表
|
||
|
||
```bash
|
||
# 1. 创建迁移脚本
|
||
cd backend/open_webui
|
||
python -m alembic revision -m "add_user_credits_table"
|
||
|
||
# 2. 编辑生成的文件 migrations/versions/xxxx_add_user_credits_table.py
|
||
```
|
||
|
||
```python
|
||
def upgrade():
|
||
op.create_table(
|
||
'user_credits',
|
||
sa.Column('id', sa.String(), nullable=False),
|
||
sa.Column('user_id', sa.String(), nullable=False),
|
||
sa.Column('credits', sa.NUMERIC(20, 6), server_default='0', nullable=False),
|
||
sa.Column('created_at', sa.BigInteger(), nullable=False),
|
||
sa.PrimaryKeyConstraint('id')
|
||
)
|
||
op.create_index('idx_user_credits_user_id', 'user_credits', ['user_id'])
|
||
|
||
def downgrade():
|
||
op.drop_index('idx_user_credits_user_id', 'user_credits')
|
||
op.drop_table('user_credits')
|
||
```
|
||
|
||
```bash
|
||
# 3. 测试迁移
|
||
source venv/bin/activate
|
||
cd open_webui
|
||
python -m alembic upgrade head # 升级
|
||
python -m alembic downgrade -1 # 降级测试
|
||
python -m alembic upgrade head # 重新升级
|
||
|
||
# 4. 验证
|
||
python -c "
|
||
from open_webui.internal.db import get_db
|
||
from sqlalchemy import inspect
|
||
with get_db() as db:
|
||
print(inspect(db.bind).get_table_names())
|
||
"
|
||
|
||
# 5. 提交
|
||
git add migrations/versions/xxxx_add_user_credits_table.py
|
||
git add open_webui/models/credits.py
|
||
git commit -m "feat: add user credits system"
|
||
git push
|
||
```
|
||
|
||
### 场景2: 修改现有表
|
||
|
||
```bash
|
||
# 1. 创建迁移
|
||
python -m alembic revision -m "add_email_verified_to_user"
|
||
|
||
# 2. 编辑迁移文件
|
||
```
|
||
|
||
```python
|
||
def upgrade():
|
||
# 添加字段
|
||
op.add_column('user', sa.Column('email_verified', sa.Boolean(),
|
||
server_default='false', nullable=False))
|
||
|
||
# 添加索引
|
||
op.create_index('idx_user_email_verified', 'user', ['email_verified'])
|
||
|
||
def downgrade():
|
||
op.drop_index('idx_user_email_verified', 'user')
|
||
op.drop_column('user', 'email_verified')
|
||
```
|
||
|
||
```bash
|
||
# 3. 测试并提交（同场景1步骤3-5）
|
||
```
|
||
|
||
### 场景3: 数据迁移
|
||
|
||
```python
|
||
from sqlalchemy import text
|
||
|
||
def upgrade():
|
||
connection = op.get_bind()
|
||
|
||
# 1. 添加新字段
|
||
op.add_column('user', sa.Column('full_name', sa.String(), nullable=True))
|
||
|
||
# 2. 迁移数据
|
||
connection.execute(text("""
|
||
UPDATE user
|
||
SET full_name = name
|
||
WHERE full_name IS NULL
|
||
"""))
|
||
|
||
# 3. 设置为NOT NULL
|
||
op.alter_column('user', 'full_name', nullable=False)
|
||
|
||
def downgrade():
|
||
op.drop_column('user', 'full_name')
|
||
```
|
||
|
||
### 场景4: 多人协作冲突
|
||
|
||
**问题**: 两个分支同时创建迁移，产生多个head
|
||
|
||
```bash
|
||
# 1. 发现问题
|
||
python -m alembic heads
|
||
# 输出: abc123 (head), def456 (head) ← 两个头部
|
||
|
||
# 2. 合并迁移
|
||
python -m alembic merge -m "merge_feature_branches" heads
|
||
|
||
# 3. 编辑生成的合并迁移
|
||
# migrations/versions/xxx_merge_feature_branches.py
|
||
# down_revision = ('abc123', 'def456') # 已自动填充
|
||
|
||
# 4. 应用合并
|
||
python -m alembic upgrade head
|
||
|
||
# 5. 提交
|
||
git add migrations/versions/xxx_merge_feature_branches.py
|
||
git commit -m "chore: merge migration branches"
|
||
```
|
||
|
||
---
|
||
|
||
## 🏭 生产环境迁移
|
||
|
||
### 方式1: 自动迁移（推荐）
|
||
|
||
```bash
|
||
# Docker 环境
|
||
git pull
|
||
docker-compose restart
|
||
# ✅ 应用启动时自动执行迁移
|
||
|
||
# Systemd 环境
|
||
git pull
|
||
systemctl restart open-webui
|
||
# ✅ 应用启动时自动执行迁移
|
||
|
||
# 验证
|
||
./scripts/check-status.sh
|
||
```
|
||
|
||
**优点**: 零停机、自动化、幂等性
|
||
**适用**: 小型迁移、添加字段、创建索引
|
||
|
||
### 方式2: 手动迁移（安全）
|
||
|
||
```bash
|
||
# 1. 备份数据库（PostgreSQL）
|
||
pg_dump -U user -d openwebui_prod > backup_$(date +%Y%m%d_%H%M%S).sql
|
||
|
||
# 2. 记录当前版本
|
||
cd backend/open_webui
|
||
python -m alembic current > migration_before.txt
|
||
|
||
# 3. 拉取代码
|
||
git pull
|
||
|
||
# 4. 查看待执行的迁移
|
||
python -m alembic history | grep -A5 "$(cat migration_before.txt | awk '{print $1}')"
|
||
|
||
# 5. 手动执行迁移
|
||
python -m alembic upgrade head
|
||
|
||
# 6. 验证
|
||
python -m alembic current > migration_after.txt
|
||
diff migration_before.txt migration_after.txt
|
||
|
||
# 7. 重启应用
|
||
systemctl restart open-webui
|
||
|
||
# 8. 功能验证
|
||
curl http://localhost:8080/health
|
||
```
|
||
|
||
**优点**: 可控、可验证、可回滚
|
||
**适用**: 大型迁移、数据迁移、高风险变更
|
||
|
||
### 方式3: 蓝绿部署（零停机）
|
||
|
||
```bash
|
||
# 1. 部署新版本到绿环境（不启动）
|
||
git clone /app/open-webui /app/open-webui-green
|
||
cd /app/open-webui-green
|
||
git pull
|
||
|
||
# 2. 在绿环境执行迁移
|
||
cd backend/open_webui
|
||
python -m alembic upgrade head
|
||
|
||
# 3. 启动绿环境（连接同一数据库）
|
||
systemctl start open-webui-green
|
||
|
||
# 4. 切换流量（Nginx/负载均衡）
|
||
# 从 localhost:8080 → localhost:8081
|
||
|
||
# 5. 停止蓝环境
|
||
systemctl stop open-webui
|
||
|
||
# 6. 验证后删除蓝环境
|
||
rm -rf /app/open-webui
|
||
mv /app/open-webui-green /app/open-webui
|
||
```
|
||
|
||
---
|
||
|
||
## 🔧 常用命令速查
|
||
|
||
### 查看状态
|
||
```bash
|
||
python -m alembic current # 当前版本
|
||
python -m alembic heads # 最新版本
|
||
python -m alembic history # 历史记录
|
||
python -m alembic branches # 分支情况
|
||
```
|
||
|
||
### 执行迁移
|
||
```bash
|
||
python -m alembic upgrade head # 升级到最新
|
||
python -m alembic upgrade +1 # 升级1个版本
|
||
python -m alembic upgrade abc123 # 升级到指定版本
|
||
python -m alembic downgrade -1 # 降级1个版本
|
||
python -m alembic downgrade abc123 # 降级到指定版本
|
||
```
|
||
|
||
### 创建迁移
|
||
```bash
|
||
python -m alembic revision -m "description" # 创建空迁移
|
||
python -m alembic merge -m "merge branches" heads # 合并分支
|
||
```
|
||
|
||
---
|
||
|
||
## ⚠️ 注意事项
|
||
|
||
### 1. 禁止使用 autogenerate
|
||
```bash
|
||
# ❌ 不要用（循环依赖问题）
|
||
python -m alembic revision --autogenerate -m "auto"
|
||
|
||
# ✅ 手动编写
|
||
python -m alembic revision -m "add_feature"
|
||
# 然后手动编写 upgrade/downgrade 函数
|
||
```
|
||
|
||
### 2. 数据库类型（PostgreSQL）
|
||
|
||
```python
|
||
# 使用 PostgreSQL 特定类型
|
||
from sqlalchemy.dialects import postgresql
|
||
|
||
def upgrade():
|
||
op.add_column('user',
|
||
sa.Column('balance', postgresql.NUMERIC(20, 6),
|
||
server_default='0', nullable=False))
|
||
```
|
||
|
||
### 3. 大表索引创建
|
||
|
||
```python
|
||
# PostgreSQL - 在线创建索引
|
||
op.create_index(
|
||
'idx_large_table_field',
|
||
'large_table',
|
||
['field'],
|
||
postgresql_concurrently=True # 不锁表
|
||
)
|
||
|
||
# 注意: CONCURRENTLY 需要在事务外执行
|
||
# 在迁移文件顶部添加:
|
||
# revision = 'xxx'
|
||
# down_revision = 'yyy'
|
||
# branch_labels = None
|
||
# depends_on = None
|
||
#
|
||
# # 禁用事务
|
||
# def upgrade():
|
||
# op.execute('COMMIT')
|
||
# ...
|
||
```
|
||
|
||
### 4. 必须编写 downgrade
|
||
|
||
```python
|
||
# ❌ 错误
|
||
def downgrade():
|
||
pass
|
||
|
||
# ✅ 正确
|
||
def downgrade():
|
||
op.drop_index('idx_user_balance')
|
||
op.drop_column('user', 'balance')
|
||
```
|
||
|
||
---
|
||
|
||
## 🚨 故障处理
|
||
|
||
### 迁移失败恢复
|
||
|
||
```bash
|
||
# 1. 查看当前状态
|
||
python -m alembic current
|
||
|
||
# 2. 检查数据库是否处于中间状态
|
||
psql -U user -d dbname
|
||
\dt # 查看表
|
||
# 手动删除失败迁移创建的表/字段
|
||
|
||
# 3. 标记为指定版本（谨慎使用）
|
||
python -m alembic stamp <version_id>
|
||
|
||
# 4. 重新执行
|
||
python -m alembic upgrade head
|
||
```
|
||
|
||
### 回滚到指定版本
|
||
|
||
```bash
|
||
# 1. 查看历史
|
||
python -m alembic history
|
||
|
||
# 2. 回滚
|
||
python -m alembic downgrade <version_id>
|
||
|
||
# 3. 重启应用
|
||
systemctl restart open-webui
|
||
```
|
||
|
||
### 强制重新初始化（危险）
|
||
|
||
```bash
|
||
# ⚠️ 会丢失所有数据
|
||
# 1. 删除 alembic_version 表
|
||
psql -U user -d dbname -c "DROP TABLE alembic_version;"
|
||
|
||
# 2. 删除所有业务表
|
||
psql -U user -d dbname -c "DROP SCHEMA public CASCADE; CREATE SCHEMA public;"
|
||
|
||
# 3. 重新执行所有迁移
|
||
python -m alembic upgrade head
|
||
```
|
||
|
||
---
|
||
|
||
## ✅ 最佳实践检查清单
|
||
|
||
### 开发阶段
|
||
- [ ] 修改模型后立即创建迁移脚本
|
||
- [ ] 迁移脚本命名清晰（描述变更内容）
|
||
- [ ] 编写完整的 upgrade 和 downgrade 函数
|
||
- [ ] 使用 PostgreSQL 特定类型（NUMERIC, JSONB 等）
|
||
- [ ] 测试升级和降级流程
|
||
- [ ] Code Review 检查迁移逻辑
|
||
- [ ] 提交迁移脚本到 Git
|
||
|
||
### 部署阶段
|
||
- [ ] 备份生产数据库
|
||
- [ ] 记录当前迁移版本
|
||
- [ ] 查看待执行的迁移内容
|
||
- [ ] 评估迁移风险（大表、数据迁移）
|
||
- [ ] 选择合适的迁移方式（自动/手动）
|
||
- [ ] 执行迁移
|
||
- [ ] 验证迁移版本
|
||
- [ ] 重启应用
|
||
- [ ] 功能验证
|
||
- [ ] 监控应用日志
|
||
|
||
---
|
||
|
||
## 📊 迁移决策树
|
||
|
||
```
|
||
新功能需要数据库变更
|
||
↓
|
||
修改 models/*.py
|
||
↓
|
||
创建迁移脚本 (alembic revision -m "xxx")
|
||
↓
|
||
编写 upgrade/downgrade 函数
|
||
↓
|
||
┌─────────────────────────────┐
|
||
│ 影响是否 > 1000万行数据？ │
|
||
└─────────┬───────────────────┘
|
||
│
|
||
┌─────┴─────┐
|
||
NO YES
|
||
│ │
|
||
│ 使用分批迁移/在线DDL
|
||
↓ ↓
|
||
测试升降级 准备回滚方案
|
||
│ │
|
||
└─────┬─────┘
|
||
↓
|
||
提交代码 (git commit)
|
||
↓
|
||
┌───────────┐
|
||
│ 生产部署 │
|
||
└─────┬─────┘
|
||
│
|
||
┌─────┴─────┐
|
||
风险评估
|
||
│
|
||
┌───┴───┐
|
||
低 高
|
||
│ │
|
||
│ 手动迁移
|
||
│ + 备份
|
||
自动 + 蓝绿
|
||
迁移
|
||
```
|
||
|
||
---
|
||
|
||
## 📚 参考资源
|
||
|
||
- **项目文档**: `docs/DATABASE_CONSISTENCY_GUIDE.md` - 完整指南
|
||
- **迁移工具**: `scripts/migrate.sh` - 便捷脚本
|
||
- **状态检查**: `scripts/check-status.sh` - 一致性验证
|
||
- **Alembic 官方文档**: https://alembic.sqlalchemy.org/
|
||
|
||
---
|
||
|
||
**版本**: v1.0
|
||
**更新**: 2025-12-06
|
||
**适用**: Open WebUI Next
|