SQLite 数据库概览

warning

本教程为社区贡献，不属于 Open WebUI 官方团队的支持范围。它仅作为如何针对特定用例自定义 Open WebUI 的演示。想要贡献？请查看贡献教程。

[!WARNING] 本文档是基于 0.6.42 版本创建/更新的，并针对最近的迁移进行了更新。

Open-WebUI 内部 SQLite 数据库

对于 Open-WebUI，SQLite 数据库是用户管理、聊天记录、文件存储以及各种其他核心功能的基石。理解这个结构对于任何想要有效贡献或维护该项目的人来说都是必不可少的。

内部 SQLite 位置

您可以在 root -> data -> webui.db 找到 SQLite 数据库。

📁 Root (/)
├── 📁 data
│   ├── 📁 cache
│   ├── 📁 uploads
│   ├── 📁 vector_db
│   └── 📄 webui.db
├── 📄 dev.sh
├── 📁 open_webui
├── 📄 requirements.txt
├── 📄 start.sh
└── 📄 start_windows.bat

在本地复制数据库

如果您想将容器中运行的 Open-WebUI SQLite 数据库复制到本地机器，可以使用：

docker cp open-webui:/app/backend/data/webui.db ./webui.db

或者，您可以使用以下命令进入容器内部访问数据库：

docker exec -it open-webui /bin/sh

数据表概览

以下是 Open-WebUI SQLite 数据库中完整的数据表列表。表格按字母顺序排列并编号，以便查阅。

编号	表名	描述
01	auth	存储用户身份验证凭据和登录信息
02	channel	管理聊天频道及其配置
03	channel_file	将文件链接到频道和消息
04	channel_member	跟踪频道内的用户成员身份和权限
05	chat	存储聊天会话及其元数据
06	chat_file	将文件链接到聊天和消息
07	chatidtag	映射聊天与其关联标签之间的关系
08	config	维护系统范围的配置设置
09	document	存储用于知识管理的文档及其元数据
10	feedback	捕获用户反馈和评分
11	file	管理上传的文件及其元数据
12	folder	将文件和内容组织成层级结构
13	function	存储自定义函数及其配置
14	group	管理用户组及其权限
15	group_member	跟踪组内的用户成员身份
16	knowledge	存储知识库条目和相关信息
17	knowledge_file	将文件链接到知识库
18	memory	维护聊天历史和上下文记忆
19	message	存储单个聊天消息及其内容
20	message_reaction	记录用户对消息的反应（表情符号/回应）
21	migrate_history	跟踪数据库模式版本和迁移记录
22	model	管理 AI 模型配置和设置
23	note	存储用户创建的笔记和注释
24	oauth_session	管理用户的活动 OAuth 会话
25	prompt	存储 AI 提示词的模板和配置
26	tag	管理用于内容分类的标签/标记
27	tool	存储系统工具和集成的配置
28	user	维护用户个人资料和账户信息

注意：Open-WebUI 的 SQLite 数据库中还有两个与核心功能无关的表，已排除在外：

• Alembic Version 表 (Alembic Version table)
• 迁移历史表 (Migrate History table)

现在我们已经列出了所有表格，让我们来了解每个表的结构。

Auth 表 (Auth Table)

列名	数据类型	约束	描述
id	String	PRIMARY KEY	唯一标识符
email	String	-	用户邮箱
password	Text	-	哈希后的密码
active	Boolean	-	账户状态

关于 auth 表需要了解的事项：

• 使用 UUID 作为主键
• 与 users 表有一对一关系（共享 id）

频道表 (Channel Table)

列名	数据类型	约束	描述
id	Text	PRIMARY KEY	唯一标识符 (UUID)
user_id	Text	-	频道所有者/创建者
type	Text	nullable	频道类型
name	Text	-	频道名称
description	Text	nullable	频道描述
data	JSON	nullable	灵活的数据存储
meta	JSON	nullable	频道元数据
access_control	JSON	nullable	权限设置
created_at	BigInteger	-	创建时间戳（纳秒）
updated_at	BigInteger	-	最后更新时间戳（纳秒）

关于 auth 表需要了解的事项：

• 使用 UUID 作为主键
• 频道名称不区分大小写（以小写形式存储）

频道成员表 (Channel Member Table)

列名	数据类型	约束	描述
id	TEXT	NOT NULL	频道成员身份的唯一标识符
channel_id	TEXT	NOT NULL	关联的频道 ID
user_id	TEXT	NOT NULL	关联的用户 ID
created_at	BIGINT	-	成员身份创建的时间戳

频道文件表 (Channel File Table)

