企业官网建设流程全解析

思源笔记 v2.9.7 深度解析：云端数据损坏防护、第三方 S3/WebDAV 接入收紧与开发者能力增强

【免费下载链接】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.7 官方更新说明（v2.9.7_zh_CHT.md）展开，解读该版本“修复云端数据损坏风险、第三方云端存储需登录后使用”两个关键变化，并结合内核源码逐一拆解同步配置结构、搜索与编辑器交互改进、Windows 卸载行为，以及面向开发者的属性视图日期列、全局鼠标位置变量、/api/file/readDir符号链接能力等新增项，帮助用户与插件开发者理解该版本的实际影响并据此规划升级。

版本定位与升级建议

v2.9.7 是一个以数据安全为核心的修复型版本，官方在概述中给出了两条重要提示：

1. 本版本修复了一个导致云端数据损坏的问题，官方建议用户尽快升级；
2. 从该版本开始，接入第三方云端存储 S3/WebDAV需要**先登录（思源账号）**才能使用。

前者关乎同步链路的可靠性，后者则改变了第三方云存储接入的前置条件，属于影响既有使用习惯的兼容性调整。对正在使用 S3/WebDAV 同步/备份的用户，升级前应确认账号登录状态与同步配置是否仍然有效。

背景知识：思源同步的云端存储架构与配置结构

要理解“S3/WebDAV 需要登录”这一变化，需要先了解思源内核中同步与云存储配置的组织方式。同步配置集中定义在 kernel/conf/sync.go 中，核心结构为Sync：

