Wox 备份与恢复插件（Backup and Restore Plugin）完整指南：触发命令、存储原理与自动备份机制

Wox 备份与恢复插件（Backup and Restore Plugin）完整指南：触发命令、存储原理与自动备份机制

【免费下载链接】WoxA cross-platform launcher that simply works项目地址: https://gitcode.com/gh_mirrors/wo/Wox

Wox 内置的 Backup and Restore 系统插件负责将 Wox 的用户数据目录整体导出为备份快照，并在需要时一键回滚，是重置数据目录或跨机器迁移配置前的标准安全操作。本文基于官方文档与源码实现，完整讲解backup/restore触发命令的用法、备份快照的存储格式与清理策略、以及自动备份与"更新前备份"等内置保护机制，帮助你掌握一套可复现、可验证的配置备份与恢复方案。

一、插件定位：何时需要手动备份

Backup 插件面向两种典型场景：重置数据目录之前，以及把当前设置迁移到另一台机器时。它做的事情本质上是对 Wox 用户数据目录做一次整体快照，后续可以随时把快照中的设置、数据原样还原回去。

如果你的目标是"多台设备长期保持配置一致"，官方文档更推荐使用 Cloud Sync：它能在不手动导出/导入的前提下持续同步设置，Backup 插件则更适合一次性、确定性的备份与还原。

从源码看，该插件是随 Wox 一起内置注册的系统插件，注册入口在 wox.core/plugin/system/backup.go：

func init() { plugin.AllSystemPlugin = append(plugin.AllSystemPlugin, &BackupPlugin{}) }

插件元数据声明了两个触发关键词restore与backup，并支持 Windows、macOS、Linux 三个平台（wox.core/plugin/system/backup.go）：

TriggerKeywords: []string{ "restore", "backup", }, SupportedOS: []string{ "Windows", "Macos", "Linux", },

因此在使用前无需安装任何额外组件，直接呼出 Wox 输入触发词即可。

二、快速上手：两条触发命令

2.1 backup —— 立即导出一次备份

在 Wox 搜索框中输入：

backup

插件会返回一个结果项（wox.core/plugin/system/backup.go），标题为"立即备份"（i18n 键plugin_backup_now），副标题提示这是一次手动备份。激活它后，底层会调用设置管理器的Backup(ctx, setting.BackupTypeManual)，即触发一次手动类型的备份：

backupErr := setting.GetSettingManager().Backup(ctx, setting.BackupTypeManual) if backupErr != nil { c.api.Notify(ctx, backupErr.Error()) } else { c.api.Notify(ctx, i18n.GetI18nManager().TranslateWox(ctx, "plugin_backup_success")) }

成功时 Wox 会弹出"备份成功"的系统通知；失败时则把错误信息原样通知给你。动作上还设置了PreventHideAfterAction: true，即执行备份后搜索窗口不会自动隐藏，方便连续操作。

2.2 restore —— 从历史快照还原

输入：

restore

插件会枚举当前机器上存在的全部备份快照，并按时间戳倒序排列（最新的排在最前，wox.core/plugin/system/backup.go），每一条记录渲染为一个结果项，标题为序号（#1、#2……），副标题展示备份类型 - 备份时间：

slices.SortFunc(backups, func(i, j setting.Backup) int { return int(j.Timestamp - i.Timestamp) })

每个还原项提供三个动作（wox.core/plugin/system/backup.go）：

动作	说明
恢复该备份	调用setting.GetSettingManager().Restore(ctx, backup.Id)执行还原；成功后弹出"恢复成功"通知，并延迟约 2 秒后自动退出 Wox（time.Sleep(2000 * time.Millisecond)后调用ui.GetUIManager().ExitApp(ctx)），确保应用以还原后的配置干净重启
打开备份文件夹	通过shell.Open(backup.Path)在系统文件管理器中打开该快照所在目录，便于人工检查或手工拷贝
（结果项）	若读取备份列表失败，则只返回一个"备份读取失败"结果项，副标题携带具体错误

还原是破坏性操作：它会用快照内容替换当前用户数据目录。执行前请确认该快照的备份时间与类型，避免覆盖掉你近期的新配置。

三、备份快照的存储位置与文件结构

3.1 目录约定

备份快照统一存放在 Wox 数据目录下的backup子目录中，该路径由Location.GetBackupDirectory()定义（wox.core/util/location.go）：

func (l *Location) GetBackupDirectory() string { return path.Join(l.woxDataDirectory, "backup") }

一次备份的完整流程（wox.core/setting/backup_restore.go）是：

1. 以当前系统时间戳（毫秒）作为备份文件夹名，例如<woxData>/backup/1691234567890；
2. 使用cp.Copy（otiai10/copy 库）将整个用户数据目录GetUserDataDirectory()递归复制到备份目录；
3. 生成一条备份元信息Backup，序列化为 JSON 写入快照目录内的backup.json：

   { "Id": "<uuid>", "Name": "1691234567890", "Timestamp": 1691234567890, "Type": "manual" }

