Cherry Studio Migration V2 迁移窗口剖析渲染进程驱动 V1→V2 数据迁移的完整实现【免费下载链接】cherry-studioAI productivity studio with smart chat, autonomous agents, and 300 assistants. Unified access to frontier LLMs项目地址: https://gitcode.com/GitHub_Trending/ch/cherry-studio导读Cherry Studio 在从旧版本V1向新架构V2演进时需要把用户存储在浏览器存储中的历史数据完整搬运到新库。Migration V2 Window正是为此设计的一个独立渲染进程窗口它不直接写盘而是通过 IPC 与主进程协作先由渲染进程把 Redux Persist、DexieIndexedDB与 localStorage 中的数据以有界分块的方式导出再由主进程在磁盘上拼装成迁移文件。本篇文章基于 src/renderer/windows/migrationV2/README.md 展开结合窗口启动、阶段状态机、数据导出器、故障诊断等源码实现帮助读者理解这一渲染进程导出 主进程落盘的迁移架构并掌握其 IPC 通道、分块策略与容错设计。目录结构一个窗口六类职责迁移窗口的全部代码集中在src/renderer/windows/migrationV2/目录下职责划分非常清晰src/renderer/windows/migrationV2/ ├── MigrationApp.tsx # UI shell 与阶段状态机唯一入口组件 ├── entryPoint.tsx # 窗口引导样式 i18n 初始化后挂载 MigrationApp ├── components/ # UI 组件进度列表、对话框、窗口控制、彩带动画 ├── hooks/ # 进度订阅 动作辅助IPC 封装 ├── exporters/ # 数据导出器Redux Persist / Dexie / localStorage ├── i18n/ # 迁移专用翻译资源与语言解析 └── index.html # HTML 入口通过 meta 声明日志窗口来源为 MigrationV2MigrationApp.tsx 是整个窗口的 UI 外壳与阶段逻辑核心entryPoint.tsx 负责在渲染前异步完成 i18n 初始化components/ 导出MigratorProgressList、SkipMigrationDialog、CloseMigrationDialog、MigrationWindowControls、Confetti、V1DownloadDialog、MigrationDiagnosticPanel等组件exporters/ 提供三个导出器ReduxExporter、DexieExporter、LocalStorageExporter。需要注意README.md中提到的components/与hooks/里实际有MigratorProgress、MigrationDiagnosticPanel等文件hooks/目录下则是useMigrationProgress.ts它同时导出了useMigrationProgress与useMigrationActions两个 hook见下文。窗口启动链路从meta声明到 React 挂载迁移窗口的启动分为三步index.html 声明日志来源HTML 中的meta namelogger-window-source contentMigrationV2 /告诉日志服务该窗口的日志来源标识为MigrationV2使主进程的日志采集能够区分这个预启动preboot窗口与主窗口。该文件同时声明了严格的 CSPdefault-src self并引入/windows/migrationV2/entryPoint.tsx作为模块脚本。entryPoint.tsx 初始化环境先引入全局样式renderer/assets/styles/index.css与tailwind.css然后调用initI18n()并等待其完成后才把MigrationApp挂载到#root。这一点很重要——如果 i18n 尚未就绪就渲染界面上会出现未翻译的 key 闪烁。MigrationApp.tsx 挂载并进入阶段状态机组件加载后立即通过 hook 订阅进度并在 header 中提供语言切换zh-CN/en-US与主题切换能力。i18n独立于偏好服务探测系统语言迁移窗口是预启动窗口此时preferenceService等主流程服务尚未就绪因此 resolver.ts 采用了独立探测策略function detectLanguage(): zh-CN | en-US { const browserLang navigator.language || navigator.languages?.[0] || en-US return browserLang.toLowerCase().includes(zh) ? zh-CN : en-US }只要系统语言包含zh含 zh、zh-CN、zh-TW、zh-HK 等即使用中文否则回退英文fallbackLng: en-US。另外翻译目录是扁平结构——migration.buttons.retry是一个完整的字面 key 而非嵌套路径所以初始化时显式设置了keySeparator: false。这个细节对于后续维护翻译文件非常关键新增 key 时必须保证全名唯一。阶段状态机五阶段向导迁移窗口的核心是一个由共享类型约束的阶段状态机。共享类型定义在 src/shared/data/migration/v2/types.tsexport type MigrationStage version_incompatible | introduction | migration | completed | errorMigrationApp.tsx中的stageStepNumber把阶段映射到步骤导轨StepRail的编号阶段步骤编号说明introduction1介绍页展示迁移特性与开始迁移按钮migration/error2迁移执行中 / 失败共用第二步失败时打叉completed3完成页展示统计摘要与重启按钮version_incompatible—版本不兼容页隐藏步骤导轨显示独立诊断面板状态机通过switch (stage)严格分支渲染且default分支调用assertNever(stage)——这是一个 TypeScript 穷尽性检查技巧如果未来新增阶段而没有处理编译期就会报错。README 的 Implementation Notes 也强调新增 UI 元素时应响应阶段状态机而不是引入临时 ad-hoc flag。值得注意的是MigrationApp内部还有一个本地错误闩锁localMigrationError某些runMigration失败发生在进度能可靠地推进到error之前此时本地状态会临时接管为 error 阶段一旦主进程推送的progress.stage离开error这个本地错误会被自动清空。进度消息的 i18n 化MigrationProgress类型同时支持两类消息纯文本的currentMessage和可翻译的i18nMessage含 key 与插值参数。progressMessage的 useMemo 逻辑是优先用t(progress.i18nMessage.key, progress.i18nMessage.params)翻译否则回退到currentMessage。这样主进程只需下发语义化的 key渲染进程负责按当前语言渲染避免跨进程传递已翻译文本。导出器三条数据通道一个共同原则README 的核心结论是渲染进程绝不直接写盘。三条导出通道都遵循渲染进程分块产出 → IPC 传给主进程 → 主进程落盘的协作模式。IPC 通道定义在同目录的共享类型中WriteExportFile: migration:write-export-file每次调用携带(exportPath, sliceName/tableName, chunk, writeMode)其中writeMode为overwrite | append——主进程在每个文件开头执行覆盖写之后按顺序追加有界块。ReduxExporter流式解码避免整串解析ReduxExporter.ts 处理localStorage中的persist:cherry-studio键。它不把整个 JSON 解析成对象那会显著抬高渲染进程峰值内存而是手工编写了一个 JSON 词法扫描器scanStringEnd/scanValueEnd跳过字符串字面量与嵌套{}/[]只定位每个 slice 的起止偏移visitPersistedSlices遍历根对象筛选出SLICES_TO_EXPORT中声明的 slice逐个回调writeSlice把每个 slice 的 JSON 字符串 token逐字符流式解码并解码\uXXXX等转义序列再按EXPORT_CHUNK_CHAR_LIMIT1 MiB分块写入。需要迁移的 Redux slice 有 13 个包括const SLICES_TO_EXPORT [ settings, // 应用设置与偏好 assistants, // 助手配置 knowledge, // 知识库元数据 llm, // LLM 提供方与模型配置 mcp, // MCP 服务器配置 minapps, // 迷你应用配置启用/禁用/置顶 note, // 笔记相关设置 selectionStore, // 划词助手设置 preprocess, // 文件预处理提供方配置 ocr, // OCR 提供方配置 websearch, // 联网搜索配置 codeTools, // 代码工具设置CLI 工具、模型、终端 paintings // 各提供方/模式的绘画历史供 PaintingMigrator 消费 ]分块时使用了共享工具 clampSurrogateBoundary 来保证不会把代理对surrogate pair即 emoji 等非 BMP 字符从中间截断。export()最终返回{ exportPath, slicesFound, slicesMissing }供主进程和日志核对缺失情况。DexieExporter主键分页 单记录驻留DexieExporter.ts 负责导出遗留 V1 的 IndexedDB 数据库库名CherryStudio。它有几个关键设计动态模式打开不依赖废弃 schema以new Dexie(DEXIE_DB_NAME)打开不声明 schema通过db.tables反射磁盘上真实存在的 object store。V2 迁移门versionPolicy.ts只放行来自最终 V1 版本的升级用户其磁盘 schema 已是最终版因此无需 Dexie 升级钩子即可导出。主键分页keyset pagination每页 100 条主键DEXIE_EXPORT_PAGE_SIZE用table.orderBy(:id).limit(100).primaryKeys()取页再以table.where(:id).above(lastPrimaryKey)续页。这种分页方式比offset更稳定不会因游标移动导致记录错位。堆内存守卫每个主键循环内await table.get(primaryKey)后立即序列化写入同一时刻渲染进程堆中只保留一条完整记录——注释明确说明一页 topics 内嵌的消息足够多时批量加载会耗尽渲染进程堆。不可恢复记录容错isIrrecoverableRecord通过特征匹配NotReadableError或携带Failed to read large IndexedDB value文本的 UnknownError识别底层 backing file 丢失的大记录跳过并记录 warn而不是让整个迁移失败。表清单分为必选与可选两组const REQUIRED_TABLES [topics, files, knowledge_notes, message_blocks] const OPTIONAL_TABLES [settings, translate_history, quick_phrases, translate_languages]exportAll会过滤出磁盘上真实存在的表逐张导出每张表的开始/结束都会回调onProgress供 UI 更新当前正在导出哪张表。序列化由自研的JsonExportWriter完成——它是一套流式 JSON 序列化器支持toJSON、包装类型、循环引用检测activeObjectsWeakSet与 BigInt 拒绝策略同样以 1 MiB 分块经 IPC 发送。LocalStorageExporter白名单键导出LocalStorageExporter.ts 只导出MIGRATION_LOCAL_STORAGE_KEYS白名单中声明的键当前为[onboarding-completed]把每个键值包装成{ key, value }记录写入localStorage.json数组。它尝试 JSON.parse 值解析失败则保留原始字符串——保证数据语义不丢失。三者的导出顺序与内存考量MigrationApp.runMigration()的调用顺序是经过堆内存考量刻意安排的PrepareExport让主进程清理并返回可信的暂存目录路径先导出Redux并显式置空rawData引用注释说明在打开 IndexedDB 之前导出 Redux因为让已解析的 state 存活到 Dexie 导出期间会抬高渲染进程峰值堆再导出Dexie每张表开始时上报ReportExportStage最后导出localStorage调用actions.startMigration({ reduxExportPath, dexieExportPath, localStorageExportPath })把三个导出路径交给主进程真正执行迁移。任一步骤抛错都会走catch记录日志、把错误消息存入本地闩锁并通过MigrationIpcChannels.ReportError镜像到主进程的终态错误阶段。进度订阅与动作封装useMigrationProgressuseMigrationProgress.ts 是窗口与主进程之间的数据总线包含两个 hookuseMigrationProgress挂载时通过window.electron.ipcRenderer.on(MigrationIpcChannels.Progress, ...)订阅主进程广播同时 invokeGetProgress与GetLastError拉取初始状态。它内部维护migrationStageStartedAtRef计时器迁移耗时Migration time以本窗口收到第一个migration阶段更新为起点、收到completed更新为终点最终写入summary.durationMs用于完成页展示。useMigrationActions把startMigration、retry、cancel、restart、skipMigration、saveDiagnostics、showDiagnosticBundleInFolder、openDownloadPage八个动作封装为对MigrationIpcChannels各通道的 invoke 调用。故障诊断体系Save Diagnostic Bundle 的交互设计README 的 Failure Diagnostics 章节描述了非常精细的故障处理 UX与源码一一对应只有 error 与 version_incompatible 页面提供保存诊断包。错误页上完整失败消息保持可见方便截图主流程只有 Retry 按钮与一个大号次级更多选项按钮。More options 三个选项的次序固定保存故障排查信息第一不使用 V1 数据直接使用 V2第二继续使用 V1第三Close App 固定在左下角 footer。源码中MigrationOptionsDialog严格按此顺序渲染。对话框切换时序每个 More options 选项都会先关闭当前对话框再等DIALOG_UNMOUNT_DELAY_MS来自cherrystudio/ui/utils后打开后续对话框防止叠加遮罩层和焦点错乱。隐私与边界诊断面板明确警告应用日志可能含敏感数据不得公开分享或发送给 Cherry Studio 支持团队之外的人保存永远只是本地保存不会上传或附加当日志无法包含时披露仅元数据回退方案。保存成功后只提供打开文件位置与复制 supportcherry-ai.com两个动作——源码中MigrationDiagnosticPanel.tsx的handleContact直接navigator.clipboard.writeText(SUPPORT_EMAIL)不启动邮件客户端、不预填邮件。错误文本的交互细节错误详情区域被设计为可聚焦的rolebuttondata-migration-error-details属性支持鼠标点击或 Enter/Space 打开诊断导出对话框但用鼠标选中错误文本进行复制时不会触发——openDiagnosticsFromError先检查window.getSelection()?.toString().trim()是否非空。这是防止复制时误弹对话框的经典细节。V1 下载页渲染进程永远不持有 URL继续使用 V1打开V1DownloadDialog其下载按钮调用actions.openDownloadPage(i18n.language)。由于该窗口运行在simplestpreload 上无 shell 访问权限打开页面必须请求主进程代劳并透传当前语言MigrationIpcHandler持有 URL 表把语言映射到区域站点其判定规则与渲染进程 i18n 的zh探测一致见 resolver.ts——保证打开的是用户能读懂的站点同时渲染进程无法自行指定任意 URL。完成页的非致命警告收纳迁移完成后非致命通知non-fatal notices会被折叠成 Restart 按钮下方的一行警告条目点击后打开可滚动对话框展示完整列表底部提供整宽复制按钮对话框刻意没有 footer。对应源码中MigrationApp的warnings合并逻辑会把progress.warningMessagesi18n 化与progress.warnings纯文本统一处理。窗口关闭的确认协议迁移过程中关闭窗口原生红绿灯 / CmdQ / 自定义按钮会被主进程拦截通过ConfirmClose通道要求渲染进程展示应用内确认对话框——这样醒目的样式与文案都由渲染进程设计系统cherrystudio/ui负责。确认后调用ConfirmQuit如果主进程因迁移写入仍在进行而延迟退出ConfirmQuit返回 false渲染进程展示非阻塞的将在当前步骤结束后关闭提示条用户取消Continue/Esc/遮罩则调用CancelClose让主进程丢弃 pending-close 标记使后续关闭行为重新弹窗而非强制退出。迁移的其余环节与阅读指引本窗口只是迁移工作流的前半程导出与向导 UI主进程侧还有配套实现值得继续阅读src/main/data/migration/v2/window/MigrationIpcHandler.ts处理渲染进程全部 IPC 调用负责暂存目录清理、文件覆盖/追加写、诊断包保存与 URL 映射src/main/data/migration/v2/window/MigrationWindowManager.ts窗口生命周期管理src/main/core/preboot/v2MigrationGate.ts迁移门含 fuzzy fallback 自动恢复非默认自定义 userData 路径其结果通过MigrationProgress.dataLocation呈现为介绍页的数据迁移目录提示src/main/data/migration/v2/index.ts迁移编排入口。共享类型 src/shared/data/migration/v2/types.ts 是渲染进程与主进程之间的契约MigrationStage、MigrationProgress、MigrationIpcChannels等全部由此定义。README 的 Implementation Notes 特别强调进度阶段必须与MigrationIpcHandler的期望保持同步改动时必须同时更新两端。总结Migration V2 窗口是一个轻渲染、重协作的架构范例渲染进程负责导出数据、渲染向导、收集诊断信息但从不直接触碰文件系统所有磁盘写入都经由migration:write-export-file等 IPC 通道交给主进程完成。三套导出器各自针对数据源特性做了内存优化流式 JSON 扫描、主键分页、白名单键而状态机 穷尽性检查 共享类型契约则保证了 UI 与主进程逻辑的长期同步。对于需要理解 Cherry Studio 数据迁移机制、或想在自己的 Electron 应用中实现大容量浏览器存储导出方案的开发者这个窗口的实现是很好的参考蓝本。【免费下载链接】cherry-studioAI productivity studio with smart chat, autonomous agents, and 300 assistants. Unified access to frontier LLMs项目地址: https://gitcode.com/GitHub_Trending/ch/cherry-studio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Cherry Studio Migration V2 迁移窗口剖析：渲染进程驱动 V1→V2 数据迁移的完整实现
Cherry Studio Migration V2 迁移窗口剖析渲染进程驱动 V1→V2 数据迁移的完整实现【免费下载链接】cherry-studioAI productivity studio with smart chat, autonomous agents, and 300 assistants. Unified access to frontier LLMs项目地址: https://gitcode.com/GitHub_Trending/ch/cherry-studio导读Cherry Studio 在从旧版本V1向新架构V2演进时需要把用户存储在浏览器存储中的历史数据完整搬运到新库。Migration V2 Window正是为此设计的一个独立渲染进程窗口它不直接写盘而是通过 IPC 与主进程协作先由渲染进程把 Redux Persist、DexieIndexedDB与 localStorage 中的数据以有界分块的方式导出再由主进程在磁盘上拼装成迁移文件。本篇文章基于 src/renderer/windows/migrationV2/README.md 展开结合窗口启动、阶段状态机、数据导出器、故障诊断等源码实现帮助读者理解这一渲染进程导出 主进程落盘的迁移架构并掌握其 IPC 通道、分块策略与容错设计。目录结构一个窗口六类职责迁移窗口的全部代码集中在src/renderer/windows/migrationV2/目录下职责划分非常清晰src/renderer/windows/migrationV2/ ├── MigrationApp.tsx # UI shell 与阶段状态机唯一入口组件 ├── entryPoint.tsx # 窗口引导样式 i18n 初始化后挂载 MigrationApp ├── components/ # UI 组件进度列表、对话框、窗口控制、彩带动画 ├── hooks/ # 进度订阅 动作辅助IPC 封装 ├── exporters/ # 数据导出器Redux Persist / Dexie / localStorage ├── i18n/ # 迁移专用翻译资源与语言解析 └── index.html # HTML 入口通过 meta 声明日志窗口来源为 MigrationV2MigrationApp.tsx 是整个窗口的 UI 外壳与阶段逻辑核心entryPoint.tsx 负责在渲染前异步完成 i18n 初始化components/ 导出MigratorProgressList、SkipMigrationDialog、CloseMigrationDialog、MigrationWindowControls、Confetti、V1DownloadDialog、MigrationDiagnosticPanel等组件exporters/ 提供三个导出器ReduxExporter、DexieExporter、LocalStorageExporter。需要注意README.md中提到的components/与hooks/里实际有MigratorProgress、MigrationDiagnosticPanel等文件hooks/目录下则是useMigrationProgress.ts它同时导出了useMigrationProgress与useMigrationActions两个 hook见下文。窗口启动链路从meta声明到 React 挂载迁移窗口的启动分为三步index.html 声明日志来源HTML 中的meta namelogger-window-source contentMigrationV2 /告诉日志服务该窗口的日志来源标识为MigrationV2使主进程的日志采集能够区分这个预启动preboot窗口与主窗口。该文件同时声明了严格的 CSPdefault-src self并引入/windows/migrationV2/entryPoint.tsx作为模块脚本。entryPoint.tsx 初始化环境先引入全局样式renderer/assets/styles/index.css与tailwind.css然后调用initI18n()并等待其完成后才把MigrationApp挂载到#root。这一点很重要——如果 i18n 尚未就绪就渲染界面上会出现未翻译的 key 闪烁。MigrationApp.tsx 挂载并进入阶段状态机组件加载后立即通过 hook 订阅进度并在 header 中提供语言切换zh-CN/en-US与主题切换能力。i18n独立于偏好服务探测系统语言迁移窗口是预启动窗口此时preferenceService等主流程服务尚未就绪因此 resolver.ts 采用了独立探测策略function detectLanguage(): zh-CN | en-US { const browserLang navigator.language || navigator.languages?.[0] || en-US return browserLang.toLowerCase().includes(zh) ? zh-CN : en-US }只要系统语言包含zh含 zh、zh-CN、zh-TW、zh-HK 等即使用中文否则回退英文fallbackLng: en-US。另外翻译目录是扁平结构——migration.buttons.retry是一个完整的字面 key 而非嵌套路径所以初始化时显式设置了keySeparator: false。这个细节对于后续维护翻译文件非常关键新增 key 时必须保证全名唯一。阶段状态机五阶段向导迁移窗口的核心是一个由共享类型约束的阶段状态机。共享类型定义在 src/shared/data/migration/v2/types.tsexport type MigrationStage version_incompatible | introduction | migration | completed | errorMigrationApp.tsx中的stageStepNumber把阶段映射到步骤导轨StepRail的编号阶段步骤编号说明introduction1介绍页展示迁移特性与开始迁移按钮migration/error2迁移执行中 / 失败共用第二步失败时打叉completed3完成页展示统计摘要与重启按钮version_incompatible—版本不兼容页隐藏步骤导轨显示独立诊断面板状态机通过switch (stage)严格分支渲染且default分支调用assertNever(stage)——这是一个 TypeScript 穷尽性检查技巧如果未来新增阶段而没有处理编译期就会报错。README 的 Implementation Notes 也强调新增 UI 元素时应响应阶段状态机而不是引入临时 ad-hoc flag。值得注意的是MigrationApp内部还有一个本地错误闩锁localMigrationError某些runMigration失败发生在进度能可靠地推进到error之前此时本地状态会临时接管为 error 阶段一旦主进程推送的progress.stage离开error这个本地错误会被自动清空。进度消息的 i18n 化MigrationProgress类型同时支持两类消息纯文本的currentMessage和可翻译的i18nMessage含 key 与插值参数。progressMessage的 useMemo 逻辑是优先用t(progress.i18nMessage.key, progress.i18nMessage.params)翻译否则回退到currentMessage。这样主进程只需下发语义化的 key渲染进程负责按当前语言渲染避免跨进程传递已翻译文本。导出器三条数据通道一个共同原则README 的核心结论是渲染进程绝不直接写盘。三条导出通道都遵循渲染进程分块产出 → IPC 传给主进程 → 主进程落盘的协作模式。IPC 通道定义在同目录的共享类型中WriteExportFile: migration:write-export-file每次调用携带(exportPath, sliceName/tableName, chunk, writeMode)其中writeMode为overwrite | append——主进程在每个文件开头执行覆盖写之后按顺序追加有界块。ReduxExporter流式解码避免整串解析ReduxExporter.ts 处理localStorage中的persist:cherry-studio键。它不把整个 JSON 解析成对象那会显著抬高渲染进程峰值内存而是手工编写了一个 JSON 词法扫描器scanStringEnd/scanValueEnd跳过字符串字面量与嵌套{}/[]只定位每个 slice 的起止偏移visitPersistedSlices遍历根对象筛选出SLICES_TO_EXPORT中声明的 slice逐个回调writeSlice把每个 slice 的 JSON 字符串 token逐字符流式解码并解码\uXXXX等转义序列再按EXPORT_CHUNK_CHAR_LIMIT1 MiB分块写入。需要迁移的 Redux slice 有 13 个包括const SLICES_TO_EXPORT [ settings, // 应用设置与偏好 assistants, // 助手配置 knowledge, // 知识库元数据 llm, // LLM 提供方与模型配置 mcp, // MCP 服务器配置 minapps, // 迷你应用配置启用/禁用/置顶 note, // 笔记相关设置 selectionStore, // 划词助手设置 preprocess, // 文件预处理提供方配置 ocr, // OCR 提供方配置 websearch, // 联网搜索配置 codeTools, // 代码工具设置CLI 工具、模型、终端 paintings // 各提供方/模式的绘画历史供 PaintingMigrator 消费 ]分块时使用了共享工具 clampSurrogateBoundary 来保证不会把代理对surrogate pair即 emoji 等非 BMP 字符从中间截断。export()最终返回{ exportPath, slicesFound, slicesMissing }供主进程和日志核对缺失情况。DexieExporter主键分页 单记录驻留DexieExporter.ts 负责导出遗留 V1 的 IndexedDB 数据库库名CherryStudio。它有几个关键设计动态模式打开不依赖废弃 schema以new Dexie(DEXIE_DB_NAME)打开不声明 schema通过db.tables反射磁盘上真实存在的 object store。V2 迁移门versionPolicy.ts只放行来自最终 V1 版本的升级用户其磁盘 schema 已是最终版因此无需 Dexie 升级钩子即可导出。主键分页keyset pagination每页 100 条主键DEXIE_EXPORT_PAGE_SIZE用table.orderBy(:id).limit(100).primaryKeys()取页再以table.where(:id).above(lastPrimaryKey)续页。这种分页方式比offset更稳定不会因游标移动导致记录错位。堆内存守卫每个主键循环内await table.get(primaryKey)后立即序列化写入同一时刻渲染进程堆中只保留一条完整记录——注释明确说明一页 topics 内嵌的消息足够多时批量加载会耗尽渲染进程堆。不可恢复记录容错isIrrecoverableRecord通过特征匹配NotReadableError或携带Failed to read large IndexedDB value文本的 UnknownError识别底层 backing file 丢失的大记录跳过并记录 warn而不是让整个迁移失败。表清单分为必选与可选两组const REQUIRED_TABLES [topics, files, knowledge_notes, message_blocks] const OPTIONAL_TABLES [settings, translate_history, quick_phrases, translate_languages]exportAll会过滤出磁盘上真实存在的表逐张导出每张表的开始/结束都会回调onProgress供 UI 更新当前正在导出哪张表。序列化由自研的JsonExportWriter完成——它是一套流式 JSON 序列化器支持toJSON、包装类型、循环引用检测activeObjectsWeakSet与 BigInt 拒绝策略同样以 1 MiB 分块经 IPC 发送。LocalStorageExporter白名单键导出LocalStorageExporter.ts 只导出MIGRATION_LOCAL_STORAGE_KEYS白名单中声明的键当前为[onboarding-completed]把每个键值包装成{ key, value }记录写入localStorage.json数组。它尝试 JSON.parse 值解析失败则保留原始字符串——保证数据语义不丢失。三者的导出顺序与内存考量MigrationApp.runMigration()的调用顺序是经过堆内存考量刻意安排的PrepareExport让主进程清理并返回可信的暂存目录路径先导出Redux并显式置空rawData引用注释说明在打开 IndexedDB 之前导出 Redux因为让已解析的 state 存活到 Dexie 导出期间会抬高渲染进程峰值堆再导出Dexie每张表开始时上报ReportExportStage最后导出localStorage调用actions.startMigration({ reduxExportPath, dexieExportPath, localStorageExportPath })把三个导出路径交给主进程真正执行迁移。任一步骤抛错都会走catch记录日志、把错误消息存入本地闩锁并通过MigrationIpcChannels.ReportError镜像到主进程的终态错误阶段。进度订阅与动作封装useMigrationProgressuseMigrationProgress.ts 是窗口与主进程之间的数据总线包含两个 hookuseMigrationProgress挂载时通过window.electron.ipcRenderer.on(MigrationIpcChannels.Progress, ...)订阅主进程广播同时 invokeGetProgress与GetLastError拉取初始状态。它内部维护migrationStageStartedAtRef计时器迁移耗时Migration time以本窗口收到第一个migration阶段更新为起点、收到completed更新为终点最终写入summary.durationMs用于完成页展示。useMigrationActions把startMigration、retry、cancel、restart、skipMigration、saveDiagnostics、showDiagnosticBundleInFolder、openDownloadPage八个动作封装为对MigrationIpcChannels各通道的 invoke 调用。故障诊断体系Save Diagnostic Bundle 的交互设计README 的 Failure Diagnostics 章节描述了非常精细的故障处理 UX与源码一一对应只有 error 与 version_incompatible 页面提供保存诊断包。错误页上完整失败消息保持可见方便截图主流程只有 Retry 按钮与一个大号次级更多选项按钮。More options 三个选项的次序固定保存故障排查信息第一不使用 V1 数据直接使用 V2第二继续使用 V1第三Close App 固定在左下角 footer。源码中MigrationOptionsDialog严格按此顺序渲染。对话框切换时序每个 More options 选项都会先关闭当前对话框再等DIALOG_UNMOUNT_DELAY_MS来自cherrystudio/ui/utils后打开后续对话框防止叠加遮罩层和焦点错乱。隐私与边界诊断面板明确警告应用日志可能含敏感数据不得公开分享或发送给 Cherry Studio 支持团队之外的人保存永远只是本地保存不会上传或附加当日志无法包含时披露仅元数据回退方案。保存成功后只提供打开文件位置与复制 supportcherry-ai.com两个动作——源码中MigrationDiagnosticPanel.tsx的handleContact直接navigator.clipboard.writeText(SUPPORT_EMAIL)不启动邮件客户端、不预填邮件。错误文本的交互细节错误详情区域被设计为可聚焦的rolebuttondata-migration-error-details属性支持鼠标点击或 Enter/Space 打开诊断导出对话框但用鼠标选中错误文本进行复制时不会触发——openDiagnosticsFromError先检查window.getSelection()?.toString().trim()是否非空。这是防止复制时误弹对话框的经典细节。V1 下载页渲染进程永远不持有 URL继续使用 V1打开V1DownloadDialog其下载按钮调用actions.openDownloadPage(i18n.language)。由于该窗口运行在simplestpreload 上无 shell 访问权限打开页面必须请求主进程代劳并透传当前语言MigrationIpcHandler持有 URL 表把语言映射到区域站点其判定规则与渲染进程 i18n 的zh探测一致见 resolver.ts——保证打开的是用户能读懂的站点同时渲染进程无法自行指定任意 URL。完成页的非致命警告收纳迁移完成后非致命通知non-fatal notices会被折叠成 Restart 按钮下方的一行警告条目点击后打开可滚动对话框展示完整列表底部提供整宽复制按钮对话框刻意没有 footer。对应源码中MigrationApp的warnings合并逻辑会把progress.warningMessagesi18n 化与progress.warnings纯文本统一处理。窗口关闭的确认协议迁移过程中关闭窗口原生红绿灯 / CmdQ / 自定义按钮会被主进程拦截通过ConfirmClose通道要求渲染进程展示应用内确认对话框——这样醒目的样式与文案都由渲染进程设计系统cherrystudio/ui负责。确认后调用ConfirmQuit如果主进程因迁移写入仍在进行而延迟退出ConfirmQuit返回 false渲染进程展示非阻塞的将在当前步骤结束后关闭提示条用户取消Continue/Esc/遮罩则调用CancelClose让主进程丢弃 pending-close 标记使后续关闭行为重新弹窗而非强制退出。迁移的其余环节与阅读指引本窗口只是迁移工作流的前半程导出与向导 UI主进程侧还有配套实现值得继续阅读src/main/data/migration/v2/window/MigrationIpcHandler.ts处理渲染进程全部 IPC 调用负责暂存目录清理、文件覆盖/追加写、诊断包保存与 URL 映射src/main/data/migration/v2/window/MigrationWindowManager.ts窗口生命周期管理src/main/core/preboot/v2MigrationGate.ts迁移门含 fuzzy fallback 自动恢复非默认自定义 userData 路径其结果通过MigrationProgress.dataLocation呈现为介绍页的数据迁移目录提示src/main/data/migration/v2/index.ts迁移编排入口。共享类型 src/shared/data/migration/v2/types.ts 是渲染进程与主进程之间的契约MigrationStage、MigrationProgress、MigrationIpcChannels等全部由此定义。README 的 Implementation Notes 特别强调进度阶段必须与MigrationIpcHandler的期望保持同步改动时必须同时更新两端。总结Migration V2 窗口是一个轻渲染、重协作的架构范例渲染进程负责导出数据、渲染向导、收集诊断信息但从不直接触碰文件系统所有磁盘写入都经由migration:write-export-file等 IPC 通道交给主进程完成。三套导出器各自针对数据源特性做了内存优化流式 JSON 扫描、主键分页、白名单键而状态机 穷尽性检查 共享类型契约则保证了 UI 与主进程逻辑的长期同步。对于需要理解 Cherry Studio 数据迁移机制、或想在自己的 Electron 应用中实现大容量浏览器存储导出方案的开发者这个窗口的实现是很好的参考蓝本。【免费下载链接】cherry-studioAI productivity studio with smart chat, autonomous agents, and 300 assistants. Unified access to frontier LLMs项目地址: https://gitcode.com/GitHub_Trending/ch/cherry-studio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考