Tolaria Canary 发布通道与本地特性标志ADR-0017 架构决策与源码级实现解析【免费下载链接】tolariaDesktop app to manage markdown knowledge bases项目地址: https://gitcode.com/GitHub_Trending/to/tolaria本文以 docs/adr/canary-release-channel-and-local-feature-flags.mdADR-0017为主体结合仓库内useFeatureFlagHook、useUpdaterHook、发布通道文档与后续 ADR 的演进脉络完整还原 Tolaria 桌面应用预发布构建分发 无需发版即可切换的特性开关这套机制的决策过程、落地实现与后续演进帮助读者理解其设计取舍并可直接对照源码验证每个细节。一、背景与动机为什么需要 Canary 通道和本地特性标志Tolaria 是一款用于管理 Markdown 知识库的桌面应用Tauri React 技术栈。在 ADR-0017 诞生之前项目面临两个现实问题新功能直接推送给所有用户风险过高。桌面应用一旦发布出问题就要发新版本修复回滚成本高、用户感知明显。实验性功能缺少灰度手段。如果想让部分早期用户先体验某个未完工功能却没有一个无需发布新版本即可开关的机制那么任何试验都要走完整发布流程。因此项目需要两套互补的能力docs/adr/canary-release-channel-and-local-feature-flags.md一个预发布pre-release构建通道让早期采用者先于正式用户拿到完整构建进行测试一套特性标志feature flags机制让实验性功能可以在不发布新版本的前提下被打开或关闭。这个决策与项目的 键盘优先设计原则 处于同一时期的演进脉络中体现了以最小基础设施成本换取最大发布灵活性的工程取向。二、决策内容Canary 分支 localStorage 特性标志ADR-0017 做出的核心决策可以概括为一句话在 stable 通道之外增加一条 canary 发布通道其构建来自canary分支特性标志采用 localStorage 键ff_name存储并带编译期默认值通过useFeatureFlag(flag)Hook 检查更新通道可在设置Settings中配置。拆解开来这条决策包含四个可落地的组成部件部件具体方案说明发布通道canary分支 stable分支stable 面向普通用户canary 面向早期采用者特性标志存储localStorage键名为ff_name例如ff_example_flag特性标志默认值编译期默认未设置 localStorage 覆盖时使用编译期默认值特性标志读取useFeatureFlag(flag)Hook类型安全通过FeatureFlagName联合类型约束更新通道配置Settings 中的update_channel字段取值为stable或canary这套方案的核心理念是把分发风险和功能风险解耦canary 通道解决完整预发布构建的分发问题特性标志解决单个功能的安全上线问题两者可以独立使用也可以组合使用。三、方案对比为什么最终放弃 Server-Side 特性标志ADR-0017 明确记录了三个候选方案及其取舍这是理解本决策的关键Option A被选中Canary 分支 localStorage 特性标志优点实现简单不需要任何服务器基础设施用户通过 Settings 主动选择进入无外部依赖、无额外延迟。缺点没有远程标志管理能力无法做按百分比的渐进式灰度gradual rollout也无法做 A/B 测试。Option B服务端特性标志LaunchDarkly、Unleash 等优点支持渐进式灰度、A/B 测试等高级能力。缺点引入外部依赖需要搭建和运维服务器基础设施增加请求延迟。Option C单一发布通道 仅使用特性标志优点CI 更简单不必维护多分支构建。缺点无法测试完整的预发布构建特性标志只能控制逻辑开关无法验证整包构建的兼容性、打包、签名、更新链路。最终选择 Option A 的根本原因是项目在当时阶段用户规模和团队规模都还不需要服务端灰度能力用本地开关 双通道就能以近乎零成本覆盖核心诉求。同时 ADR 也明确留下了再评估触发器Re-evaluation trigger一旦用户基数增长到需要服务端渐进式灰度就应重新评估该决策。这保证了决策不是僵化的而是有明确演进路径的。四、源码级实现useFeatureFlagHook 与 localStorage 覆盖机制ADR-0017 描述的useFeatureFlag(flag)Hook 在仓库中有完整实现src/hooks/useFeatureFlag.ts/** * Feature flag hook backed by PostHog release channels. * * Flags are resolved in order: * 1. localStorage override (ff_name) — for dev/QA testing * 2. PostHog feature flags (evaluated by release channel) * 3. Alpha channel always returns true (sees all features) */ import { isFeatureEnabled } from ../lib/telemetry export type FeatureFlagName example_flag export function useFeatureFlag(flag: FeatureFlagName): boolean { try { const override localStorage.getItem(ff_${flag}) if (override ! null) return override true } catch { // localStorage may be unavailable in some contexts } return isFeatureEnabled(flag) }结合源码注释可以确认该 Hook 的解析优先级在项目后续演进中扩展为三层localStorage 覆盖ff_name用于开发与 QA 测试优先级最高。只要存在该键true即视为开启其余任何值包括false都视为关闭。PostHog 特性标志按发布通道评估这是 ADR-0042PostHog 发布通道与特性标志 引入的远程能力。Alpha 通道兜底Alpha 通道始终返回true即所有特性对 Alpha 用户可见这属于后续 0057/0066 决策中的演进行为。几个值得注意的实现细节类型安全FeatureFlagName被定义为字符串字面量联合类型当前示例为example_flag所有调用点传入的标志名都受编译期约束避免拼写错误导致开关静默失效。异常兜底localStorage在少数环境如部分 WebView 或隐私模式可能不可用代码用try/catch包裹读取失败时静默回退到默认值保证应用不因开关检查而崩溃。非布尔值处理覆盖值只有严格等于字符串true才开启false、maybe等一律视为关闭——这是一个防御性设计防止脏数据误开功能。测试用例验证src/hooks/useFeatureFlag.test.ts 用 Vitest 完整覆盖了上述行为默认情况下localStorage 无覆盖example_flag返回false覆盖值设为true时返回true覆盖值设为false时返回false非布尔值如maybe被视为false当localStorage抛异常时回退到默认值false。这组测试用例本身就是一份行为契约任何改动都必须保持这五条语义不变这正体现了 ADR 决策在代码层面的可验证性。五、更新通道useUpdater(channel)与设置项update_channelADR-0017 规定更新检查通过useUpdater(channel)完成更新通道在设置中以update_channel存储stable或canary。仓库实现见 src/hooks/useUpdater.ts其核心签名与状态机如下export function useUpdater( releaseChannel: string | null | undefined, automaticChecksEnabled true, ): { status: UpdateStatus; actions: UpdateActions }入参releaseChannel即从设置读取的更新通道值直接传给底层checkForAppUpdate(releaseChannel)与downloadAndInstallAppUpdate(releaseChannel, version, handler)决定去拉取哪个更新清单manifest。自动检查在 Tauri 环境下挂载后约 3 秒自动触发一次检查setTimeout(..., 3000)也可手动调用checkForUpdates。状态机UpdateStatus覆盖idle → checking → available → downloading带进度 → ready → error的完整更新流程downloading状态通过Started/Progress/Finished事件驱动progress按已下载字节数计算。非 Tauri 环境isTauri()为假时直接返回up-to-date保证 Web 端调试不触发更新逻辑。在设置层面update_channel是持久化的应用设置项用户在 Settings 中选择 stable 或 canary 后后续所有更新检查都会按该通道拉取对应清单。ADR-0017 要求切换通道后能收到对应通道的预发布更新这正是useUpdater(channel)将通道值贯穿到更新清单选择这一设计的目的。六、发布流水线从release.yml到latest-canary.jsonADR-0017 的 Consequences 部分明确了双通道的 CI 分工release.yml从main分支构建stable发布release-canary.yml从canary分支构建canary发布Canary 发布产物在 GitHub Pages 上生成latest-canary.json更新清单并标记为prerelease预发布。latest-canary.json是一个指向最新 canary 构建的更新元数据文件更新器读取它即可获知最新版本号与下载地址从而实现切换到 canary 通道 → 自动发现并安装预发布构建的闭环。这一机制在仓库文档中留有持续痕迹docs/ARCHITECTURE.md 提到latest-canary.json作为兼容别名被刷新指向 alpha 元数据而 site/reference/release-channels.md 中列出/latest.json /latest-canary.json作为兼容性端点继续指向 alpha 元数据详情见下节演进说明。七、影响与落地Consequences总结ADR-0017 记录的决策影响可归纳为五条均能在仓库中找到对应实现或文档双 CI 流水线stable 与 canary 由不同工作流、不同分支驱动互不干扰预发布清单latest-canary.json承载 canary 通道的更新发现更新检查按通道分流useUpdater(channel)依据设置值选择对应更新清单特性检查两级解析useFeatureFlag(flag)先查 localStorage 覆盖再回退编译期默认值且以FeatureFlagName联合类型保证类型安全设置持久化update_channel仅接受stable与canary两个合法值。此外ADR 明确写入了再评估条件当用户基数增长到需要服务端渐进式灰度时重新评估该决策。这为后续演进埋下了伏笔。八、历史演进从 Canary 分支到 Alpha/Stable 双通道需要特别说明的是ADR-0017 本身的状态为active但其描述的canary 分支更新器模型在后续被 docs/adr/0057-alpha-stable-release-channels-and-beta-cohorts.mdADR-0057明确取代0057 声明 This ADR supersedes ADR-0017s canary-branch updater model。演进后的模型为Alpha 通道每次推送到main即自动发布 alpha 预发布构建到alpha/latest.jsonStable 通道手动推送stable-vX.Y.Z标签触发稳定版发布到stable/latest.jsonBeta 受众不再作为独立二进制或更新源而是在 PostHog 中用人群/属性建模兼容别名遗留的latest.json与latest-canary.json继续作为兼容端点镜像 alpha 元数据保证老配置的更新器仍能工作版本号语义Alpha 版本采用日历语义预发布号如1.2.4-alpha.202604122135.7确保用户在 stable 与 alpha 间切换时 semver 排序始终正确不会因低于最新稳定版而漏掉新构建。而 ADR-0017 的localStorage 特性标志机制则完整保留并延续下来并在 docs/adr/0042-posthog-release-channels-feature-flags.md 中演进出localStorage 覆盖 → PostHog 特性标志 → 通道兜底的三级解析模型即useFeatureFlag源码注释中描述的顺序。可见 ADR-0017 的本地开关设计作为基础设施层其价值并未随通道模型的更替而消失。九、实践要点开发者如何使用这套机制基于以上分析在实际开发与测试中可以这样使用本地开启一个实验功能在应用 DevTools 控制台执行localStorage.setItem(ff_name, true)即可不依赖任何后端强制开启对应特性置为false或删除该键localStorage.removeItem(ff_name)即可关闭。键名必须与FeatureFlagName联合类型中的名称一致。新增一个特性标志在 src/hooks/useFeatureFlag.ts 的FeatureFlagName联合类型中加入新名称然后在组件中调用useFeatureFlag(new_flag)并按布尔值渲染同时建议参照 src/hooks/useFeatureFlag.test.ts 补充测试用例。体验预发布构建在 Settings 中将更新通道切换为 canary或按 0057 之后的模型切换 alpha更新器会按对应通道拉取latest-canary.json或alpha/latest.json并提示安装预发布版本。切换前务必先提交或推送重要的 vault 变更使 Git 处于干净状态——这是 site/reference/release-channels.md 中明确给出的建议因为笔记本体是本地文件干净的 Git 状态能让回滚与恢复更简单。理解解析顺序任何特性检查的结果都是localStorage 覆盖优先否则编译期默认值后续演进中还有 PostHog 与通道兜底。调试时若发现开关不生效应首先确认是否存在残留的ff_*键。十、小结ADR-0017 展示了一个典型的用最小基础设施换取最大发布灵活性的架构决策以canary分支 latest-canary.json解决预发布构建分发以ff_namelocalStorage 键 useFeatureFlag(flag)Hook 解决免发版特性开关以设置项update_channel串联两条通道。它主动放弃了服务端灰度能力同时用明确的再评估条件为未来升级留出路径。这一决策在仓库中的完整落地——useFeatureFlag.ts、useFeatureFlag.test.ts、useUpdater.ts 以及 release-channels.md——为理解如何低成本地为桌面应用建立安全发布体系提供了可直接对照的工程范本而其后续被 ADR-0057 演进取代的过程也展示了 ADR 机制本身可被显式取代、演进有据可循的价值。【免费下载链接】tolariaDesktop app to manage markdown knowledge bases项目地址: https://gitcode.com/GitHub_Trending/to/tolaria创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Tolaria Canary 发布通道与本地特性标志：ADR-0017 架构决策与源码级实现解析
Tolaria Canary 发布通道与本地特性标志ADR-0017 架构决策与源码级实现解析【免费下载链接】tolariaDesktop app to manage markdown knowledge bases项目地址: https://gitcode.com/GitHub_Trending/to/tolaria本文以 docs/adr/canary-release-channel-and-local-feature-flags.mdADR-0017为主体结合仓库内useFeatureFlagHook、useUpdaterHook、发布通道文档与后续 ADR 的演进脉络完整还原 Tolaria 桌面应用预发布构建分发 无需发版即可切换的特性开关这套机制的决策过程、落地实现与后续演进帮助读者理解其设计取舍并可直接对照源码验证每个细节。一、背景与动机为什么需要 Canary 通道和本地特性标志Tolaria 是一款用于管理 Markdown 知识库的桌面应用Tauri React 技术栈。在 ADR-0017 诞生之前项目面临两个现实问题新功能直接推送给所有用户风险过高。桌面应用一旦发布出问题就要发新版本修复回滚成本高、用户感知明显。实验性功能缺少灰度手段。如果想让部分早期用户先体验某个未完工功能却没有一个无需发布新版本即可开关的机制那么任何试验都要走完整发布流程。因此项目需要两套互补的能力docs/adr/canary-release-channel-and-local-feature-flags.md一个预发布pre-release构建通道让早期采用者先于正式用户拿到完整构建进行测试一套特性标志feature flags机制让实验性功能可以在不发布新版本的前提下被打开或关闭。这个决策与项目的 键盘优先设计原则 处于同一时期的演进脉络中体现了以最小基础设施成本换取最大发布灵活性的工程取向。二、决策内容Canary 分支 localStorage 特性标志ADR-0017 做出的核心决策可以概括为一句话在 stable 通道之外增加一条 canary 发布通道其构建来自canary分支特性标志采用 localStorage 键ff_name存储并带编译期默认值通过useFeatureFlag(flag)Hook 检查更新通道可在设置Settings中配置。拆解开来这条决策包含四个可落地的组成部件部件具体方案说明发布通道canary分支 stable分支stable 面向普通用户canary 面向早期采用者特性标志存储localStorage键名为ff_name例如ff_example_flag特性标志默认值编译期默认未设置 localStorage 覆盖时使用编译期默认值特性标志读取useFeatureFlag(flag)Hook类型安全通过FeatureFlagName联合类型约束更新通道配置Settings 中的update_channel字段取值为stable或canary这套方案的核心理念是把分发风险和功能风险解耦canary 通道解决完整预发布构建的分发问题特性标志解决单个功能的安全上线问题两者可以独立使用也可以组合使用。三、方案对比为什么最终放弃 Server-Side 特性标志ADR-0017 明确记录了三个候选方案及其取舍这是理解本决策的关键Option A被选中Canary 分支 localStorage 特性标志优点实现简单不需要任何服务器基础设施用户通过 Settings 主动选择进入无外部依赖、无额外延迟。缺点没有远程标志管理能力无法做按百分比的渐进式灰度gradual rollout也无法做 A/B 测试。Option B服务端特性标志LaunchDarkly、Unleash 等优点支持渐进式灰度、A/B 测试等高级能力。缺点引入外部依赖需要搭建和运维服务器基础设施增加请求延迟。Option C单一发布通道 仅使用特性标志优点CI 更简单不必维护多分支构建。缺点无法测试完整的预发布构建特性标志只能控制逻辑开关无法验证整包构建的兼容性、打包、签名、更新链路。最终选择 Option A 的根本原因是项目在当时阶段用户规模和团队规模都还不需要服务端灰度能力用本地开关 双通道就能以近乎零成本覆盖核心诉求。同时 ADR 也明确留下了再评估触发器Re-evaluation trigger一旦用户基数增长到需要服务端渐进式灰度就应重新评估该决策。这保证了决策不是僵化的而是有明确演进路径的。四、源码级实现useFeatureFlagHook 与 localStorage 覆盖机制ADR-0017 描述的useFeatureFlag(flag)Hook 在仓库中有完整实现src/hooks/useFeatureFlag.ts/** * Feature flag hook backed by PostHog release channels. * * Flags are resolved in order: * 1. localStorage override (ff_name) — for dev/QA testing * 2. PostHog feature flags (evaluated by release channel) * 3. Alpha channel always returns true (sees all features) */ import { isFeatureEnabled } from ../lib/telemetry export type FeatureFlagName example_flag export function useFeatureFlag(flag: FeatureFlagName): boolean { try { const override localStorage.getItem(ff_${flag}) if (override ! null) return override true } catch { // localStorage may be unavailable in some contexts } return isFeatureEnabled(flag) }结合源码注释可以确认该 Hook 的解析优先级在项目后续演进中扩展为三层localStorage 覆盖ff_name用于开发与 QA 测试优先级最高。只要存在该键true即视为开启其余任何值包括false都视为关闭。PostHog 特性标志按发布通道评估这是 ADR-0042PostHog 发布通道与特性标志 引入的远程能力。Alpha 通道兜底Alpha 通道始终返回true即所有特性对 Alpha 用户可见这属于后续 0057/0066 决策中的演进行为。几个值得注意的实现细节类型安全FeatureFlagName被定义为字符串字面量联合类型当前示例为example_flag所有调用点传入的标志名都受编译期约束避免拼写错误导致开关静默失效。异常兜底localStorage在少数环境如部分 WebView 或隐私模式可能不可用代码用try/catch包裹读取失败时静默回退到默认值保证应用不因开关检查而崩溃。非布尔值处理覆盖值只有严格等于字符串true才开启false、maybe等一律视为关闭——这是一个防御性设计防止脏数据误开功能。测试用例验证src/hooks/useFeatureFlag.test.ts 用 Vitest 完整覆盖了上述行为默认情况下localStorage 无覆盖example_flag返回false覆盖值设为true时返回true覆盖值设为false时返回false非布尔值如maybe被视为false当localStorage抛异常时回退到默认值false。这组测试用例本身就是一份行为契约任何改动都必须保持这五条语义不变这正体现了 ADR 决策在代码层面的可验证性。五、更新通道useUpdater(channel)与设置项update_channelADR-0017 规定更新检查通过useUpdater(channel)完成更新通道在设置中以update_channel存储stable或canary。仓库实现见 src/hooks/useUpdater.ts其核心签名与状态机如下export function useUpdater( releaseChannel: string | null | undefined, automaticChecksEnabled true, ): { status: UpdateStatus; actions: UpdateActions }入参releaseChannel即从设置读取的更新通道值直接传给底层checkForAppUpdate(releaseChannel)与downloadAndInstallAppUpdate(releaseChannel, version, handler)决定去拉取哪个更新清单manifest。自动检查在 Tauri 环境下挂载后约 3 秒自动触发一次检查setTimeout(..., 3000)也可手动调用checkForUpdates。状态机UpdateStatus覆盖idle → checking → available → downloading带进度 → ready → error的完整更新流程downloading状态通过Started/Progress/Finished事件驱动progress按已下载字节数计算。非 Tauri 环境isTauri()为假时直接返回up-to-date保证 Web 端调试不触发更新逻辑。在设置层面update_channel是持久化的应用设置项用户在 Settings 中选择 stable 或 canary 后后续所有更新检查都会按该通道拉取对应清单。ADR-0017 要求切换通道后能收到对应通道的预发布更新这正是useUpdater(channel)将通道值贯穿到更新清单选择这一设计的目的。六、发布流水线从release.yml到latest-canary.jsonADR-0017 的 Consequences 部分明确了双通道的 CI 分工release.yml从main分支构建stable发布release-canary.yml从canary分支构建canary发布Canary 发布产物在 GitHub Pages 上生成latest-canary.json更新清单并标记为prerelease预发布。latest-canary.json是一个指向最新 canary 构建的更新元数据文件更新器读取它即可获知最新版本号与下载地址从而实现切换到 canary 通道 → 自动发现并安装预发布构建的闭环。这一机制在仓库文档中留有持续痕迹docs/ARCHITECTURE.md 提到latest-canary.json作为兼容别名被刷新指向 alpha 元数据而 site/reference/release-channels.md 中列出/latest.json /latest-canary.json作为兼容性端点继续指向 alpha 元数据详情见下节演进说明。七、影响与落地Consequences总结ADR-0017 记录的决策影响可归纳为五条均能在仓库中找到对应实现或文档双 CI 流水线stable 与 canary 由不同工作流、不同分支驱动互不干扰预发布清单latest-canary.json承载 canary 通道的更新发现更新检查按通道分流useUpdater(channel)依据设置值选择对应更新清单特性检查两级解析useFeatureFlag(flag)先查 localStorage 覆盖再回退编译期默认值且以FeatureFlagName联合类型保证类型安全设置持久化update_channel仅接受stable与canary两个合法值。此外ADR 明确写入了再评估条件当用户基数增长到需要服务端渐进式灰度时重新评估该决策。这为后续演进埋下了伏笔。八、历史演进从 Canary 分支到 Alpha/Stable 双通道需要特别说明的是ADR-0017 本身的状态为active但其描述的canary 分支更新器模型在后续被 docs/adr/0057-alpha-stable-release-channels-and-beta-cohorts.mdADR-0057明确取代0057 声明 This ADR supersedes ADR-0017s canary-branch updater model。演进后的模型为Alpha 通道每次推送到main即自动发布 alpha 预发布构建到alpha/latest.jsonStable 通道手动推送stable-vX.Y.Z标签触发稳定版发布到stable/latest.jsonBeta 受众不再作为独立二进制或更新源而是在 PostHog 中用人群/属性建模兼容别名遗留的latest.json与latest-canary.json继续作为兼容端点镜像 alpha 元数据保证老配置的更新器仍能工作版本号语义Alpha 版本采用日历语义预发布号如1.2.4-alpha.202604122135.7确保用户在 stable 与 alpha 间切换时 semver 排序始终正确不会因低于最新稳定版而漏掉新构建。而 ADR-0017 的localStorage 特性标志机制则完整保留并延续下来并在 docs/adr/0042-posthog-release-channels-feature-flags.md 中演进出localStorage 覆盖 → PostHog 特性标志 → 通道兜底的三级解析模型即useFeatureFlag源码注释中描述的顺序。可见 ADR-0017 的本地开关设计作为基础设施层其价值并未随通道模型的更替而消失。九、实践要点开发者如何使用这套机制基于以上分析在实际开发与测试中可以这样使用本地开启一个实验功能在应用 DevTools 控制台执行localStorage.setItem(ff_name, true)即可不依赖任何后端强制开启对应特性置为false或删除该键localStorage.removeItem(ff_name)即可关闭。键名必须与FeatureFlagName联合类型中的名称一致。新增一个特性标志在 src/hooks/useFeatureFlag.ts 的FeatureFlagName联合类型中加入新名称然后在组件中调用useFeatureFlag(new_flag)并按布尔值渲染同时建议参照 src/hooks/useFeatureFlag.test.ts 补充测试用例。体验预发布构建在 Settings 中将更新通道切换为 canary或按 0057 之后的模型切换 alpha更新器会按对应通道拉取latest-canary.json或alpha/latest.json并提示安装预发布版本。切换前务必先提交或推送重要的 vault 变更使 Git 处于干净状态——这是 site/reference/release-channels.md 中明确给出的建议因为笔记本体是本地文件干净的 Git 状态能让回滚与恢复更简单。理解解析顺序任何特性检查的结果都是localStorage 覆盖优先否则编译期默认值后续演进中还有 PostHog 与通道兜底。调试时若发现开关不生效应首先确认是否存在残留的ff_*键。十、小结ADR-0017 展示了一个典型的用最小基础设施换取最大发布灵活性的架构决策以canary分支 latest-canary.json解决预发布构建分发以ff_namelocalStorage 键 useFeatureFlag(flag)Hook 解决免发版特性开关以设置项update_channel串联两条通道。它主动放弃了服务端灰度能力同时用明确的再评估条件为未来升级留出路径。这一决策在仓库中的完整落地——useFeatureFlag.ts、useFeatureFlag.test.ts、useUpdater.ts 以及 release-channels.md——为理解如何低成本地为桌面应用建立安全发布体系提供了可直接对照的工程范本而其后续被 ADR-0057 演进取代的过程也展示了 ADR 机制本身可被显式取代、演进有据可循的价值。【免费下载链接】tolariaDesktop app to manage markdown knowledge bases项目地址: https://gitcode.com/GitHub_Trending/to/tolaria创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
