备份与恢复

定期备份你的 Wesclaw 数据是保护重要信息的最佳实践。本文介绍如何备份、恢复数据，以及如何迁移到新设备。

功能概述

Wesclaw 的备份系统支持：

完整备份：备份所有数据（对话、记忆、知识库、配置等）
选择性备份：只备份特定类型的数据
自动备份：配置定时自动备份
一键恢复：从备份文件恢复所有数据
跨设备迁移：将数据从一台设备迁移到另一台

数据目录概览

在开始备份之前，了解 Wesclaw 的数据结构有助于你做出更好的选择：

wesclaw/                              # 数据根目录
├── hypervisor.db                     # Cell 注册信息
├── secrets/spec.key                  # 加密密钥（⚠️ 重要）
├── cells/main/                       # 主 Cell 数据
│   ├── meta.db                       # 元数据
│   ├── sessions.db                   # 对话和消息
│   ├── state.db                      # 运行时状态（traces 等）
│   ├── skills/                       # 已安装的技能
│   ├── knowledge/                    # 知识库文件
│   └── workspace/                    # 工作区产出文件
├── db/
│   └── wesclaw.db                    # 应用层数据
├── logs/                             # 日志文件
└── crashes/                          # 崩溃日志

数据	重要性	是否包含在完整备份中
对话历史（sessions.db）	⭐⭐⭐⭐⭐	✅
记忆数据（sessions.db）	⭐⭐⭐⭐⭐	✅
知识库文件	⭐⭐⭐⭐	✅
Agent 配置	⭐⭐⭐⭐	✅
技能文件	⭐⭐⭐	✅
应用设置	⭐⭐⭐	✅
加密密钥	⭐⭐⭐⭐⭐	⚠️ 单独处理
日志文件	⭐	❌
崩溃报告	⭐	❌

自动备份

配置自动备份

推荐设置定时自动备份，防止数据意外丢失。

方式一：通过设置界面

进入 设置 → 数据管理 → 备份
开启 自动备份
设置备份频率（推荐每周一次）
设置备份保存位置
设置保留数量（推荐保留最近 4 个）

方式二：通过定时任务

在对话中告诉 AI：

"帮我设置每周日凌晨 2 点自动备份所有数据，保存到 ~/wesclaw-backups/ 目录，保留最近 4 个备份"

自动备份配置参考

backup:
  enabled: true
  schedule: "0 2 * * 0"           # 每周日凌晨 2 点
  destination: "~/wesclaw-backups" # 备份保存位置
  retention: 4                     # 保留最近 4 个备份
  include_workspace: true          # 包含工作区文件
  notify_on_failure: true          # 失败时通知

自动备份的工作原理

到达设定时间后，系统创建一致性快照
使用 SQLite 安全备份机制（VACUUM INTO），确保数据完整性
将快照打包为 .tar.gz 文件
保存到指定目录
删除超出保留数量的旧备份
记录备份状态和结果

手动备份

完整备份

方式一：通过应用界面

进入 设置 → 数据管理 → 备份
点击 立即备份
选择备份选项：
- ☑ 对话历史
- ☑ 记忆数据
- ☑ 知识库
- ☑ Agent 配置
- ☑ 技能
- ☑ 应用设置
- ☐ 工作区文件（可选，可能很大）
选择保存位置
等待备份完成

方式二：通过对话

"帮我备份所有数据到桌面"

方式三：手动复制数据目录

# macOS
cp -r ~/Library/Application\ Support/wesclaw/ ~/wesclaw-backup-$(date +%Y%m%d)/

# Linux
cp -r ~/.local/share/wesclaw/ ~/wesclaw-backup-$(date +%Y%m%d)/

# Windows (PowerShell)
Copy-Item -Recurse "$env:APPDATA\wesclaw" ".\wesclaw-backup-$(Get-Date -Format yyyyMMdd)"

⚠️ 重要：手动复制时，请确保 Wesclaw 应用已关闭，否则可能复制到不一致的数据库文件。

选择性备份

如果你只需要备份特定数据：

只备份对话历史：

# 备份 sessions.db（包含对话和记忆）
cp ~/Library/Application\ Support/wesclaw/cells/main/sessions.db ~/backup-sessions.db

只备份知识库：

# 备份知识库目录
cp -r ~/Library/Application\ Support/wesclaw/cells/main/knowledge/ ~/backup-knowledge/

数据恢复

从完整备份恢复

关闭 Wesclaw 应用
进入 设置 → 数据管理 → 恢复
选择备份文件（.tar.gz）
选择恢复选项：
- 完全恢复：用备份数据替换当前所有数据
- 合并恢复：将备份数据与当前数据合并
确认恢复操作
等待恢复完成
重启 Wesclaw

手动恢复

如果应用无法启动，可以手动恢复：

# 1. 确保 Wesclaw 已关闭

# 2. 备份当前数据（以防万一）
mv ~/Library/Application\ Support/wesclaw/ ~/wesclaw-current-backup/

# 3. 解压备份文件
tar -xzf ~/wesclaw-backup-20260901.tar.gz -C ~/Library/Application\ Support/

# 4. 启动 Wesclaw

恢复单一数据类型

如果只想恢复特定数据：