列名	数据类型	约束	描述
id	Text	PRIMARY KEY	唯一标识符 (UUID)
user_id	Text	NOT NULL	关系的所有者
channel_id	Text	FOREIGN KEY(channel.id), NOT NULL	关联的频道 ID
file_id	Text	FOREIGN KEY(file.id), NOT NULL	关联的文件 ID
message_id	Text	FOREIGN KEY(message.id), nullable	关联的消息 ID
created_at	BigInteger	NOT NULL	创建时间戳
updated_at	BigInteger	NOT NULL	最后更新时间戳

关于 channel_file 表需要了解的事项：

• 在 (channel_id, file_id) 上有唯一约束，防止重复条目
• 具有 CASCADE 删除的外键关系
• 在 channel_id、file_id 和 user_id 上建立了索引以提高性能

聊天表 (Chat Table)

列名	数据类型	约束	描述
id	String	PRIMARY KEY	唯一标识符 (UUID)
user_id	String	-	聊天的所有者
title	Text	-	聊天标题
chat	JSON	-	聊天内容和历史记录
created_at	BigInteger	-	创建时间戳
updated_at	BigInteger	-	最后更新时间戳
share_id	Text	UNIQUE, nullable	分享标识符
archived	Boolean	default=False	归档状态
pinned	Boolean	default=False, nullable	置顶状态
meta	JSON	server_default=""	包含标签的元数据
folder_id	Text	nullable	父文件夹 ID

聊天文件表 (Chat File Table)

列名	数据类型	约束	描述
id	Text	PRIMARY KEY	唯一标识符 (UUID)
user_id	Text	NOT NULL	与文件关联的用户
chat_id	Text	FOREIGN KEY(chat.id), NOT NULL	关联的聊天 ID
file_id	Text	FOREIGN KEY(file.id), NOT NULL	关联的文件 ID
message_id	Text	nullable	关联的消息 ID
created_at	BigInteger	NOT NULL	创建时间戳
updated_at	BigInteger	NOT NULL	最后更新时间戳

关于 chat_file 表需要了解的事项：

• 在 (chat_id, file_id) 上有唯一约束，防止重复条目
• 具有 CASCADE 删除的外键关系
• 在 chat_id、file_id、message_id 和 user_id 上建立了索引以提高性能

为什么要添加这个表：

• 查询效率：在此之前，文件是嵌入在消息对象中的。这个表允许通过索引直接查找聊天中的所有文件，而无需遍历每条消息。
• 数据一致性：作为文件关联的单一事实来源。在多节点部署中，所有节点都查询此表，而不是依赖可能不一致的嵌入数据。
• 去重：数据库层面的唯一约束防止了重复的文件关联，这比应用层面的检查更可靠。

聊天 ID 标签表 (Chat ID Tag Table)

列名	数据类型	约束	描述
id	VARCHAR(255)	NOT NULL	唯一标识符
tag_name	VARCHAR(255)	NOT NULL	标签名称
chat_id	VARCHAR(255)	NOT NULL	关联的聊天 ID
user_id	VARCHAR(255)	NOT NULL	关联的用户 ID
timestamp	INTEGER	NOT NULL	创建时间戳

配置表 (Config)

列名	数据类型	约束	默认值	描述
id	INTEGER	NOT NULL	-	主键标识符
data	JSON	NOT NULL	-	配置数据
version	INTEGER	NOT NULL	-	配置版本号
created_at	DATETIME	NOT NULL	CURRENT_TIMESTAMP	创建时间戳
updated_at	DATETIME	-	CURRENT_TIMESTAMP	最后更新时间戳

反馈表 (Feedback Table)

列名	数据类型	约束	描述
id	Text	PRIMARY KEY	唯一标识符 (UUID)
user_id	Text	-	提供反馈的用户
version	BigInteger	default=0	反馈版本号
type	Text	-	反馈类型
data	JSON	nullable	包含评分的反馈数据
meta	JSON	nullable	元数据（竞技场、聊天 ID 等）
snapshot	JSON	nullable	关联的聊天快照
created_at	BigInteger	-	创建时间戳
updated_at	BigInteger	-	最后更新时间戳

文件表 (File Table)

列名	数据类型	约束	描述
id	String	PRIMARY KEY	唯一标识符
user_id	String	-	文件所有者
hash	Text	nullable	文件哈希/校验和
filename	Text	-	文件名称
path	Text	nullable	文件系统路径
data	JSON	nullable	文件相关数据
meta	JSON	nullable	文件元数据
access_control	JSON	nullable	权限设置
created_at	BigInteger	-	创建时间戳
updated_at	BigInteger	-	最后更新时间戳

meta 字段的预期结构：

{
    "name": string,          # 可选的显示名称
    "content_type": string,  # MIME 类型
    "size": integer,         # 文件大小（字节）
    # 通过 ConfigDict(extra="allow") 支持的其他元数据
}

