跳到主要内容
注意

本教程为社区贡献内容,不由 Open WebUI 团队提供支持。它仅用于展示如何根据具体使用案例定制 Open WebUI。有意贡献?请查看贡献教程。

[!WARNING]
此文档基于当前版本 (0.5.11) 创建,并会持续更新。

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 数据库中的完整表清单。为方便起见,表按字母顺序排列并附带编号。

编号表名描述
01auth存储用户认证凭据和登录信息
02channel管理聊天频道及其配置
03channel_member跟踪频道内的用户成员和权限
04chat存储聊天会话及其元数据
05chatidtag映射聊天与其关联标签之间的关系
06config维护系统范围的配置设置
07document存储知识管理相关的文档及元数据
08feedback捕捉用户反馈和评分
09file管理上传的文件及其元数据
10folder将文件和内容组织为层次结构
11function存储自定义函数及其配置
12group管理用户组及其权限
13knowledge存储知识库条目及相关信息
14memory维护聊天历史和上下文记忆
15message存储单独的聊天消息及其内容
16message_reaction记录用户对消息的反应(表情符号/回复)
17migrate_history跟踪数据库模式版本和迁移记录
18model管理 AI 模型配置和设置
19prompt存储 AI 提示的模板和配置
20tag管理用于内容分类的标签/标识
21tool存储系统工具和集成配置
22user维护用户资料和账户信息

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

  • Alembic Version 表
  • Migrate History 表

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

Auth 表

列名数据类型约束描述
idStringPRIMARY KEY唯一标识符
emailString-用户的邮箱
passwordText-哈希密码
activeBoolean-账户状态

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

  • 使用 UUID 作为主键
  • users 表为一对一关系(共享 id)

Channel 表

列名数据类型约束描述
idTextPRIMARY KEY唯一标识符 (UUID)
user_idText-频道的拥有者/创建者
typeTextnullable频道类型
nameText-频道名称
descriptionTextnullable频道描述
dataJSONnullable灵活的数据存储
metaJSONnullable频道元数据
access_controlJSONnullable权限设置
created_atBigInteger-创建时间戳(纳秒)
updated_atBigInteger-最后更新时间戳(纳秒)

关于认证表需要了解的内容:

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

频道成员表

列名称数据类型约束条件描述
idTEXTNOT NULL频道成员的唯一标识符
channel_idTEXTNOT NULL引用频道
user_idTEXTNOT NULL引用用户
created_atBIGINT-创建成员关系的时间戳

聊天表

列名称数据类型约束条件描述
idStringPRIMARY KEY唯一标识符 (UUID)
user_idString-聊天的创建者
titleText-聊天标题
chatJSON-聊天内容及历史记录
created_atBigInteger-创建时间戳
updated_atBigInteger-最后更新时间戳
share_idTextUNIQUE, nullable分享标识符
archivedBooleandefault=False存档状态
pinnedBooleandefault=False, nullable置顶状态
metaJSONserver_default=""包含标签的元数据
folder_idTextnullable父文件夹ID

聊天标签表

列名称数据类型约束条件描述
idVARCHAR(255)NOT NULL唯一标识符
tag_nameVARCHAR(255)NOT NULL标签名称
chat_idVARCHAR(255)NOT NULL引用聊天
user_idVARCHAR(255)NOT NULL引用用户
timestampINTEGERNOT NULL创建时间戳

配置

列名称数据类型约束条件默认值描述
idINTEGERNOT NULL-主键标识符
dataJSONNOT NULL-配置信息
versionINTEGERNOT NULL-配置版本号
created_atDATETIMENOT NULLCURRENT_TIMESTAMP创建时间戳
updated_atDATETIME-CURRENT_TIMESTAMP最后更新时间戳

反馈表

列名称数据类型约束条件描述
idTextPRIMARY KEY唯一标识符 (UUID)
user_idText-提供反馈的用户
versionBigIntegerdefault=0反馈版本号
typeText-反馈类型
dataJSONnullable包含评分的反馈数据
metaJSONnullable元数据(如竞技场、聊天ID等)
snapshotJSONnullable相关聊天快照
created_atBigInteger-创建时间戳
updated_atBigInteger-最后更新时间戳

文件表

列名数据类型约束条件描述
idStringPRIMARY KEY唯一标识符
user_idString-文件的所有者
hashTextnullable文件哈希/校验和
filenameText-文件名
pathTextnullable文件系统路径
dataJSONnullable与文件相关的数据
metaJSONnullable文件元数据
access_controlJSONnullable权限设置
created_atBigInteger-创建时间戳
updated_atBigInteger-最后更新时间戳

meta 字段的预期结构:

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

文件夹表

