数据库 Schema

社区贡献

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

[!WARNING] 本篇文档反映了截至 Open WebUI v0.9.5 版本的数据库表结构 (Schema) 变更。

Open WebUI 内部 SQLite 数据库

对于 Open WebUI 来说，SQLite 数据库是用户管理、对话历史记录、文件存储以及各种其他核心功能的基石。理解这一结构对于任何希望有效地为该项目做贡献或进行维护的人来说都至关重要。

内部 SQLite 位置

您可以在以下路径找到 SQLite 数据库：根目录 -> data -> webui.db

📁 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	access_grant	存储所有资源的标准化访问控制授权配置
02	auth	存储用户身份验证凭据和登录信息
03	calendar	存储包含访问控制的、用户拥有的日历
04	calendar_event	存储支持循环规则 (RRULE) 的日历事件
05	calendar_event_attendee	跟踪共享日历事件的参与者 RSVP 回复
06	channel	管理聊天频道及其配置
07	channel_file	将文件链接至频道和消息
08	channel_member	跟踪频道内的用户成员资格和权限
09	chat	存储对话会话及其元数据
10	chat_file	将文件链接至对话和消息
11	chatidtag	映射对话与其关联标签之间的关系
12	config	维护系统级别的全局配置设置
13	document	存储知识库管理所需的文档及其元数据
14	feedback	捕获用户反馈和评分
15	file	管理已上传的文件及其元数据
16	folder	将文件和内容组织进层级目录结构中
17	function	存储自定义的 Functions 及其配置
18	group	管理用户群组及其权限
19	group_member	跟踪群组内的用户成员资格
20	knowledge	存储知识库条目和相关信息
21	knowledge_file	将文件链接到知识库
22	memory	维护对话历史和上下文记忆 (Memory)
23	message	存储单条聊天消息及其内容
24	message_reaction	记录用户对消息的反应（表情符号/回应）
25	migrate_history	跟踪数据库 Schema 版本和迁移记录
26	model	管理 AI 模型配置和设置
27	note	存储用户创建的笔记和注释
28	oauth_session	管理活跃的用户 OAuth 会话
29	prompt	存储 AI 提示词 (Prompts) 的模板和配置
30	prompt_history	跟踪提示词的版本历史和快照
31	shared_chat	存储共享对话的快照，用于生成共享链接
32	skill	存储可复用的 Markdown 指令集 (Skills)
33	tag	管理用于内容分类的标签/类别
34	tool	存储系统工具和集成的配置
35	user	维护用户个人资料和账户信息
36	automation	存储用户定义的时间表自动化任务
37	automation_run	存储自动化任务的执行历史记录
38	pinned_note	跟踪每位用户的笔记置顶（每行 = 某个用户置顶了某篇笔记）

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

Alembic Version 表
Migrate History 表

既然我们了解了所有的表，接下来就让我们逐个理解每个表的具体结构。

Access Grant（访问授权）表

列名	数据类型	约束	描述
id	Integer	PRIMARY KEY, AUTOINCREMENT	唯一标识符
resource_type	Text	NOT NULL	资源类型（例如 `model`、`knowledge`、`tool`）
resource_id	Text	NOT NULL	特定资源的 ID
principal_type	Text	NOT NULL	被授权主体的类型：`user` 或 `group`
principal_id	Text	NOT NULL	用户或群组的 ID（对于公共权限为 `*`）
permission	Text	NOT NULL	权限级别：`read` 或 `write`
created_at	BigInteger	nullable	授权创建的时间戳

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

在 (resource_type, resource_id, principal_type, principal_id, permission) 上存在唯一性约束，以防止重复授权
在 (resource_type, resource_id) 和 (principal_type, principal_id) 上建有索引，以实现高效查询
取代了以前嵌入在各个资源表中的 access_control JSON 列
principal_type 为 user 且 principal_id 为 * 代表公共（公开）访问权限
同时支持群组级和单个用户级的访问授权

