企业官网建设流程全解析

• 人工智能
• 大模型
• AI 应用
• 交互助手
• 本地部署

本篇技术指南围绕 Cherry Studio 数据迁移体系中的一条关键升级策略展开：V1.9.13 用户现在可以跳过 V2.0.0、直接安装任意 V2.0.x 补丁版本完成 v1→v2 迁移，而 V2.1.0 及之后的版本仍必须首先经过 V2.0.x 迁移线。文章将完整解释该变更的内容、底层版本门禁实现、测试验证方式，以及发布管理者需要配合的动作，帮助用户、测试人员与发布工程师准确理解这条升级路径的边界与原理。

变更概述：V2.0.x 全系列成为合法迁移目标

本变更记录于 v1 直升 V2.0.x 变更文档，核心结论是：

从 V1.9.13 升级的每一位用户，现在可以把任意一个 V2.0.x 补丁版本作为首个 v2 迁移目标（first v2 migration target），而不必先安装 V2.0.0。

其背后的含义是：

• 每个 V2.0.x 补丁都完整保留 v1→v2 的一次性迁移逻辑，不会因为补丁迭代而丢失迁移能力；
• V2.0.x 补丁可能包含对迁移崩溃、内存压力、Agent 数据路径、遗留 Provider 凭证等问题的修复；
• 因此用户可以直接安装最新的 V2.0.x 补丁，一次性获得"迁移能力 + 全部补丁修复"，无需在 V2.0.0 与最新补丁之间走两步。

同时存在一条明确的上限约束：从 V2.1.0 开始，后续版本不再接受 V1.x 用户作为首个迁移目标，用户必须先进入 V2.0.x 迁移线完成数据迁移，再升级到更高版本。

背景：为什么 v1→v2 需要一次性迁移与版本门禁

Cherry Studio v2.0.0 引入了从旧版存储（Redux Persist + Dexie）到 SQLite 新架构的一次性数据迁移。整个迁移系统实现在 src/main/data/migration/v2，相关架构说明见 V2 迁移指南。

为了保证数据完整性，迁移系统强制一条线性升级路径：

v1.old → v1.last (≥1.9.12) → v2.0.x → v2.1+

采用线性路径的根本原因是工程代价：如果允许从任意 v1 版本直接迁移，迁移代码需要面对 O(n²) 的源数据格式组合测试矩阵。通过要求所有用户先升级到最终 v1 版本（≥ 1.9.12），迁移代码只需处理单一源数据格式，大幅降低测试与维护成本。

该线性路径同时由两层机制独立强制：

1. 托管发布服务（managed release service）：客户端通过 AppUpdaterService 上报安装版本与客户端元数据，由服务端选择 OTA 升级目标并强制升级网关（见 应用更新架构）；
2. 本地迁移门禁（migration gate）：对绕过自动更新、手动下载安装的场景，v2MigrationGate在创建迁移窗口前用 versionPolicy.ts 校验升级路径，作为独立的安全网。

底层实现：版本策略的拦截规则

本地迁移门禁的核心逻辑位于 src/main/data/migration/v2/core/versionPolicy.ts，其中定义了三个版本常量：

纯函数checkUpgradePathCompatibility负责判定升级路径是否兼容，规则如下：

其中v2_gateway_skipped规则与本变更直接对应：V1.9.13 升级到任意 2.0.x 版本都不触发该拦截（因为当前版本 < 2.1.0），而 V1.9.13 → 2.1.0 则会被拦截，提示用户先安装 2.0.x。

预发布版本的处理

策略对预发布版本做了特殊处理，源码注释明确了以下约定：

• currentVersion通过semver.coerce()去除预发布标签，2.0.0-alpha被视作2.0.0，因此v1.last → v2.0.0-alpha 允许通过，不会误拦安装预发布版的 v1 用户；
• previousVersion不做 coerce，2.0.0-beta被视为"2.0.0 之前"，说明用户尚未通过迁移网关；
• 预发布之间的升级（alpha → beta → rc → 2.0.0）允许，因为首次成功后迁移状态已为completed。

version.log 的读取细节

版本检查读取MigrationPaths.versionLogFile（经resolveMigrationPaths()解析、已考虑 v1 自定义 userData 目录的路径），而不是VersionService的缓存路径。这对配置过自定义用户数据目录的 v1 用户至关重要——迁移系统所有路径都必须来自MigrationPaths，严禁直接调用app.getPath('userData')（详见 迁移系统 README 的 Path Safety 章节）。