文件夹表 (Folder Table)

列名	数据类型	约束	描述
id	Text	PK (复合)	唯一标识符 (UUID)
parent_id	Text	nullable	用于层级结构的父文件夹 ID
user_id	Text	PK (复合)	文件夹所有者
name	Text	-	文件夹名称
items	JSON	nullable	文件夹内容
data	JSON	nullable	额外的文件夹数据
meta	JSON	nullable	文件夹元数据
is_expanded	Boolean	default=False	UI 展开状态
created_at	BigInteger	-	创建时间戳
updated_at	BigInteger	-	最后更新时间戳

关于文件夹表需要了解的事项：

• 主键是复合主键 (id, user_id)
• 文件夹可以嵌套（通过 parent_id 引用）
• 根文件夹的 parent_id 为 null
• 同一父文件夹下的文件夹名称必须唯一

函数表 (Function Table)

列名	数据类型	约束	描述
id	String	PRIMARY KEY	唯一标识符
user_id	String	-	函数所有者
name	Text	-	函数名称
type	Text	-	函数类型
content	Text	-	函数内容/代码
meta	JSON	-	函数元数据
valves	JSON	-	函数控制设置
is_active	Boolean	-	函数激活状态
is_global	Boolean	-	全局可用性标志
created_at	BigInteger	-	创建时间戳
updated_at	BigInteger	-	最后更新时间戳

关于函数表需要了解的事项：

• type 只能是：["filter", "action"]

组表 (Group Table)

列名	数据类型	约束	描述
id	Text	PRIMARY KEY, UNIQUE	唯一标识符 (UUID)
user_id	Text	-	组所有者/创建者
name	Text	-	组名称
description	Text	-	组描述
data	JSON	nullable	额外的组数据
meta	JSON	nullable	组元数据
permissions	JSON	nullable	权限配置
created_at	BigInteger	-	创建时间戳
updated_at	BigInteger	-	最后更新时间戳

注意：user_ids 列已迁移到 group_member 表。

组成员表 (Group Member Table)

列名	数据类型	约束	描述
id	Text	PRIMARY KEY, UNIQUE	唯一标识符 (UUID)
group_id	Text	FOREIGN KEY(group.id), NOT NULL	关联的组 ID
user_id	Text	FOREIGN KEY(user.id), NOT NULL	关联的用户 ID
created_at	BigInteger	nullable	创建时间戳
updated_at	BigInteger	nullable	最后更新时间戳

关于 group_member 表需要了解的事项：

• 在 (group_id, user_id) 上有唯一约束，防止重复成员身份
• 与组表和用户表具有 CASCADE 删除的外键关系

知识库表 (Knowledge Table)

列名	数据类型	约束	描述
id	Text	PRIMARY KEY, UNIQUE	唯一标识符 (UUID)
user_id	Text	-	知识库所有者
name	Text	-	知识库名称
description	Text	-	知识库描述
data	JSON	nullable	知识库内容
meta	JSON	nullable	额外的元数据
access_control	JSON	nullable	访问控制规则
created_at	BigInteger	-	创建时间戳
updated_at	BigInteger	-	最后更新时间戳

知识库文件表 (Knowledge File Table)

列名	数据类型	约束	描述
id	Text	PRIMARY KEY	唯一标识符 (UUID)
user_id	Text	NOT NULL	关系的所有者
knowledge_id	Text	FOREIGN KEY(knowledge.id), NOT NULL	关联的知识库 ID
file_id	Text	FOREIGN KEY(file.id), NOT NULL	关联的文件 ID
created_at	BigInteger	NOT NULL	创建时间戳
updated_at	BigInteger	NOT NULL	最后更新时间戳

关于 knowledge_file 表需要了解的事项：

• 在 (knowledge_id, file_id) 上有唯一约束
• 具有 CASCADE 删除的外键关系
• 在 knowledge_id 和 file_id 上建立了索引以提高性能

记忆表 (Memory Table)

列名	数据类型	约束	描述
id	String	PRIMARY KEY	唯一标识符
user_id	String	-	记忆的所有者
content	Text	-	记忆的内容
created_at	BigInteger	-	创建时间戳
updated_at	BigInteger	-	最后更新时间戳

消息表 (Message Table)

列名	数据类型	约束	描述
id	String	PRIMARY KEY	唯一标识符
user_id	String	-	消息的所有者
chat_id	String	-	关联的聊天 ID
content	Text	-	消息的内容
data	JSON	-	消息相关的灵活数据
meta	JSON	-	消息元数据
created_at	BigInteger	-	创建时间戳
updated_at	BigInteger	-	最后更新时间戳

消息反应表 (Message Reaction Table)

