feat:补充Alembic指南

docs/ALEMBIC_GUIDE.md

@@ -0,0 +1,451 @@
+# 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