Auth（身份验证）表

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

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

使用 UUID 作为主键
与 users 表呈一对一关系（共享相同 id）

Channel（频道）表

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

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

使用 UUID 作为主键
频道名称不区分大小写（在数据库中存为小写）

Channel Member（频道成员）表

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

Channel File（频道文件）表

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

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

在 (channel_id, file_id) 上存在唯一性约束，以防止重复条目
支持级联删除 (CASCADE delete) 的外键关系
在 channel_id、file_id 和 user_id 上建有索引，以优化性能

Chat（对话）表

列名	数据类型	约束	描述
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
tasks	JSON	nullable	智能体工作流使用的对话级任务/待办事项列表
summary	Text	nullable	可选的对话摘要文本
last_read_at	BigInteger	nullable	上次阅读的时间戳，用于未读指示器

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

tasks 和 summary 支持对话会话中的结构化规划/状态界面展示。
last_read_at 被侧边栏未读状态逻辑使用（与 updated_at 进行对比）。
当对话具有活动的共享链接时，share_id 会引用 shared_chat.id 的 Token。

Shared Chat（共享对话）表

列名	数据类型	约束	描述
id	Text	PRIMARY KEY	在 `/s/{id}` URL 中使用的共享 Token (UUID)
chat_id	Text	FOREIGN KEY(chat.id) CASCADE, NOT NULL	对原始对话的引用
user_id	Text	NOT NULL	创建该共享的用户
title	Text	nullable	共享时的对话标题
chat	JSON	nullable	共享时的对话内容快照
created_at	BigInteger	nullable	共享创建的时间戳
updated_at	BigInteger	nullable	上次更新快照的时间戳

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

取代了先前通过在 chat 表中插入 user_id 设置为 shared-{chat_id} 的虚拟行来存储共享对话快照的模式。
每一行都是共享时（或最后一次重新共享时）原始对话的不可变快照。当用户点击“更新并复制链接”时，该快照会被更新。
删除原始对话会级联删除对应的共享快照。
共享对话的访问控制是通过 access_grant 表管理的，其中 resource_type = 'shared_chat'。

Automation（自动化）表

列名	数据类型	约束	描述
id	Text	PRIMARY KEY	唯一标识符 (UUID)
user_id	Text	NOT NULL	自动化的拥有者
name	Text	NOT NULL	自动化显示的名称
data	JSON	NOT NULL	自动化负载（包括 `prompt`、`model_id`、`rrule` 以及可选的终端配置）
meta	JSON	nullable	可选元数据
is_active	Boolean	NOT NULL, default=True	启用/暂停状态
last_run_at	BigInteger	nullable	上次执行时间
next_run_at	BigInteger	nullable	下次计划执行时间
created_at	BigInteger	NOT NULL	创建时间戳
updated_at	BigInteger	NOT NULL	最后更新时间戳

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

next_run_at 建有索引以实现对到期执行任务的高效轮询。
data.rrule 定义了循环规则并驱动调度器的计算。

Automation Run（自动化执行）表

列名	数据类型	约束	描述
id	Text	PRIMARY KEY	唯一标识符 (UUID)
automation_id	Text	NOT NULL	对自动化的引用
chat_id	Text	nullable	由此运行创建的对话（如果可用）
status	Text	NOT NULL	运行状态（`success` / `error`）
error	Text	nullable	状态为 `error` 时的错误详情
created_at	BigInteger	NOT NULL	执行记录时间戳

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

按 automation_id 进行索引，以实现对单个自动化执行历史的快速查询。
当删除某个自动化任务时，其对应的执行记录也会被删除。

Calendar（日历）表

