SiYuan v2.9.2 版本深度解析：数据同步多内核在线感知、冲突文件治理与启动体验重塑

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）在 v2.9.x 稳定线中的一次重要迭代，主线围绕“数据同步”展开：既修复了部分系统上同步冲突文件被重复生成的缺陷，又引入多内核在线感知（multi-kernel online perception）、状态栏同步进度、同步启动提速与文件时间戳比较优化等一批增强。本文以官方英文版更新日志（v2.9.2.md，中文对照见 v2.9.2_zh_CN.md）为骨架，结合本仓库 Go 内核源码逐条展开，帮助你在升级前理解版本边界，升级后正确配置同步，并理解其底层实现机制。

版本概览：一次以“数据同步”为主线的修复与打磨

本版本官方定位为“改进了数据同步功能，解决了某些系统上重复生成冲突文件的问题”，同时附带编辑器、导出导入、搜索、集市、AI 等多个模块的体验增强与缺陷修复。整个 v2.9.x 系列的变更记录集中存放于仓库 app/changelogs/v2.8.4-v2.12.8/ 目录下，按版本号分子目录管理。

版本的功能改动可以归纳为四大板块：

升级前必读：两条关键注意事项

升级日志在版本说明的最前面专门列出两条注意事项，这是所有用户在升级 v2.9.2 前必须了解的风险边界，官方将其列为“Things to note when upgrading this version”（升级此版本需要注意）。

注意一：首次启动会自动重建云端数据索引，耗时与数据量成正比。升级后第一次启动时，内核会自动重建云端数据索引。如果数据量较大，该过程会比较耗时，官方建议在网络状况较好的时候再进行启动。从源码看，思源在索引异常场景下本身就具备重建与恢复机制：例如全量全文索引重建失败时会回退到完整重建流程（见 kernel/model/box.go 中rebuild fts index failed, falling back to full reindex的处理路径）；树索引与引用索引也存在按文档、按更新时间差异驱动的增量重建逻辑（kernel/model/index_fix.go 中的reindexTreeByPath、reindexTreeByUpdated等）。本次升级触发的“云端数据索引重建”同样属于这类数据一致性保障动作，应将其视为正常过程而非故障。

注意二：云端数据格式不再兼容旧版本，必须“全端同步升级”。升级到 v2.9.2 之后，云端数据与之前的版本不兼容，所有设备（内核实例）都必须升级到此版本后才能正常使用。如果混用版本，不同版本会互相覆盖云端数据索引，极有可能导致云端数据损坏。这与本版本引入的数据同步相关结构性改动（见下文“多内核在线感知”）直接相关——云端同步协议与索引结构变化后，旧版本内核无法正确理解新版本产生的同步状态，因此必须统一升级。

数据同步核心改进：本版本的主线

修复部分系统重复生成冲突文件

v2.9.2 的目标之一是解决“某些系统上重复生成冲突文件”的问题。冲突文件（conflict doc）是云端同步检测到同一文件在不同设备上被并发修改、无法自动合并时生成的副本文档。

是否生成冲突文档在思源内核中是一个可配置开关。同步配置结构体Sync位于 kernel/conf/sync.go，其中字段GenerateConflictDoc（JSON 键generateConflictDoc）专门控制“云端同步冲突时是否生成冲突文档”，默认值为false（见同文件NewSync()的初始化，kernel/conf/sync.go）。该开关可通过设置接口动态修改：内核侧处理函数为SetSyncGenerateConflictDoc（kernel/model/sync.go），其 HTTP 路由注册在 kernel/api/router.go（POST /api/sync/setSyncGenerateConflictDoc，需管理员角色且非只读模式），接口实现在 kernel/api/sync.go；冲突判定处则读取该配置决定是否落盘冲突文档（相关判断出现在数据仓库处理逻辑 kernel/model/repository.go 中）。

本版本同时在“文件时间戳比较”上做了针对性改进（对应同步文件时间戳比较 issue），通过更可靠地判断文件在本地与云端的先后关系，从源头减少误判导致的冲突文档反复生成。

数据同步支持多内核在线感知

