opwen-webui 数据搬迁

背景：一次从 SQLite 到 PostgreSQL 的 Open WebUI 搬迁

Open WebUI 默认用的是 SQLite，部署起来很省心。但当你开始把它跑在更“正式”的环境里（多用户、长期保留聊天记录、附件和标签等），SQLite 往往就会成为瓶颈：备份、迁移、并发、运维手段都不如 PostgreSQL 顺手。

这篇文章记录我把一套旧版 Open WebUI（SQLite）迁移到新版 Open WebUI v0.8.11（PostgreSQL 16）的完整过程。核心目标很明确：

• 保留多用户登录信息
• 保留历史聊天、消息、标签、文件等业务数据
• 新环境使用 Docker Compose，数据库切到 PostgreSQL

需要先说清楚一个“坑”：官方文档明确提到，仅修改 DATABASE_URL 并不会自动把 SQLite 数据迁到 PostgreSQL，跨数据库类型迁移需要手工处理。参考：

• Env 配置： https://docs.openwebui.com/reference/env-configuration/
• 手工迁移： https://docs.openwebui.com/troubleshooting/manual-database-migration/

适用/不适用场景

适用：

• 旧环境用默认 SQLite
• 新环境已改用 PostgreSQL
• 希望原样保留用户与历史数据

不适用：

• 期待“只改 DATABASE_URL 就自动迁移”
• 需要把两套数据库做复杂数据合并

目标环境（Docker Compose）

我在新环境使用的 docker-compose.yml 大致如下（删掉了与迁移无关的配置）：

• PostgreSQL 16，数据目录映射到宿主机
• Open WebUI v0.8.11，挂载 /app/backend/data
• DATABASE_URL 指向 PostgreSQL

services:
  postgres:
    image: postgres:16
    container_name: open-webui-db
    restart: unless-stopped
    environment:
      - POSTGRES_USER=openwebui
      - POSTGRES_PASSWORD=changeme_please
      - POSTGRES_DB=openwebui
    volumes:
      - ./data/postgres:/var/lib/postgresql/data

  open-webui:
    image: ghcr.io/open-webui/open-webui:v0.8.11
    container_name: open-webui
    restart: unless-stopped
    ports:
      - "3000:8080"
    volumes:
      - ./data/open-webui:/app/backend/data
    environment:
      - WEBUI_AUTH=true
      - DATABASE_URL=postgresql://openwebui:changeme_please@postgres:5432/openwebui

迁移前：三件事先确认清楚

1）旧备份确实是 SQLite

最简单的方式是读一下 SQLite 文件头：

python - <<'PY'
with open("webui.db.backup", "rb") as f:
    print(f.read(16))
PY

如果看到 SQLite format 3，那就没错。

也可以直接查询 Alembic 版本号：

sqlite3 /path/to/webui.db "select version_num from alembic_version;"

2）旧库健康度 OK

我会在迁移前跑一次完整性检查 + 统计关键表的数据量：

sqlite3 ~/open-webui/migration/sqlite-data/webui.db "PRAGMA integrity_check;"
sqlite3 ~/open-webui/migration/sqlite-data/webui.db "select version_num from alembic_version;"
sqlite3 ~/open-webui/migration/sqlite-data/webui.db "select 'user',count(*) from user union all select 'auth',count(*) from auth union all select 'chat',count(*) from chat union all select 'file',count(*) from file;"

我这次的结果：

• integrity_check = ok
• 旧库 Alembic 版本：c440947495f3
• 数据量：
  • user = 10
  • auth = 10
  • chat = 672
  • file = 25

3）新 PostgreSQL 已被目标版本初始化

这一步非常关键，因为它决定“能不能直接导入”。

docker compose ps
docker compose logs open-webui --tail=200
docker exec -it open-webui-db psql -U openwebui -d openwebui -c "\\dt"
docker exec -it open-webui-db psql -U openwebui -d openwebui -c "select * from alembic_version;"

我这次看到：

• 新库 Alembic 版本：b2c3d4e5f6a7
• 新库表数：35
• 相比旧库新增了关键表：access_grant、chat_message、prompt_history、skill

这说明：不能把旧 SQLite “整库无脑导入”到 PostgreSQL；你必须先把旧库的 schema 升到与目标版本一致。

总体路线：先升 SQLite schema，再导入 PostgreSQL

我最终验证过稳定可复用的路线是：

1. 先把旧 SQLite 升级到目标 Open WebUI 版本的 schema
2. 再把升级后的 SQLite 数据导入 PostgreSQL
3. 如果 chat 表导入失败，单独修复 chat
4. 清理孤儿附件记录，并补回外键

下面按步骤展开。

Step 1：把旧 SQLite 升级到 v0.8.11 的 schema

先做一份“原始旧库”的冷备份：

cp migration/sqlite-data/webui.db migration/sqlite-data/webui.db.pre_v0811_backup

然后我启动一个临时容器，让 Open WebUI v0.8.11 直接挂载旧 SQLite，并自动执行 Alembic 迁移：

docker rm -f open-webui-sqlite-migrator 2>/dev/null || true
docker run -d \\
  --name open-webui-sqlite-migrator \\
  -v ~/open-webui/migration/sqlite-data:/app/backend/data \\
  -e WEBUI_AUTH=true \\
  ghcr.io/open-webui/open-webui:v0.8.11

观察日志：

docker logs -f --tail=200 open-webui-sqlite-migrator

我这次的升级链路里，关键迁移包括：

• c440947495f3 -> 374d2f66af06 Add prompt history table
• 374d2f66af06 -> 8452d01d26d7 Add chat_message table
• 8452d01d26d7 -> f1e2d3c4b5a6 Add access_grant table
• f1e2d3c4b5a6 -> a1b2c3d4e5f6 Add skill table
• a1b2c3d4e5f6 -> b2c3d4e5f6a7 add scim column to user table

