Tolaria 隐私优先遥测架构Sentry 崩溃上报 PostHog 产品分析的双轨 Opt-in 设计【免费下载链接】tolariaDesktop app to manage markdown knowledge bases项目地址: https://gitcode.com/GitHub_Trending/to/tolaria本文基于 Tolaria基于 Tauri v2 React 的本地优先 Markdown 知识库桌面应用仓库即GitHub_Trending/to/tolaria的架构决策记录 ADR-0016Sentry crash reporting PostHog analytics with consent系统讲解一个以 Markdown Vault 为数据核心的桌面应用如何在公开版本到来之际同时满足「可观测性」与「用户隐私」两个看似冲突的诉求。读完本文你将掌握TelemetryConsentDialog 首启同意对话框的完整数据流、useTelemetry响应式初始化/拆除机制、前后端双路径脱敏path scrubber的具体实现、DSN/Key 的环境变量注入与校验规则以及可复用的「按用户设置实时启停遥测」的工程模式。一、背景为什么一个纯本地应用也需要遥测Tolaria 的核心产品形态是「本地 Vault Git 同步」Vault 中存放的是用户真实的笔记内容。这类应用对外发布后往往面临两个致命盲区崩溃盲区用户侧发生 Rust panic 或渲染层异常时开发者完全不知道错误栈只能依赖用户主动反馈功能采纳盲区团队无法判断哪些功能真实被使用、哪些入口形同虚设难以做特性优先级排序。但与此同时个人知识管理应用处理的是高敏感数据遥测一旦默认开启就等同于背叛用户信任。因此 ADR-0016 确立的核心约束是任何遥测都必须是显式 Opt-in且必须在首次启动时通过明确的同意对话框获得授权未经肯定性同意绝不发送任何数据。二、决策双服务 双开关的 Consent 架构决策原文如下来自 docs/adr/0016-sentry-posthog-telemetry.mdIntegrate Sentry for crash reporting and PostHog for product analytics, both gated behind an explicit consent dialog on first launch. Users can toggle each independently in Settings. No telemetry is sent without affirmative consent.即维度设计崩溃上报Sentry前端sentry/react 后端sentryRust crate产品分析PostHogposthog-js授权方式首启TelemetryConsentDialog接受/拒绝二选一精细控制崩溃上报与产品分析在 Settings 中各自独立开关底线原则无明确同意 → 零遥测ADR 同时对比了三个备选方案Option A选定Sentry PostHog 同意对话框。行业标准工具、崩溃/分析双开关独立、尊重隐私的 Opt-in。代价是两个外部依赖、两套服务要维护。Option B自建错误追踪服务。数据完全自控但运维负担重、分析功能有限。Option C完全不采集遥测。最简单最隐私但对崩溃和用法模式完全失明难以排定功能优先级。从该决策衍生出的具体落点包括首启同意对话框、接受后生成无 PII 的anonymous_id并写入设置、useTelemetry响应式启停、前后端beforeSend路径脱敏、环境变量注入 DSN/Key以及reinit_telemetryTauri 命令支持运行时切换 Rust 侧 Sentry。以下逐一展开源码级验证。三、首启同意对话框接受/拒绝背后的完整数据流3.1 对话框 UI 与文案承诺TelemetryConsentDialogsrc/components/TelemetryConsentDialog.tsx以全屏遮罩 盾牌图标ShieldCheckPhosphor Icons呈现核心文案明确列出我们会收集JS 与 Rust 两侧错误栈Stack traces from errors (JS Rust)、应用版本/OS/架构我们绝不收集Vault 内容、笔记标题、文件路径个人数据或 IP 地址。两个按钮分别为No thanksdecline默认聚焦与Allow anonymous reportingaccept并附注「You can change this anytime in Settings」。对这类产品而言这份文案本身就是「可验证的隐私承诺」——因为后文会看到路径脱敏与不采集 PII 在代码层面是真实落地的。3.2 选择结果如何写入设置对话框挂在首启流程的StartupScreensrc/components/StartupScreen.tsx中通过shouldShowTelemetryConsent(params)判断是否展示。两个分支的持久化逻辑清晰可读onAccept: () new Promise((resolve) { const id crypto.randomUUID() void params.saveSettings({ ...params.settings, telemetry_consent: true, crash_reporting_enabled: true, analytics_enabled: true, anonymous_id: id, }, resolve) }) onDecline: () new Promise((resolve) { void params.saveSettings({ ...params.settings, telemetry_consent: false, crash_reporting_enabled: false, analytics_enabled: false, anonymous_id: null, }, resolve) })关键设计点接受crypto.randomUUID()生成一次性匿名 IDUUID v4不含任何个人信息同时把crash_reporting_enabled与analytics_enabled一并置为true——即「一次接受默认全开」但后续仍可在设置页单独关闭任意一项拒绝anonymous_id置为null两个开关全部false且telemetry_consent: false会在未来启动时阻止对话框再次弹出不再反复骚扰用户设置写入失败时对话框内会显示telemetryConsent.saveError提示避免「用户点了接受但没保存成功」的状态不一致。anonymous_id作为设置字段定义在 src/hooks/useSettings.ts 的默认值中telemetry_consent: null、crash_reporting_enabled: null、analytics_enabled: null、anonymous_id: null并在 Rust 侧 src-tauri/src/settings.rs 中作为可空字符串字段持久化加载时经normalize_optional_string归一化相关单测见 src-tauri/src/settings_normalization_tests.rs。3.3 设置页的双独立开关同意之后用户随时可以在 Settings → Privacy 区域分别控制两项遥测。PrivacySettingsSectionsrc/components/PrivacySettingsSection.tsx渲染两个复选开关settings-crash-reportingCrash reporting 开关settings-analyticsAnalytics 开关。这与 ADR 中「Users can toggle each independently in Settings」的决策一一对应崩溃上报与产品分析是两个正交的同意维度而不是一把大锁。四、useTelemetry按设置响应式启停的协调器ADR 的 Consequences 指出useTelemetryhook 会根据设置响应式地初始化/拆除 Sentry 与 PostHog。实现在 src/hooks/useTelemetry.ts。function syncCrashReporting(crashEnabled, anonymousId, wasEnabled) { if (crashEnabled anonymousId) { if (!wasEnabled) initSentry(anonymousId) // 由关到开 → 初始化 return } if (!wasEnabled) return teardownSentry() // 由开到关 → 拆除 tauriCall(reinit_telemetry) // 通知 Rust 侧同步 } function syncAnalytics(analyticsEnabled, anonymousId, releaseChannel, wasEnabled) { if (!analyticsEnabled) { if (wasEnabled) teardownPostHog(); return } if (!anonymousId) return if (wasEnabled) { updatePostHogIdentify(releaseChannel); return } void Promise.resolve(initPostHog(anonymousId, releaseChannel)).catch(...) }实现细节值得借鉴状态机以useRef记忆上一状态prevCrash/prevAnalytics在 effect 依赖数组里同时追踪crash_reporting_enabled、analytics_enabled、anonymous_id、release_channel四个设置字段保证任何一项变化都触发重新协调由开到关前端teardownSentry()主动Sentry.close()并通过 Tauriinvoke调用reinit_telemetry命令该命令注册于 src-tauri/src/lib.rs实现于 src-tauri/src/commands/system.rs作用是让 Rust 侧丢弃旧 Client 并重读设置、决定是否重建 Sentry——双端状态始终保持一致由关到开initSentry(anonymousId)/initPostHog(anonymousId, releaseChannel)懒加载初始化开着的状态下换 release channel只调用updatePostHogIdentify更新 PostHog 的 identify 属性不重建实例非 Tauri 环境如浏览器开发调试通过mockInvoke走 mock保证 hook 可测试。对应测试见 src/hooks/useTelemetry.test.ts。五、前端遥测库初始化、良性事件过滤与脱敏src/lib/telemetry.ts 是前端遥测的核心模块包含初始化、事件拦截、过滤三层逻辑。5.1 Sentry 初始化Sentry.init({ dsn: sentryDsn, release: sentryRelease || undefined, sendDefaultPii: false, // 显式关闭 PII 采集 beforeSend: scrubSentryEvent, // 上报前必经脱敏管道 }) Sentry.setUser({ id: anonymousId })sendDefaultPii: false直接关闭 Sentry 默认的 PII 采集setUser仅写入anonymous_idUUID不携带用户名、邮箱等任何真实身份附加两个调试标签tolaria.build_version与tolaria.release_kind取值 stable / prerelease / internal由构建版本号形态推导见下文 Rust 侧同款逻辑。5.2 良性事件过滤避免噪音污染错误流beforeSend里除了脱敏还内置了一套「可丢弃事件」的判定shouldDropSentryEventsrc/lib/telemetry.ts只放行真正有诊断价值的错误ResizeObserver 循环警告浏览器已知噪音Tauri 监听器清理的陈旧签名listeners[eventId].handlerId框架内部回收噪音BlockNote/ProseMirror 富文本编辑器的「已恢复错误」包括 stale block reference、block missing id、dom_not_found、prosemirror_position_out_of_range等——这些错误编辑器自身已通过richEditorRecoveryClassifier完成恢复src/components/richEditorRecoveryClassifier.test.ts不需要再报给 Sentry 造成误报File does not exist这类非错误 Promise rejectionVault 文件被外部删除等可预期场景白板平台权限拒绝类事件在活动白板权限保护生效时丢弃见whiteboardPlatformPermissionRejection工具。这套「过滤 脱敏」的组合拳意味着 Sentry 收到的每一条事件都经过语义级筛选避免「已知噪音淹没真实崩溃」。5.3 路径脱敏管道scrubSentryEventsrc/lib/telemetry.ts对事件的三处文本做统一脱敏event.message—— 顶层错误消息event.exception.values[]中每个异常值的value所有breadcrumbs面包屑的message。脱敏函数scrubPaths委托给redactPathTextsrc/lib/sensitiveTextRedaction.ts用于把错误消息中的绝对文件路径替换为脱敏占位防止 Vault 路径经 Sentry 泄露。值得注意的是该函数还作为_scrubPathsForTest导出供单测直接验证模块级测试见 src/lib/telemetry.ts。5.4 PostHog 初始化克制的最小采集posthog.init(posthogKey, { api_host: posthogHost, autocapture: false, // 关闭自动捕获 capture_pageview: false, // 不自动上报页面浏览 persistence: memory, // 不写 localStorage/cookie进程内记忆 disable_session_recording: true, // 关闭会话录制 }) posthog.identify(anonymousId, releaseChannel ? { release_channel: releaseChannel } : undefined)四个选项逐条对应隐私策略不自动捕获点击、不追踪页面浏览、内存级持久化应用退出即遗忘、关闭会话录制。产品分析只携带anonymous_idrelease_channel两个属性。事件上报统一走trackEvent(name, properties)例如 Vault 打开事件src/hooks/useVaultOpenedTelemetry.tstrackEvent(vault_opened, { git_root_relation: workspace.relation, has_git: gitRepoState ready ? 1 : 0, note_count: entryCount, }) trackEvent(git_root_resolution_failed, { reason: workspace.failure })注意这里上报的是聚合型特征笔记数量、是否有 Git、Git 根关系而非任何笔记内容本身——事件命名与字段规范化策略详见 docs/adr/0101-categorical-product-analytics-events.md。遥测关闭时teardownPostHog会调用opt_out_capturing()与reset()彻底停止采集并清空实例引用。5.5 基于 PostHog 的特性开关PostHog 实例还承担了远程特性开关feature flag职责src/lib/telemetry.tsexport function isFeatureEnabled(flagKey: FeatureFlagKey): boolean { if (currentReleaseChannel alpha) return true // alpha 渠道默认全开 return posthogInstance?.isFeatureEnabled(flagKey) ?? (Reflect.get(FEATURE_DEFAULTS, flagKey) as boolean | undefined) ?? false }alpha 渠道无条件放行、其余渠道以 PostHog 远程 flag 为准、离线时回退到硬编码默认值FEATURE_DEFAULTS三者结合保证了「无网络首启」也不至于功能缺失。这一设计与 docs/adr/0042-posthog-release-channels-feature-flags.md 的发布渠道特性开关方案相衔接。六、Rust 后端遥测双端对称的脱敏与生命周期前端之外Rust 层同样接入 Sentry核心实现在 src-tauri/src/telemetry.rs。6.1 按设置条件初始化pub fn init_sentry_from_settings() - bool { let settings match settings::get_settings() { Ok(s) s, Err(_) return false }; if settings.crash_reporting_enabled ! Some(true) { return false; } // 无同意 → 不初始化 let Some(dsn) parse_embedded_sentry_dsn(option_env!(SENTRY_DSN)) else { return false; }; ... let guard sentry::init(sentry::ClientOptions { dsn: Some(dsn), release: sentry_release_for_version(build_version), send_default_pii: false, before_send: Some(std::sync::Arc::new(|mut event| { if let Some(ref mut msg) event.message { *msg scrub_paths(msg); } Some(event) })), ..Default::default() }); sentry::configure_scope(|scope| { scope.set_user(Some(sentry::User { id: Some(anonymous_id), ..Default::default() })); scope.set_tag(tolaria.build_version, build_version); scope.set_tag(tolaria.release_kind, sentry_release_kind(build_version)); }); *SENTRY_GUARD.lock().unwrap() Some(guard); // ClientInitGuard 必须存活整个生命周期 true }要点双重保险crash_reporting_enabled ! Some(true)直接短路返回没有同意连 DSN 解析都不会发生DSN 通过option_env!(SENTRY_DSN)在编译期注入无 DSN 的本地开发构建自动跳过 Sentry对应单测test_init_sentry_returns_false_without_dsnsentry::ClientInitGuard存入全局static SENTRY_GUARD: MutexOption...防止 guard 在作用域结束时被 drop 导致 SDK 提前关闭。6.2 Rust 侧路径脱敏正则fn scrub_paths(input: str) - String { let re Regex::new(r(?:/[\w.-]){2,}|[A-Z]:\\[\w\\.-]).unwrap(); re.replace_all(input, redacted-path).to_string() }同时覆盖 Unix 风格路径连续两段以上/segment与 Windows 盘符路径C:\...脱敏占位为redacted-path。单测覆盖了 Unix、Windows、无路径三类输入src-tauri/src/telemetry.rs。由此可以看到前后端「对称脱敏」的完整闭环前端在 JS 层拦截渲染错误后端在 Rust 层拦截文件系统/Git 错误任何一侧的错误文本都不会携带真实路径。6.3 日历版本号驱动的 release 归类Rust 侧与前端同步实现了基于版本号形态的 release 策略对应 docs/adr/0066-calendar-semver-versioning-for-alpha-and-stable-releases.md2026.4.28→stable且作为 Sentryrelease上报2026.4.28-alpha.7→prerelease不作为 release 标识0.1.0这类本地开发版本 →internal同样不作为 release。这样 Sentry 侧既能区分渠道与构建又避免把本地开发版本误归为正式 release。相关判定函数is_stable_calendar_release会校验年/月/日能否构成合法日期sentry_release_kind的分类逻辑在 src-tauri/src/telemetry.rs 有完整单测。6.4 运行时重初始化pub fn reinit_sentry() { *SENTRY_GUARD.lock().unwrap() None; // 先丢弃旧 guard init_sentry_from_settings(); // 重读设置决定重建或保持关闭 }这正是前端useTelemetry在关闭崩溃上报时通过reinit_telemetry命令触发的后端动作用户切换开关的瞬间Rust 侧 Sentry 立即同步启停不留任何「设置已关但 SDK 仍在运行」的窗口。七、环境变量注入与合法性校验DSN/Key 的注入遵循「前端 VITE_ 前缀、后端编译期 env!」的惯例前端配置解析集中在 src/lib/telemetryConfig.ts环境变量作用解析/校验规则VITE_SENTRY_DSN前端 Sentry DSN归一化为 http(s) URL 后才接受normalizeSentryDsnVITE_SENTRY_RELEASE构建版本标签仅接受合法日历日期格式YYYY.M.DnormalizeSentryReleaseVITE_POSTHOG_KEYPostHog project key去除包裹引号、trim 后取用sanitizeTelemetryEnvValueVITE_POSTHOG_HOSTPostHog API 地址默认回退https://us.i.posthog.com仅接受校验通过的主机名SENTRY_DSNRust 侧后端 Sentry DSNoption_env!编译期读取支持带引号/缺 scheme 的宽容解析parse_embedded_sentry_dsn前端校验还相当严格isAllowedTelemetryHostname会拒绝false/null/disabled等占位字符串只接受localhost、包含.的域名或合法 IP含 IPv4 逐段 0-255 校验与 IPv6 形态校验从源头杜绝「误配环境变量把遥测发到未知地址」的可能。resolveFrontendTelemetryConfig汇总输出{ sentryDsn, sentryBuildVersion, sentryRelease, posthogKey, posthogHost }telemetry.ts初始化时消费该配置所有环境变量缺失时各项返回空值初始化函数据此静默跳过——即未配置遥测服务的开发构建天然零上报。八、测试覆盖把隐私承诺变成可回归的断言该模块的测试体系让「不泄露路径、无同意不初始化」成为可自动验证的契约对话框交互src/components/TelemetryConsentDialog.test.tsx接受/拒绝回调、保存失败提示、按钮禁用态等场景全覆盖useTelemetry 协调逻辑src/hooks/useTelemetry.test.ts覆盖关闭/开启、ID 缺失等状态切换路径Rust 脱敏与初始化src-tauri/src/telemetry.rsUnix/Windows 路径脱敏、DSN 宽容解析、无 DSN 时不初始化、release 归类等设置持久化src-tauri/src/settings_storage_tests.rsanonymous_id的写入/读取往返一致性。九、设计权衡与再评估触发点ADR-0016 的 Consequences 明确给出了未来的再评估条件如果出现能统一替代两个服务的平台如 OpenTelemetry应重新评估该方案。当前选择的双依赖代价两套服务接入与维护、两处脱敏逻辑需要同步演进是已知取舍而useTelemetryreinit_telemetry的架构已经为「替换底层服务」预留了清晰的接缝——上层只关心init/teardown/track三个语义具体 SDK 随时可换。十、可复用的工程要点总结同意是硬门槛而非软提示crash_reporting_enabled/analytics_enabled双重门控任何 SDK 初始化前必须短路检查匿名 ID 一次生成、全局复用crypto.randomUUID()生成、Rust/JS 双端共用同一anonymous_id关联事件但绝不含 PII脱敏必须双端对称前端redactPathText 后端scrub_paths各守一层错误消息、异常值、面包屑三处文本全部覆盖良性噪音在前置过滤把「已知可恢复/可预期」的错误在beforeSend丢弃让 Sentry 只收到真实需要人看的崩溃运行时启停要打通前后端设置变化 →useTelemetry协调 →reinit_telemetry命令 → Rust 侧重建/销毁 Client全链路无残留采集克制即合规autocapture: false、内存持久化、关闭会话录制、只上报聚合特征事件。对正在设计遥测体系的桌面应用团队而言本项目的完整实现链路决策文档 → 前端库 → Rust 后端 → 测试提供了一份可直接参照的「隐私优先遥测」参考实现。【免费下载链接】tolariaDesktop app to manage markdown knowledge bases项目地址: https://gitcode.com/GitHub_Trending/to/tolaria创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考