Cherry Studio v2 一次性数据迁移引擎深度解析从 Redux/Dexie 到 SQLite 的架构设计与实战指南【免费下载链接】cherry-studio Cherry Studio 是一款支持多个 LLM 提供商的桌面客户端项目地址: https://gitcode.com/CherryHQ/cherry-studio本文是 Cherry StudioCherryHQ/cherry-studio数据层 V2 迁移系统的技术指南围绕 v2-migration-guide.md 展开深入剖析从 v1 遗留的 Dexie Redux Persist 存储一次性迁移到 SQLite 新架构的完整方案包括线性升级门禁、迁移引擎与迁移器Migrator契约、外键完整性策略、数据源读取器、IPC 窗口集成与 orderKey 排序键打标机制。读完本文你将掌握该迁移模块的架构脉络、各核心组件的实现原理以及如何按照项目既有约定新增一个领域迁移器的完整实践路径。背景为什么需要一次性的 v1 → v2 迁移Cherry Studio v2 对数据层进行了根本性重构v1 时代的数据分散在DexieIndexedDB、Redux Persist 导出文件与electron-storeconfig.json中而 v2 统一收敛到SQLite 数据库{userData}/Data/cherrystudio.sqlite。为了不丢失用户历史数据v2 引入了一个一次性one-shot迁移引擎负责把上述遗留存储中的数据按领域拆解、转换并写入 SQLite 新表。从源码看整个迁移模块集中在 src/main/data/migration/v2主进程编排、数据访问、迁移器插件与 IPC 入口和 src/shared/data/migration/v2/types.ts主进程与渲染进程共享的阶段、结果与校验统计类型。渲染进程的迁移窗口只是 UI 外壳真正的编排逻辑全部在主进程完成。线性升级路径与版本门禁强制线性升级路径迁移系统强制一条线性升级路径以保证数据完整性v1.old → v1.last (≥1.9.12) → v2.0.x → v2.1为什么是线性路径v2.0.0 引入了从 Redux/Dexie 到 SQLite 的一次性数据迁移且每个 v2.0.x 补丁版本都完整保留该迁移逻辑并附带修复。如果要从每一个 v1 版本直接迁移测试矩阵会膨胀为 O(n²)。通过要求所有用户先升级到最终 v1 版本迁移代码只需处理一种确定的源数据格式大大降低了兼容面。门禁如何工作整个门禁依赖version.log文件VersionService 自 v1.7 起内嵌每当版本变化就在{userData}/写入一个version.log文件。v2 首次启动时v2MigrationGate.ts通过MigrationPaths.versionLogFile读取该文件该路径基于考虑了 v1 自定义目录的解析后 userData 路径。若上一版本过旧、缺失或用户跳过了 v2.0.x 迁移线门禁会弹出错误对话框并退出用户不会进入迁移 UI。从 versionPolicy.ts 可以看到核心判定函数checkUpgradePathCompatibility的实现规则V1_REQUIRED_VERSION 1.9.12v2 数据迁移支持的最低 v1 版本V2_GATEWAY_VERSION 2.0.0v2.0.x 迁移网关线的起始版本V2_DIRECT_MIGRATION_CEILING 2.1.0第一个不能作为 v1→v2 直接迁移目标的版本线。判定规则按顺序无version.log且无上一版本 → 判定为从未运行过内嵌 VersionService 的 v1 版本阻止no_version_log上一版本低于1.9.12→ 阻止v1_too_old上一版本是 v1.x或早于 2.0.0且当前版本 ≥2.1.0→ 判定跳过了迁移网关线阻止v2_gateway_skippedversion.log存在但没有解析出上一版本重试或单条目场景→ 放行其余情况放行。阻止规则一览场景阻止原因用户操作无version.logv1 1.7 用户no_version_log先安装 v1.last 并运行一次再安装最新 v2.0.x 版本上一版本 1.9.12v1_too_old先升级到 v1.last上一版本是 v1.x 但当前版本 ≥ 2.1.0v2_gateway_skipped先安装最新 v2.0.x 完成迁移再升级到当前版本当判定阻止时getBlockMessage会生成用户可读的提示文案英文硬编码与门禁的dialog.showErrorBox用法一致。预发布版本的处理v2.0.0 预发布版本alpha/beta/rc按 semver 语义被视作2.0.0 之前因此允许作为从 v1.last 迁移的目标门禁检查会对currentVersion做semver.coerce()处理使2.0.0-alpha被视为2.0.0从而放行。但previousVersion不做 coerce——2.0.0-beta仍被视作“未通过网关”。预发布之间的升级alpha→beta→rc→2.0.0之所以安全是因为首次成功运行后迁移状态即为completed后续needsMigration()返回 false。经过验证的直接迁移目标是完整的v2.0.x版本线从 v2.1.0 起后续版本在迁移兼容性被显式验证之前都会被阻止作为首次迁移目标。与自动更新器的关系自动更新器AppUpdaterService会把已安装版本等客户端元数据上报给受管发布服务由其选择 OTA 目标并强制执行升级网关。而迁移门禁是另一道独立的安全网针对手动下载安装版本的用户。两套系统都强制兼容的升级路径但彼此独立运作。目录布局src/main/data/migration/v2/ ├── core/ # Engine shared context ├── migrators/ # Domain-specific migrators and mappings ├── utils/ # Data source readers (Redux, Dexie, streaming JSON) ├── window/ # IPC handlers migration window manager └── index.ts # Public exports for main process与文档描述一致源码目录中还包含每个迁移器的README-MigratorName.md文档、mappings/映射定义、transformers/转换器以及覆盖各迁移器的__tests__/测试目录如 MigrationEngine.test.ts、MigrationPaths.test.ts、versionPolicy.test.ts 等可用于验证本文所述行为。核心契约MigrationEngine编排中枢core/MigrationEngine.ts是迁移编排的单一入口单例migrationEngine负责按序协调所有迁移器registerMigrators按各迁移器的order字段升序排序run()逐个执行。向 UI 上报进度通过onProgress回调calculateProgress按“已完成迁移器数 当前迁移器内进度”加权计算 0–100 的整体进度updateProgress携带当前消息与 i18n 键默认migration.progress.processing以及每个迁移器的pending/running/completed状态。唯一持久化迁移标记以app_state表key migration_v2_status记录状态见 migrationStatus.ts状态值包含statuscompleted/failed/in_progress、migratedFromV1、时间戳与错误信息。运行前清空新架构表verifyAndClearNewTables会先检查MIGRATION_TARGET_TABLES所有迁移写入的表清单是否非空并告警然后在事务中clearMigrationData清空全部目标表——该清单同时服务于“重试”和“跳过”两条路径避免清理范围漂移。注意清空顺序有讲究子表必须先于父表如user_model先于user_provider、message先于topic、topic先于assistant。校验失败即中止validateMigratorResult强制计数校验——若targetCount sourceCount - skippedCount或ValidateResult.errors非空直接抛错终止整个迁移全局外键校验失败同样中止。运行后清理临时文件无论成功失败finally中都会删除migration_temp下的 Redux/Dexie/localStorage 导出目录避免失败重试时遗留大体积导出快照。needsMigration()的判定逻辑值得注意优先读取已存储的迁移状态若无状态首次启动则以legacyDataConfirmed门禁路径解析的权威信号能识别version.log、Chromium 存储、config 键等标记或hasLegacyData()electron-store 探测二者之一为准防止“重定向到的自定义目录恰好 electron-store 为空”被误判为新安装而永久锁定为 completed。全新安装无任何遗留数据会直接markCompleted(false)跳过迁移。MigrationPaths路径安全约定core/MigrationPaths.ts定义了MigrationPaths冻结的预计算路径对象和resolveMigrationPaths()。它会在迁移门禁入口被调用一次引擎初始化之前从~/.cherrystudio/config/config.json检测 v1 遗留的 userData 目录。这是全模块最关键的约定之一所有迁移代码一律使用ctx.paths绝不调用app.getPath()或自行path.join拼路径。原因在文件头注释中写得很直白v1 用户若通过~/.cherrystudio/config/config.json配置了自定义 userData 目录v2 首次启动时app.getPath(userData)返回的是 Electron 默认值——因为resolveUserDataLocation()尚未把遗留配置迁移进 boot-config.json——直接使用会导致数据丢失。MigrationPaths提供的路径包括基础目录userData、cherryHome数据库与数据目录databaseFile{userData}/Data/cherrystudio.sqlite、knowledgeBaseDir、filesDataDir遗留源versionLogFile、legacyAgentDbFilev1 独立 agents SQLite、legacyClaudeConfigDir/legacyClaudeProjectsDir、customMiniAppsFile、legacyConfigFilev2 目标agentsDataDir、claudeConfigDir、claudeProjectsDir、agentSystemWorkspacesDir导出暂存migrationTempDir及migrationReduxExportDir、migrationDexieExportDir、migrationLocalStorageExportDir/File构建期migrationsFolder按app.isPackaged解析 Drizzle 迁移脚本目录。resolveMigrationPaths()的返回对象还携带userDataChanged、inaccessibleLegacyPath遗留目录不可达时的回退提示如外置硬盘未挂载、legacyDataConfirmed最终解析目录是否真的含 v1 数据纯属性计算不受启动顺序影响和dataLocation模糊回退自动选中的非默认目录用于在迁移介绍页展示。其中纯函数selectLegacyUserData实现了完整的目录选择策略按优先级先命中者生效分支条件动作A0当前 userData 已有非空 sqlitekeep——绝不因模糊猜测放弃已 V2 化的目录A1config.json 中有精确的 exe→dir 映射redirect或inaccessible权威映射不做模糊化处理B1存在可用且含 v1 数据且版本合格的目录redirect最新使用目录带noticeB2存在候选但版本不合格仍redirect交由版本门禁用该目录自己的 version.log 阻止B3无候选但记录目录不可达inaccessible提示用户而非静默全新启动B4无可恢复数据default走正常流程此外readLegacyEntries兼容 v1 的两种历史形态字符串{ appDataPath: /path }适用于所有可执行文件会合成一条以当前 exe 为键的精确条目与数组{ appDataPath: [{ executablePath, dataPath }, ...] }原样返回用于精确匹配与模糊枚举。pinUserDataPath会把解析结果写入 boot-config且采用严格持久化persist()写失败会抛错确保下次启动能直接解析到正确目录。MigrationContext迁移器共享上下文core/MigrationContext.ts构建传给每个迁移器的共享上下文MigrationContextsources各数据源读取器——electronStoreelectron-store 只读接口、reduxStateReduxStateReader按类别的 Redux Persist 导出文件、dexieExportDexieFileReaderJSON 导出表、dexieSettings、localStorage、knowledgeVectorSource知识库向量源以及legacyHomeConfigLegacyHomeConfigReaderv1~/.cherrystudio/config/config.json供BootConfigMigrator的 config 文件迁移路径使用。db当前 SQLite 连接drizzle better-sqlite3。paths预计算的MigrationPaths。sharedDataMapstring, unknown用于迁移器之间传递跨域信息如 assistant → chat 的 ID 引用。loggerscoped 到迁移的日志服务。共享类型定义src/shared/data/migration/v2/types.ts 定义了主进程与渲染进程共享的完整类型体系迁移阶段version_incompatible/introduction/migration/completed/error、迁移器状态pending/running/completed/failed、三阶段结果PrepareResult/ExecuteResult/ValidateResult、迁移进度、摘要与诊断数据以及全部 IPC 通道名常量MigrationIpcChannels。迁移器Migrator体系基础契约每个迁移器继承migrators/BaseMigrator.ts实现元数据id、nameUI 显示名、description、order越小越先执行。reset()重置上次运行的实例状态。引擎会复用迁移器实例并在每次run()前调用保证重试时计数、缓存、预取数据均为干净状态。prepare(ctx)干跑检查、计数与暂存数据返回PrepareResultsuccess、itemCount、非致命warnings/warningMessages。execute(ctx)执行插入/更新自行管理事务通过reportProgress上报进度结束时用this.assertOwnedForeignKeys(ctx.db, [...])对自己拥有的表做外键自检。validate(ctx)校验计数与完整性返回带统计信息sourceCount、targetCount、skippedCount和errors数组的ValidateResult。注册与执行顺序迁移器在migrators/migratorRegistry.ts中登记引擎按其order排序执行。当前实现的 16 个迁移器及其执行顺序为BootConfigMigrator→PreferencesMigrator→NoteMigrator→MiniAppMigrator→McpServerMigrator→ProviderModelMigrator→AssistantMigrator→FileMigrator→AgentsMigrator→KnowledgeMigrator→KnowledgeVectorMigrator→ChatMigrator→AiUsageRecordMigrator→PaintingMigrator→TranslateMigrator→PromptMigrator注册表是执行集合的权威来源每个已注册迁移器的order是顺序的权威来源各领域额外的源码、转换或恢复细节记录在migrators/README-name.md中如 README-ChatMigrator.md、README-AgentsMigrator.md。BootConfigMigrator是唯一的文件目标例外它把早期启动设置写入bootConfigService而其余迁移器写入 SQLite 或按知识库生成的 Index 产物。迁移器约定所有日志通过loggerService输出并带迁移器专属 context。使用MigrationContext.sources访问数据而非直接读原始文件/存储。用sharedData在迁移器间传递 ID 或查找表如 assistant → chat 引用避免重复读取源。大体积 Dexie 导出使用JsonStreamReader流式读取并批量插入避免内存尖峰。整个迁移过程外键保持关闭详见下节。计数校验是强制的targetCount sourceCount - skippedCount或errors非空都会导致引擎失败。保持幂等引擎运行前会清空目标表但每个迁移器仍应容忍同一次运行内的重试。保留 v1 源数据以支持降级兼容例如AgentsMigrator会把遗留 Agent 文件复制进 v2 布局但绝不删除agents.db或遗留短 ID 工作区。路径安全所有文件系统路径必须来自ctx.paths。如果缺少某路径把它加进MigrationPaths接口而不是内联拼接。外键Foreign Key处理策略这是迁移性能与数据完整性之间的核心平衡点外键在整个迁移期间保持关闭OFF且不允许单个迁移器自行开关。原因在于 better-sqlite3 在整个进程内维持单一持久连接因此引擎在MigrationDbService中只设置一次PRAGMA foreign_keys OFF必须在applyMigrations之后执行因为后者会恢复它自己的连接设置为 ON该设置在整段迁移内持续生效——不存在按事务重连导致重置的情况。这允许批量插入携带尚未解析的引用如自引用的message.parentId或由更晚迁移器解析的跨域引用。完整性校验分两层迁移器自检每个迁移器在execute()结束时调用this.assertOwnedForeignKeys(ctx.db, [...])对自己拥有的表执行PRAGMA foreign_key_check(table)尽早暴露归属于本域的外键错误便于准确定位责任方。引擎兜底全部迁移器完成后MigrationEngine.verifyForeignKeys执行全库PRAGMA foreign_key_check扫描所有表一旦发现违规即抛出含违规样本的错误。自检范围原则只传入“当前迁移器完成时其外键已被完全解析”的表。排除由更晚迁移器解析的引用——例如assistant_knowledge_base.knowledgeBaseId由AssistantMigrator写入但只有KnowledgeMigrator完成重映射/剪枝后才有效因此该表由KnowledgeMigrator自检而非AssistantMigrator。专属文件关联表如chat_message_file_ref可由同时拥有源行与引用行的迁移器自检。工具层数据源读取器utils/目录提供了四个核心读取器ReduxStateReader.ts对分类存放的 Redux Persist 导出文件提供安全的按需访问支持点路径查找。DexieFileReader.ts读取导出的 Dexie JSON 表支持大表流式读取。JsonStreamReader.ts针对超大数组的流式读取器内置批量处理、计数与采样辅助。LegacyHomeConfigReader.ts同步读取 v1~/.cherrystudio/config/config.json并将其appDataPath字段归一化为RecordexecutablePath, dataPath | null——同时兼容遗留的字符串形态与当前的{ executablePath, dataPath }[]数组形态。仅供BootConfigMigrator的configfile数据源使用。MigrationContext构建时会预加载 Dexiesettings表与 localStorage 导出到内存以便同步访问缺失时降级为警告日志。另有DexieSettingsReader、LocalStorageReader、KnowledgeVectorSourceReader等补充读取器均有对应单元测试覆盖。窗口与 IPC 集成MigrationIpcHandlerwindow/MigrationIpcHandler.ts为迁移 UI 暴露 IPC 通道通道名定义于共享类型中的MigrationIpcChannels状态查询migration:check-needed、migration:get-progress、migration:get-last-error流程控制migration:start、migration:prepare-export准备导出路径并重置 Redux/Dexie/localStorage 暂存目录、校验导出写入、migration:start-migration启动引擎、migration:retry、migration:cancel、migration:restart、migration:skip-migration进度广播主 → 渲染migration:progress、migration:export-progress文件传输渲染 → 主migration:write-export-file、migration:save-diagnostic-bundle、migration:show-diagnostic-bundle-in-folder窗口控制migration:minimize、migration:close-window、关闭确认三连confirm-close/confirm-quit/cancel-close。实现上的几个关键点所有处理器通过validateSender校验发送方assertMigrationWindowSender防止未授权方调用引擎以inFlightMigration防止并发启动重复启动返回Migration is already in progress.打开 v1 下载页需要走主进程迁移窗口使用仅含 ipcRenderer 的simplestpreload主进程根据界面语言选择 CN/Global 下载站migration:report-export-stage与migration:report-error用于渲染进程导出 OOM 等故障的主进程面包屑与终态错误同步。MigrationWindowManagerwindow/MigrationWindowManager.ts创建无边框迁移窗口负责生命周期管理并在生产环境完成后给出重启指引。新增迁移器的实现清单参照原文档与源码约定新增一个领域迁移器的标准流程如需要在migrators/mappings/下添加映射定义继承BaseMigrator实现prepare/execute/validate包含显式计数、批量插入与完整性自检通过reportProgress接通进度上报让 UI 显示每个迁移器的进度在migrators/migratorRegistry.ts中以正确的order注册迁移器目标表建好后把新表加入MigrationEngine.verifyAndClearNewTables的MIGRATION_TARGET_TABLES清单注意子表先于父表的清空顺序在execute()末尾通过this.assertOwnedForeignKeys(ctx.db, [...ownedTables])自检外键排除跨域延迟引用与共享多态表见外键约定不要自行开关PRAGMA foreign_keys——引擎已在整个迁移期间将其保持 OFF记录不明显的业务不变量与转换依据而非复述实现细节当迁移器存在调用方无法从通用契约推断的源格式、恢复或转换规则时创建或更新migrators/README-MigratorName.md。可排序资源的 OrderKey 打标遗留 Redux/Dexie → SQLite 迁移中所有可排序资源必须为插入的每一行生成order_key。v2 迁移层在 src/main/data/migration/v2/utils/orderKey.ts 提供了一对纯函数不触碰数据库——接收已拍平的数组返回带上orderKey的同一批行辅助函数形态适用场景assignOrderKeysInSequence(rows)为每行返回一个单调递增的orderKey整表排序如mcp_server、user_provider、miniappassignOrderKeysByScope(rows, getScope)按作用域键分组每个桶独立打标各桶独立键空间分区表如user_model.providerId、group.entityType模式——先拍平、后打标保持transform*函数纯净不接收index参数、不传sortOrder参数先把遗留源拍平成数组再对整批数组打标import { assignOrderKeysByScope, assignOrderKeysInSequence } from data/migration/v2/utils/orderKey // 之前——每个 transform 接收 index 并产出 sortOrder const rows legacyServers.map((src, i) transformMcpServer(src, i).row) // 之后——transforms 保持纯净键在拍平之后统一分配 const rows legacyServers.map((src) transformMcpServerV2(src).row) const stamped assignOrderKeysInSequence(rows) tx.insert(mcpServerTable).values(stamped).run() // 分区示例——每个 providerId 拥有独立键空间 const stamped assignOrderKeysByScope(userModels, (m) m.providerId)导入规则——绝不直接引用fractional-indexing迁移器辅助函数委托给 src/main/data/services/utils/orderKey.ts 导出的generateOrderKeySequence这是该库唯一被认可的集成点。迁移器代码、迁移脚本与 drizzle 自定义迁移回调都必须从这个服务层包装重新导入以保证库边界可审计且后续更换字符集或替换实现时只有一个改动位置。迁移窗口之外的运行时对应物insertWithOrderKey/insertManyWithOrderKey/applyMoves/resetOrder参见数据排序指南——服务端辅助函数。小结Cherry Studio 的 v2 一次性迁移系统是一套设计严谨的“数据搬迁”架构用线性升级门禁把源数据格式收敛为单一形态用MigrationPaths 路径安全约定规避 v1 自定义目录的数据丢失风险用迁移器注册表 三阶段契约把 16 个业务领域解耦为可独立开发、测试、文档化的单元用全局外键关闭 双层校验平衡批量插入性能与引用完整性再通过IPC 窗口 进度流为用户提供可控、可重试、可跳过的迁移体验。对于需要扩展该模块的开发者本文的实现清单、外键自检边界与 orderKey 打标规范是三条最值得遵循的纪律。【免费下载链接】cherry-studio Cherry Studio 是一款支持多个 LLM 提供商的桌面客户端项目地址: https://gitcode.com/CherryHQ/cherry-studio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考