列名	数据类型	约束	描述
id	Text	PRIMARY KEY	唯一标识符 (UUID)
user_id	Text	NOT NULL	日历的拥有者
name	Text	NOT NULL	日历显示的名称
color	Text	nullable	显示的颜色（十六进制，例如 `#3b82f6`）
is_default	Boolean	NOT NULL, default=False	这是否是用户的默认日历
data	JSON	nullable	可扩展的数据负载
meta	JSON	nullable	可选元数据
created_at	BigInteger	NOT NULL	创建时间戳
updated_at	BigInteger	NOT NULL	最后更新时间戳

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

在 user_id 上建有索引，以实现对每个用户日历列表的高效列出。
首次访问时会自动创建默认的“个人 (Personal)”日历。
“计划任务 (Scheduled Tasks)”日历是虚拟的 —— 它不存储在此表中。相反，对于拥有 Automations 访问权限的用户，API 会在响应时合成该日历（其固定 ID 为 __scheduled_tasks__）。自动化的 RRULE 未来执行计划和过去的执行记录将作为虚拟事件渲染在此日历上。
访问控制通过 access_grant 表（resource_type = 'calendar'）进行管理，从而支持在用户和群组之间共享日历。
用户只能删除非默认的日历。删除日历会级联删除其所有的事件、参与者和访问授权。

Calendar Event（日历事件）表

列名	数据类型	约束	描述
id	Text	PRIMARY KEY	唯一标识符 (UUID)
calendar_id	Text	NOT NULL	对父日历的引用
user_id	Text	NOT NULL	创建该事件的用户
title	Text	NOT NULL	事件标题
description	Text	nullable	事件描述
start_at	BigInteger	NOT NULL	开始时间（Epoch 纳秒）
end_at	BigInteger	nullable	结束时间（Epoch 纳秒）
all_day	Boolean	NOT NULL, default=False	是否是全天事件
rrule	Text	nullable	用于事件循环的 iCalendar RRULE
color	Text	nullable	单个事件的覆盖颜色
location	Text	nullable	事件地点
data	JSON	nullable	可扩展的数据负载
meta	JSON	nullable	可选元数据（例如 `automation_id`）
is_cancelled	Boolean	NOT NULL, default=False	软取消标志
created_at	BigInteger	NOT NULL	创建时间戳
updated_at	BigInteger	NOT NULL	最后更新时间戳

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

在 (calendar_id, start_at) 上建有复合索引，以便在日历内进行高效的范围查询。
在 (user_id, start_at) 上建有复合索引，以便进行每个用户的高效日期范围查询。
循环事件存储一个 rrule 字符串，并在查询时展开为具体的每个实例（服务器端使用 Python 的 dateutil 库进行展开）。
已取消的事件 (is_cancelled = True) 会从范围查询中排除，但会保留在数据库中。

Calendar Event Attendee（日历事件参与者）表

列名	数据类型	约束	描述
id	Text	PRIMARY KEY	唯一标识符 (UUID)
event_id	Text	NOT NULL	对日历事件的引用
user_id	Text	NOT NULL	被邀请加入事件的用户
status	Text	NOT NULL, default='pending'	RSVP 状态：`pending`、`accepted`、`declined`、`tentative`
meta	JSON	nullable	可选元数据
created_at	BigInteger	NOT NULL	创建时间戳
updated_at	BigInteger	NOT NULL	最后更新时间戳

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

在 (event_id, user_id) 上存在唯一性约束，以防止重复的参与者条目。
在 (user_id, status) 上建有索引，以便高效查找用户受邀参加的事件。
当事件使用新的参与者列表更新时，参与者会被批量替换。
删除事件会级联删除所有参与者记录。

Chat File（对话文件）表

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

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

在 (chat_id, file_id) 上存在唯一性约束，以防止重复条目
支持级联删除 (CASCADE delete) 的外键关系
在 chat_id、file_id、message_id 和 user_id 上建有索引以优化性能

为什么添加这个表：

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

Chat ID Tag（对话标签关联）表