列名数据类型约束条件描述
idTextPRIMARY KEY唯一标识符 (UUID)
parent_idTextnullable用于层级关系的父文件夹 ID
user_idText-文件夹的所有者
nameText-文件夹名称
itemsJSONnullable文件夹内容
metaJSONnullable文件夹元数据
is_expandedBooleandefault=FalseUI 展开状态
created_atBigInteger-创建时间戳
updated_atBigInteger-最后更新时间戳

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

  • 文件夹可以嵌套(通过 parent_id 引用)
  • 根文件夹的 parent_id 为 null
  • 同一父级下文件夹名称必须唯一

函数表

列名数据类型约束条件描述
idStringPRIMARY KEY唯一标识符
user_idString-函数的所有者
nameText-函数名称
typeText-函数类型
contentText-函数内容/代码
metaJSON-函数元数据
valvesJSON-函数控制设定
is_activeBoolean-函数激活状态
is_globalBoolean-全局可用性标志
created_atBigInteger-创建时间戳
updated_atBigInteger-最后更新时间戳

关于函数表需要了解事项:

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

群组表

列名数据类型约束条件描述
idTextPRIMARY KEY, UNIQUE唯一标识符 (UUID)
user_idText-群组所有者/创建者
nameText-群组名称
descriptionText-群组描述
dataJSONnullable附加群组数据
metaJSONnullable群组元数据
permissionsJSONnullable权限配置
user_idsJSONnullable成员用户 ID 列表
created_atBigInteger-创建时间戳
updated_atBigInteger-最后更新时间戳

知识表

列名数据类型约束条件描述
idTextPRIMARY KEY, UNIQUE唯一标识符 (UUID)
user_idText-知识库所有者
nameText-知识库名称
descriptionText-知识库描述
dataJSONnullable知识库内容
metaJSONnullable附加元数据
access_controlJSONnullable访问控制规则
created_atBigInteger-创建时间戳
updated_atBigInteger-最后更新时间戳

access_control字段的预期结构:

{
"read": {
"group_ids": ["group_id1", "group_id2"],
"user_ids": ["user_id1", "user_id2"]
},
"write": {
"group_ids": ["group_id1", "group_id2"],
"user_ids": ["user_id1", "user_id2"]
}
}

内存表

列名数据类型约束条件描述
idStringPRIMARY KEY唯一标识符 (UUID)
user_idString-内存所有者
contentText-内存内容
created_atBigInteger-创建时间戳
updated_atBigInteger-最后更新时间戳

消息表

列名数据类型约束条件描述
idTextPRIMARY KEY唯一标识符 (UUID)
user_idText-消息作者
channel_idTextnullable关联的频道
parent_idTextnullable线程的父消息
contentText-消息内容
dataJSONnullable附加的消息数据
metaJSONnullable消息元数据
created_atBigInteger-创建时间戳(纳秒)
updated_atBigInteger-最后更新时间戳(纳秒)

消息反应表

列名数据类型约束条件描述
idTextPRIMARY KEY唯一标识符 (UUID)
user_idText-反应的用户
message_idText-关联的消息
nameText-反应名称/表情
created_atBigInteger-反应时间戳

模型表

列名数据类型约束条件描述
idTextPRIMARY KEY模型标识符
user_idText-模型所有者
base_model_idTextnullable父模型引用
nameText-显示名称
paramsJSON-模型参数
metaJSON-模型元数据
access_controlJSONnullable访问权限
is_activeBooleandefault=True激活状态
created_atBigInteger-创建时间戳
updated_atBigInteger-最后更新时间戳

提示表

列名数据类型约束条件描述
commandStringPRIMARY KEY唯一指令标识符
user_idString-提示所有者
titleText-提示标题
contentText-提示内容/模板
timestampBigInteger-最后更新时间戳
access_controlJSONnullable访问权限

标签表

列名数据类型约束条件描述
id字符串主键(复合)标准化标签标识
name字符串-显示名称
user_id字符串主键(复合)标签所属者
metaJSON可为空标签元数据

关于标签表需要了解的事项:

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

工具表

列名数据类型约束条件描述
id字符串主键唯一标识符
user_id字符串-工具所属者
name文本-工具名称
content文本-工具内容/代码
specsJSON-工具规格
metaJSON-工具元数据
valvesJSON-工具控制设置
access_controlJSON可为空访问权限
created_at大整数-创建时间戳
updated_at大整数-最近更新时间戳

用户表

列名数据类型约束条件描述
id字符串主键唯一标识符
name字符串-用户的名称
email字符串-用户的邮箱
role字符串-用户的角色
profile_image_url文本-用户头像路径
last_active_at大整数-最近活跃时间戳
updated_at大整数-最近更新时间戳
created_at大整数-创建时间戳
api_key字符串唯一,可为空API认证密钥
settingsJSON可为空用户偏好设置
infoJSON可为空额外的用户信息
oauth_sub文本唯一OAuth主题标识符

实体关系图

为了帮助可视化表之间的关系,请参考以下由Mermaid生成的实体关系图(ERD)。