mirror of https://github.com/CherryHQ/cherry-studio.git synced 2025-12-19 14:41:24 +08:00

chore: rename cs-releases to x-files/app-upgrade-config (#11290 )

rename cs-releases to x-files/app-upgrade-config

2025-11-14 18:53:11 +08:00

17 KiB

Raw Blame History

更新配置系统设计文档

背景

当前 AppUpdater 直接请求 GitHub API 获取 beta 和 rc 的更新信息。为了支持国内用户，需要根据 IP 地理位置，分别从 GitHub/GitCode 获取一个固定的 JSON 配置文件，该文件包含所有渠道的更新地址。

设计目标

支持根据 IP 地理位置选择不同的配置源（GitHub/GitCode）
支持版本兼容性控制（如 v1.x 以下必须先升级到 v1.7.0 才能升级到 v2.0）
易于扩展，支持未来多个主版本的升级路径（v1.6 → v1.7 → v2.0 → v2.8 → v3.0）
保持与现有 electron-updater 机制的兼容性

当前版本策略

v1.7.x 是 1.x 系列的最后版本
v1.7.0 以下的用户必须先升级到 v1.7.0（或更高的 1.7.x 版本）
v1.7.0 及以上的用户可以直接升级到 v2.x.x

自动化工作流

x-files/app-upgrade-config/app-upgrade-config.json 由 Update App Upgrade Config workflow 自动同步。工作流会调用 scripts/update-app-upgrade-config.ts 脚本，根据指定 tag 更新 x-files/app-upgrade-config 分支上的配置文件。

触发条件

Release 事件（release: released/prereleased）
- Draft release 会被忽略。
- 当 GitHub 将 release 标记为 prerelease 时，tag 必须包含 -beta/-rc（可带序号），否则直接跳过。
- 当 release 标记为稳定版时，tag 必须与 GitHub API 返回的最新稳定版本一致，防止发布历史 tag 时意外挂起工作流。
- 满足上述条件后，工作流会根据语义化版本判断渠道（latest/beta/rc），并通过 IS_PRERELEASE 传递给脚本。
手动触发（workflow_dispatch）
- 必填：tag（例：v2.0.1）；选填：is_prerelease（默认 false）。
- 当 is_prerelease=true 时，同样要求 tag 带有 beta/rc 后缀。
- 手动运行仍会请求 GitHub 最新 release 信息，用于在 PR 说明中标注该 tag 是否是最新稳定版。

工作流步骤

检查与元数据准备：Check if should proceed 和 Prepare metadata 步骤会计算 tag、prerelease 标志、是否最新版本以及用于分支名的 safe_tag。若任意校验失败，工作流立即退出。
检出分支：默认分支被检出到 main/，长期维护的 x-files/app-upgrade-config 分支则在 cs/ 中，所有改动都发生在 cs/。
安装工具链：安装 Node.js 22、启用 Corepack，并在 main/ 目录执行 yarn install --immutable。
运行更新脚本：执行 yarn tsx scripts/update-app-upgrade-config.ts --tag <tag> --config ../cs/app-upgrade-config.json --is-prerelease <flag>。
- 脚本会标准化 tag（去掉 v 前缀等）、识别渠道、加载 config/app-upgrade-segments.json 中的分段规则。
- 校验 prerelease 标志与语义后缀是否匹配、强制锁定的 segment 是否满足、生成镜像的下载地址，并检查 release 是否已经在 GitHub/GitCode 可用（latest 渠道在 GitCode 不可用时会回退到 https://releases.cherry-ai.com）。
- 更新对应的渠道配置后，脚本会按 semver 排序写回 JSON，并刷新 lastUpdated。
检测变更并创建 PR：若 cs/app-upgrade-config.json 有变更，则创建 chore/update-app-upgrade-config/<safe_tag> 分支，提交信息为 🤖 chore: sync app-upgrade-config for <tag>，并向 x-files/app-upgrade-config 提 PR；无变更则输出提示。

手动触发指南

进入 Cherry Studio 仓库的 GitHub Actions 页面，选择 Update App Upgrade Config 工作流。
点击 Run workflow，保持默认分支（通常为 main），填写 tag（如 v2.1.0）。
只有在 tag 带 -beta/-rc 后缀时才勾选 is_prerelease，稳定版保持默认。
启动运行并等待完成，随后到 x-files/app-upgrade-config 分支的 PR 查看 app-upgrade-config.json 的变更并在验证后合并。

JSON 配置文件格式

文件位置

GitHub: https://raw.githubusercontent.com/CherryHQ/cherry-studio/refs/heads/x-files/app-upgrade-config/app-upgrade-config.json
GitCode: https://gitcode.com/CherryHQ/cherry-studio/raw/x-files/app-upgrade-config/app-upgrade-config.json

说明：两个镜像源提供相同的配置文件，统一托管在 x-files/app-upgrade-config 分支上。客户端根据 IP 地理位置自动选择最优镜像源。

配置结构（当前实际配置）

{
  "lastUpdated": "2025-01-05T00:00:00Z",
  "versions": {
    "1.6.7": {
      "minCompatibleVersion": "1.0.0",
      "description": "Last stable v1.7.x release - required intermediate version for users below v1.7",
      "channels": {
        "latest": {
          "version": "1.6.7",
          "feedUrls": {
            "github": "https://github.com/CherryHQ/cherry-studio/releases/download/v1.6.7",
            "gitcode": "https://gitcode.com/CherryHQ/cherry-studio/releases/download/v1.6.7"
          }
        },
        "rc": {
          "version": "1.6.0-rc.5",
          "feedUrls": {
            "github": "https://github.com/CherryHQ/cherry-studio/releases/download/v1.6.0-rc.5",
            "gitcode": "https://github.com/CherryHQ/cherry-studio/releases/download/v1.6.0-rc.5"
          }
        },
        "beta": {
          "version": "1.6.7-beta.3",
          "feedUrls": {
            "github": "https://github.com/CherryHQ/cherry-studio/releases/download/v1.7.0-beta.3",
            "gitcode": "https://github.com/CherryHQ/cherry-studio/releases/download/v1.7.0-beta.3"
          }
        }
      }
    },
    "2.0.0": {
      "minCompatibleVersion": "1.7.0",
      "description": "Major release v2.0 - required intermediate version for v2.x upgrades",
      "channels": {
        "latest": null,
        "rc": null,
        "beta": null
      }
    }
  }
}

未来扩展示例

当需要发布 v3.0 时，如果需要强制用户先升级到 v2.8，可以添加：

{
  "2.8.0": {
    "minCompatibleVersion": "2.0.0",
    "description": "Stable v2.8 - required for v3 upgrade",
    "channels": {
      "latest": {
        "version": "2.8.0",
        "feedUrls": {
          "github": "https://github.com/CherryHQ/cherry-studio/releases/download/v2.8.0",
          "gitcode": "https://gitcode.com/CherryHQ/cherry-studio/releases/download/v2.8.0"
        }
      },
      "rc": null,
      "beta": null
    }
  },
  "3.0.0": {
    "minCompatibleVersion": "2.8.0",
    "description": "Major release v3.0",
    "channels": {
      "latest": {
        "version": "3.0.0",
        "feedUrls": {
          "github": "https://github.com/CherryHQ/cherry-studio/releases/latest",
          "gitcode": "https://gitcode.com/CherryHQ/cherry-studio/releases/latest"
        }
      },
      "rc": {
        "version": "3.0.0-rc.1",
        "feedUrls": {
          "github": "https://github.com/CherryHQ/cherry-studio/releases/download/v3.0.0-rc.1",
          "gitcode": "https://gitcode.com/CherryHQ/cherry-studio/releases/download/v3.0.0-rc.1"
        }
      },
      "beta": null
    }
  }
}

字段说明

lastUpdated: 配置文件最后更新时间（ISO 8601 格式）
versions: 版本配置对象，key 为版本号，按语义化版本排序
- minCompatibleVersion: 可以升级到此版本的最低兼容版本
- description: 版本描述
- channels: 更新渠道配置
  - latest: 稳定版渠道
  - rc: Release Candidate 渠道
  - beta: Beta 测试渠道
  - 每个渠道包含：
    - version: 该渠道的版本号
    - feedUrls: 多镜像源 URL 配置
      - github: GitHub 镜像源的 electron-updater feed URL
      - gitcode: GitCode 镜像源的 electron-updater feed URL
- metadata: 自动化匹配所需的稳定标识
  - segmentId: 来自 config/app-upgrade-segments.json 的段位 ID
  - segmentType: 可选字段（legacy | breaking | latest），便于文档/调试

TypeScript 类型定义

// 镜像源枚举
enum UpdateMirror {
  GITHUB = 'github',
  GITCODE = 'gitcode'
}

interface UpdateConfig {
  lastUpdated: string
  versions: {
    [versionKey: string]: VersionConfig
  }
}

interface VersionConfig {
  minCompatibleVersion: string
  description: string
  channels: {
    latest: ChannelConfig | null
    rc: ChannelConfig | null
    beta: ChannelConfig | null
  }
  metadata?: {
    segmentId: string
    segmentType?: 'legacy' | 'breaking' | 'latest'
  }
}

interface ChannelConfig {
  version: string
  feedUrls: Record<UpdateMirror, string>
  // 等同于:
  // feedUrls: {
  //   github: string
  //   gitcode: string
  // }
}

段位元数据（Break Change 标记）

所有段位定义（如 legacy-v1、gateway-v2 等）集中在 config/app-upgrade-segments.json，用于描述匹配范围、segmentId、segmentType、默认 minCompatibleVersion/description 以及各渠道的 URL 模板。
versions 下的每个节点都会带上 metadata.segmentId。自动脚本始终依据该 ID 来定位并更新条目，即便 key 从 2.1.5 切换到 2.1.6 也不会错位。
如果某段需要锁死在特定版本（例如 2.0.0 的 break change），可在段定义中设置 segmentType: "breaking" 并提供 lockedVersion，脚本在遇到不匹配的 tag 时会短路报错，保证升级路径安全。
面对未来新的断层（例如 3.0.0），只需要在段定义里新增一段，自动化即可识别并更新。

自动化工作流

.github/workflows/update-app-upgrade-config.yml 会在 GitHub Release（包含正常发布与 Pre Release）触发：

同时 Checkout 仓库默认分支（用于脚本）和 x-files/app-upgrade-config 分支（真实托管配置的分支）。
在默认分支目录执行 yarn tsx scripts/update-app-upgrade-config.ts --tag <tag> --config ../cs/app-upgrade-config.json，直接重写 x-files/app-upgrade-config 分支里的配置文件。
如果 app-upgrade-config.json 有变化，则通过 peter-evans/create-pull-request 自动创建一个指向 x-files/app-upgrade-config 的 PR，Diff 仅包含该文件。

如需本地调试，可执行 yarn update:upgrade-config --tag v2.1.6 --config ../cs/app-upgrade-config.json（加 --dry-run 仅打印结果）来复现 CI 行为。若需要暂时跳过 GitHub/GitCode Release 页面是否就绪的校验，可在 --dry-run 的同时附加 --skip-release-checks。不加 --config 时默认更新当前工作目录（通常是 main 分支）下的副本，方便文档/审查。

版本匹配逻辑

算法流程

获取用户当前版本（currentVersion）和请求的渠道（requestedChannel）
获取配置文件中所有版本号，按语义化版本从大到小排序
遍历排序后的版本列表：
- 检查 currentVersion >= minCompatibleVersion
- 检查请求的 channel 是否存在且不为 null
- 如果满足条件，返回该渠道配置
如果没有找到匹配版本，返回 null

伪代码实现

function findCompatibleVersion(
  currentVersion: string,
  requestedChannel: UpgradeChannel,
  config: UpdateConfig
): ChannelConfig | null {
  // 获取所有版本号并从大到小排序
  const versions = Object.keys(config.versions).sort(semver.rcompare)

  for (const versionKey of versions) {
    const versionConfig = config.versions[versionKey]
    const channelConfig = versionConfig.channels[requestedChannel]

    // 检查版本兼容性和渠道可用性
    if (
      semver.gte(currentVersion, versionConfig.minCompatibleVersion) &&
      channelConfig !== null
    ) {
      return channelConfig
    }
  }

  return null // 没有找到兼容版本
}

升级路径示例

场景 1: v1.6.5 用户升级（低于 1.7）

当前版本: 1.6.5
请求渠道: latest
匹配结果: 1.7.0
原因: 1.6.5 >= 0.0.0（满足 1.7.0 的 minCompatibleVersion），但不满足 2.0.0 的 minCompatibleVersion (1.7.0)
操作: 提示用户升级到 1.7.0，这是升级到 v2.x 的必要中间版本

场景 2: v1.6.5 用户请求 rc/beta

当前版本: 1.6.5
请求渠道: rc 或 beta
匹配结果: 1.7.0 (latest)
原因: 1.7.0 版本不提供 rc/beta 渠道（值为 null）
操作: 升级到 1.7.0 稳定版

场景 3: v1.7.0 用户升级到最新版

当前版本: 1.7.0
请求渠道: latest
匹配结果: 2.0.0
原因: 1.7.0 >= 1.7.0（满足 2.0.0 的 minCompatibleVersion）
操作: 直接升级到 2.0.0（当前最新稳定版）

场景 4: v1.7.2 用户升级到 RC 版本

当前版本: 1.7.2
请求渠道: rc
匹配结果: 2.0.0-rc.1
原因: 1.7.2 >= 1.7.0（满足 2.0.0 的 minCompatibleVersion），且 rc 渠道存在
操作: 升级到 2.0.0-rc.1

场景 5: v1.7.0 用户升级到 Beta 版本

当前版本: 1.7.0
请求渠道: beta
匹配结果: 2.0.0-beta.1
原因: 1.7.0 >= 1.7.0，且 beta 渠道存在
操作: 升级到 2.0.0-beta.1

场景 6: v2.5.0 用户升级（未来）

假设已添加 v2.8.0 和 v3.0.0 配置：

当前版本: 2.5.0
请求渠道: latest
匹配结果: 2.8.0
原因: 2.5.0 >= 2.0.0（满足 2.8.0 的 minCompatibleVersion），但不满足 3.0.0 的要求
操作: 提示用户升级到 2.8.0，这是升级到 v3.x 的必要中间版本

代码改动计划

主要修改

新增方法
- _fetchUpdateConfig(ipCountry: string): Promise<UpdateConfig | null> - 根据 IP 获取配置文件
- _findCompatibleChannel(currentVersion: string, channel: UpgradeChannel, config: UpdateConfig): ChannelConfig | null - 查找兼容的渠道配置
修改方法
- _getReleaseVersionFromGithub() → 移除或重构为 _getChannelFeedUrl()
- _setFeedUrl() - 使用新的配置系统替代现有逻辑
新增类型定义
- UpdateConfig
- VersionConfig
- ChannelConfig

镜像源选择逻辑

客户端根据 IP 地理位置自动选择最优镜像源：

private async _setFeedUrl() {
  const currentVersion = app.getVersion()
  const testPlan = configManager.getTestPlan()
  const requestedChannel = testPlan ? this._getTestChannel() : UpgradeChannel.LATEST

  // 根据 IP 国家确定镜像源
  const ipCountry = await getIpCountry()
  const mirror = ipCountry.toLowerCase() === 'cn' ? 'gitcode' : 'github'

  // 获取更新配置
  const config = await this._fetchUpdateConfig(mirror)

  if (config) {
    const channelConfig = this._findCompatibleChannel(currentVersion, requestedChannel, config)
    if (channelConfig) {
      // 从配置中选择对应镜像源的 URL
      const feedUrl = channelConfig.feedUrls[mirror]
      this._setChannel(requestedChannel, feedUrl)
      return
    }
  }

  // Fallback 逻辑
  const defaultFeedUrl = mirror === 'gitcode'
    ? FeedUrl.PRODUCTION
    : FeedUrl.GITHUB_LATEST
  this._setChannel(UpgradeChannel.LATEST, defaultFeedUrl)
}

private async _fetchUpdateConfig(mirror: 'github' | 'gitcode'): Promise<UpdateConfig | null> {
  const configUrl = mirror === 'gitcode'
    ? UpdateConfigUrl.GITCODE
    : UpdateConfigUrl.GITHUB

  try {
    const response = await net.fetch(configUrl, {
      headers: {
        'User-Agent': generateUserAgent(),
        'Accept': 'application/json',
        'X-Client-Id': configManager.getClientId()
      }
    })
    return await response.json() as UpdateConfig
  } catch (error) {
    logger.error('Failed to fetch update config:', error)
    return null
  }
}

降级和容错策略

配置文件获取失败: 记录错误日志，返回当前版本，不提供更新
没有匹配的版本: 提示用户当前版本不支持自动升级
网络异常: 缓存上次成功获取的配置（可选）

GitHub Release 要求

为支持中间版本升级，需要保留以下文件：

v1.7.0 release 及其 latest*.yml 文件（作为 v1.7 以下用户的升级目标）
未来如需强制中间版本（如 v2.8.0），需要保留对应的 release 和 latest*.yml 文件
各版本的完整安装包

当前需要的 Release

版本	用途	必须保留
v1.7.0	1.7 以下用户的升级目标	✅ 是
v2.0.0-rc.1	RC 测试渠道	❌ 可选
v2.0.0-beta.1	Beta 测试渠道	❌ 可选
latest	最新稳定版（自动）	✅ 是

优势

灵活性: 支持任意复杂的升级路径
可扩展性: 新增版本只需在配置文件中添加新条目
可维护性: 配置与代码分离，无需发版即可调整升级策略
多源支持: 自动根据地理位置选择最优配置源
版本控制: 强制中间版本升级，确保数据迁移和兼容性

未来扩展

支持更细粒度的版本范围控制（如 >=1.5.0 <1.8.0）
支持多步升级路径提示（如提示用户需要 1.5 → 1.8 → 2.0）
支持 A/B 测试和灰度发布
支持配置文件的本地缓存和过期策略

17 KiB Raw Blame History Unescape Escape

更新配置系统设计文档

背景

设计目标

当前版本策略

自动化工作流

触发条件

工作流步骤

手动触发指南

JSON 配置文件格式

文件位置

配置结构（当前实际配置）

未来扩展示例

字段说明

TypeScript 类型定义

段位元数据（Break Change 标记）

自动化工作流

版本匹配逻辑

算法流程

伪代码实现

升级路径示例

场景 1: v1.6.5 用户升级（低于 1.7）

场景 2: v1.6.5 用户请求 rc/beta

场景 3: v1.7.0 用户升级到最新版

场景 4: v1.7.2 用户升级到 RC 版本

场景 5: v1.7.0 用户升级到 Beta 版本

场景 6: v2.5.0 用户升级（未来）

代码改动计划

主要修改

镜像源选择逻辑

降级和容错策略

GitHub Release 要求

当前需要的 Release

优势

未来扩展

17 KiB

Raw Blame History