数据备份与清理
本页介绍本地数据的导出、导入和清理命令。导入或清理会修改现有数据,执行前建议先导出备份。
跨进程操作通过资源锁与维护锁互斥。正常进程退出或崩溃后可重新获取锁;如果提示“锁信息尚未就绪或已损坏”,先等待当前操作结束,持续出现时需确认所有使用该数据目录的 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-backup-2026-08-04T01-02-03-456Z.zip。显式传入 [file] 时,由用户指定目标路径;如果文件已经存在,CLI 会直接覆盖。
loci data import [file]
从 ZIP 备份恢复数据,并覆盖当前本地数据。Loci 会先校验安全路径、索引、文件大小、记录数量、SHA-256 和数据引用,校验通过后显示文档源和文档数量并要求确认;校验或事务写入失败时保留原数据库。
例如:
省略文件参数时,交互终端会打开带补全的路径选择器,并只接受实际存在的文件。文件不是有效 Loci ZIP 归档时,CLI 会停止导入并提示检查备份来源。
非交互终端必须同时提供文件路径和 --yes:
备份中含有持久后台能力时,CLI 会在导入完成后确保后台 worker 可用;服务激活失败不会回滚已经恢复的数据,错误信息会给出手动启动和日志命令。默认数据目录会使用登录自启动服务;设置 LOCI_DATA_DIR 时只启动 detached worker,不保证注销或机器重启后恢复。
清理本地数据
loci data clear-documents
清空全部文档和全文索引,但保留文档源配置。之后可以重新同步文档源:
loci data clear-sources
清空全部文档源、文档、全文索引和抓取历史:
交互终端省略 --yes 时会再次确认。非交互终端执行导入或清理命令时必须传入 --yes,避免脚本在无法显示确认提示时继续运行。
需要隔离数据目录或根据退出码处理结果时,请查看基础命令与运行设置。