这是本版本数据同步侧最具架构意义的新能力（官方 changelog 对应条目为“数据同步支持多内核在线时同步感知”）。所谓“多内核在线感知”，是指思源的同步逻辑通过 WebSocket 与云端建立长连接，感知当前是否有其他内核实例（如桌面端与手机端同时在线）正在工作，并据此调整同步行为，避免多个实例同时向云端写数据造成互相覆盖。

这一能力对应的同步开关是Sync结构体中的Perception字段（JSON 键perception，kernel/conf/sync.go），默认关闭，设置入口为SetSyncPerception（kernel/model/sync.go）。感知连接的建立集中体现在启动同步流程BootSyncData中（kernel/model/sync.go）：

• 启动时若Conf.Sync.Perception为真，首先调用connectSyncWebSocket()建立与云端的感知长连接；
• 在后续自动同步调度中，只有当 WebSocket 连接存在且本地数据确实发生变化时，才执行上传动作（相关判断见 kernel/model/sync.go），从而避免重复推送或空推送；
• 同步完成状态通过BroadcastByType("main", "syncing", code, Conf.Sync.Stat, nil)推送给前端界面（同上函数体中）。

内核还抽象了OnlineKernel类型与GetOnlineKernels()查询函数（kernel/model/sync.go），用于描述和枚举当前在线的内核实例；WebSocket 连接的建立由dialSyncWebSocket等底层函数支撑（kernel/model/sync.go）。

需要说明的是，多内核感知属于同步模式的增量能力：思源同步模式分为自动（Mode 1）、手动（Mode 2）、完全手动（Mode 3）等，见 kernel/conf/sync.go 的注释，感知功能是在这些既有模式之上进一步提升“谁在线上、何时该写”的判断精度。

状态栏显示数据同步进度

为了改善同步过程的可感知性，v2.9.2 在状态栏中加入了同步进度显示。内核侧由BootSyncData/syncData等函数在整个同步生命周期内维护进度状态并广播：同步开始、进行中、成功、失败分别通过BroadcastByType向主界面发送syncing消息，其中携带的状态码与Conf.Sync.Stat统计字符串即为前端状态栏渲染进度的数据来源。同步的调度与节流由SyncDataJob（定时任务，kernel/model/sync.go）、planSyncAfter（延时规划）与IncSync（计数触发）共同配合（kernel/model/sync.go），手动触发入口为SyncData/SyncDataUpload/SyncDataDownload（kernel/model/sync.go）。

提升启用数据同步时的启动速度，并改进同步向导

日志同时收录了两项同步使用体验改进：一是“改进启用数据同步时的启动速度”，二是“改进数据同步向导”。从实现路径看，启动同步（bootSyncRepo）被安排在启动进度的较后阶段执行（BootSyncData在启动进度推进到第 3 步之后才进入实际仓库同步，见 kernel/model/sync.go），启动期间对感知 WebSocket 的延迟连接、以及失败时通过flushAndRetryOnDNSError/isDNSError（kernel/model/sync.go）对 DNS 类错误先刷新系统 DNS 缓存再重试的容错设计，都服务于让同步尽量少阻塞或打断启动主流程。同步向导（首次配置云同步目录的引导流程）则对应CreateCloudSyncDir、SetCloudSyncDir、ListCloudSyncDir等接口（kernel/model/sync.go）。

改进数据同步的文件时间戳比较

同步冲突判定的核心依据之一就是文件时间戳的比较。v2.9.2 专门改进了“数据同步文件时间戳比较”逻辑，避免因时间精度、时钟偏差或文件系统元数据差异造成误判，从而减少无谓的冲突与冗余下载/上传。这与“修复重复生成冲突文件”在机制上是配套的：时间戳比较更可靠 → 文件新旧的判定更准确 → 冲突文档只在真正并发修改时产生一次。

导入导出、备份与索引健壮性增强

本版本在数据资产的安全与可迁移性上做了多项改进，这些功能同样直接服务于“数据在本地与云端之间安全流转”的总体目标。

编辑器、搜索与预览体验增强

v2.9.2 同时覆盖了一批编辑器与浏览路径的日常效率改进，适合逐条对照升级后的行为变化：

