Cherry Studio V1 到 V2 升级迁移，先备份再迁移
为什么需要专门的升级指南
Cherry Studio V2 不是普通的功能迭代——它是架构级升级。主要变化：
| 维度 | V1 | V2 |
|---|---|---|
| 核心能力 | 对话助手为主 | 对话 + Agent 智能体 + 知识库 + 绘画 + 翻译 + MCP + 小程序 |
| 知识库结构 | V1 格式（本地嵌入） | V2 格式（支持本地/云端嵌入、数据源独立管理） |
| 对话结构 | 扁平对话列表 | 按助手分组的多对话架构 |
| 数据存储 | 单文件数据库 | 多文件分模块存储 |
| 启动台 | 无 | 九个内置应用入口 |
直接用 V2 覆盖 V1 安装包可能会导致数据不可用或丢失。必须按官方迁移流程来。
升级前必做：备份 V1 数据
- 找到 V1 的数据目录：
- Windows：
%APPDATA%\CherryStudio - macOS：
~/Library/Application Support/CherryStudio - Linux：
~/.config/CherryStudio
- 把整个目录完整复制一份到安全位置（外部硬盘、云盘、另一个本地路径）
- 给备份加个时间戳：
CherryStudio-V1-backup-2024-12-09/
备份是升级流程里最关键的一步——如果升级失败，用备份还原可以回到升级前状态。
V1 → V2 升级步骤
官方文档推荐用 V2.0.2 或以上版本完成迁移（早期 V2 版本迁移脚本有 bug）：
- 确认备份完成（上一步）
- 下载 V2 安装包，关闭 V1
- 运行 V2 安装包——会自动检测到 V1 并询问是否迁移数据
- 点「迁移」，V2 会读取 V1 数据、转换格式、导入到 V2 的新数据目录
- 迁移完成后打开 V2，检查助手列表、对话历史、知识库是否都在
如果 V2 安装包没有自动检测到 V1，手动操作：把 V1 数据目录整体复制到 V2 期望的位置，然后在 V2 设置 → 数据设置 → 导入 V1 数据里手动触发。
升级后检查项
V2 启动后逐个检查：
| 检查项 | 怎么验证 | 常见问题 |
|---|---|---|
| 助手列表 | 左侧助手都在 | 迁移失败时助手全丢了 |
| 对话历史 | 点进助手能看到之前的对话 | 部分对话可能格式不兼容 |
| 知识库 | 启动台 → 知识库 → 知识库列表都在 | 需重新索引（格式变了） |
| 模型服务商 | 设置 → 模型服务商 → 都在 | API Key 加密方式变了可能需要重新填 |
| Agent 配置 | 如果你之前自己写的 Agent，检查还在不在 | V1 没有 Agent，这块从零开始 |
知识库升级 V2 后需要重新索引全部数据源——因为 V2 知识库的嵌入和切分机制和 V1 不同。
V2 → V1 降级（回退）
升级后发现 V2 不符合预期想回到 V1？流程：
- 备份 V2 数据（当前状态）
- 卸载 V2（保留 V2 数据目录）
- 安装 V1
- 把升级前做的 V1 备份恢复到 V1 数据目录位置
- 启动 V1——应该能看到升级前的所有数据
⚠️ 回退不能用 V2 的数据——V2 数据目录格式 V1 读不懂。必须用升级前那一份 V1 备份。
数据迁移的几个坑
- 大知识库迁移慢：如果你的知识库有几百份文档，V2 迁移 + 重新索引可能要等几分钟甚至更久。保持耐心，不要中途关掉 Cherry Studio
- 自建嵌入模型：如果你在 V1 里用了自建的嵌入模型，V2 里可能需要重新配置端点——嵌入模型的 API 格式在 V2 里可能有变化
- 移动版同步：升级 V2 后如果之前用 V1 移动版同步过，V2 升级完成后建议在桌面端重新备份一次 WebDAV，移动端再恢复