Open WebUI数据库从SQLite迁移到PostgreSQL的步骤与验证方法

Open WebUI的数据库从SQLite换到PostgreSQL，核心不在文件复制，而在于改启动参数和数据搬运。Open WebUI使用SQLAlchemy作为数据库层，切换数据库本质上是修改 DATABASE_URL 环境变量，让服务连上新的数据库；但SQLite里已存在的用户、会话、消息等存量数据，需要通过工具或脚本搬过去。下面给出迁移路径和验证方法，执行前需要先明确当前Open WebUI的启动方式和原SQLite文件的位置。

迁移可行，通常分三步：准备PostgreSQL、迁移表与数据、切换连接串。建议先用pgloader整体搬迁，再启动Open WebUI验证，最后保留原SQLite文件以便回滚。迁移后需检查关键表行数和登录/对话功能，不能只看服务是否启动。

迁移前先确认连接方式

Open WebUI在启动时通过环境变量 DATABASE_URL 决定数据库连接。默认没设置时会用本地SQLite文件。要迁移到PostgreSQL，需要先把连接串改成PostgreSQL格式，并确保目标库可用。连接串一般形如：postgresql://user:password@host:5432/dbname。建议为Open WebUI单独建库和账号，避免和其他应用共用。

-- 在PostgreSQL服务器上执行，或者用psql连接后执行
CREATE USER openwebui WITH PASSWORD 'your_password';
CREATE DATABASE openwebui OWNER openwebui;
GRANT ALL PRIVILEGES ON DATABASE openwebui TO openwebui;

执行后可以用 psql -U openwebui -h 127.0.0.1 -d openwebui -c "SELECT 1;" 验证连接是否正常。

两种可行的数据迁移路径

第一种是使用 pgloader 工具直接转换。pgloader可以从SQLite读取表结构和数据，写入PostgreSQL。先安装pgloader，然后执行：

pgloader sqlite:///path/to/webui.db postgresql://openwebui:your_password@127.0.0.1/openwebui

路径中的 webui.db 是Open WebUI原有的SQLite文件。执行前先确认PostgreSQL里没有同名表，避免覆盖冲突。如果导入过程中遇到类型转换错误，可以检查原SQLite中是否有异常字段，再决定手动修正还是改用脚本迁移。

第二种是写临时Python脚本，用SQLAlchemy同时连接两个数据库，按表复制。这种方式更适合要控制字段映射或部分迁移的场景。核心动作是先读取SQLite的表定义，再在PostgreSQL里建同名表，然后逐表SELECT再INSERT。由于Open WebUI本身也使用SQLAlchemy，这个脚本可以沿用模型定义，但要注意不要让脚本和目标服务同时操作同一张表，以免锁冲突。

Open WebUI数据库从SQLite迁移到PostgreSQL的步骤与验证方法

如果你之前已经用PostgreSQL启动过Open WebUI，可能表已经建好了，那么pgloader导入时可能会遇到“表已存在”的报错。这种情况下可以先备份目标库，然后清空表结构再重新导入，或者临时把数据库指向一个空库。

启动配置与后续切换

数据迁移完成后，Open WebUI的启动命令要显式带上 DATABASE_URL。例如Docker方式：

docker run -d -p 3000:8080 -e DATABASE_URL="postgresql://openwebui:your_password@127.0.0.1:5432/openwebui" -v open-webui:/data ghcr.io/open-webui/open-webui:main

如果你用docker-compose，就把它写进services下的environment里。改完连接串后第一次启动，Open WebUI会自动检查PostgreSQL中的表结构，缺失的表会自动创建。但如果迁移时只导入了数据而没有保留列名，可能启动后查询数据报错。稳妥的做法是：先让一个空的PostgreSQL库跑一次Open WebUI初始化，再对空表导入SQLite数据，或者直接用带完整schema的pgloader迁移结果。

验证迁移是否完成

验证的目标是确认数据没丢、功能可用。可以分三层：

连接层：服务启动日志里没有连接PostgreSQL报错，页面能正常打开。
数据层：对比关键表的行数。Open WebUI中常见的是 user、chat、message 等表。分别查询SQLite旧库和PostgreSQL新库中的行数，应一致。

-- PostgreSQL中查询
SELECT count(*) FROM "user";
SELECT count(*) FROM chat;
SELECT count(*) FROM message;

功能层：用已有账号登录，能看到历史会话；新建一条对话并发送消息，刷新后仍在。如果这两项都正常，基本可以认为迁移成功。

不要把“服务能启动”当作迁移完成的标准。最直接的信号是历史会话是否原样出现、新写数据是否落库。