SQLite 存储
Libre WebUI 默认把应用数据存储在 SQLite 中。存储层在一个本地数据库内保存聊天、 消息、用户、偏好、文档及其分块、角色、插件凭据、记忆和相关元数据。
数据库位置
从源代码启动时按以下顺序选择位置：
- 已设置
DATA_DIR时使用它；相对值从后端目录解析。 - 未设置时使用
backend/data。
为保持向后兼容，如果只有 backend/backend/data 存在持久状态，未设置变量的源代码
配置仍会使用它。如果两个位置都有状态，启动时必须明确选择，绝不会复制或合并。
打包的 npm/Homebrew 启动器默认使用 ~/.libre-webui，并从调用者工作目录解析明确的
相对 DATA_DIR。Docker 和 Kubernetes 部署提供绝对容器路径。
SQLite 文件名为 data.sqlite。
示例：
DATA_DIR=/var/lib/libre-webui
SQLite 存储的内容
- 用户和角色
- 会话和消息
- 偏好与界面设置
- 文档和分块
- 角色及角色设置
- 角色记忆和变异状态
- 插件凭据及其路由/身份验证绑定、变量、用户激活状态、可写定义批准和已发现模型目录
- 系统设置
- Work 任务所有权、模型/提供商路由、运行、消息、工具活动、状态和 Docker 资源标识符
敏感值通过加密存储辅助程序时在应用层加密。
Work 存储是分离的
Work 对话和任务元数据位于 SQLite，但 Work 文件不在其中。每个任务都有专用命名
Docker 卷，挂载到 /workspace。容器是可替换执行状态；命名卷才是任务的持久文件系统。
因此，仅备份数据库并不是完整 Work 备份。请使用 Docker 主机的卷备份流程备份对应
卷。Libre WebUI 使用 ai.libre-webui.managed=true 和所属任务 ID 标记托管卷。
删除 Work 任务会永久移除 SQLite 记录和托管命名卷。取消运行、停止预览或重启后端 不会删除其文件。
JSON 兼容性
旧版 Libre WebUI 使用 JSON 文件存储部分数据。当前版本以 SQLite 为主要路径，并将 访问封装在服务/模型层后，使应用其他部分无需了解持久化格式。
升级旧安装前，请备份整个数据目录。
.status.json 中的旧插件激活状态只会为升级时已有账户迁移一次，而且仅限与固定哈希
完全匹配的内置定义。旧自定义定义和影子定义会一直隔离，直到管理员重新导入；批准
不会恢复旧激活行。以后创建的账户不带活动插件，各账户的激活更改彼此独立。
备份
复制数据库前停止后端：
cp -R backend/data backend/data.backup
使用 DATA_DIR 的部署：
cp -R "$DATA_DIR" "$DATA_DIR.backup"
使用 Work 时，还要在后端停止期间备份所有托管命名卷。数据库、加密密钥和卷备份 必须来自同一时间点。
恢复
停止后端，用备份替换数据目录，然后重启。保留相同的 ENCRYPTION_KEY；其他密钥
无法解密现有值。
对于 Work，请在启动后端前，以恢复数据库中记录的准确名称恢复命名卷。Libre WebUI 可以重建任务容器，但无法从对话历史重建缺失的工作区文件。
运维说明
- SQLite 启用 WAL，以改善并发读取。
- 后端进程必须能写入数据目录。
- Docker 和 Kubernetes 中应把
DATA_DIR放在持久存储上。 - 将
ENCRYPTION_KEY与数据库一起备份。 - 测量、迁移或恢复存储时单独计算 Work 命名卷。