数据管理

更新: 2026/10/06字数: 2106 字时长: 7 分钟

用 WebUI 的数据管理页可以把 MaiBot 的配置、数据、插件和日志打包成一个 zip 压缩包下载，也可以把这样的压缩包导回来，不用手动整目录拷贝。入口在侧边栏 高级工具 → 数据管理（地址 /data-transfer）。1.3.2 起该页新增了带 24 小时保留期的「导出历史」：导出完成后关掉页面甚至重启 MaiBot，都不影响重新下载。

页面分左右两栏：左边导出数据（下方是导出历史），右边导入数据；页面底部还有本地缓存清理工具（图片缓存、日志目录与数据库 VACUUM，与数据导入导出相互独立）。

导出数据

左侧「导出数据」卡片用于生成压缩包，默认范围就是最常见的配置与数据，直接点 开始导出 即可：

配置与数据（config / data） — 固定必选，复选框锁定不可取消，对应 MaiBot 目录下的 config/ 和 data/
已安装插件（plugins） — 可选，连带已安装插件及其目录内的配置和数据
日志（logs） — 可选，包含 logs/ 下的运行日志

导出是异步任务。点「开始导出」后，卡片内出现进度区：

当前阶段消息 — 正在扫描需要导出的文件 → 正在固定记忆图快照 → 正在写入压缩包 → 导出完成
进度明细 — 已处理文件数 / 总文件数、已处理字节 / 总字节，以及状态徽标和进度条
自动刷新 — 页面每约 1.2 秒拉一次任务进度，不用手动操作
取消导出 — 运行中点「取消导出」，任务状态变为 cancelled，已生成的半成品压缩包会被删除，不会留下可下载的文件
下载压缩包 — 完成后进度区出现该按钮；失败时进度区显示红色错误信息，并弹出「导出失败」提示
一个导出任务运行期间「开始导出」按钮不可点击，即同时只能有一个导出任务

导出历史

导出进度区下方是导出历史区，右上角有「刷新」按钮；列表为空显示「暂无导出记录」，加载失败显示红色错误。列表顶部固定写着一行提示：压缩包保留 24 小时，下载后重新计时；刷新页面仍可重新下载。

每条历史记录显示文件名、压缩包体积、完成时间，以及「保留至 <时间>」；文件过期或被删除后，该行显示「文件已过期或已删除」且下载按钮置灰。每行右侧两个按钮：

下载 — 重新下载该压缩包
删除 — 删除该条记录及其压缩包，成功后弹出「已删除导出记录和压缩包」

具体行为：

保留 24 小时 — 压缩包只保存在服务器系统临时目录（maibot_webui_transfer），不是持久目录；超时未下载会被自动清理
下载后续期 — 每次下载开始和完成时都会把保留期限重置为 24 小时；经常回来下载能让它一直留在历史里
可跨重启下载 — 历史记录持久化在临时目录，刷新页面或重启 MaiBot 后重新进入该页仍能下载
自动巡检 — MaiBot 启动时以及每小时内各巡检一次临时目录，清理失败 / 取消任务的残留、超过 24 小时的压缩包和重启遗留的临时项；正在写入或正在下载的会跳过
删除可能返回 409 — 任务仍在导出或正在下载时点「删除」，后端返回 409「任务仍在处理或下载中，请稍后删除」，页面弹「删除失败」提示；等任务结束后再删
升级兼容 — 从旧版本升级后，升级前已完整生成的压缩包会被自动补建历史记录；半成品不会获得下载入口

压缩包文件名

压缩包名为 maibot-data-<导出时间>.zip（如 maibot-data-20260709-123456.zip），下载到浏览器时按此命名。

导出内容与排除项

压缩包顶层固定包含一个 manifest.json，其余是按勾选范围打包的 config/、data/（以及可选的 plugins/、logs/）目录，包内路径与 MaiBot 目录内的相对路径一致。

manifest.json 记录数据包的元信息，导入时由后端校验：

manifest.json

json

{
  "format": "maibot-data-archive",
  "format_version": 1,
  "created_at": "2026-07-09T12:34:56.789012+00:00",
  "maibot_version": "1.3.2",
  "included": ["config", "data"],
  "parts": {
    "config": { "file_count": 12, "total_bytes": 1048576 },
    "data": { "file_count": 3456, "total_bytes": 209715200 }
  }
}

