Skip to main content

手动 Alembic 数据库迁移

概述​

Open WebUI 在启动时会自动运行数据库迁移。手动迁移极少被需要，仅应在特定的失败场景或维护情况下执行。

何时需要手动迁移

仅在以下情况下您才需要手动迁移：

  • Open WebUI 日志显示启动过程中出现了特定的迁移错误
  • 您正在进行离线数据库维护
  • 版本升级后自动迁移失败
  • 您正在进行数据库类型之间的迁移（SQLite ↔ PostgreSQL）
  • 开发人员指示您手动运行迁移
关键警告

如果执行不当，手动迁移可能会损坏您的数据库。在继续之前，请务必创建经过验证的备份。

前提条件清单​

在开始之前，请确保您拥有：

  • 对 Open WebUI 安装目录的 Root/管理员权限
  • 确认数据库位置（Docker 中的默认位置：/app/backend/data/webui.db）
  • 完全停止 Open WebUI（无正在运行的进程）
  • 已创建并验证备份（见下文）
  • 进入容器或 Python 环境（即运行 Open WebUI 的环境）
首先停止所有进程

在 Open WebUI 处于活动状态时无法运行数据库迁移。在尝试手动迁移之前，您 必须 停止所有 Open WebUI 进程。

第 1 步：创建并验证备份​

备份您的数据库​

终端
# 首先找到您的数据库位置
docker inspect open-webui | grep -A 5 Mounts

# 创建带时间戳的备份
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;"

# 验证架构 (Schema) 是否匹配
sqlite3 /path/to/webui.db ".schema" > current-schema.sql
sqlite3 /path/to/webui.db.backup ".schema" > backup-schema.sql
diff current-schema.sql backup-schema.sql
备份存储

将备份存储在与数据库 不同的磁盘或卷 上，以防止磁盘故障。

第 2 步：诊断当前状态​

在尝试任何修复之前，请收集有关数据库状态的信息。

进入您的环境​

终端
docker exec -it open-webui bash