列名	数据类型	约束	描述
id	VARCHAR(255)	NOT NULL	唯一标识符
tag_name	VARCHAR(255)	NOT NULL	标签名称
chat_id	VARCHAR(255)	NOT NULL	对对话的引用
user_id	VARCHAR(255)	NOT NULL	对用户的引用
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（反馈）表

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

File（文件）表

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

meta 字段的预期结构：

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

Folder（文件夹）表

列名	数据类型	约束	描述
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	-	最后更新时间戳

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

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

Function（函数）表

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

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

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

Group（群组）表

列名	数据类型	约束	描述
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（群组成员）表

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

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

在 (group_id, user_id) 上存在唯一性约束，以防止重复成员关系
与群组和用户表具有级联删除 (CASCADE delete) 的外键关系

Knowledge（知识库）表

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

Knowledge File（知识库文件关联）表

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

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

在 (knowledge_id, file_id) 上存在唯一性约束，以防止重复条目
支持级联删除 (CASCADE delete) 的外键关系
在 knowledge_id、file_id 和 user_id 上建有索引以优化性能

资源（模型、知识库、工具、提示词、笔记、文件、频道）的访问控制是通过 access_grant 表而不是嵌入式 JSON 管理的。每个授权条目都指定了资源、主体（用户或群组）以及权限级别（只读或可写）。详见上文的 Access Grant 表部分。

Memory（记忆）表

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

Message（消息）表

列名	数据类型	约束	描述
id	Text	PRIMARY KEY	唯一标识符 (UUID)
user_id	Text	-	消息的作者
channel_id	Text	nullable	相关联的频道
parent_id	Text	nullable	实现消息分支线时的父消息 ID
content	Text	-	消息具体内容
data	JSON	nullable	额外消息数据
meta	JSON	nullable	消息元数据
created_at	BigInteger	-	创建时间戳（纳秒）
updated_at	BigInteger	-	最后更新时间戳（纳秒）

Message Reaction（消息反应）表

列名	数据类型	约束	描述
id	Text	PRIMARY KEY	唯一标识符 (UUID)
user_id	Text	-	做出该反应的用户
message_id	Text	-	被反应的相关消息
name	Text	-	反应的名称/表情符号
created_at	BigInteger	-	反应时间戳

Model（模型）表

列名	数据类型	约束	描述
id	Text	PRIMARY KEY	模型标识符
user_id	Text	-	模型的拥有者
base_model_id	Text	nullable	父模型引用
name	Text	-	显示的名称
params	JSON	-	模型参数
meta	JSON	-	模型元数据
is_active	Boolean	default=True	启用状态
created_at	BigInteger	-	创建时间戳
updated_at	BigInteger	-	最后更新时间戳

Note（笔记）表

列名	数据类型	约束	描述
id	Text	PRIMARY KEY	唯一标识符
user_id	Text	nullable	笔记的拥有者
title	Text	nullable	笔记标题
data	JSON	nullable	笔记具体内容和数据
meta	JSON	nullable	笔记元数据
created_at	BigInteger	nullable	创建时间戳
updated_at	BigInteger	nullable	最后更新时间戳

置顶状态不再存储在该表中 —— 历史遗留的 is_pinned 列已在数据迁移 4de81c2a3af1 中被移除，并由每个用户独立的置顶笔记表取代。先前已存在的置顶信息已回填给笔记的所有者；API 通过对当前调用用户的行进行单次请求联接 (Join) 来对外呈现 is_pinned 状态。

Pinned Note（置顶笔记）表

每个用户独立的笔记置顶。每一行记录了某个用户为自己的侧边栏置顶了一篇笔记 —— 置顶操作是私有的，不会影响有权访问同一篇笔记的其他用户。

列名	数据类型	约束	描述
id	Text	PRIMARY KEY	唯一标识符 (UUID)
user_id	Text	NOT NULL	置顶该笔记的用户
note_id	Text	NOT NULL, FOREIGN KEY(note.id) ON DELETE CASCADE	被置顶的笔记
created_at	BigInteger	NOT NULL	置顶创建的时间戳（用于排序）

