# 备份与恢复

**备份与恢复** 让你为 QwenPaw 实例建立备份：可视化创建、导出、导入、还原整个智能体环境。适合**版本升级前回滚、跨设备迁移、试验性改动前留底**等场景。

> 侧边栏：**设置 → 备份**

---

## 备份里包含什么

一个备份 = 一个 zip 包（位于 `~/.qwenpaw.backups/<backup_id>.zip`），最多包含以下四类内容：

| 模块             | 物理路径                            | 实际内容                                                                                                                  |
| ---------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| **智能体工作区** | `~/.qwenpaw/workspaces/<agent_id>/` | 每个智能体工作目录下的全部文件，例如人设文件、记忆、技能、聊天历史、频道配置（含 `bot_token`、`app_secret` 等渠道凭据）。 |
| **全局设置**     | `~/.qwenpaw/config.json`            | 运行参数、安全规则等全局设置。                                                                                            |
| **技能池**       | `~/.qwenpaw/skill_pool/`            | 全局共享的技能仓库。                                                                                                      |
| **密钥信息**     | `~/.qwenpaw.secret/`                | **LLM 模型提供商配置（含 API Key）**、工具与技能用到的环境变量等密钥信息。                                                |

> **不会被打包的内容**：本地模型权重（体积大、可在目标机器重新下载）、运行时缓存、临时文件。

每个备份的 zip 内部目录结构如下：

```
<backup_id>.zip
├─ meta.json                        # 备份元数据（id / 名称 / 创建时间 / 范围 / Agent 数）
└─ data/
   ├─ config.json                   # 仅当包含「全局设置」时存在
   ├─ workspaces/<agent_id>/...     # 按勾选的 Agent 打包
   ├─ skill_pool/...                # 仅当包含「技能池」时存在
   └─ secrets/...                   # 仅当包含「密钥信息」时存在
```

备份 ID 的格式为 `qwenpaw-<version>-<timestamp>-<short8>`，便于在多台设备间识别版本与生成时间。

> **提示**：模型提供商的 API Key 属于「密钥信息」而**不在「全局设置」里**；如果只备份了全局设置而没有备份密钥信息，恢复后需要在控制台重新填入模型 API Key。

---

## 如何创建备份

控制台 → **设置 → 备份**。点击右上角的 **创建备份**，对话框默认创建**完整备份**，也可切换到**部分备份**：

| 模式         | 行为                                                                                                                                   |
| ------------ | -------------------------------------------------------------------------------------------------------------------------------------- |
| **完整备份** | **一键打包全部四类内容**：所有智能体工作区 + 全局设置 + 技能池 + **密钥信息**。无需逐项勾选，但会显式提示包含敏感信息。                |
| **部分备份** | 分别勾选要纳入备份的内容：① 智能体工作区（并选择具体的 Agent）② 全局设置 ③ 技能池 ④ 密钥信息。**密钥默认不勾选**，避免无意中分发凭证。 |

> 即使是「完整备份」，也只覆盖上面四类静态资源——本地模型权重不会被纳入，需在目标机器重新下载。

### 完整备份