type Sync struct { CloudName string `json:"cloudName"` // 云端同步目录名称 Enabled bool `json:"enabled"` // 是否开启同步 Perception bool `json:"perception"` // 是否开启感知 Mode int `json:"mode"` // 同步模式 0:未设置 1:自动 2:手动 3:完全手动 Interval int `json:"interval"` // 自动同步间隔，单位：秒 Synced int64 `json:"synced"` // 最近同步时间 Stat string `json:"stat"` // 最近同步统计信息 GenerateConflictDoc bool `json:"generateConflictDoc"` // 云端同步冲突时是否生成冲突文档 Provider int `json:"provider"` // 云端存储服务提供者 S3 *S3 `json:"s3"` // S3 对象存储服务配置 WebDAV *WebDAV `json:"webdav"` // WebDAV 服务配置 Local *Local `json:"local"` // 本地文件系统服务配置 }

服务提供者通过整数枚举区分，见 kernel/conf/sync.go：

const ( ProviderSiYuan = 0 // ProviderSiYuan 为思源官方提供的云端存储服务 ProviderS3 = 2 // ProviderS3 为 S3 协议对象存储提供的云端存储服务 ProviderWebDAV = 3 // ProviderWebDAV 为 WebDAV 协议提供的云端存储服务 ProviderLocal = 4 // ProviderLocal 为本地文件系统提供的存储服务 )

其中官方云端服务为ProviderSiYuan，而ProviderS3（值 2）与ProviderWebDAV（值 3）正是本文涉及的“第三方云端存储”。

S3 对象存储的完整配置字段

在思源设置中接入 S3 时，实际落盘的配置对应S3结构体（kernel/conf/sync.go）：

type S3 struct { Endpoint string `json:"endpoint"` // 服务端点 AccessKey string `json:"accessKey"` // Access Key SecretKey string `json:"secretKey"` // Secret Key Bucket string `json:"bucket"` // 存储空间 Region string `json:"region"` // 存储区域 PathStyle bool `json:"pathStyle"` // 是否使用路径风格 SkipTlsVerify bool `json:"skipTlsVerify"` // 是否跳过 TLS 验证 Timeout int `json:"timeout"` // 超时时间，单位：秒 ConcurrentReqs int `json:"concurrentReqs"` // 并发请求数 }

WebDAV 的完整配置字段

WebDAV 服务对应的WebDAV结构体（kernel/conf/sync.go）与 S3 基本同构，但鉴权字段换为用户名/密码：

type WebDAV struct { Endpoint string `json:"endpoint"` // 服务端点 Username string `json:"username"` // 用户名 Password string `json:"password"` // 密码 SkipTlsVerify bool `json:"skipTlsVerify"` // 是否跳过 TLS 验证 Timeout int `json:"timeout"` // 超时时间，单位：秒 ConcurrentReqs int `json:"concurrentReqs"` // 并发请求数 }

从源码结构可以看到两类第三方存储共有的几个关键参数：

• Endpoint：第三方服务地址（S3 为对象存储端点，WebDAV 为服务根地址）；
• SkipTlsVerify：当使用自签名证书或非标准 HTTPS 端点时可开启，但会降低传输安全性，仅建议在受控网络中开启；
• Timeout：单次请求超时时间，单位秒，避免网络异常时同步长时间挂起；
• ConcurrentReqs：并发请求数，影响大仓库同步/备份的吞吐与目标服务的负载。

一个典型的同步配置（对应Sync各字段的json标签）形如：

{ "cloudName": "main", "enabled": true, "mode": 1, "interval": 30, "provider": 3, "webdav": { "endpoint": "https://dav.example.com/siyuan/", "username": "user", "password": "******", "skipTlsVerify": false, "timeout": 30, "concurrentReqs": 2 } }

NewSync()（kernel/conf/sync.go）给出的默认值包括：同步目录名为main、默认不启用、默认同步模式为自动（Mode: 1）、同步间隔 30 秒。若将provider改为 2 并填充s3字段，即为 S3 场景。

关键变化一：第三方 S3/WebDAV 接入需登录

自 v2.9.7 起，配置 S3/WebDAV 第三方云端存储（同步与备份）均要求登录思源账号后方可使用。从内核实现看，这一限制与同步链路强绑定：

• 同步会话的建立依赖用户身份。内核在发起同步 WebSocket 连接时会携带用户标识与设备标识，例如 kernel/model/sync.go 中dialSyncWebSocket构造请求头时包含"x-siyuan-uid": Conf.GetUser().UserId、"x-siyuan-kernel"、"x-siyuan-ver"、"x-siyuan-os"等字段；若当前未登录，则无法取得有效UserId。
• 在同步相关接口的入口处存在用户态校验，例如 kernel/api/sync.go 出现if nil == model.Conf.GetUser() || !model.Conf.Sync.Enabled这样的守卫逻辑，未登录状态下相关操作会被拒绝。

需要澄清的是，该限制只要求登录思源账号以启用/维持同步通道，数据本身仍存储在用户自建/自选的 S3 或 WebDAV 端点，并不改变第三方存储作为数据落地位置的事实。对长期依赖 WebDAV 进行备份、且在无网/离线环境管理多台设备的用户，升级到 v2.9.7 后请留意：新接入或重新配置第三方云存储时，需要保证当前设备处于已登录状态。

关键变化二：文件被外部占用时不再导致云端数据损坏

v2.9.7 修复的“云端数据损坏”问题主要发生在同步目录中的文件被外部程序占用的场景——例如用户把数据目录放在网盘、同步盘，或磁盘上存在被其他进程以独占方式打开的文件时，旧的同步流程可能读取到不一致的中间状态，进而把损坏内容上传至云端仓库。

该修复对应改进项“文件被外部佔用時數據同步不再導致雲端數據損壞”，其核心目标是让同步流程在遭遇文件锁/占用时放弃本次处理或安全重试，而不是强制读写导致仓库元数据被污染。相关逻辑落在内核同步与仓库管理模块（kernel/model/sync.go、kernel/model/repository.go）中。修复后，即使本地存在外部占用文件，云端仓库也不会因此写入损坏数据。这也是官方在概述中“建議盡快升級”的直接原因——凡是使用思源官方云或第三方存储进行同步的用户，都应尽快升级到该版本以获得此数据安全保护。

编辑器与搜索体验改进速览

v2.9.7 在编辑与搜索交互上有一批小而实的改进，官方更新说明中逐条列出，按功能域可归类如下：

搜索相关（4 项）

• Alt+↓/↑选择搜索历史关键字：在搜索输入框聚焦历史关键字时，可用方向键快速切换，减少重复输入；
• 改进搜索替换：对搜索替换的整体交互进行了优化；
• Ctrl+P搜索不再沿用上一次指定的路径：此前全局搜索会记忆上次选择的范围/路径，容易导致本次搜索在错误的范围内进行；该版本改为每次打开均为默认全局范围，降低误搜概率；
• 搜索界面添加刷新按钮：搜索结果过期时无需重新触发搜索，直接点击刷新即可获取最新数据。

块引、嵌入与文档结构相关

• 改进块引浮窗位置和大小：提升块引预览浮窗的定位精度与尺寸自适应；
• 改进块引计数显示位置：调整块引被引用次数角标的布局；
• 嵌入块显示提示文案：当嵌入块内容为空或处于待加载状态时给出明确提示，避免用户误以为渲染异常；
• 删除块后刷新面包屑：删除块之后文档顶部路径（面包屑）即时更新，不再残留已删除块的痕迹；
• 优化文档树提示文案文字间隙大小：改善文档树中提示性文字的排印可读性；
• 优化标签背景和文字颜色：调整标签（Tag）的前景色/背景色搭配，保证不同主题下的辨识度。

界面与平台细节

• 代码块操作图标不再被遮挡：修复代码块右上角操作图标在部分滚动/重叠场景下被遮住的问题；
• 改进菜单滚动条：长菜单项的滚动条样式与操作体验优化；
• 修改圖標改為隨機圖標：文档树/块右键菜单中原来的“修改图标”更名为“随机图标”，更准确地描述其从图标库随机取图的默认行为；
• 改进移动端字体设置交互：优化移动端字体面板的操作反馈；
• 改进 Android 端输入法相关问题：针对 Android 输入法遮挡、候选词弹出等兼容性问题的修复。

导出修复

• 修复导出 Word 时不渲染行级元素的問題：此前的 Word（.docx）导出流程未完整还原行级内联元素（如加粗、行内代码、行内公式等），该版本修复了该渲染缺失，导出的 Word 文档与正文呈现更一致。

Windows 卸载程序：支持选择是否删除全局配置

Windows 端卸载流程新增了“是否删除全局配置”的选项（对应更新说明“Windows 端卸載應用程序時支持選擇是否刪除全局配置”）。这意味着卸载时用户可以保留配置文件以便日后重装后快速恢复设置，也可以彻底清除残留。思源桌面安装包基于 NSIS 构建，相关安装/卸载脚本位于 app/nsis/installer.nsh，需要按需选择删除全局配置的用户，在卸载向导中留意该新增询问项即可。

开发重构：升级 Electron

本版本将桌面端所依赖的 Electron 运行时进行了升级（对应“升級 Electron”一项）。Electron 升级通常伴随内核（Chromium/Node.js）能力提升与安全补丁更新，对桌面端整体稳定性、渲染性能与 Web 标准兼容性有间接改善。升级后建议在目标平台上验证窗口行为、快捷键（如Alt+↓/↑）以及同步弹窗等桌面特性是否正常。

面向开发者：属性视图日期列与内核 API 增强

v2.9.7 同时包含三项面向开发者（插件/内核扩展）的增强，属性视图相关类型扩展与内核文件 API 均可直接与源码对应。

属性视图新增日期类型列

属性视图（Attribute View，AV）新增了日期类型列，开发者可在属性视图中添加“日期”语义的列来记录时间字段。思源内核中属性视图的类型系统、取值与排序逻辑集中在 kernel/av（含value.go、sort.go、filter.go等）以及 kernel/model/attribute_view.go 中，日期列在此前文本、数字等类型基础上扩展了时间数据的建模能力，配合已有的筛选与排序机制可用于按时间维度组织文档数据。

新增全局鼠标位置变量

社区贡献者提交的“添加全局鼠标位置变量”能力（对应 PR #8793）使插件在渲染浮层（例如右键菜单、悬浮预览、自定义面板）时，可以引用当前鼠标的全局坐标变量来精确定位弹出位置，解决全屏/多窗口场景下浮层偏移问题。对构建复杂交互浮窗的插件作者而言，这是一个实用的定位基础设施。

内核 API/api/file/readDir支持返回符号链接信息

/api/file/readDir此前仅返回目录项的基础信息，无法区分普通文件/目录与符号链接（symlink）。该版本起该接口返回结果中新增了isSymlink字段。对应实现见 kernel/api/file.go：内核通过os.ReadDir遍历目录项，并逐项输出结构化信息：

files = append(files, map[string]any{ "name": entry.Name(), "isDir": info.IsDir(), "isSymlink": util.IsSymlink(entry), "updated": info.ModTime().Unix(), })

即每个目录项现在包含四个字段：

• name：文件名；
• isDir：是否为目录；
• isSymlink：是否为符号链接（由 kernel/util 中的util.IsSymlink(entry)判定）；
• updated：最近修改时间（Unix 时间戳）。

该能力的背景在于：思源内核在处理文件时对符号链接采取了更严格的防护策略（例如拒绝目标已存在的 symlink 以避免绕过加密笔记本目录写入，见 kernel/api/file.go 中os.Lstat对ModeSymlink的检查）。因此，让文件管理 API 显式暴露 symlink 信息，有助于插件与外部工具在展示或操作前识别并规避链接文件带来的路径歧义与安全风险。

小结与升级核对清单

v2.9.7 是一个“安全优先、体验并行”的版本。升级后建议按以下清单核对：

1. 确认同步功能正常，尤其使用 S3/WebDAV 的用户确认设备处于登录状态，同步通道（含依赖x-siyuan-uid的同步 WebSocket）可正常建立；
2. 观察存在外部占用文件的同步目录是否不再触发云端数据损坏告警；
3. 验证搜索历史关键字的Alt+↓/↑、Ctrl+P默认搜索范围、搜索界面刷新按钮等交互变化是否符合预期；
4. 桌面端确认 Electron 升级后快捷键与窗口行为正常；
5. Windows 用户在卸载时按需选择是否保留全局配置；
6. 插件开发者可开始使用日期类型列、全局鼠标位置变量与带isSymlink字段的readDir返回值进行适配或新功能开发。

如需对照后续版本变化，可继续查阅 CHANGELOG.md 及 app/changelogs 下的分版本更新说明。

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