思源笔记 v3.1.0 技术解读只读发布服务、剪藏管线增强与内核 API 的演进【免费下载链接】siyuanAn open-source, privacy-first, self-hosted knowledge workspace where humans and AI agents work together 开源、隐私优先、自托管的知识工作空间让人与智能体在此协作项目地址: https://gitcode.com/GitHub_Trending/si/siyuan本解读基于仓库内 v3.1.0 中文发布说明 撰写。该版本以只读发布服务为主线新特性系统性改进了网页剪藏、编辑交互与导出能力并为开发者新增了批量块属性内核 API 与 OCR 文本坐标能力。读完本文你将掌握该版本引入的核心机制在源码层的落地形态发布访问控制模型、块属性批量读取链路、Tesseract OCR 结果结构并获得一份按主题整理的完整变更清单便于对照验证与二次开发。版本主线速览v3.1.0 的整体定位是发布可用性 细节打磨一方面打通了只读发布服务这一关键能力让知识库在只读场景下可以被安全地对外访问另一方面围绕日常编辑、数据库、剪藏、导出等高频路径做了约 30 项体验改进并修复了 15 个缺陷同时完成三项工程重构Mermaid v10.9.1、Electron v31.1.0、块树存储重构。按官方发布说明的分类本版本变更构成如下变更类别数量特征代表内容引入特性1 项支持只读发布服务改进功能约 36 项编辑交互、数据库、剪藏、导出、渲染修复缺陷15 项块移动、多窗口、播放、XSS 等改进文档1 项用户指南类型过滤章节开发重构3 项Mermaid / Electron 升级、块树存储重构开发者2 项OCR 坐标返回、批量块属性 API引入特性只读发布服务本版本最重要的能力是支持只读发布服务对应上游 PR 11367。它意味着知识库内容可以以只读形态对特定访问者公开而不再暴露可编辑入口适合对外分享文档、搭建只读知识站点等场景。发布访问控制的底层支撑虽然发布说明只用一个条目概括了该特性但从当前仓库源码中仍可看到这一机制完整、成体系的实现可作为理解该版本引入能力的直接落地参照数据模型定义在 publish_access.go 中每个发布访问控制项包含三个关键字段type PublishAccessItem struct { ID string json:id // 被控制的笔记本 / 文档 / 块 ID Visible bool json:visible // 是否发布可见 Password string json:password // 访问密码为空表示无密码 Disable bool json:disable // 是否禁止发布 }控制状态持久化在数据目录下的.siyuan/publishAccess.jsonGetPublishAccess / SetPublishAccess配合 30 秒内存缓存与互斥锁控制并发读写。请求侧在 serve.go 调用GetPublishAccess()与CheckAbsPathAccessableByPublishAccess()在对外服务层统一进行路径级放行判定。只读语义如何落地从源码结构可以推断只读 访问控制由一组层次化规则共同组成密码保护Password非空时通过GetPathPasswordByPublishAccess沿文档路径逐级向上查找最近一级密码校验采用发布专用 CookieSetPublishAuthCookie/CheckPublishAuthCookie见 publish_access.goCookie 名为publish-auth-{ID}值为 ID 与密码的 SHA-256 摘要有效期一天。禁止发布Disable为 true 的笔记本 / 文档将直接被过滤。内容层会替换为禁止访问占位块资源、列表、搜索、标签、图、反链等所有可能泄漏路径的出口都有对应的Filter*ByPublishAccess/Filter*ByPublishIgnore过滤函数集中在 publish_access.go。只读模式下禁用编辑入口发布说明中另一条改进只读模式下禁用一些菜单项PR 11733与只读发布相辅相成确保只读场景下编辑菜单不再暴露。对于普通用户而言使用只读发布服务的路径是先在设置中开启对外发布 / 只读访问能力再按需对笔记本或文档设置可见、加密码、禁止发布最后通过发布的访问地址即可只读浏览内容。开发者能力升级两个内核 API 级变更本版本面向插件 / 集成开发者的两条变更都能在当前仓库源码中直接定位到实现。新增内核 API/api/attr/batchGetBlockAttrs此前获取块属性只能单块调用getBlockAttrs批量场景下会产生大量往返请求。本版本新增了内部内核/api/attr/batchGetBlockAttrs对应上游 issue 11786一次请求读取多个块的属性。路由注册位于 router.goginServer.Handle(POST, /api/attr/batchGetBlockAttrs, model.CheckAuth, batchGetBlockAttrs)处理函数在 attr.go请求体示例{ ids: [20210808180117-6v0mkxr, 20230405172236-pg3l9eu] }实现要点请求参数为ids字符串数组不做 ID 合法性InvalidIDPattern逐项校验——这与单块接口不同说明它面向内部高频批量场景、追求吞吐数据层调用 sql.BatchGetBlockAttrs优先命中块 IAL 缓存cache.GetBlockIALWithBoxFallback按 block ID 与所在笔记本 box 双键回退未命中时经filesys.LoadTrees(ids)批量装载文档树后逐块解析属性返回结构为map[string]map[string]string即块 ID → 属性键值对的映射方便调用方直接索引与配套的BatchGetBlockAttrsWitTreesblock.go支持外部传入已加载树以复用构成完整读写链路。内核 API OCR 返回文本坐标信息面向资产识别的/api/asset/ocr接口在本版本起会随结果返回 OCR 文本坐标信息对应上游 PR 11738让调用方可以拿到识别文本在图片上的几何位置为框选高亮、图文定位等场景提供基础。路由注册router.go带上了管理员与只读限制ginServer.Handle(POST, /api/asset/ocr, model.CheckAuth, model.CheckAdminRole, model.CheckReadonly, ocr)接口处理函数见 asset.go返回体中同时携带两个字段{ text: 连接后的整段识别文本, ocrJSON: [ { left: …, top: …, width: …, height: …, conf: …, text: …, …: … } ] }其中text是由所有词条text字段拼接的纯文本便于直接建索引/搜索ocrJSON是逐词条的完整明细。坐标信息来源于底层调用 Tesseract 时使用tsv输出格式ocr.go随后按 TSV 表头逐行解析为map[string]anyocr.go。TSV 的left/top/width/height列即构成文本块在图片上的包围盒坐标conf为置信度。识别任务侧由 model/ocr.go 中的OCRAssetsJob等驱动对尚未识别、可识别的图片资源排队执行 OCR并限制单次任务处理数量一次最多 7 张以防长时间占用资源加密笔记本内的资源会被显式跳过避免密文图片产生无意义文本污染索引。编辑器与交互体验改进本版本在编辑器高频操作路径上投入了大量细节优化相关条目按主题整理如下新建文档引导创建空文档后提供交互指导降低空文档的困惑感issue 10528。行级元素改进行级元素菜单交互10577、行级元素粘贴11740修复行级元素内ShiftEnter失效11766、行级代码内粘贴转义文本异常11778等问题。选择与光标改进Shift↑/↓扩展选择11671、代码块内光标移动11647、表格内↑/↓移动11694、包含图片的块的多重选择11763以及图片居中后的选择操作11757。标题与结构改进展开标题的性能10935、优化文档标题中↓的使用11729支持在开头粘贴块并将其插入上方11677。查找与快捷键改进CtrlP与CtrlF11637转换列表支持配置快捷键11634修复快捷键设置中按辅助键时无提示11720。超级块与嵌入块修复移动超级块的子块异常11609改进嵌入块导出11725修复CtrlX应剪切嵌入块本身而非其内容11793。数据库与属性面板改进围绕数据库 / 属性视图这一定位日益重要的能力本版本进行了多项修正复制数据库表视图字段时保持字段宽度11552改进带数据库的文档复制11602属性面板中数据库支持右键点击字段11625改进添加到数据库搜索11644并修复移动端无法使用添加到数据库的问题11651在书签面板中显示数据库标题11666。网页剪藏与内容渲染优化网页剪藏是本版本的另一个重点打磨方向覆盖面从站点适配到 HTML 结构再到公式代码HTML 结构化处理改进 HTML 实体剪藏11557、HTML 代码剪藏11642、HTML 表格剪藏11783与 HTML 公式剪藏11743改进网页剪藏中转义代码块标记的处理11643。站点适配改进维基百科剪藏11640、知乎公式剪藏11653、StackExchange 公式剪藏11646。渲染与内容显示改进 Mermaid 的 Markdown 渲染11670本版本同步将 Mermaid 升级至 v10.9.111645改进自定义表情搜索PR 11768与移动端自定义表情渲染11690自定义表情文件夹发生更改后也不再需要手动刷新11749。导入、导出与文件资源改进 PDF 导出11258改进导出 PDF 注释超链接的页码显示11780在 PDF 标签的右键菜单中添加复制11758。导出.sy.zip与data.zip时显示详情11696。导出块引用锚点哈希支持文档级别11814。Windows arm64 与 Linux arm64 不再打包 pandoc11649可显著减小对应平台安装包体积。改进字体家族11841上传资源时从文件名中移除不可见字符11683。修复多窗口编辑时文档无法在新窗口正常打开11610移动文档后无法重命名11661启用自适应宽度时 IFrame 块不随动11695音频或视频偶尔无法播放11810图片标题转义内容重复11681。附件相关补充改进 IFrame、媒体资源健壮性之外还修复了拖动和撤销 HTML 块时显示标签的问题11656。其他细节与体验修复文档树面板中显示已关闭笔记本数量11648。笔记本配置变更后数据同步将重新索引笔记本并重新加载界面11850。若笔记本配置改变同步后刷新相关状态避免界面与磁盘配置不一致。缺陷修复中较关键的安全项搜索界面 XSS11848与代码块语言搜索 XSS11869均在本版本修复。功能修复方面还包括含有%的行级备注无法显示11709、AI 自定义操作无法编辑11791等。文档与工程重构改进文档改进用户指南中类型过滤章节的说明PR 11692。依赖升级Mermaid 升级至 v10.9.111645、Electron 升级至 v31.1.011654。架构重构重构块树存储11773。块树BlockTree是思源内核中块 ID → 所在笔记本与路径的核心索引当前实现位于 kernel/treenode 包如 blocktree.go、tree.go其上承载了上述发布访问控制、批量属性读取、反链/引用过滤等大量查询路径因此该重构的意义在于让这些高频只读索引更加稳定高效。获取版本与继续阅读完整中英日三语发布说明保存在仓库 app/changelogs 目录下本版本目录为 v3.1.0其余版本按 v3.x.y 分目录存放便于横向对照相邻版本的演进脉络。若希望基于源码继续验证本文提到的实现可优先阅读 publish_access.go、attr.go、block.go 与 ocr.go 这几个核心文件。内核内核 API 全量路由定义见 router.go接入插件时可对照其中的认证、角色与只读中间件组合来评估接口的调用权限前提。提示本文所述发布访问控制、批量块属性与 OCR 坐标等机制在当前仓库源码中仍然可见由于仓库持续演进个别行为细节可能随后续版本迭代有所调整落地时请以所使用版本的实际行为为准。【免费下载链接】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），仅供参考