UNIQUE(user_id, note_id) 约束防止了同一用户/笔记对出现重复置顶。置顶笔记列表在每位用户下按 created_at DESC 排序，因此最新置顶的笔记会显示在最前面。删除一篇笔记会级联删除此表中的相关行；切换置顶状态不会修改 note.updated_at。

OAuth Session 表

列名	数据类型	约束	描述
id	Text	PRIMARY KEY	唯一会话标识符
user_id	Text	FOREIGN KEY(user.id)	关联的用户
provider	Text	-	OAuth 提供商（例如 'google'）
token	Text	-	OAuth 会话 Token
expires_at	BigInteger	-	Token 过期时间戳
created_at	BigInteger	-	会话创建时间戳
updated_at	BigInteger	-	会话最后更新时间戳

Prompt（提示词）表

列名	数据类型	约束	描述
id	Text	PRIMARY KEY	唯一标识符 (UUID)
command	String	UNIQUE, INDEX	唯一的提示词斜杠命令标识符
user_id	String	NOT NULL	提示词的拥有者
name	Text	NOT NULL	提示词的显示名称
content	Text	NOT NULL	提示词的具体内容/模板
data	JSON	nullable	额外提示词数据
meta	JSON	nullable	提示词元数据
is_active	Boolean	default=True	启用状态
version_id	Text	nullable	当前版本标识符
tags	JSON	nullable	关联标签
created_at	BigInteger	NOT NULL	创建时间戳
updated_at	BigInteger	NOT NULL	最后更新时间戳

Prompt History（提示词历史）表

列名	数据类型	约束	描述
id	Text	PRIMARY KEY	唯一标识符 (UUID)
prompt_id	Text	FOREIGN KEY(prompt.id), INDEX	对提示词的引用
parent_id	Text	nullable	对父版本的引用
snapshot	JSON	NOT NULL	提示词在该版本下的快照
user_id	Text	NOT NULL	创建该版本的用户
commit_message	Text	nullable	版本提交说明信息
created_at	BigInteger	NOT NULL	创建时间戳

Skill（技能）表

列名	数据类型	约束	描述
id	Text	PRIMARY KEY	唯一标识符 (UUID)
user_id	Text	NOT NULL	技能的拥有者/创建者
name	Text	NOT NULL	技能的显示名称
description	Text	nullable	技能的简短描述（用于 Manifest）
content	Text	NOT NULL	技能的完整 Markdown 指令集内容
data	JSON	nullable	额外技能数据
meta	JSON	nullable	技能元数据
is_active	Boolean	default=True	启用状态
created_at	BigInteger	NOT NULL	创建时间戳
updated_at	BigInteger	NOT NULL	最后更新时间戳

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

使用 UUID 作为主键
访问控制通过 access_grant 表进行管理（resource_type 为 skill）
description 作为 Manifest 的一部分注入到 System Prompt（系统提示词）中；content 会在需要时通过内置的 view_skill 工具按需加载

Tag（标签）表

列名	数据类型	约束	描述
id	String	PK（复合主键）	标准化后的标签标识符
name	String	-	显示的名称
user_id	String	PK（复合主键）	标签拥有者
meta	JSON	nullable	标签元数据

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

主键是复合主键 (id, user_id)

Tool（工具）表

列名	数据类型	约束	描述
id	String	PRIMARY KEY	唯一标识符
user_id	String	-	工具拥有者
name	Text	-	工具名称
content	Text	-	工具具体内容/代码
specs	JSON	-	工具 specifications（规范描述）
meta	JSON	-	工具元数据
valves	JSON	-	工具控制阀门配置
created_at	BigInteger	-	创建时间戳
updated_at	BigInteger	-	最后更新时间戳

User（用户）表

