数据与迁移
迁移或重装前需要备份什么？
至少备份以下内容：
data/ — 数据库、记忆、表情包及运行数据。
config/ — Bot、模型和其他主配置。
plugins/ — 已安装插件及插件目录内的配置和数据。
如果适配器或一键包在 MaiBot 目录外保存配置，也要单独备份。不要把 plugins 误认为位于 config 目录。
不想手动整目录拷贝时，改用 WebUI 一键导出，见下文「用 WebUI 数据管理页导出」。
用 WebUI 数据管理页导出
用 WebUI 的数据管理页导出压缩包：侧边栏进入 高级工具 → 数据管理（地址 /data-transfer）。导出是异步任务，页面显示实时进度，完成后直接在浏览器下载 zip，其中 config + data 固定必选，其余两项按需勾选：
plugins — 可选，连带已安装插件及其目录内的配置和数据。
logs — 可选，包含运行日志。
压缩包内含 manifest.json（记录导出时间、MaiBot 版本和各部分文件统计），导入时后端按 config / data / plugins / logs 四个分块还原，勾选需要的范围即可。
导出历史与 24 小时保留
导出卡片下方是导出历史列表，每条显示文件名、压缩包体积、完成时间和「保留至 <时间>」。
- 压缩包只存在服务器临时目录，保留 24 小时；每点击一次下载就重新计时。
- 保留期内刷新页面或重启 MaiBot 都能重新下载，历史记录持久化在临时目录，重新进入页面即恢复。
- 超过保留期后文件被自动清理，该条显示「文件已过期或已删除」，下载按钮置灰。
- 点「删除」可移除单条记录及其压缩包；任务仍在导出或正在下载时删除会返回 409，等它结束后再删。
不会被打包的内容
- 记忆运行锁
data/.a_memorix_runtime_writer.lock与data/a-memorix/.a_memorix_runtime_writer.lock；Windows 下持锁读取还会触发 PermissionError。 - 推理预览图片目录
data/prompt_imgs/，要备份这部分需手动复制该目录。 - 半成品：取消导出会连已生成的压缩包一起删除，任务状态变为
cancelled，不会获得下载入口。
怎样迁移到另一台设备或另一个目录？
- 停止 MaiBot、适配器和相关启动器。
- 备份完整目录，并记录当前版本。
- 在目标位置准备兼容版本和运行环境。
- 恢复
data、config、plugins及外部适配器配置。 - 检查配置中的绝对路径、端口、权限和网络地址。
- 启动后查看配置升级、数据库迁移和插件加载日志。
确认新位置运行正常后再删除旧副本。
如果用 WebUI 导出的压缩包恢复，包内 manifest.json 已记录导出时间、MaiBot 版本与各部分文件统计；导入时后端会校验 manifest，按 config / data / plugins / logs 分块还原，并在解包前拒绝符号链接、.. 路径穿越和白名单外的顶层目录。
恢复备份后无法启动怎么办？
重点检查源版本与目标版本是否兼容、配置是否需要升级、数据库迁移是否失败、插件是否支持当前版本，以及文件权限和绝对路径是否仍然有效。
不要在没有额外备份的情况下删除数据库或覆盖原始备份。
本地模型提示禁止访问非公网地址怎么办？
这是 WebUI 的出站 URL 安全校验。确认目标确实是可信的本地或内网模型服务后，可以关闭 enforce_public_outbound_url。关闭后 WebUI 将允许访问内网地址，也会降低防止服务端请求伪造的保护强度。
如果模型服务运行在 Docker 或另一台设备上，还要确认地址不是错误地使用了当前容器的 127.0.0.1。