列名	数据类型	约束	描述
id	String	PRIMARY KEY	唯一标识符
user_id	String	-	反应的所有者
message_id	String	-	关联的消息 ID
reaction	Text	-	反应（例如表情符号）
created_at	BigInteger	-	创建时间戳
updated_at	BigInteger	-	最后更新时间戳

迁移历史表 (Migrate History Table)

列名	数据类型	约束	描述
id	Integer	PRIMARY KEY	唯一标识符
version	String	-	数据库模式版本
created_at	BigInteger	-	创建时间戳

模型表 (Model Table)

列名	数据类型	约束	描述
id	String	PRIMARY KEY	唯一标识符
user_id	String	-	模型配置的所有者
base_model_id	String	-	基础模型的 ID
name	Text	-	模型名称
params	JSON	-	模型参数
meta	JSON	-	模型元数据
access_control	JSON	-	访问控制设置
is_active	Boolean	-	模型激活状态
created_at	BigInteger	-	创建时间戳
updated_at	BigInteger	-	最后更新时间戳

笔记表 (Note Table)

列名	数据类型	约束	描述
id	String	PRIMARY KEY	唯一标识符
user_id	String	-	笔记的所有者
content	Text	-	笔记的内容
created_at	BigInteger	-	创建时间戳
updated_at	BigInteger	-	最后更新时间戳

OAuth 会话表 (OAuth Session Table)

列名	数据类型	约束	描述
id	String	PRIMARY KEY	唯一标识符
user_id	String	-	会话的所有者
provider	String	-	OAuth 提供商
access_token	Text	-	访问令牌
refresh_token	Text	-	刷新令牌
expires_at	BigInteger	-	过期时间戳
created_at	BigInteger	-	创建时间戳
updated_at	BigInteger	-	最后更新时间戳

提示词表 (Prompt Table)

列名	数据类型	约束	描述
command	String	PRIMARY KEY	提示词命令（唯一标识符）
user_id	String	-	提示词的所有者
title	Text	-	提示词标题
content	Text	-	提示词内容
access_control	JSON	-	访问控制设置
created_at	BigInteger	-	创建时间戳
updated_at	BigInteger	-	最后更新时间戳

标签表 (Tag Table)

列名	数据类型	约束	描述
id	String	PRIMARY KEY	唯一标识符
name	String	UNIQUE	标签名称
user_id	String	-	标签的创建者
created_at	BigInteger	-	创建时间戳

工具表 (Tool Table)

列名	数据类型	约束	描述
id	String	PRIMARY KEY	唯一标识符
user_id	String	-	工具的所有者
name	Text	-	工具名称
content	Text	-	工具内容/代码
meta	JSON	-	工具元数据
valves	JSON	-	工具控制设置
access_control	JSON	-	访问控制设置
created_at	BigInteger	-	创建时间戳
updated_at	BigInteger	-	最后更新时间戳

用户表 (User Table)

列名	数据类型	约束	描述
id	String	PRIMARY KEY	唯一标识符 (UUID)
name	Text	-	用户姓名
email	String	UNIQUE	用户邮箱
role	String	-	用户角色（admin/user/pending）
profile_image_url	Text	-	头像 URL
last_active_at	BigInteger	-	最后活动时间戳
created_at	BigInteger	-	创建时间戳
updated_at	BigInteger	-	最后更新时间戳
api_key	String	UNIQUE, nullable	API 密钥
settings	JSON	nullable	用户个人设置
info	JSON	nullable	用户附加信息
oauth_sub	Text	UNIQUE, nullable	OAuth 订阅标识符

关于用户表需要了解的事项：

• 默认角色由 DEFAULT_USER_ROLE 环境变量决定
• api_key 用于对 Open WebUI API 的编程访问
• oauth_sub 存储来自外部身份验证提供商的唯一 ID

---

使用 SQLCipher 进行数据库加密

为了增强安全性，Open WebUI 支持使用 SQLCipher 对其主 SQLite 数据库进行静态加密。对于处理敏感数据且不需要使用 PostgreSQL 等大型数据库的部署，建议使用此功能。

要求

SQLCipher 加密需要额外的依赖项，默认不包含。在使用此功能之前，您必须安装：

• SQLCipher 系统库（例如，Debian/Ubuntu 上的 libsqlcipher-dev，或通过 Homebrew 在 macOS 上的 sqlcipher）
• 支持 SQLCipher 的 Python 绑定（通常是 pysqlcipher3）

配置

要启用加密，请设置以下环境变量：

# 必填：设置数据库类型以使用 SQLCipher
DATABASE_TYPE=sqlite+sqlcipher

# 必填：设置加密密码
DATABASE_PASSWORD=your_secure_encryption_password