SiYuan v2.9.2 数据同步机制升级解读云端索引重建、冲突文件治理与多端协同【免费下载链接】siyuanAn open-source, privacy-first, self-hosted knowledge workspace where humans and AI agents work together 开源、隐私优先、自托管的知识工作空间让人与智能体在此协作项目地址: https://gitcode.com/GitHub_Trending/si/siyuan版本导读v2.9.2 是思源笔记SiYuan围绕数据同步做的一次系统性加固版本核心目标是修复在部分系统上反复生成冲突文件的问题同时引入“多内核在线同步感知”“状态栏同步进度”等提升多设备、多端使用体验的机制。阅读本文后你将理解本次升级的完整变更清单与升级风险点云端数据索引重建、跨版本不兼容并能结合仓库源码掌握同步感知 WebSocket 通道、冲突文档生成、自动重建文件历史索引等底层实现原理。本文以 v2.9.2 变更记录 为主体骨架仓库源码仅用于印证各改进项的实际落地。一、版本概述与升级须知1.1 本次版本的核心目标v2.9.2 的概述明确指出此版本改进了数据同步功能解决了某些系统上重复生成冲突文件问题。也就是说本次版本主要不是一个功能大版本而是针对数据仓库Data Repo同步链路的可靠性修复与体验优化值得所有开启了云端同步的用户关注。1.2 升级此版本前必须了解的两点原文档强调了两条升级注意事项直接影响使用安全和升级节奏升级后首次启动会自动重建云端数据索引。如果数据量较大该过程会比较耗时官方建议在网络较好的环境下再启动内核避免重建过程中网络中断。升级此版本后云端数据不再兼容旧版本。需要所有使用同一云同步目录的设备都升级到 v2.9.2 及以上才能正常使用若混用新旧版本会引起云端数据索引相互覆盖很有可能会导致云端数据损坏。从数据一致性角度解读云端索引重建相当于对数据仓库的索引结构做了一次“迁移”新旧内核写入的索引格式不同因此多端必须同步升级、保持索引读写版本一致这与一般的文件同步“向前兼容”策略不同升级前建议先在关键设备上备份。二、数据同步机制改进本版本主线2.1 多内核在线同步感知原文档改进项“数据同步支持多内核在线时同步感知”意味着当多个设备桌面端、移动端等多个内核实例同时在线且都开启了云同步时内核之间可以感知彼此的在线状态并联动触发同步而不是各自按固定间隔盲目拉取。从当前仓库源码看该机制的实现依赖内核间的 WebSocket 通道与“感知”开关同步配置结构中存在Perception感知布尔开关见 kernel/conf/sync.go系统启动时若开启感知且使用思源官方同步服务会主动connectSyncWebSocket()建立长连接见 kernel/model/sync.go 的BootSyncData()内核维护“在线内核”列表可通过GetOnlineKernels()获取除自身外的其他在线内核见 kernel/model/sync.go在一次数据变更同步完成后如果当前为自动同步模式Mode 1且感知已开启内核会通过 WebSocket 向其他设备广播synced消息通知其他内核尽快拉取最新数据见 kernel/model/sync.go。也就是说感知同步将原本“设备 A 推完不管、设备 B 等到下一个间隔才拉”的模式升级为“设备 A 推完立即通知设备 B 拉取”的实时联动模式缩短了多设备间数据收敛的延迟。2.2 状态栏显示数据同步进度原文档改进项“在状态栏显示数据同步进度”让用户在同步进行中能够直观看到进度状态。源码中对应的实现方式是内核通过主线程广播syncing事件并携带阶段码同步开始前推送syncing, 0同步失败推送syncing, 2同步成功推送syncing, 1并附带同步统计信息Conf.Sync.Stat。参见 kernel/model/sync.go 中SyncDataDownload()、SyncDataUpload()以及 kernel/model/sync.go 中syncData()的事件广播逻辑。注意同步在判断网络在线前就先推送syncing事件目的是给用户更即时的界面反馈耗时操作 网络探测都比较慢。2.3 改进启动速度与同步向导改进启用数据同步时的启动速度结合启动同步函数BootSyncData()的实现可推断优化方向包括仅在感知开启时才建立 WebSocket避免无效连接、先完成本地事务刷新再执行网络拉取、以及复用启动进度条机制util.IncBootProgress来降低阻塞感。改进数据同步向导同步向导属于首次配置云同步目录时的交互流程对应源码层面CreateCloudSyncDir、ListCloudSyncDir、SetSyncProvider*等一组设置接口见 kernel/model/sync.go。用户侧表现为引导选择云端存储服务思源官方 / S3 / WebDAV / 本地文件系统并设置同步目录的流程更顺畅。2.4 改进数据同步文件时间比较“改进数据同步文件时间比较”直接服务于本版本的标题性修复——解决某些系统上重复生成冲突文件问题。文件时间比较是数据仓库判断“云端文件 vs 本地文件谁更新”的依据若比较策略不严谨例如只比毫秒时间戳、忽略文件系统粒度的差异就会在时间近似相等时误判为双向修改从而反复生成冲突文件。在 kernel/model/sync.go 中可以观察到同步链路中存在诸如syncSameCount统计、autoSyncErrCount、fixSyncInterval修复性兜底同步间隔等状态量说明内核会对同步结果做计数与自愈处理。2.5 冲突文件的生成与开关关于冲突文件需要区分两个层面冲突检测合并云端与本地数据后若同一文档在两处都被修改会进入mergeResult.Conflicts列表。合并完成后同步日志会打印merge result [conflicts%d, upserts%d, removes%d]汇总见 kernel/model/repository.go。冲突文档生成是否把冲突内容落成可见的“冲突副本”文档取决于配置项GenerateConflictDoc对应“生成冲突文档”设置。开启后内核会遍历mergeResult.Conflicts将冲突的.sy文件加载解析通过resetTree(tree, Conflicted, true)重置后以新建文档事务写入数据仓库见 kernel/model/repository.go。v2.9.2 通过改进时间比较算法从根源上减少了“误判冲突”从而显著降低冲突文档的重复生成频率。相关配置字段定义与默认值可在 kernel/conf/sync.go 查看同步相关的 API 入口如设置感知、设置生成冲突文档在 kernel/api/router.go 注册。2.6 降低快照创建与恢复的内存占用“降低数据仓库创建快照和恢复快照时的内存占用”优化的是同步与历史快照链的内存峰值。思源的数据仓库会在每次同步前记录快照Snapshot大库场景下全量快照对内存压力明显该改进通过复用索引、按需加载数据块等方式降低峰值对老设备和大数据量用户收益明显。这与 kernel/model/repository.go 中快照相关函数RollbackRepoSnapshotFile、OpenRepoSnapshotFile、DiffRepoSnapshots所处理的“读取-解析-恢复”链路的资源开销直接相关。2.7 小结同步配置面板的关键字段结合 kernel/conf/sync.go 的结构体当前仓库中数据同步相关的核心配置可归纳如下字段语义与 v2.9.2 保持一致配置字段语义默认值CloudName云端同步目录名称mainEnabled是否开启同步falsePerception是否开启多内核在线感知falseMode同步模式1自动、2手动、3完全手动1Interval自动同步间隔秒30GenerateConflictDoc云端同步冲突时是否生成冲突文档falseProvider存储服务提供者思源/S3/WebDAV/本地ProviderSiYuan其中Provider常量在 kernel/conf/sync.go 定义0为思源官方云2为 S3 协议对象存储3为 WebDAV4为本地文件系统目录。手动与完全手动的差异体现在checkSync()手动模式下启动/退出仍会同步完全手动模式下只有用户显式触发才同步见 kernel/model/sync.go。三、编辑器与操作体验改进3.1 搜索对话框与文档树支持Alt.向右分屏打开原文档改进项“搜索对话框和文档树面板支持通过Alt.向右分屏打开”扩充了键盘操作路径在搜索面板或左侧文档树中定位到目标文档后可通过快捷键将文档在右侧分屏中打开避免打断当前编辑上下文适合“边搜边对照”的场景。3.2 保存查询条件与移除查询条件的入口改进“改进保存查询条件和移除查询条件功能入口”让这两个高频操作从深层菜单中上浮到更易触达的位置。仓库前端常量中可以找到对应的对话框标识DIALOG_SAVECRITERION保存查询条件见 app/src/constants.ts说明该功能拥有独立的对话框承载逻辑。3.3 未选中内容时也可使用“清除行级元素”此前清除行级元素如加粗、斜体、行内代码等必须先选中对应文本本次改进使未选中文本时也能执行该操作——通常是将光标所在的行内标记清除减少了“必须先精确选中”的操作负担。3.4 浏览器端新增“粘贴为纯文本”右键菜单桌面端此前已有纯文本粘贴能力本次补齐了浏览器端编辑器右键菜单中的粘贴为纯文本入口。仓库前端源码中pasteAsPlainText作为统一能力被多个入口复用编辑器右键菜单app/src/menus/protyle.ts、文档标题右键菜单app/src/protyle/header/Title.ts以及工具栏动作分发app/src/protyle/toolbar/index.ts底层统一调用 app/src/protyle/util/paste.ts 中的pasteAsPlainText。粘贴时去除富文本样式可避免从网页复制内容时带入大量无关格式。3.5 新增“复制 PNG”快捷键CtrlShiftC原文档新增复制 PNG 快捷键CtrlShiftC用户可按需复制为 PNG 图片而不是传统文本方便在聊天工具或图片类文档中直接粘贴所见内容例如行内代码、公式、渲染后的块内容。四、导出与导入相关改进4.1 导出预览模式下可通过大纲面板定位标题此前导出预览Prevew 导出结果模式与大纲面板联动不完整本次改进后用户在导出预览中点击大纲中的标题即可定位到正文对应位置便于在导出前快速检查长文档的章节结构。4.2 导出 data.zip 压缩包名称加入工作空间名原文档改进“导出 Data 压缩包名称加入工作空间名”让导出包在多工作空间并存时更好区分。从当前仓库实现看ExportData()在生成导出文件名时使用util.FilterFileName(util.WorkspaceName) - 当前时间戳作为临时目录与压缩包命名前缀见 kernel/model/export.go导出流程会把整个data目录复制到临时目录后打包为data-时间戳.zipkernel/model/export.go最终文件名会携带工作空间名。4.3 导出 data.zip 后再导入不再改变文件时间修复了“导出 data.zip → 迁移到新设备 → 导入”这一完整链路中文件时间被改写的问题。文件时间mtime保持原样对数据仓库同步非常重要——若导入改变了本地文件时间可能会被同步机制误判为“本地更新”从而引发不必要的上传甚至冲突该修复对迁移后首次同步的稳定性有直接帮助。4.4 改进 iOS 端导出图片渲染iOS 端导出图片的渲染质量/兼容性改进主要解决移动端导出长图时的渲染差异问题属于平台相关的渲染适配。五、文件历史、AI 模型与平台细节5.1 文件历史索引失败时自动重建“当插入文件历史索引失败时自动重建文件历史数据索引”属于自愈机制文件历史File History索引是检索历史版本的前提若单次插入索引失败而不处理会导致该历史版本后续不可检索。本次改进在写入失败时自动触发整体重建确保索引完整。仓库中对应的重建能力为ReindexHistory()kernel/model/history.go通过/api/history/reindexHistory接口暴露kernel/api/router.go并在多处写操作后调用indexHistoryDir进行增量入索引。5.2 新增 OpenAI GPT 模型gpt-3.5-turbo-16k在 AI 接入侧本版本新增了模型gpt-3.5-turbo-16k。当前仓库的模型清单 kernel/agent/models.json 中已收录gpt-3.5-turbo-16k与gpt-3.5-turbo-0613并列说明模型由集中式配置驱动新增模型无需改动内核主逻辑。5.3 支持 Dvorak 键盘布局快捷键Dvorak 是不同于 QWERTY 的键盘布局方案此前快捷键系统可能仅按物理键位或 QWERTY 语义解析导致 Dvorak 用户快捷键失效或错位。本次改进让快捷键解析兼容 Dvorak 布局属于键盘映射层适配。5.4 平台与路径细节改进Android 端启动界面更平滑Android 端启动加载更流畅降低冷启动白屏/卡顿感。指定工作空间路径的情况下不再创建Documents/SiYuan/此前无论是否指定了自定义工作空间路径系统都可能在用户目录下生成默认目录本次修复避免在自定义路径模式下产生无用的默认目录残留。改进file://开头链接在“网络图片转换为本地图片”时的处理将网络图片转本地图片功能fetch拉取远程资源并落盘到assets对file://本地协议地址做了更正确的处理避免把本地文件误当网络资源或转换失败。六、缺陷修复明细原文档列出 5 项修复均为用户可感知的稳定性问题修复项影响说明集市默认排序失效集市Bazaar中插件/主题列表的默认排序不再生效恢复按发布更新时间等规则的默认排序见集市更新时间解析逻辑 kernel/bazaar/bazaar.go 所处理的updated字段解析某些情况下 Pandoc 未初始化Pandoc 转换链路偶发未初始化导致导出/导入 Markdown、Word 等格式失败本次修复确保转换前完成初始化兜底取消拖拽移动列表项后数据丢失拖拽列表项后取消操作导致原内容丢失属于编辑器拖拽事务回滚缺陷FlowChart 在导出预览模式下未渲染流程图在导出预览视图中不显示属于预览渲染管线对图表类型的兼容性修复导出预览模式无法切换回编辑模式进入导出预览后无法退出回到编辑状态修复了预览状态机切换异常七、开发者相关更新7.1 通过自定义协议链接打开自定义页签面向开发者尤其插件开发者的能力自定义协议Custom Protocol /siyuan://类链接现在可以携带参数用于打开自定义页签Tab使插件通过协议链接完成“唤起内核并打开指定面板”的闭环。这意味着插件可以将“打开自定义页签”的入口挂到系统级协议上便于跨应用唤起与深度链接集成。八、升级建议与最佳实践综合本次版本说明面向使用云端同步的用户给出如下实践建议规划升级窗口因为首次启动会重建云端数据索引且较耗时建议选择网络稳定、非工作高峰的时间升级并保持设备供电/电量充足。所有端同步升级同一云同步目录下接入的所有设备桌面、移动、浏览器端等都要升级到 v2.9.2 及以上避免新旧版本内核交错读写导致云端数据索引相互覆盖。迁移与备份联动如需更换设备优先使用“导出 Data 压缩包已携带工作空间名→ 新设备导入”的方式导入不再改写文件时间配合升级后的同步机制可减少迁移后首次同步的冲突概率。合理使用同步配置若多设备频繁交替编辑建议开启“感知”与“自动同步”以缩短端间延迟若担心误判产生冲突副本可结合冲突检测结果决定是否开启“生成冲突文档”。善用文件历史自愈与导出预览升级后文件历史索引在异常时会自动重建导出前可先使用导出预览模式结合大纲面板快速核对文档结构。总结v2.9.2 是一次以“数据同步可靠性”为绝对主线的版本从时间比较算法的修正解决冲突文件重复生成到多内核感知、状态栏同步进度等体验增强再到云端索引重建与版本不兼容提醒构成了一个完整的“同步体验升级包”。对于使用思源云同步的用户本文列出的升级注意事项应优先落实对于希望深入理解同步实现的研究者可以从 kernel/model/sync.go、kernel/conf/sync.go、kernel/model/repository.go 三条主链路出发结合本版本的变更清单逐项验证其实现细节。【免费下载链接】siyuanAn open-source, privacy-first, self-hosted knowledge workspace where humans and AI agents work together 开源、隐私优先、自托管的知识工作空间让人与智能体在此协作项目地址: https://gitcode.com/GitHub_Trending/si/siyuan创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