列名	数据类型	约束	描述
id	String	PRIMARY KEY	唯一标识符
username	String(50)	nullable	用户的唯一用户名
name	String	-	用户真实姓名/昵称
email	String	-	用户邮箱
role	String	-	用户角色
profile_image_url	Text	-	个人资料头像路径
bio	Text	nullable	用户个人简介
gender	Text	nullable	用户性别
date_of_birth	Date	nullable	用户出生日期
last_active_at	BigInteger	-	上次活动的时间戳
updated_at	BigInteger	-	最后更新时间戳
created_at	BigInteger	-	创建时间戳
api_key	String	UNIQUE, nullable	API 身份验证密钥
settings	JSON	nullable	用户个性化首选项
info	JSON	nullable	用户其他信息说明
oauth_sub	Text	UNIQUE	OAuth 主体唯一标识符
scim	JSON	nullable	SCIM 账号预配数据

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

使用 UUID 作为主键
与 auth 表呈一对一关系（共享相同 id）
与 oauth_session 表呈一对一关系（通过 user_id 外键）

scim 字段的预期结构：

{
    "<provider>": {
        "external_id": string,  # 身份提供商提供的 externalId
    },
    # 可以同时存储多个提供商的信息
    # 示例:
    # "microsoft": { "external_id": "abc-123" },
    # "okta": { "external_id": "def-456" }
}

为什么添加这个列：

SCIM 账户关联：存储来自 SCIM 预配的每个提供商的 externalId 值，使身份提供商（如 Azure AD、Okta）能够通过其外部标识符匹配用户，而不是仅仅依赖邮箱。
多提供商支持：按提供商划分的键结构允许同一个用户同时由多个身份提供商进行预配，每个提供商独立存储其自己的 externalId。
OAuth 备选机制：当通过 externalId 查找用户时，如果未找到 scim 条目，系统会回退到匹配 oauth_sub，从而实现 SCIM 预配账户与 OAuth 认证账户的无缝关联。

实体关系图 (ERD)

为了帮助您直观地了解表之间的关系，请参考下方使用 Mermaid 生成的实体关系图 (ERD)。

使用 SQLCipher 进行数据库加密

为了增强安全性，Open WebUI 支持使用 SQLCipher 对其主 SQLite 数据库进行静态数据加密（Encryption at-rest）。这被推荐用于处理敏感数据的部署环境，且在这些环境中无需使用类似 PostgreSQL 这样更大型的数据库。

前提条件

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

SQLCipher 系统库（例如，Debian/Ubuntu 上的 libsqlcipher-dev，macOS 上通过 Homebrew 安装的 sqlcipher）
sqlcipher3-wheels Python 包（运行 pip install sqlcipher3-wheels 安装）

对于 Docker 用户，这意味着需要构建一个包含这些依赖项的自定义镜像。

配置方法

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

# 必填: 将数据库类型设置为使用 SQLCipher
DATABASE_TYPE=sqlite+sqlcipher

# 必填: 设置一个安全的数据库加密密码
DATABASE_PASSWORD=your-secure-password

当设置了这些变量且没有明确定义完整的 DATABASE_URL 时，Open WebUI 会自动在 ./data/webui.db 创建并使用加密数据库文件。

重要注意事项

危险

使用 sqlite+sqlcipher 时，DATABASE_PASSWORD 环境变量是必填的。
DATABASE_TYPE 变量会告诉 Open WebUI 使用哪种连接逻辑。将其设置为 sqlite+sqlcipher 会激活加密功能。
请务必确保密码的安全，因为它是解密和访问所有应用数据所必需的。
丢失密码意味着将永远失去对加密数据库中所有数据的访问权限。

将现有数据迁移至 SQLCipher

Open WebUI 不支持从常规未加密 SQLite 数据库到加密 SQLCipher 数据库的自动迁移。 如果您在现有安装上启用了 SQLCipher，应用程序将无法读取您现有的未加密数据。

要将 SQLCipher 用于现有数据，您必须采取以下措施之一：