迁移完成后，确认 SQLite 已到目标版本：

sqlite3 ~/open-webui/migration/sqlite-data/webui.db "select version_num from alembic_version;"
sqlite3 ~/open-webui/migration/sqlite-data/webui.db "select name from sqlite_master where type='table' order by name;"

预期：

• alembic_version = b2c3d4e5f6a7
• 新表（如 chat_message 等）已出现

Step 2：导入 PostgreSQL（pgloader）

2.1 先停服务 + 备份 PostgreSQL

导入前，我会先停掉正式 Open WebUI，避免写入冲突；同时给 PostgreSQL 做一份 dump，方便随时回滚：

docker compose stop open-webui
docker exec -t open-webui-db pg_dump -U openwebui -d openwebui -Fc > migration/pg-backup/openwebui_before_import_$(date +%Y%m%d_%H%M%S).dump

2.2 准备 pgloader 任务文件

我用的 sqlite_to_pg.load 如下（重点是 data-only + truncate + 不创建表）：

LOAD DATABASE
     FROM sqlite:///mnt/sqlite/webui.db
     INTO postgresql://openwebui:changeme_please@localhost:5432/openwebui

 WITH include no drop,
      create no tables,
      create no indexes,
      truncate,
      data only,
      reset sequences,
      workers = 1,
      concurrency = 1

 SET work_mem to '16MB',
     maintenance_work_mem to '128MB';

执行导入：

docker run --rm \\
  --name pgloader-openwebui \\
  --network container:open-webui-db \\
  -v ~/open-webui/migration/sqlite-data:/mnt/sqlite \\
  -v ~/open-webui/migration:/work \\
  dimitri/pgloader:latest \\
  pgloader /work/sqlite_to_pg.load

踩坑：chat 表导入失败（以及怎么补救）

我这次 pgloader 直接导入时，chat 表报错：

invalid input syntax for type bigint: "1764129103-01-01"
COPY chat, line 1, column created_at

我对这个问题的理解是：

• 旧 SQLite 的 chat.created_at / chat.updated_at 和新 PostgreSQL 的字段类型不完全一致
• pgloader 在推断类型时把原始整数时间戳误判成了日期字符串
• 结果导致 chat 无法插入

直接后果：

• chat = 0
• chat_file 外键恢复失败
• chat_message 外键恢复失败

修复策略：不要重来，单独重导 chat

我的做法是把 chat 拆出来单独处理：

1. 从 SQLite 单独导出 chat
2. 强制把 created_at / updated_at 转成整数时间戳
3. 用 CSV 导入 PostgreSQL 的中转表
4. 再插入正式 chat 表
5. 最后恢复外键

我当时用的脚本（路径按我本机环境记录）：

• run_sqlite_to_postgres.sh
• fix_chat_import.sh

修复后统计：

• chat = 672
• chat_message = 5854

踩坑：chat_file 有孤儿记录

恢复 chat_file 外键时，我遇到：

insert or update on table "chat_file" violates foreign key constraint "chat_file_chat_id_fkey"

原因是 chat_file 存在若干条记录引用了不存在的 chat_id。

我选择直接清理孤儿记录，再补回外键：

docker exec -it open-webui-db psql -U openwebui -d openwebui -c "delete from chat_file cf where not exists (select 1 from chat c where c.id=cf.chat_id);"
docker exec -it open-webui-db psql -U openwebui -d openwebui -c "alter table chat_file add constraint chat_file_chat_id_fkey foreign key (chat_id) references chat(id) on delete cascade;"

这次实际删除了 8 条孤儿记录（DELETE 8）。

最终两个关键外键都能正常存在：

• chat_file_chat_id_fkey
• chat_message_chat_id_fkey

最终验收：至少做这两类检查

1）核心业务表计数

docker exec -it open-webui-db psql -U openwebui -d openwebui -c "select 'user',count(*) from \\"user\\" union all select 'auth',count(*) from auth union all select 'chat',count(*) from chat union all select 'chat_message',count(*) from chat_message union all select 'file',count(*) from file;"

我最终的结果：

• user = 10
• auth = 10
• chat = 672
• chat_message = 5854
• file = 25

2）外键约束是否在位

docker exec -it open-webui-db psql -U openwebui -d openwebui -c "select conname, conrelid::regclass as table_name from pg_constraint where conname in ('chat_file_chat_id_fkey','chat_message_chat_id_fkey') order by conname;"

预期能看到：

• chat_file_chat_id_fkey
• chat_message_chat_id_fkey

3）应用启动与抽样验证

docker compose up -d open-webui
docker compose logs open-webui --tail=100

然后在 Web UI 做抽样：

• 随机用户登录
• 管理员账号登录
• 历史聊天可正常打开
• 标签和附件可见
• 新建聊天正常

备份建议（强烈建议保留至少 1 周）

• 原始旧库：migration/sqlite-data/webui.db.pre_v0811_backup
• 升级后的中间库：migration/sqlite-data/webui.db
• 导入前 PostgreSQL 备份：migration/pg-backup/*.dump

总结

把旧版 Open WebUI 的 SQLite 迁到新版 PostgreSQL 是完全可行的，但关键不是“直接改连接串”，而是：

• 先用目标版本把旧 SQLite schema 升到一致
• 再用 pgloader 做 data-only 导入
• 对 chat 这种容易被类型推断坑到的表，做好单表补救方案
• 导入后一定要做外键与业务抽样验收

如果你遇到类似的 chat.created_at 导入报错，建议优先考虑“单表重导 + 强制类型”而不是推倒重来。