![创建完整备份](https://img.alicdn.com/imgextra/i3/O1CN01lMb2N81Wh9e3WnYPG_!!6000000002819-2-tps-882-928.png)

完整备份适合作为「全量快照」：

1. 点击右上角 **创建备份**。
2. 默认就是**完整模式**，无需修改任何选项。
3. 填写备份名称与可选描述。
4. 注意红色的**敏感信息提醒**——完整备份会一并打包密钥目录。
5. 点击 **创建**。

### 部分备份

部分备份适合「只迁移特定模块」或「仅同步某几个智能体」：

1. 点击右上角 **创建备份**，切换到 **部分备份**。
2. 按需勾选：
   - **智能体工作区**：勾选后再选择具体要备份的智能体工作区。
   - **全局设置**：是否包含全局设置（对应 `config.json`）。
   - **技能池**：是否包含技能池（对应 `skill_pool/` 目录）。
   - **密钥信息**：是否包含密钥信息（对应 `~/.qwenpaw.secret/` 目录）。默认关闭，开启时同样会有红色敏感信息提醒。
3. 填写名称与描述，点击 **创建**。

---

## 如何恢复备份

> ⚠️ 恢复操作**不可逆**。请在执行前先阅读「恢复前备份」一节。

### 恢复前备份

![创建恢复前备份](https://img.alicdn.com/imgextra/i4/O1CN01xIWPgV1bBcS9THtY8_!!6000000003427-2-tps-866-273.png)

点击列表上任意备份的 **恢复** 按钮后，系统会先弹出 **恢复前备份** 对话框：

- 强烈建议先勾选「先创建恢复前备份」选项，一键留一份当前状态的快照。
- 出现问题时，可立刻用这份快照回退到执行恢复前的状态。

### 两种恢复模式

| 模式           | 适用场景                                 | 行为                                                                           |
| -------------- | ---------------------------------------- | ------------------------------------------------------------------------------ |
| **整体恢复**   | 完全回滚到备份时刻；接收完整迁移         | 用备份内容**完全替换**当前实例（含智能体注册表、全局设置、技能池、密钥）。     |
| **自定义恢复** | 仅迁移部分模块、保留未在恢复范围内的模块 | **逐项**选择要恢复哪些模块、哪些智能体；未在恢复范围内的本地内容**保持不动**。 |

### 整体恢复

**完全替换**当前实例的内容：

- 原实例的智能体工作区全部被备份中包含的所有智能体工作区覆盖。
- 全局设置、技能池、密钥一并替换。

操作步骤：

1. 在恢复对话框中切换到 **整体恢复**。
2. 手动勾选「我确认要恢复此备份」二次确认。
3. 点击 **开始恢复**。

### 自定义恢复

**精细化控制要恢复的内容**，避免误删：

- **逐个智能体选择**：可以恢复勾选的部分智能体，未在恢复范围内的智能体仍然保留。可以在恢复时指定要恢复的新增智能体的默认存储位置，如果未指定默认放置在 `~/.qwenpaw/workspaces/<agent_id>/`。
- **全局设置 / 技能池 / 密钥**：可独立选择是否恢复，恢复即完全替换当前实例已有的内容。

操作步骤：

1. 在恢复对话框中保持 **自定义恢复**（默认选项）。
2. 在恢复框里填写智能体默认存放位置（仅当备份里有新智能体时）。
3. 在智能体列表中勾选要恢复的智能体。
4. 勾选是否恢复全局设置 / 技能池 / 密钥信息。
5. 点击 **开始恢复**。

![自定义恢复](https://img.alicdn.com/imgextra/i2/O1CN01rObfhL23GTtnvidfq_!!6000000007228-2-tps-1131-1396.png)

---

## 导出 / 导入 / 删除

| 操作     | 说明                                                                                                                                        |
| -------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| **导出** | 在列表中点击 **导出**，下载该备份的 `.zip` 文件，方便归档或迁移到另一台设备。                                                               |
| **导入** | 点击页面顶部 **导入备份**，选择本地 `.zip` 文件。如果备份 ID 与现有备份冲突，系统会弹出**覆盖确认**——确认后无需重新上传，直接续传完成导入。 |
| **删除** | 单条删除或批量勾选删除；删除即时清理磁盘上的 zip 文件。                                                                                     |

---

## 安全提示

- 备份文件**可能包含敏感凭证**：完整备份默认会打包密钥信息（模型 API Key、加密主密钥、控制台登录凭证等）；即使是部分备份，智能体设置中也包含频道凭据（`bot_token`、`app_secret` 等）。**请妥善保管备份文件，不要分享给他人。**
- 跨设备迁移时，**本地模型权重不会被打包**，请在目标设备上重新下载所需模型。
- 恢复完成后请**重启服务**以使新配置完全生效。

---

## 典型使用场景

| 场景             | 建议操作                                                       |
| ---------------- | -------------------------------------------------------------- |
| 大版本升级前     | 创建一次「完整备份」，万一升级出问题可一键回退                 |
| 试验性改动前     | 改动前点击 **恢复** 时勾选「先创建恢复前备份」即可             |
| 仅迁移部分智能体 | 创建部分备份只勾选需要的智能体，恢复时使用 **自定义恢复** 模式 |

---

## 备份文件存储

| 项目     | 路径 / 默认值                |
| -------- | ---------------------------- |
| 备份目录 | `~/.qwenpaw.backups/`        |
| 单个备份 | `<备份目录>/<backup_id>.zip` |

---

## Docker 用户注意事项

Docker 容器内备份目录为 `/app/working.backups`。如果你使用 Docker 部署，需要挂载该目录以确保备份数据持久化，否则容器重建后所有备份将丢失。

在 `docker run` 中添加 `-v qwenpaw-backups:/app/working.backups`：

```bash
docker run -p 127.0.0.1:8088:8088 \
  -v qwenpaw-data:/app/working \
  -v qwenpaw-secrets:/app/working.secret \
  -v qwenpaw-backups:/app/working.backups \
  agentscope/qwenpaw:latest
```

---

## 常见问题

**Q：备份会包含本地下载的模型吗？**
A：不会。模型体积过大，备份只覆盖配置、技能、记忆等小体量资产。迁移到新机器后请重新下载所需模型。

**Q：导入时提示「备份已存在」怎么办？**
A：QwenPaw 会弹出覆盖确认；确认后即可继续导入并覆盖原备份。

**Q：完整恢复和部分恢复有什么本质区别？**
A：完整恢复是恢复备份时的整个实例，可以理解成「旧的实例删除 → 创建新实例」；部分恢复是恢复你选择的部分内容（如部分智能体），不在恢复范围内的其他内容仍然保留。

---

## 相关页面

- [控制台](./console) — 备份页面位于「设置」分组
- [配置与工作目录](./config) — `config.json`、工作目录、环境变量
- [多智能体](./multi-agent) — Agent 工作区结构
- [Skills](./skills) — 技能池与单 Agent 技能的关系