version.log使用version|os|environment|packaged|mode|timestamp的管道分隔格式，readPreviousVersion从文件末尾向前扫描，返回与当前版本不同的最近一个版本；损坏行会被静默跳过并输出警告日志。

测试验证：测试用例如何锁定这条升级路径

策略的行为由 versionPolicy.test.ts 中的 12 个用例逐条锁定，其中与本变更直接相关的用例包括：

• #7「passes when v1.9.13 upgrades directly to v2.0.1」：previousVersion: '1.9.13'、currentAppVersion: '2.0.1'判定为pass—— 这正是本变更声明所允许的场景；
• #8「passes for later v2.0.x patch releases」：v1.9.13 → 2.0.99同样pass—— 证明"任意 v2.0.x 补丁"都是合法目标，而非仅限 v2.0.1；
• #6「blocks when v2 gateway is skipped (1.9.12 → 2.1.0)」：判定为v2_gateway_skipped，返回提示gatewayVersion: '2.0.x'—— 证明 2.1.0 及以上仍被拦截；
• #10「blocks when previous is 2.0.0-beta」：2.0.0-beta → 2.1.0判定为v2_gateway_skipped—— 预发布版本不能充当迁移网关；
• #5「passes when current version is a pre-release coerced to 2.0.0」：v1.9.12 → 2.0.0-alpha允许通过。

这些用例同时验证了readPreviousVersion对多版本文件、空文件、损坏行、文件不存在等边界场景的处理，可作为理解版本门禁行为的最小可执行示例。

用户需要做什么：什么都不用做

对于从 V1.9.13 升级的用户，本变更完全自动生效，无需任何手动操作：

• 当托管发布服务将 V1.9.13 客户端的升级目标指向最新 V2.0.x 补丁（如 V2.0.1）时，本地迁移门禁会放行该路径；
• 用户安装该 V2.0.x 补丁后即进入既有的一次性迁移流程，迁移完成后数据进入 SQLite 新架构；
• 用户获得的不仅是最新补丁修复，还包括该补丁内携带的全部迁移相关修复（迁移崩溃、内存压力、Agent 数据路径、遗留 Provider 凭证等）。

需要注意的是，迁移是一次性动作，且各迁移步骤独立提交。如果迁移中途失败后选择"跳过迁移"（Use V2 without importing V1 data），系统会先清空本次运行已写入新库的数据再以默认数据启动 v2（详见 跳过迁移会清除已迁移数据）。因此若迁移结果不理想，仍可借助 v1 迁移可重跑 机制（保留的 v1 Redux 数据存在时，在 设置 > 数据 中可重跑迁移）重新迁移；迁移失败时也可在失败界面保存本地诊断 ZIP 用于排查（见 迁移诊断包）。

发布管理者注意事项

本变更属于数据迁移策略调整，发布管理者需要额外关注两点：

1. 托管发布服务网关需单独更新：本地迁移门禁只是安全网，决定 V1.9.13 客户端实际升级目标的是托管发布服务端。截至本变更记录撰写时，生产环境仍将 V1.9.13 客户端路由到 V2.0.0；要真正让用户直接获得最新 V2.0.x 补丁，必须先在发布服务网关侧完成配置更新；
2. 2.1.0 及以后的发布：任何 2.1.0 之后的版本都必须确保用户先经过 2.0.x 迁移线，发布服务与本地门禁需要保持一致，避免"本地门禁放行但服务端路由错误"或反向的不一致。

整个变更目录的存放约定与索引见 V2 Breaking Changes 总览，同类迁移类变更（如重跑迁移、跳过迁移清理、迁移诊断包）均按YYYY-MM-DD-short-description.md命名规范收录。

小结与判定速查表

总而言之，本次变更为 V1.9.13 用户打通了一条"一步到位"的 v2 迁移通道：任意 V2.0.x 补丁版本都是合法且推荐的首个迁移目标，其正确性由 versionPolicy.ts 的实现与配套测试共同保证；而 V2.1.0 作为迁移天花板，继续守护着"必须先经过 v2.0.x 迁移线"的线性路径铁律。

• 人工智能
• 大模型
• AI 应用
• 交互助手
• 本地部署