全新开始 —— 在全新的安装中启用 SQLCipher，并让用户手动导出/重新导入其对话
手动数据库迁移 —— 使用外部 SQLite/SQLCipher 工具从未加密数据库中导出数据并导入到新的加密数据库中（仅限高级用户）
使用文件系统级加密 —— 考虑使用如 LUKS (Linux) 或 BitLocker (Windows) 等替代方案进行静态数据加密，无需改动数据库层面
切换到 PostgreSQL —— 对于多用户部署，带有 TLS 的 PostgreSQL 提供了传输中加密，并可以与加密存储配合使用

变量	默认值	描述
`DATABASE_TYPE`	`None`	设置为 `sqlite+sqlcipher` 以使用加密的 SQLite
`DATABASE_PASSWORD`	-	加密密码（SQLCipher 必填）
`DATABASE_ENABLE_SQLITE_WAL`	`False`	启用预写式日志 (WAL) 以获得更好的性能
`DATABASE_SQLITE_PRAGMA_SYNCHRONOUS`	`NORMAL`	SQLite 同步模式（与 WAL 配合使用更安全，避免每次事务进行 fsync）
`DATABASE_SQLITE_PRAGMA_BUSY_TIMEOUT`	`5000`	写入锁等待时间（以毫秒为单位）
`DATABASE_SQLITE_PRAGMA_CACHE_SIZE`	`-65536`	页面缓存大小（负数表示 KiB；≈ 64 MB）
`DATABASE_SQLITE_PRAGMA_TEMP_STORE`	`MEMORY`	临时表存储模式（`MEMORY` 将临时表保留在内存中）
`DATABASE_SQLITE_PRAGMA_MMAP_SIZE`	`268435456`	内存映射 I/O 大小（以字节为单位，≈ 256 MB）
`DATABASE_SQLITE_PRAGMA_JOURNAL_SIZE_LIMIT`	`67108864`	Checkpoint 后的最大 WAL 文件大小（≈ 64 MB）
`DATABASE_POOL_SIZE`	`None`	数据库连接池大小
`DATABASE_POOL_TIMEOUT`	`30`	连接池连接超时时间（以秒为单位）
`DATABASE_POOL_RECYCLE`	`3600`	连接池连接回收时间（以秒为单位）

欲了解更多详情，请参阅环境变量配置文档。

This content is for informational purposes only and does not constitute a warranty, guarantee, or contractual commitment. Open WebUI is provided "as is." See your license for applicable terms.

Open WebUI 内部 SQLite 数据库​

内部 SQLite 位置​

本地复制数据库​

表结构概述​

Access Grant（访问授权）表​

Auth（身份验证）表​

Channel（频道）表​

Channel Member（频道成员）表​

Channel File（频道文件）表​

Chat（对话）表​

Shared Chat（共享对话）表​

Automation（自动化）表​

Automation Run（自动化执行）表​

Calendar（日历）表​

Calendar Event（日历事件）表​

Calendar Event Attendee（日历事件参与者）表​

Chat File（对话文件）表​

Chat ID Tag（对话标签关联）表​

Config（配置）表​

Feedback（反馈）表​

File（文件）表​

Folder（文件夹）表​

Function（函数）表​

Group（群组）表​

Group Member（群组成员）表​

Knowledge（知识库）表​

Knowledge File（知识库文件关联）表​

Memory（记忆）表​

Message（消息）表​

Message Reaction（消息反应）表​

Model（模型）表​

Note（笔记）表​

Pinned Note（置顶笔记）表​

OAuth Session 表​

Prompt（提示词）表​

Prompt History（提示词历史）表​

Skill（技能）表​

Tag（标签）表​

Tool（工具）表​

User（用户）表​

实体关系图 (ERD)​

使用 SQLCipher 进行数据库加密​

前提条件​

配置方法​

重要注意事项​

相关的数据库环境变量​