数据备份与清理

本页介绍本地数据的导出、导入和清理命令。导入或清理会修改现有数据,执行前建议先导出备份。

跨进程操作通过资源锁与维护锁互斥。正常进程退出或崩溃后可重新获取锁;如果提示“锁信息尚未就绪或已损坏”,先等待当前操作结束,持续出现时需确认所有使用该数据目录的 Loci 进程均已退出,再检查对应锁文件。运行期间不要手动删除锁文件。

导出与导入

如果更习惯浏览器,可以运行 loci ui,在“设置 → 备份与恢复”中下载或上传 ZIP。Web 导入上限为 512 MB;导入会替换当前本地库,存在活动同步或其他数据维护操作时会被拒绝。恢复结果立即生效;备份中含有定时抓取或云端每日同步时,会立即确保无 HTTP 的后台 worker 可用。默认数据目录使用登录自启动服务,自定义 LOCI_DATA_DIR 只启动 detached worker。

loci data export [file]

导出本地数据的 ZIP 备份。归档包含 index.json,文档源、正文、指定页面、抓取记录、域名规则、操作日志和设置分别保存在独立 JSON 文件中;索引记录每个文件的记录数、字节数和 SHA-256。省略文件路径时,CLI 会在最近使用的目录或当前目录生成带 UTC 毫秒时间的文件,并拒绝覆盖同名文件。

例如:

loci data export

生成的文件名类似 loci-backup-2026-08-04T01-02-03-456Z.zip。显式传入 [file] 时,由用户指定目标路径;如果文件已经存在,CLI 会直接覆盖。

loci data import [file]

从 ZIP 备份恢复数据,并覆盖当前本地数据。Loci 会先校验安全路径、索引、文件大小、记录数量、SHA-256 和数据引用,校验通过后显示文档源和文档数量并要求确认;校验或事务写入失败时保留原数据库。

例如:

loci data import ./backups/loci-2026-08-04.zip

省略文件参数时,交互终端会打开带补全的路径选择器,并只接受实际存在的文件。文件不是有效 Loci ZIP 归档时,CLI 会停止导入并提示检查备份来源。

非交互终端必须同时提供文件路径和 --yes:

loci data import ./backups/loci.zip --yes

备份中含有持久后台能力时,CLI 会在导入完成后确保后台 worker 可用;服务激活失败不会回滚已经恢复的数据,错误信息会给出手动启动和日志命令。默认数据目录会使用登录自启动服务;设置 LOCI_DATA_DIR 时只启动 detached worker,不保证注销或机器重启后恢复。

清理本地数据

loci data clear-documents

清空全部文档和全文索引,但保留文档源配置。之后可以重新同步文档源:

loci data clear-documents --yes
loci source sync <source>

loci data clear-sources

清空全部文档源、文档、全文索引和抓取历史:

loci data clear-sources --yes

交互终端省略 --yes 时会再次确认。非交互终端执行导入或清理命令时必须传入 --yes,避免脚本在无法显示确认提示时继续运行。

需要隔离数据目录或根据退出码处理结果时,请查看基础命令与运行设置。