跳到主要内容

数据可移植性

Libre WebUI 可以从 设置 → 数据管理 导出和导入按用户划分的版本化 JSON 存档。它用于在 Libre WebUI 安装之间移动受支持的个人数据，或将其恢复到某个账户。它不是完整服务器备份。

存档版本 3​

当前格式由以下内容标识：

{
  "format": "libre-webui-user-data",
  "version": 3,
  "integrity": {
    "algorithm": "sha256",
    "canonicalization": "libre-json-sort-v1",
    "digest": "<64 lowercase hexadecimal characters>"
  }
}

后端通过经过身份验证、限定到用户的数据库查询创建导出，其中包含：

  • 用户偏好设置，但不包括选中的可复用声音配置引用；
  • 聊天文件夹；
  • 聊天会话、消息、分支、评分、构件和每个聊天的设置；
  • 独立 Notes，包括固定状态；
  • 知识集合；
  • 提取的文档内容和元数据、会话/集合关联及文本片段。

文档嵌入是派生数据，因此不会导出。启用语义检索时，请在导入后重新生成嵌入。存档携带 RAG 使用的提取文本，而不是原始上传文件字节，因此无法逐字节重建原文件。

每个存档包含 exclusions 列表。版本 3 有意排除：

  • 账户、密码、登录会话和 OAuth 状态；
  • 提供商凭据和加密插件变量；
  • 克隆声音的参考录音和文本，它们属于生物识别数据，需要单独的同意处理；
  • 角色和角色记忆；
  • 生成图片、音频和视频的媒体库文件；
  • 笔记修订历史和附件；
  • Work 任务、运行、沙盒以及 Docker 或 Kubernetes 卷。

频道、通知、日历和自动化也不在可移植存档中；它们属于实例/团队状态，随完整服务器备份迁移。

完整服务器恢复应使用数据库/数据目录备份和相同的 ENCRYPTION_KEY。Work 还需要一致备份命名卷。参阅 SQLite 迁移与备份和 Work 工作区。

完整性与导出验证​

版本 3 使用 SHA-256 完整性摘要保护存档载荷。libre-json-sort-v1 规范形式省略顶层 integrity 字段，按字典顺序排序每个 JSON 对象的键，保留数组顺序，并以 UTF-8 对生成的紧凑 JSON 计算哈希。即使 JSON 语法有效，只要摘要不匹配，导入也会拒绝版本 3 存档。

该摘要可检测意外损坏和导出后的修改。它不是数字签名，不能验证文件创建者，也不会让存档保密。请像保护用户私人聊天和 Notes 的其他副本一样保护存档。

在提供下载前，导出会执行与导入相同的架构、字段大小、ID 和存档数量检查，并确认 Web UI 下载的格式化 JSON 不超过 50 MiB 上传限制。Libre WebUI 会返回准确的验证错误，而不是提供已知无法恢复的文件。

当前存档和账户限制：

  • 每个上传或生成的存档 50 MiB；
  • 100 个聊天文件夹；
  • 5,000 个聊天会话；
  • 100,000 条聊天消息；
  • 100 个 Notes，标题最多 200 个字符，内容最多 200,000 个字符；
  • 5,000 个知识集合；
  • 5,000 个文档；
  • 100,000 个文档片段；
  • 常规内容字段最多 2,000,000 个字符，ID 最多 256 个字符；运行时资源可采用更严格限制。

安全导入行为​

选择文件后，后端会立即预检。设置会显示传入总数、预计创建/覆盖/跳过数量、ID 重映射和迁移警告，然后才启用最终“导入”操作。更改冲突策略会重新计算预览。

预检会在可用时验证完整性摘要，迁移受支持的旧格式，验证完整架构、资源数量、唯一 ID、时间戳、内容边界和包含的关系，并在不写入的情况下规划冲突和引用重映射。悬空的文件夹、集合、消息父项或文档关联会被拒绝，而不是悄然丢弃。实际导入时后端会重复验证和规划。所有写入在 SQLite 和 PostgreSQL 中都位于单个数据库事务内；发生错误时，偏好设置、文件夹、会话/消息、Notes、集合、文档和片段会一起回滚。

有两种冲突策略：

  • 跳过重复项：保留 ID 匹配的记录并导入新记录。偏好设置与账户当前设置合并。
  • 覆盖现有项：替换 ID 匹配的记录。偏好设置覆盖 Libre WebUI 默认值。存档中缺少的记录绝不会删除。

两种策略对 ID 匹配的记录都具有幂等性。若某个 ID 已归目标服务器上的另一账户所有，Libre WebUI 会确定性重映射该 ID 及所有包含的引用。它绝不会覆盖或读取其他用户资源。对排除或不可用资源（如另一安装中的角色）的引用是已记录例外；预检会报告会话将在导入前分离。

设置中的结果会报告文件夹、会话、Notes、集合和文档的创建、覆盖与跳过数量。导入成功后，Libre 会重新加载偏好设置、聊天和文件夹，并刷新文档。

旧版存档​

导入器接受版本 2 libre-webui-user-data 存档，并在验证期间迁移到版本 3。版本 2 没有完整性摘要，也不含 Notes，因此 Libre 无法验证其来源或恢复从未导出的 Notes。预检会说明这两项限制。

导入器还接受旧版 libre-webui-export 版本 1.0 格式。该浏览器生成格式只含偏好设置及浏览器中已加载的会话。其 documents 数组始终为空，不含文件夹、Notes、知识集合或文档片段。Libre 会在导入前报告这些迁移限制。

HTTP 端点​

所有端点都需要经过身份验证的用户 Bearer 令牌或会话：

方法端点用途
GET/api/preferences/export构建当前用户的 v3 存档
POST/api/preferences/import/preflight在不写入的情况下验证和规划
POST/api/preferences/import在事务中验证和导入

Web UI 将存档作为名为 archive 的 multipart/form-data 字段发送，并将冲突策略作为 strategy 字段发送。上传限制为 50 MiB。对于较小的 API 迁移，两个 POST 端点也接受 JSON：

{
  "data": { "format": "libre-webui-user-data", "version": 3 },
  "strategy": "skip"
}

strategy 为 skip 或 overwrite。为兼容旧偏好设置客户端，mergeStrategy: "merge" 映射到 skip，mergeStrategy: "replace" 映射到 overwrite。