# 只恢复对话（先关闭 Wesclaw）
cp ~/backup-sessions.db ~/Library/Application\ Support/wesclaw/cells/main/sessions.db

⚠️ 警告：恢复操作会覆盖对应的现有数据。恢复前请确认已做好当前数据的备份。

迁移到新设备

完整迁移流程

将 Wesclaw 的所有数据从旧设备迁移到新设备：

步骤一：在旧设备上导出

打开旧设备上的 Wesclaw
进入 设置 → 数据管理 → 备份
执行 完整备份
将备份文件传输到新设备（通过 U 盘、云盘、AirDrop 等）

步骤二：在新设备上安装

在新设备上安装 Wesclaw
首次启动，完成基本设置
进入 设置 → 数据管理 → 恢复
选择从旧设备传来的备份文件
选择 完全恢复
等待恢复完成

步骤三：重新配置敏感信息

由于安全原因，以下信息需要在新设备上重新配置：

LLM API 密钥：需要重新输入各 Provider 的 API Key
IM 渠道凭证：企业微信/飞书等的 Bot Token
登录状态：需要重新登录 WES 平台

说明：API 密钥等敏感信息使用加密存储，加密密钥文件（spec.key）绑定当前设备，不包含在标准备份中。如果你需要在新设备上还原原有的密钥，需要单独复制 secrets/spec.key 文件。

跨平台迁移

Wesclaw 的数据格式跨平台兼容：

迁移方向	是否支持	注意事项
macOS → macOS	✅	完全兼容
macOS → Windows	✅	路径会自动适配
macOS → Linux	✅	路径会自动适配
Windows → macOS	✅	路径会自动适配
Windows → Linux	✅	路径会自动适配
桌面 → SaaS	⚠️	需要通过导入功能
SaaS → 桌面	⚠️	需要通过导出功能

版本管理

备份文件命名

自动备份使用以下命名格式：

wesclaw-backup-2026-09-14T020000.tar.gz
wesclaw-backup-2026-09-07T020000.tar.gz
wesclaw-backup-2026-08-31T020000.tar.gz
wesclaw-backup-2026-08-24T020000.tar.gz

查看备份历史

在 设置 → 数据管理 → 备份历史 中查看：

信息	说明
备份时间	何时创建的备份
文件大小	备份文件的大小
数据范围	包含哪些数据类型
备份状态	成功 / 失败 / 部分成功
存储位置	备份文件的保存路径

备份保留策略

策略	说明	推荐场景
保留最近 N 个	只保留最新的 N 个备份	日常使用
保留 N 天内	保留指定天数内的备份	合规要求
全部保留	不自动删除	存储充裕时

灾难恢复

数据损坏修复

如果 Wesclaw 数据库损坏导致应用无法启动：

Wesclaw 内置了三层数据韧性机制，大多数情况下会自动修复
如果自动修复失败，系统会降级启动（部分功能可能不可用）
损坏的数据库文件会被归档到 corrupt/ 目录供诊断
你可以从最近的备份恢复数据

应急操作

当一切方法都失效时的最后手段：

# 1. 关闭 Wesclaw

# 2. 将现有数据目录改名保留
mv ~/Library/Application\ Support/wesclaw/ ~/Library/Application\ Support/wesclaw-damaged/

# 3. 启动 Wesclaw（将以全新状态启动）

# 4. 如果有备份，执行恢复操作

# 5. 如果没有备份，可以尝试从损坏目录中手动恢复部分数据

注意事项

备份安全

备份文件可能包含你的对话内容和个人偏好，请妥善保管
不要将备份文件上传到公共云存储
如果备份到云盘，建议使用加密功能
定期验证备份文件的完整性

恢复风险

恢复操作会覆盖现有数据，请先备份当前数据
恢复过程中不要关闭应用或关机
如果恢复失败，可以从刚才的备份中再次恢复
大量数据的恢复可能需要几分钟时间

存储空间

定期检查备份目录的磁盘占用
设置合理的保留策略，避免占用过多空间
知识库文件可能占据备份的大部分空间

常见问题

Q: 备份文件有多大？

A: 取决于你的数据量。典型的个人使用，备份文件通常在 10MB 到 500MB 之间。如果有大量知识库文件，可能会更大。

Q: 恢复后 API 密钥还在吗？

A: 这取决于你是否同时迁移了加密密钥文件（spec.key）。如果只恢复标准备份而不包含密钥文件，API 密钥将需要重新配置。这是出于安全考虑的设计。

Q: 可以在多台设备之间同步数据吗？

A: Wesclaw 目前不提供实时数据同步功能。你可以通过手动备份和恢复在设备之间传输数据。SaaS 版的数据存储在云端，可以从任何设备访问。

Q: 自动备份会影响性能吗？

A: 自动备份使用 SQLite 安全备份机制，对正常使用的影响极小。建议将备份安排在低使用时段（如凌晨）。

Q: 备份能保存多少天前的数据？

A: 备份保存的是执行备份时的完整数据快照。如果你的对话历史包含 6 个月前的数据，那么备份也会包含这些数据。备份的保留策略（保留几个备份）是独立的设置。

Q: 旧版本的备份能在新版本中恢复吗？

A: 通常可以。Wesclaw 的数据库迁移机制支持从旧版本格式自动升级到新版本。如果遇到不兼容的情况，恢复过程中会提示你。