思源笔记 v3.1.19 版本深度解析本地文件系统同步、广播消息内核 API 与细节打磨【免费下载链接】siyuanAn open-source, privacy-first, self-hosted knowledge workspace where humans and AI agents work together 开源、隐私优先、自托管的知识工作空间让人与智能体在此协作项目地址: https://gitcode.com/GitHub_Trending/si/siyuan本文基于思源笔记SiYuan官方 v3.1.19 版本变更记录简体中文版、繁体中文版、英文版展开。v3.1.19 是一个典型的细节改进版本它引入了面向离线用户的本地文件系统同步与备份能力面向开发者的广播消息内核 API同时修复了包括任意文件删除漏洞在内的多项缺陷。读完本文你将掌握该版本的全部功能变化、关键特性的底层实现原理以及升级前需要注意的兼容性要点。版本概述一次聚焦细节与安全的中量级更新v3.1.19 延续了思源笔记高频迭代的节奏官方对该版本的定位是改进了一些细节。从变更记录看本次共包含 20 项功能改进、5 项缺陷修复和 2 项面向开发者的内核 API 变更覆盖编辑器、数据库、搜索、同步、移动端、平台适配与安全性等多个维度。其中最具分量的两个变化是支持本地文件系统同步与备份PR #13663为不依赖云端/S3/WebDAV 的用户提供了新的同步提供方Provider数据直接写入本地指定目录。广播消息内核 APIPR #13681、PR #13694内核新增通过 WebSocket/SSE 发布与订阅广播消息的能力为插件与外部程序与内核实时通信铺平了道路。本地文件系统同步与备份不依赖云端的同步方案功能背景与使用场景在此版本之前思源笔记的同步依赖思源官方云同步、S3 或 WebDAV 三种提供方。对于完全离线的用户例如内网环境、不信任第三方云存储、或者希望将笔记数据直接落在自己管理的磁盘上这构成了一定的门槛。v3.1.19 引入的本地文件系统同步允许将一个本地目录作为同步目标数据仓库dejavu 格式的同步快照直接写入该目录从而实现离线云同步和备份。源码级原理路径校验与配置写入从源码看本地提供方的配置入口是SetSyncProviderLocalkernel/model/sync.go其处理流程如下func SetSyncProviderLocal(local *conf.Local) (err error) { local.Endpoint strings.TrimSpace(local.Endpoint) local.Endpoint util.NormalizeLocalPath(local.Endpoint) absPath, err : filepath.Abs(local.Endpoint) // 1. 目录必须存在 if !gulu.File.IsExist(absPath) { ... } // 2. 不能是工作空间目录或其内部路径 if util.IsAbsPathInWorkspace(absPath) || filepath.Clean(absPath) filepath.Clean(util.WorkspaceDir) { ... } // 3. 不能是工作空间的父目录 if gulu.File.IsSubPath(absPath, util.WorkspaceDir) { ... } local.Timeout util.NormalizeTimeout(local.Timeout) local.ConcurrentReqs util.NormalizeConcurrentReqs(local.ConcurrentReqs, conf.ProviderLocal) Conf.Sync.Local local Conf.Save() return }这段代码揭示了三条关键约束用户在配置时务必注意目标目录必须已存在否则会直接报错endpoint [xxx] not exist同步目录不能位于思源工作空间workspace内部否则会被拒绝——这是为了避免把仓库快照写进数据目录自身造成递归污染同步目录不能是工作空间的父目录避免同步范围意外覆盖工作空间。此外CreateCloudSyncDir与RemoveCloudSyncDirkernel/model/sync.go两个管理云端同步目录的函数在本版本中仅对ProviderSiYuan思源官方云和ProviderLocal本地文件系统两种提供方开放其余提供方S3/WebDAV会返回错误提示。配套调整移除 S3/WebDAV 的目录管理按钮与本地同步配套本版本在设置界面移除了 S3/WebDAV 云同步目录设置中的添加和移除按钮Issue #13682。结合源码可以理解这一改动的原因CreateCloudSyncDir/RemoveCloudSyncDir本质上是在云端或本地创建/删除 dejavu 数据仓库目录该能力仅对思源云和本地提供方有意义S3/WebDAV 的同步目录语义不同继续保留按钮反而容易引起误操作。这一调整让设置界面与底层能力边界保持一致。编辑器体验改进页签、超级块与快捷键改进页签拖动页签Tab拖动是思源多文档工作流中的高频操作本版本针对拖动的交互细节进行了优化Issue #13548改善了拖动预览与放置位置的反馈减少误放。超级块Super Block三连改进超级块是思源笔记用于构建复杂排版如多列布局的核心容器本次更新包含三处相关改进改进在超级块中创建新块Issue #13568修复了在超级块内部特定位置尤其是块首/块尾创建新块时的行为使新建块的落点更符合直觉。新增取消超级块和切换水平/垂直布局的快捷键Issue #13664此前切换超级块布局需要进入右键菜单操作现在可以直接通过快捷键完成取消超级块与水平/垂直布局切换显著提升排版效率。快捷键的具体绑定可在设置 - 快捷键中查看与自定义。修复ShiftEnter在块内不执行软换行Issue #13683软换行不产生新块、仅段落内换行是 Markdown 写作中的常用操作该回归问题在本次修复。其他编辑器细节模板弹出窗口支持拖动预览区域大小Issue #13623模板选择弹窗的预览区域现在可以自由调整大小方便查看长模板效果。改进行级公式中的备注Issue #13667改进了行级公式Inline Math中添加注释\text{}等时的渲染与编辑体验。改进包含空格的查找替换Issue #13705修复了查找/替换Find Replace中关键词含空格时匹配行为异常的问题。改进右键块选择Issue #13716优化了右键点击时块的选中范围与菜单触发逻辑。改进设置界面Issue #13626设置面板整体布局与交互细节得到打磨。数据库属性视图改进思源笔记的属性视图数据库功能在本版本收获多项改进数据库主键锚文本支持换行Issue #13624主键列中的锚文本现在可以换行显示长标题不再被截断。改进数据库关联和汇总样式Issue #13692关联字段与汇总字段的样式得到优化信息展示更清晰。改进数据库资源字段弹出窗口Issue #13719资源Assets字段的弹出预览窗口交互与展示效果得到优化。搜索与剪藏改进改进搜索高亮Issue #13686搜索结果中的关键词高亮在部分复杂文档结构下的覆盖范围得到修正。改进搜索 OCR 图像预览区域定位Issue #13703搜索命中的 OCR 图片其预览区域定位更准确便于快速核对图片内容。改进微信公众号文章剪藏Issue #13733针对微信公众号文章的结构特点优化了剪藏Clip后的排版与图片处理降低正文丢失概率。移动端与平台适配在移动设备上编辑时禁用左右滑动弹出侧栏面板Issue #13647此前在移动端编辑时左右滑动的手势容易误触发出侧栏面板干扰输入。本版本在编辑态禁用了该手势仅在非编辑态保留滑动呼出能力。改善鸿蒙HarmonyOS系统支持Issue #13676。在 Android 上申请相机权限时弹出用途说明Issue #13712遵循 Android 权限最佳实践在申请相机权限前向用户说明用途提升权限申请的透明度和合规性。安全与稳定性漏洞修复与崩溃预防本版本的安全修复值得所有用户重视修复任意文件删除漏洞Issue #13709这是本版本最重要的安全更新。思源内核对外暴露 API 服务恶意请求可能利用路径处理缺陷删除工作空间外的任意文件。建议所有暴露在不可信网络中的实例立即升级并排查是否已受影响。加载某些字体文件导致内核崩溃Issue #13739修复了内核在解析特定畸形字体文件时崩溃的问题增强了对异常字体文件的容错。设置 - 编辑器 - 字体在 macOS 上显示乱码Issue #13713修复了 macOS 平台字体列表乱码问题。另外针对 Windows 用户本版本支持忽略新增 Microsoft Defender 排除项的提示Issue #13687 中的ignoreAddMicrosoftDefenderExclusion实现——调用后即写入配置Conf.System.MicrosoftDefenderExcluded true对应配置项定义见 kernel/conf/system.go此后 kernel/job/cron.go 中每 30 分钟触发的AutoCheckMicrosoftDefenderJob将跳过提示。对不需要 Defender 排除、或由企业 IT 统一管理杀软的白名单用户来说这避免了重复弹窗打扰。开发者 API内核广播消息通道v3.1.19 面向开发者新增了两项广播相关内核 APIPR #13681路由注册见 kernel/api/router.go。架构统一的广播通道模型广播体系的核心抽象是BroadcastChannelkernel/api/broadcast.gotype BroadcastChannel struct { Name string // channel name WebSocket *melody.Melody // WebSocket 订阅端 Subscriber *BroadcastSubscriber // SSE 订阅计数 }每个通道同时支持两种订阅协议WebSocket基于 melody 库客户端通过GET /ws/broadcast?channeltest建立连接SSEServer-Sent Events基于 gin-contrib/sse EventBus客户端通过GET /es/broadcast/subscribe订阅。消息分为字符串string和二进制binary两种类型由MessageType枚举区分kernel/api/broadcast.go。全局注册表BroadcastChannels使用sync.Map管理所有通道保证并发安全。发布消息三个 API 入口POST /api/broadcast/publishbroadcastPublishkernel/api/broadcast.go使用multipart/form-data一次性向多个通道发布消息。表单字段名为通道名值为字符串数组或文件文件即二进制消息返回每个通道的订阅者数与每条消息的发送结果。POST /api/broadcast/postMessagepostMessagekernel/api/broadcast.go以 JSON 参数{ channel: test, message: hello }向单个通道发布字符串消息并返回该通道的订阅者数。查询接口getChannels列出所有通道及订阅数getChannelInfo查询单通道信息kernel/api/broadcast.go。值得注意的细节GetBroadcastChannelkernel/api/broadcast.go在通道不存在时若存在全局 SSE 订阅者UnifiedSSE.Subscribed()会自动创建新通道否则返回 nil即无订阅者则不产生消息投递。订阅消息WebSocket 与 SSE 两种方式WebSocket 订阅GET /ws/broadcast?channeltest同通道内消息会广播给所有 WebSocket 会话BroadcastOthers排除发送者自身。SSE 订阅GET /es/broadcast/subscribe?retry1000channeltest1channeltest2支持一次订阅多个通道retry参数指定断线重连间隔毫秒若不传channel参数则订阅全部通道SubscribeAll。SSE 的推送基于进程内 EventBus事件总线SendEvent将事件发布到broadcast.message主题kernel/api/broadcast.go各订阅连接通过Stream循环消费kernel/api/broadcast.go。客户端断开时通过CloseNotify感知并自动清理订阅计数。所有广播路由均挂载了CheckAuth与CheckAdminRole两个中间件见 kernel/api/router.go即广播通道仅对管理员开放外部调用方需先通过鉴权。通道生命周期管理内核提供完整的通道清理机制客户端断开 WebSocket 后触发HandleClose回调尝试销毁通道Destroy在无订阅者时关闭 WebSocket 并向 SSE 订阅端推送close类型事件PruneBroadcastChannels则周期性清理所有无订阅者的孤儿通道kernel/api/broadcast.go。这保证了长连接场景下资源的及时回收。升级建议与获取方式升级建议所有用户都建议升级——尤其是任意文件删除漏洞#13709的修复涉及数据安全不要长期停留在旧版本使用 S3/WebDAV 同步的用户请注意设置界面已移除云端目录的添加/移除按钮这是预期行为不影响同步本身希望离线同步的用户升级后可在设置 - 同步中选择本地文件系统提供方并指定一个已存在、且位于工作空间之外的目录作为同步目标插件开发者可关注广播 API用于实现内核与插件/外部服务之间的实时消息推送。获取方式可从思源官网下载页B3log或 GitHub Releases 页面获取对应平台Windows/macOS/Linux/移动端/鸿蒙的安装包Docker 用户可拉取最新镜像仓库 Dockerfile 定义了镜像构建方式。总结v3.1.19 体现了思源笔记高频小步快跑的迭代风格一方面通过本地文件系统同步补齐了离线场景的能力缺口通过广播内核 API 为生态扩展铺路另一方面对编辑器、数据库、搜索、移动端进行了大量交互细节打磨并修复了任意文件删除漏洞、字体加载崩溃等关键问题。对于普通用户而言这是一次值得立即升级的版本对于开发者而言广播 API 的引入则为插件实时通信提供了全新的可能性。【免费下载链接】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），仅供参考