format — 固定为 maibot-data-archive
format_version — 固定为 1
created_at — 导出时间（UTC，ISO 8601 格式）
maibot_version — 导出时的 MaiBot 版本号
included — 实际包含的分块列表
parts — 各分块的文件数（file_count）与字节数（total_bytes）统计

以下内容不会被打进压缩包：

记忆运行锁 — data/.a_memorix_runtime_writer.lock 与 data/a-memorix/.a_memorix_runtime_writer.lock。锁文件不是业务数据，且 Windows 下持锁读取还会触发 PermissionError
推理预览图片 — 整个 data/prompt_imgs/ 目录。这些图片只用于在 WebUI 里查看历史推理过程，默认不随业务数据导出；要备份需手动复制该目录
符号链接 — 导出时直接跳过

另有两个内部行为值得知道：记忆图谱快照会先复制到临时目录再压缩，避免长时间压缩期间旧 generation 被轮换删除；单个文件读取失败时，错误信息会带上具体路径，形如：

导出文件失败 (data/mai.db): 另一个程序正在使用此文件

导入与恢复

右侧「导入数据」卡片用于从数据包恢复：

点文件选择框，选中一个 .zip 数据包（只接受本功能导出的包）
勾选要还原的分块：配置（config）、数据（data） 默认已勾选，插件（plugins）、日志（logs） 按需勾选；至少要选一个
点 开始导入

导入分两步：先把压缩包上传到服务器（显示上传百分比），再由后台任务按分块还原。进度区显示阶段消息（正在校验压缩包 → 正在导入文件 → 导入完成）、文件数、字节数和状态徽标，失败时显示具体错误。

导入前后端会校验压缩包：

必须有 manifest.json，且 format / format_version 正确，否则提示「压缩包缺少 manifest.json」「manifest.json 不是合法 JSON」或「不支持的数据包格式」
拒绝包含符号链接的包，提示「压缩包不允许包含符号链接」
拒绝 .. 路径穿越（「压缩包包含非法路径」）和四个分块之外的顶层目录（「压缩包包含不支持的顶层目录」）
通过校验的文件按包内路径直接写回 MaiBot 目录下的对应位置

导入会覆盖现有文件

导入前先备份当前数据（可用本页再导出一份留底），并确认版本一致：manifest.json 里记录了导出时的 MaiBot 版本，跨大版本恢复后要检查配置升级、数据库迁移和插件兼容性。导入完成后重启 MaiBot 再验证运行状态。

验证与排错

验证：点「开始导出」导出一份数据，等进度到 100% 后到「导出历史」点「下载」，解压得到的 zip 能看到 manifest.json 和 config/、data/ 目录，说明导出正常。

导出失败？

看进度区的红色错误信息：文件级失败会带具体路径（导出文件失败 (<包内路径>): <错误原因>)），按路径检查该文件是否可读
磁盘不足：logs/ 和 plugins/ 可能很大，先只带默认的 config+data 导出，或清理磁盘后重试
Windows 下记忆运行锁已被默认排除；仍报 PermissionError 时，检查是否有其他程序正在占用数据文件

历史里的下载按钮是灰的？

该条超过 24 小时未下载，压缩包已被自动清理，显示「文件已过期或已删除」，重新导出即可
每次下载都会把保留期重置为 24 小时

删除记录提示「任务仍在处理或下载中」？

409 表示导出任务还在运行，或压缩包正在被下载，等进度结束、下载完成后再删

导入报错？

「请上传 .zip 格式的数据包」— 只支持 .zip
「压缩包缺少 manifest.json」「不支持的数据包格式」— 包不是由本功能导出的
「压缩包包含不支持的顶层目录」「压缩包包含非法路径」「压缩包不允许包含符号链接」— 压缩包被改动过，换原始导出包重试
一个范围都没勾时，页面提示「请至少选择一个导入范围」

数据管理 ​

导出数据 ​

导出历史 ​

导出内容与排除项 ​

导入与恢复 ​

验证与排错 ​

相关文档 ​