• 导出/预览模式下支持通过大纲面板定位标题：在大纲（outline）面板点击标题即可在预览文档中跳转，解决了预览态下“只能看不能定位”的问题。
• 搜索对话框与文档树面板支持Alt+.向右分屏打开：在搜索结果或文档树中按Alt+.即可将目标文档在右侧分屏打开，与编辑器内的既有分屏快捷键形成一致操作习惯。
• 支持 Dvorak 键盘布局快捷键：修复 Dvorak 布局下快捷键失效问题，属于对非 QWERTY 用户的键位兼容性修复。
• 改进“保存查询条件”与“移除查询条件”的功能入口：SQL/搜索查询条件的保存与移除入口更易发现、操作路径更短。
• 不选择文本时也可使用“清除行级元素”：光标停留在含行级元素（如加粗、行内代码）的文本中即可一键清除，不再强求先选中。
• 新增复制 PNG 快捷键Ctrl+Shift+C：与复制文本的Ctrl+C并列，提升“复制为图片”的效率。
• 浏览器端编辑器右键菜单新增“粘贴为纯文本”：网页端粘贴时按纯文本落入，避免样式污染，属浏览器端与桌面端能力对齐。
• 改进以file://开头的链接执行“网络图片转本地图片”：把转换范围从 http(s) 扩展覆盖到本地文件链接场景。

多端与 AI 能力同步更新

• 新增 OpenAI GPT 模型gpt-3.5-turbo-16k：在既有 GPT 模型列表中加入 16k 上下文版本，适用于更长上下文的对话场景（思源内核 AI 对话由Conf.AI配置与 OpenAI 兼容客户端驱动，模型获取逻辑见 kernel/model/ai.go，配置结构见 kernel/conf/ai.go）。
• 修复 iOS 端导出图片渲染不正确：统一移动端与桌面端的导出图片渲染结果。
• Android 端启动画面更平滑：减少启动阶段的白屏/跳变，改善冷启动观感。

缺陷修复清单

本版本共修复 5 个缺陷，官方英文版日志（v2.9.2.md）中的 Bugfix 一节完整列举如下：

面向开发者：通过自定义协议链接打开自定义页签

在 Development 栏目中，v2.9.2 面向插件开发者开放了新能力：支持通过自定义协议（custom protocol）链接打开自定义页签。这意味着插件/主题可以通过自定义协议 URL 唤起内核并打开指定的自定义 tab 页，为“外部唤起 + 内部分屏/页签跳转”类集成（例如从浏览器、其他应用一键定位到思源中的特定面板）提供了基础通道。

升级路线与落地建议

综合本版本变更，给出如下升级与使用建议：

1. 先统一版本再升级：由于 v2.9.2 云端数据与旧版不兼容，建议在同一时间窗口内完成所有设备（桌面、移动、服务端）的升级，避免新旧版本混跑造成云端索引互相覆盖。
2. 选择网络良好的时机启动：首次启动会重建云端数据索引，大库用户请预留足够时间，并在网络稳定的环境下进行，避免中断。
3. 关注同步感知开关：多内核在线感知是“同账号多设备同时在线”场景下的关键可靠性增强。如需在桌面与手机同时频繁使用，可在同步设置中确认感知能力已启用（对应配置键perception，默认关闭）。
4. 按需管理冲突文档开关：generateConflictDoc默认关闭。对于并发编辑频繁、依赖冲突文档做人工裁决的用户，可在设置中开启；对绝大多数单写多读场景，保持关闭配合本次时间戳比较改进即可获得更干净的同步结果。
5. 善用新增的高频操作：Alt+.分屏、Ctrl+Shift+C复制 PNG、浏览器端粘贴为纯文本等均为零成本效率提升，建议升级后立即上手。

如果需要在升级前回溯同步机制的完整实现，推荐以 kernel/model/sync.go 为主干，配合同步配置结构 kernel/conf/sync.go 与同步相关 HTTP 接口 kernel/api/sync.go 交叉阅读，即可完整还原思源“定时任务 + WebSocket 感知 + 冲突判定 + 进度广播”的同步链路全貌。

【免费下载链接】siyuanAn open-source, privacy-first, self-hosted knowledge workspace where humans and AI agents work together 开源、隐私优先、自托管的知识工作空间，让人与智能体在此协作项目地址: https://gitcode.com/GitHub_Trending/si/siyuan