跳到主要内容

数据库迁移

概览​

OPL 数据空间 启动时通常会自动执行数据库迁移。大多数情况下不需要手动迁移。只有在升级失败、离线维护或数据库类型切换等特殊场景下，才应该人工运行 Alembic。

注意

如果你的部署启用了 组织，数据库 schema 升级成功不代表租户数据已经完全安全可用。升级后还可能需要额外核对 landing organization、文件归属同步和向量归属修复。

危险

手动迁移操作不当会直接损坏数据库。开始前必须先做可验证的备份。

什么时候才需要手动迁移​

  • 启动日志里明确出现 migration 错误
  • 版本升级后自动迁移失败
  • 你在做离线数据库维护
  • 你在做 SQLite ↔ PostgreSQL 迁移
  • 开发者明确要求你手动执行 Alembic

前置检查​

  • 已确认数据库位置
  • OPL 数据空间 进程已经完全停止
  • 已创建并验证备份
  • 可以进入容器或本地 Python 运行环境

第一步：备份并验证​

SQLite​

cp /path/to/webui.db /path/to/webui.db.backup.$(date +%Y%m%d_%H%M%S)
sqlite3 /path/to/webui.db.backup "SELECT count(*) FROM user;"

PostgreSQL​

pg_dump -h localhost -U your_user -d open_webui_db > backup_$(date +%Y%m%d_%H%M%S).sql
head -n 20 backup_*.sql

第二步：进入运行环境​

Docker​

docker stop open-webui
docker run --rm -it \
  -v open-webui:/app/backend/data \
  --entrypoint /bin/bash \
  ghcr.io/open-webui/open-webui:main
cd /app/backend/open_webui

本地安装​

cd /path/to/open-webui/backend/open_webui
source ../../venv/bin/activate

第三步：设置必须的环境变量​

export DATABASE_URL="sqlite:////app/backend/data/webui.db"
export WEBUI_SECRET_KEY=$(cat /app/backend/.webui_secret_key)

如果是 PostgreSQL，把 DATABASE_URL 改成对应的连接串即可。

危险

DATABASE_URL 和 WEBUI_SECRET_KEY 缺一不可。少了 WEBUI_SECRET_KEY，Alembic 在真正连库前就会失败。

第四步：先做只读诊断​

alembic current -v
alembic heads
alembic history
alembic upgrade head --sql | head -30
alembic branches

你要先确认：

  • 当前数据库认为自己在哪个 migration
  • 代码期望的 head 是什么
  • 是否存在分叉、半迁移状态或明显不一致

第五步：执行迁移​

标准升级：

alembic upgrade head

常见错误：

  • No such table：说明该跑的迁移没跑到
  • Table already exists：通常是之前部分迁移已经落地，但 Alembic 版本记录没同步
  • 多条错误串联出现：往往是跨多个版本升级时进入了半迁移状态，需要逐步修复

操作建议​

  • 先看清楚 current 和 heads 再动手
  • 不要在多个副本同时跑迁移
  • 多副本环境里，升级前先缩到一个实例最稳
  • schema 迁移完成后，如果有组织化数据，再继续检查 ownership / repair 状态

相关文档​