4. 异步触发历史备份清理（cleanBackups）。

Backup结构体定义在 wox.core/setting/backup_restore.go：

type Backup struct { Id string Name string // backup folder name Timestamp int64 Type BackupType Path string // backup file path }

3.2 备份类型（BackupType）

源码定义了三种备份来源（wox.core/setting/backup_restore.go）：

类型常量	取值	触发场景
BackupTypeAuto	auto	设置项"自动备份"开启后，由StartAutoBackup定时循环触发
BackupTypeManual	manual	用户通过backup命令手动触发
BackupTypeUpdate	update	Wox 升级前自动备份（源码注释：backup before update Wox）

在restore的结果列表中，副标题会直接展示该类型字符串（如manual - 2026-09-19 04:00:00），据此可以区分快照来源。

3.3 备份发现与还原前的"逃生舱"

FindAllBackups（wox.core/setting/backup_restore.go）会扫描backup目录下每个子文件夹，跳过以temp_开头的临时目录，读取其中的backup.json反序列化为Backup记录并回填真实路径。

还原时（wox.core/setting/backup_restore.go）有一个值得注意的安全设计：不会直接覆盖当前数据目录，而是先把现有用户数据目录重命名为xxx.before_restore_<时间戳>（重名时自动追加_2、_3等后缀，见ensureUniquePath），再把备份快照复制回标准位置，最后删除还原进来的backup.json。这意味着：

• 即使还原失败，Restore也会尝试把原目录重新改回来，尽可能避免数据丢失；
• 还原成功后，改名前的目录仍保留在磁盘上，可作为最终的兜底副本手动检查或清理。

四、自动备份与保留策略

4.1 每天一次的自动备份循环

设置管理器在启动后会拉起一个常驻 goroutine（wox.core/setting/backup_restore.go），逻辑如下：

for range time.NewTimer(24 * time.Hour).C { settings := m.GetWoxSetting(ctx) if !settings.EnableAutoBackup.Get() { continue } backupErr := m.Backup(ctx, BackupTypeAuto) }

即：每 24 小时检查一次设置项EnableAutoBackup（"自动备份"），开启时执行一次auto类型备份。该开关是 Wox 通用设置的一部分，定义于 wox.core/setting/wox_setting.go，默认值为true（NewWoxSettingValue(store, "EnableAutoBackup", true)），并在设置界面（Data 设置的 Backup 区块）暴露为 "Automatic backup" 选项，切换逻辑见 wox.core/ui/launcher/data_settings.go。

4.2 最多保留 5 份快照

每次备份完成后会异步执行cleanBackups（wox.core/setting/backup_restore.go），保留策略为：最多保留 5 份，超出部分按时间戳升序排序后，把最旧的快照整目录删除：

maxBackups := 5 ... slices.SortFunc(backups, func(i, j Backup) int { return int(i.Timestamp - j.Timestamp) }) for i := 0; i < len(backups)-maxBackups; i++ { rmErr := os.RemoveAll(path.Join(util.GetLocation().GetBackupDirectory(), backups[i].Name)) }

因此不用担心备份无限堆积磁盘；但同时要留意，若你期望长期保留某个快照（例如升级前迁移场景），应在 5 份之外的旧快照被清理前，先手动把backup目录中的对应文件夹复制到安全位置。

五、进阶建议与注意事项

1. 迁移到新机器的标准流程：在新机器上先完成一次 Wox 首次配置，再用旧机器导出的快照（拷贝backup目录中的文件夹，或直接复制用户数据目录）通过restore还原；也可参考 Cloud Sync 实现免手动导出。
2. 还原后会自动退出：restore成功约 2 秒后 Wox 会自行退出，这是为了让设置以完整状态重新加载；此时应手动重新启动 Wox 验证效果。
3. "更新前备份"的保护：BackupTypeUpdate表明升级流程在覆盖数据前也会生成快照，配合 5 份保留策略，可为你提供最近几次升级前的回退点。
4. 随时人工确认：restore结果项中的"打开备份文件夹"动作，可在还原前直接进入系统文件管理器检查backup.json的Type与Timestamp，确认这是你真正想还原的快照。

相关源码与文档索引

• 插件实现：wox.core/plugin/system/backup.go
• 备份/还原/清理核心逻辑：wox.core/setting/backup_restore.go
• 备份目录位置：wox.core/util/location.go
• 自动备份设置项：wox.core/setting/wox_setting.go
• 设置界面相关：wox.core/ui/launcher/data_settings.go
• 官方文档原文：www/docs/guide/plugins/system/backup.md
• 替代方案 Cloud Sync：www/docs/guide/plugins/system/cloudsync.md

【免费下载链接】WoxA cross-platform launcher that simply works项目地址: https://gitcode.com/gh_mirrors/wo/Wox