Cherry Studio 跳过 V1 数据迁移为何现在会先清除已迁移数据并以默认状态启动 V2【免费下载链接】cherry-studio Cherry Studio 是一款支持多个 LLM 提供商的桌面客户端项目地址: https://gitcode.com/CherryHQ/cherry-studio本文面向 Cherry Studio 用户与维护者讲解 v2 数据迁移的跳过Skip行为变更从 2026-07-29 起在迁移失败界面选择不导入 V1 数据直接使用 V2程序会先清除本次迁移已写入新数据库的全部数据含已排程的 agent 任务再以默认数据启动 v2而 V1 原始数据与迁移过程中已复制的文件仍完整保留在磁盘上。读完本文你将理解这一行为背后的分步提交机制、跳过操作的完整执行链路与原子性保证以及界面上的 10 秒确认倒计时和各项操作的含义。变更背景迁移是分步提交的失败会留下半成品数据Cherry Studio 从 v1 升级到 v2 时数据迁移不是一个巨大的事务而是按迁移器Migrator逐个独立提交。在 MigrationEngine.run() 中可以看到每个迁移器依次经历 prepare含 dry-run 校验→ execute各自管理自己的事务→ validate 三个阶段任何一个迁移器失败都会让整次运行进入error阶段并标记失败状态但在此之前已经成功提交的迁移器数据会留在新数据库里。这正是本变更要解决的痛点一次跑到一半失败的迁移会让新数据库中混有已导入的部分数据 默认数据用户根本无法分辨哪些行来自旧版、哪些是默认生成的。旧的跳过逻辑只是把迁移状态标记为完成随后 v2 就启动在这堆部分导入行之上产生一个不干不净的起始状态。变更内容跳过 清空迁移产物 以默认数据启动自 2026-07-29PR #17593起行为变更如下迁移失败界面在更多选项More options下新增直接使用 V2 / Use V2 without importing V1 data入口选择该选项不再仅仅标记迁移完成而是先清除迁移已写入新数据库的一切包括已排程的 agent 任务然后以默认数据启动 v2V1 原始数据和迁移过程中已复制的文件仍然保留在磁盘上不会被删除无论跳过发生在迁移开始前、版本不兼容的安装上还是失败之后现在都产生完全一致的干净起始状态。界面入口三处共用同一个跳过对话框在 MigrationApp.tsx 中SkipMigrationDialog被三处复用场景入口位置触发方式迁移开始前介绍页右上角 More options 图标打开更多选项后选择直接使用 V2迁移失败后错误页的更多选项显示标签的按钮选择直接使用 V2版本不兼容时version_incompatible页面点击忽略迁移 / Ignore migration破坏性按钮错误页面的 More options 共提供三个常规选项顺序与 README.md 描述一致先保存诊断信息Save troubleshooting information→直接使用 V2不导入 V1 数据→继续使用 V1Continue using V1打开 V1 下载页对话框。每个选项都会等前一个对话框的关闭动画结束后再打开后续对话框避免遮罩重叠与焦点错乱。确认对话框10 秒倒计时的破坏性操作SkipMigrationDialog.tsx 实现了专门的破坏性确认对话框COUNTDOWN_SECONDS 10确认按钮初始为禁用态经过10 秒倒计时后才变为可点击按钮文案随倒计时变化I understand the risk, skip and restart ({{seconds}}s)倒计时结束后为I understand the risk, skip and restart对话框内以红色 Alert 标明高危操作High-risk action并列出四条要点中英文文案见 locales.ts 与 locales.ts已迁移到新数据库的记录将被清除如有新版将以默认数据启动旧版原始数据不会被删除仍保留在磁盘中但对话、设置、知识库等内容不会出现在新版中迁移过程中已复制的文件可能仍占用磁盘空间但不会出现在新版中仅当你确定要放弃本次自动迁移时继续。对话框可以随时取消Cancel 按钮 / 关闭 / Esc未确认前不会执行任何清理。主进程执行链路先清理导出目录再清库并标记完成Renderer 确认后调用migration:skip-migrationIPC主进程的处理器位于 MigrationIpcHandler.ts执行顺序如下并发保护若已有迁移在运行inFlightMigration非空直接抛出Migration is already in progress.绝不允许清理与正在写入的迁移交错执行清理导出临时目录cleanupExportDirectories()删除 Redux / Dexie / localStorage 三处登台的导出目录。注释明确说明清理必须先于状态写入成功否则下次启动会因状态已是completed而跳过迁移流程导致这些大体积快照永远无法被清理执行migrationEngine.skipMigration()关闭引擎并重启应用migrationWindowManager.restartApp()。底层实现skipMigration 的两阶段原子操作核心逻辑在 MigrationEngine.skipMigration()分两个阶段阶段一先恢复被迁移改动的 Boot 配置DB 之外bootConfigService.set(app.disable_hardware_acceleration, DefaultBootConfig[app.disable_hardware_acceleration]) bootConfigService.persist()源码注释解释了顺序的必要性先写 boot 配置再动数据库事务。如果 boot 写入失败数据库未受任何影响、状态保持原样用户可以重试或再次跳过反过来若先落库就可能出现状态已 completed 而迁移来的硬件加速配置永远保留的永久性不一致。被恢复的只有app.disable_hardware_acceleration这一个 v1 派生键见BootConfigMappings而app.user_data_path标识着迁移入口时固定的数据目录必须保留。阶段二同一事务内清库 写入 completed 状态const db this.getDb() db.transaction((tx) { this.clearMigrationData(tx) this.upsertMigrationStatus(tx, { status: completed, migratedFromV1: false, completedAt: Date.now(), version: 2.0.0, error: null }) }) this.migratedFromV1 false清库与状态写入在同一个数据库事务中完成二者要么全部成功、要么全部回滚。migratedFromV1: false会被needsMigration()与registerMigrationOriginReader读取确保后续启动把该配置档案识别为非 v1 迁移而来。清理范围MIGRATION_TARGET_TABLES 是唯一事实来源clearMigrationData(tx)MigrationEngine.ts逐表执行tx.delete(table).run()清理范围由常量 MIGRATION_TARGET_TABLES 统一定义——该常量同时被重试前的预清理verifyAndClearNewTables与跳过两条路径共享注释明确要求二者不得漂移。覆盖的表包括pin、ai_usage_record、tag/entity_tag、user_model/user_provider、message/topic、painting、assistant及其关联表、mcp_server、mini_app、preference、note、translate_*、knowledge_*、group、prompt_*以及 Agents 域全部表agent_*、agent_channel*、agent_session*、agent_workspace等与文件域引用表chat_message_file_ref、file_entry等。顺序严格按子表先于父表排列以规避外键引用问题。需要特别说明的例外job_schedule是 v2 任务系统共享的表清理时只删除type agent.task的迁移产物行绝不触碰其他类型调度tx.delete(jobScheduleTable).where(eq(jobScheduleTable.type, agent.task)).run()另外agent_task/agent_task_run_log已废弃并迁移至 JobManager不在清理清单内。测试如何验证这一行为MigrationEngine.skip.test.ts 用真实数据库覆盖了跳过路径的完整语义可作为理解实现的活文档清除迁移行与 agent.task 调度、保留其他调度预置一行preference和两条job_schedule一条agent.task、一条other.job执行skipMigration()后preference为空、job_schedule只剩other.job状态为completed / migratedFromV1: false / error: null恢复硬件加速默认值、不碰 user_data_path断言bootConfigService.set只收到app.disable_hardware_acceleration false且调用键列表不含app.user_data_pathboot 配置写失败时数据库分毫不动persist抛disk full后skipMigration()拒绝数据行与failed状态全部保持状态写入失败时回滚所有清除用 SQL 触发器在app_state插入前RAISE(ABORT)制造失败验证事务中先执行的删除语句被一并回滚与重试预清理共享同一份清理定义verifyAndClearNewTables()产生与跳过完全一致的效果。用户需要做什么无需任何操作什么都不用做——跳过行为是自动生效的。确认对话框会事先明确告知已迁移的记录将被清除V1 数据不会被删除迁移将不再被提示。并保留 10 秒倒计时后才可点击确认且随时可取消。如果你希望保留数据有两个替代选择重试Retry回到介绍页重新执行迁移——失败页的主操作按钮重试前会通过verifyAndClearNewTables先清空上次残留保证从干净库开始继续使用 V1Continue using V1在 More options 中选择打开V1DownloadDialog点击下载后由主进程MigrationIpcHandler根据向导当前语言解析地区化 V1 下载页中文环境走cherryai.com.cn/download/v1其余走cherryai.com/download/v1见 MigrationIpcHandler.ts。需要留意的是在部分失败后选择跳过你将看不到那些恰好在报错前被导入的少量助手、设置或会话——这正是本变更的预期行为用可预期的干净初始状态换取无法分辨的半成品数据。发布管理者注意事项Notes for Release Manager跳过操作永远不删除V1 数据目录也不删除迁移期间已复制的文件——这些文件只是在新数据库中不再有任何引用会继续占用磁盘空间。建议与本变更的发布说明配套向用户解释如何回收这部分磁盘空间例如手动清理对应目录迁移的completed状态一旦写入后续启动将不再进入迁移流程因此清理导出临时目录等收尾动作必须在状态写入前完成这一点已在 IPC 处理器中强制保证跳过后的启动依赖默认数据填充状态标记为completed后v2 的种子数据seeders会在启动时重新填充默认配置因此不必担心清库后应用无数据可用。小结跳过迁移从形式上结束迁移升级为真正回到干净的默认状态其背后是三重保障以MIGRATION_TARGET_TABLES为唯一事实来源的确定性清库、boot 配置恢复与数据库事务的两阶段顺序、以及清理必须先于状态写入的收尾纪律。对用户而言规则变得简单可预期选择跳过 放弃本次迁移结果但保留 V1 原件选择重试 从头再来选择继续使用 V1 回到旧版。【免费下载链接】cherry-studio Cherry Studio 是一款支持多个 LLM 提供商的桌面客户端项目地址: https://gitcode.com/CherryHQ/cherry-studio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Cherry Studio 跳过 V1 数据迁移为何现在会先清除已迁移数据并以默认状态启动 V2【免费下载链接】cherry-studio Cherry Studio 是一款支持多个 LLM 提供商的桌面客户端项目地址: https://gitcode.com/CherryHQ/cherry-studio本文面向 Cherry Studio 用户与维护者讲解 v2 数据迁移的跳过Skip行为变更从 2026-07-29 起在迁移失败界面选择不导入 V1 数据直接使用 V2程序会先清除本次迁移已写入新数据库的全部数据含已排程的 agent 任务再以默认数据启动 v2而 V1 原始数据与迁移过程中已复制的文件仍完整保留在磁盘上。读完本文你将理解这一行为背后的分步提交机制、跳过操作的完整执行链路与原子性保证以及界面上的 10 秒确认倒计时和各项操作的含义。变更背景迁移是分步提交的失败会留下半成品数据Cherry Studio 从 v1 升级到 v2 时数据迁移不是一个巨大的事务而是按迁移器Migrator逐个独立提交。在 MigrationEngine.run() 中可以看到每个迁移器依次经历 prepare含 dry-run 校验→ execute各自管理自己的事务→ validate 三个阶段任何一个迁移器失败都会让整次运行进入error阶段并标记失败状态但在此之前已经成功提交的迁移器数据会留在新数据库里。这正是本变更要解决的痛点一次跑到一半失败的迁移会让新数据库中混有已导入的部分数据 默认数据用户根本无法分辨哪些行来自旧版、哪些是默认生成的。旧的跳过逻辑只是把迁移状态标记为完成随后 v2 就启动在这堆部分导入行之上产生一个不干不净的起始状态。变更内容跳过 清空迁移产物 以默认数据启动自 2026-07-29PR #17593起行为变更如下迁移失败界面在更多选项More options下新增直接使用 V2 / Use V2 without importing V1 data入口选择该选项不再仅仅标记迁移完成而是先清除迁移已写入新数据库的一切包括已排程的 agent 任务然后以默认数据启动 v2V1 原始数据和迁移过程中已复制的文件仍然保留在磁盘上不会被删除无论跳过发生在迁移开始前、版本不兼容的安装上还是失败之后现在都产生完全一致的干净起始状态。界面入口三处共用同一个跳过对话框在 MigrationApp.tsx 中SkipMigrationDialog被三处复用场景入口位置触发方式迁移开始前介绍页右上角 More options 图标打开更多选项后选择直接使用 V2迁移失败后错误页的更多选项显示标签的按钮选择直接使用 V2版本不兼容时version_incompatible页面点击忽略迁移 / Ignore migration破坏性按钮错误页面的 More options 共提供三个常规选项顺序与 README.md 描述一致先保存诊断信息Save troubleshooting information→直接使用 V2不导入 V1 数据→继续使用 V1Continue using V1打开 V1 下载页对话框。每个选项都会等前一个对话框的关闭动画结束后再打开后续对话框避免遮罩重叠与焦点错乱。确认对话框10 秒倒计时的破坏性操作SkipMigrationDialog.tsx 实现了专门的破坏性确认对话框COUNTDOWN_SECONDS 10确认按钮初始为禁用态经过10 秒倒计时后才变为可点击按钮文案随倒计时变化I understand the risk, skip and restart ({{seconds}}s)倒计时结束后为I understand the risk, skip and restart对话框内以红色 Alert 标明高危操作High-risk action并列出四条要点中英文文案见 locales.ts 与 locales.ts已迁移到新数据库的记录将被清除如有新版将以默认数据启动旧版原始数据不会被删除仍保留在磁盘中但对话、设置、知识库等内容不会出现在新版中迁移过程中已复制的文件可能仍占用磁盘空间但不会出现在新版中仅当你确定要放弃本次自动迁移时继续。对话框可以随时取消Cancel 按钮 / 关闭 / Esc未确认前不会执行任何清理。主进程执行链路先清理导出目录再清库并标记完成Renderer 确认后调用migration:skip-migrationIPC主进程的处理器位于 MigrationIpcHandler.ts执行顺序如下并发保护若已有迁移在运行inFlightMigration非空直接抛出Migration is already in progress.绝不允许清理与正在写入的迁移交错执行清理导出临时目录cleanupExportDirectories()删除 Redux / Dexie / localStorage 三处登台的导出目录。注释明确说明清理必须先于状态写入成功否则下次启动会因状态已是completed而跳过迁移流程导致这些大体积快照永远无法被清理执行migrationEngine.skipMigration()关闭引擎并重启应用migrationWindowManager.restartApp()。底层实现skipMigration 的两阶段原子操作核心逻辑在 MigrationEngine.skipMigration()分两个阶段阶段一先恢复被迁移改动的 Boot 配置DB 之外bootConfigService.set(app.disable_hardware_acceleration, DefaultBootConfig[app.disable_hardware_acceleration]) bootConfigService.persist()源码注释解释了顺序的必要性先写 boot 配置再动数据库事务。如果 boot 写入失败数据库未受任何影响、状态保持原样用户可以重试或再次跳过反过来若先落库就可能出现状态已 completed 而迁移来的硬件加速配置永远保留的永久性不一致。被恢复的只有app.disable_hardware_acceleration这一个 v1 派生键见BootConfigMappings而app.user_data_path标识着迁移入口时固定的数据目录必须保留。阶段二同一事务内清库 写入 completed 状态const db this.getDb() db.transaction((tx) { this.clearMigrationData(tx) this.upsertMigrationStatus(tx, { status: completed, migratedFromV1: false, completedAt: Date.now(), version: 2.0.0, error: null }) }) this.migratedFromV1 false清库与状态写入在同一个数据库事务中完成二者要么全部成功、要么全部回滚。migratedFromV1: false会被needsMigration()与registerMigrationOriginReader读取确保后续启动把该配置档案识别为非 v1 迁移而来。清理范围MIGRATION_TARGET_TABLES 是唯一事实来源clearMigrationData(tx)MigrationEngine.ts逐表执行tx.delete(table).run()清理范围由常量 MIGRATION_TARGET_TABLES 统一定义——该常量同时被重试前的预清理verifyAndClearNewTables与跳过两条路径共享注释明确要求二者不得漂移。覆盖的表包括pin、ai_usage_record、tag/entity_tag、user_model/user_provider、message/topic、painting、assistant及其关联表、mcp_server、mini_app、preference、note、translate_*、knowledge_*、group、prompt_*以及 Agents 域全部表agent_*、agent_channel*、agent_session*、agent_workspace等与文件域引用表chat_message_file_ref、file_entry等。顺序严格按子表先于父表排列以规避外键引用问题。需要特别说明的例外job_schedule是 v2 任务系统共享的表清理时只删除type agent.task的迁移产物行绝不触碰其他类型调度tx.delete(jobScheduleTable).where(eq(jobScheduleTable.type, agent.task)).run()另外agent_task/agent_task_run_log已废弃并迁移至 JobManager不在清理清单内。测试如何验证这一行为MigrationEngine.skip.test.ts 用真实数据库覆盖了跳过路径的完整语义可作为理解实现的活文档清除迁移行与 agent.task 调度、保留其他调度预置一行preference和两条job_schedule一条agent.task、一条other.job执行skipMigration()后preference为空、job_schedule只剩other.job状态为completed / migratedFromV1: false / error: null恢复硬件加速默认值、不碰 user_data_path断言bootConfigService.set只收到app.disable_hardware_acceleration false且调用键列表不含app.user_data_pathboot 配置写失败时数据库分毫不动persist抛disk full后skipMigration()拒绝数据行与failed状态全部保持状态写入失败时回滚所有清除用 SQL 触发器在app_state插入前RAISE(ABORT)制造失败验证事务中先执行的删除语句被一并回滚与重试预清理共享同一份清理定义verifyAndClearNewTables()产生与跳过完全一致的效果。用户需要做什么无需任何操作什么都不用做——跳过行为是自动生效的。确认对话框会事先明确告知已迁移的记录将被清除V1 数据不会被删除迁移将不再被提示。并保留 10 秒倒计时后才可点击确认且随时可取消。如果你希望保留数据有两个替代选择重试Retry回到介绍页重新执行迁移——失败页的主操作按钮重试前会通过verifyAndClearNewTables先清空上次残留保证从干净库开始继续使用 V1Continue using V1在 More options 中选择打开V1DownloadDialog点击下载后由主进程MigrationIpcHandler根据向导当前语言解析地区化 V1 下载页中文环境走cherryai.com.cn/download/v1其余走cherryai.com/download/v1见 MigrationIpcHandler.ts。需要留意的是在部分失败后选择跳过你将看不到那些恰好在报错前被导入的少量助手、设置或会话——这正是本变更的预期行为用可预期的干净初始状态换取无法分辨的半成品数据。发布管理者注意事项Notes for Release Manager跳过操作永远不删除V1 数据目录也不删除迁移期间已复制的文件——这些文件只是在新数据库中不再有任何引用会继续占用磁盘空间。建议与本变更的发布说明配套向用户解释如何回收这部分磁盘空间例如手动清理对应目录迁移的completed状态一旦写入后续启动将不再进入迁移流程因此清理导出临时目录等收尾动作必须在状态写入前完成这一点已在 IPC 处理器中强制保证跳过后的启动依赖默认数据填充状态标记为completed后v2 的种子数据seeders会在启动时重新填充默认配置因此不必担心清库后应用无数据可用。小结跳过迁移从形式上结束迁移升级为真正回到干净的默认状态其背后是三重保障以MIGRATION_TARGET_TABLES为唯一事实来源的确定性清库、boot 配置恢复与数据库事务的两阶段顺序、以及清理必须先于状态写入的收尾纪律。对用户而言规则变得简单可预期选择跳过 放弃本次迁移结果但保留 V1 原件选择重试 从头再来选择继续使用 V1 回到旧版。【免费下载链接】cherry-studio Cherry Studio 是一款支持多个 LLM 提供商的桌面客户端项目地址: https://gitcode.com/CherryHQ/cherry-studio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
