Siyuan v2.10.10 紧急修复版技术解析:插件兼容性、PDF 标注资产与资产鉴权改进
Siyuan v2.10.10 紧急修复版技术解析:插件兼容性、PDF 标注资产与资产鉴权改进【免费下载链接】siyuanAn open-source, privacy-first, self-hosted knowledge workspace where humans and AI agents work together 开源、隐私优先、自托管的知识工作空间让人与智能体在此协作项目地址: https://gitcode.com/GitHub_Trending/si/siyuan本篇基于 Siyuan 官方变更日志 v2.10.10 撰写。你将了解该紧急修复版的完整变更记录,以及其背后涉及的关键实现——.syaPDF 标注文件机制、siyuan://plugins/协议的事件总线分发、非 127.0.0.1 资产请求鉴权,从而掌握如何在 Siyuan 中理解版本演进与源码级验证方法。版本定位:一次面向插件生态的紧急修复v2.10.10 被官方明确标注为“紧急缺陷修复版”an emergency bug fix version其首要目标是解决部分插件的兼容性问题。这意味着该版本不是功能大版本而是对上一版本v2.10.9 及之后引入的、影响第三方插件运行的问题的快速补救。从变更记录结构看官方将其划分为三个层次:增强Enhancement10 项面向用户的体验改进修复Bugfix2 项缺陷修复其中一项直接指向插件兼容性开发Development5 项面向插件开发者与底层行为的变化其中包含事件总线open-siyuan-url-plugin的改进——这恰是插件兼容性问题的技术焦点之一。版本说明中还保留了当时的商业模式备注:功能特性PRO Features处于早鸟价阶段且年付订阅包含功能特性订阅会员无需单独购买。这是版本日志的原始说明不影响技术变更本身。完整变更记录以下完整继承 v2.10.10.md中文见 v2.10.10_zh_CN.md的原始条目对应 issue 编号以 # 号标注便于在仓库与社区中检索:增强改进 PDF 标注颜色#9206导出 PDF 的页面中加入插件 CSS 与自定义代码片段CSS#9376块引用block ref右键菜单新增“打开反向链接”与“打开关系图”#9383代码片段设置使用等宽字体#9385在--b3-font-family-code中加入--b3-font-family#9386对来自非 127.0.0.1 的 assets 请求进行鉴权#9388重命名 PDF 资产时关联重命名.sya标注文件#9390新增“复制块引超链接Markdown”快捷键#9392改进移动端选中文本后弹出工具栏的位置#9393改进代码块语言提示的默认选择#9396修复导出数据 Data 失败的问题#9389修复若干插件兼容性问题#9397开发编辑器中的块显示数据库角标#8894改进事件总线open-siyuan-url-pluginPR #9256改进数据库“创建时间/更新时间”列的取值#9391改进数据库列过滤器包含空值时的处理#9394数据库启用过滤器后添加行覆盖数据的问题#9395资产安全:非 127.0.0.1 访问 assets 的鉴权本版本中最具安全意义的变更是“对来自非 127.0.0.1 的 assets 请求进行鉴权”#9388。Siyuan 的静态资源附件、PDF、标注文件通过/api/...与 assets 路径对外提供此前若以非回环地址如局域网 IP 或远程端口转发访问存在资源被未鉴权读取的风险。从源码结构看这套“仅限本机回环免鉴权、其余来源必须鉴权”的策略由会话中间件统一实施。在 kernel/model/session.go 中可以看到对应逻辑:服务端依次检查请求的Host、Origin、X-Forwarded-Host头与客户端 IP一旦任一值不属于本机回环127.0.0.1即返回 401 并提示“为安全起见使用非 127.0.0.1 访问时请设置锁屏密码”:// Authenticate requests with the Origin header other than 127.0.0.1 clientIP : c.ClientIP() host : c.GetHeader(Host) origin : c.GetHeader(Origin) forwardedHost : c.GetHeader(X-Forwarded-Host) if !localhost || ( ! clientIP !util.IsLocalHostname(clientIP)) || ( ! host !util.IsLocalHost(host)) || ( ! origin !util.IsLocalOrigin(origin)) || ( ! forwardedHost !util.IsLocalHost(forwardedHost)) { c.JSON(http.StatusUnauthorized, ...) c.Abort() return }这条变更的实践含义是:如果你通过局域网 IP 访问 Siyuan 工作区例如手机与电脑同网段协作需要确保已设置锁屏密码并持有有效鉴权凭据仅在本机 127.0.0.1 上访问才会走免密管理通道。PDF 标注体系:.sya 文件的命名与加密联动变更记录中“重命名 PDF 时关联重命名 .sya 标注文件”#9390涉及 Siyuan 的 PDF 标注存储模型。Siyuan 将每个 PDF 资产的标注数据存放在与 PDF 同名的.sya文件中标注内容以链接/文本等注释对象的形式挂在assets/a.pdf之下。在 kernel/api/asset.go 中.sya的解析规则被显式约定:“.sya在 URL 末尾例如assets/a.pdf?boxid.sya”实现上通过strings.TrimSuffix剥离.sya后缀得到原始 PDF 路径再拼回得到标注文件绝对路径:func resolveFileAnnotationAbsPath(assetRelPath string) (ret string, err error) { // .sya 在 URL 末尾例如 assets/a.pdf?boxid.sya filePath : strings.TrimSuffix(assetRelPath, .sya) absPath, err : model.GetAssetAbsPathInBox(filePath, ) if err ! nil { return } ret absPath .sya return }同一文件中还可以看到.sya与加密笔记本的联动:写入前若路径属于加密笔记本model.IsEncryptedBox.sya内容必须加密落盘未解锁时拒绝写入fail-closed读取后必须解密未解锁时拒绝返回见 kernel/api/asset.go。这解释了为什么 PDF 重命名必须“关联重命名”.sya:一旦两者失配标注数据既可能丢失也可能在加密笔记本场景下指向错误的密文文件。标注数据本身在模型层的组织可见于 kernel/model/pdf.go:链接型注释LinkAnnotation会按目标是否指向本机 assetshttp://127.0.0.1:port/assets/...拆分为两组处理——这正是“改进 PDF 标注颜色”#9206所在的数据通道:颜色、位置等标注属性就记录在这些注释对象中随.sya持久化。样式系统:--b3-font-family-code 与代码片段等宽字体两条增强项共同指向 Siyuan 的 CSS 变量字体体系:“在--b3-font-family-code中加入--b3-font-family”#9386“代码片段设置使用等宽字体”#9385。--b3-font-family是用户可自定义的正文字体变量--b3-font-family-code是代码/等宽字体变量。变更前两者互不派生;变更后将正文字体并入代码字体栈使自定义字体尤其是中文字体在代码块中也能按用户偏好回落显示。该变量的定义与使用散落在主题样式与渲染逻辑中例如内置主题 app/appearance/themes/daylight/theme.css 与 app/appearance/themes/midnight/theme.css 中的变量声明以及前端渲染代码 app/src/protyle/render/av/calc.ts计算引擎求值时对字体变量的引用。配套地代码片段Custom Snippets设置界面改为等宽字体展示其设置逻辑位于 app/src/config/util/snippets.ts与 app/src/assets/scss/component/_typography.scss 中的排版样式共同保证用户在编辑 CSS 片段时所见即所得。导出 PDF:带入插件 CSS 与代码片段样式“导出 PDF 的页面中加入插件 CSS 和自定义 CSS”#9376解决的是导出保真度问题:此前导出 PDF 只携带核心主题样式用户通过插件或代码片段注入的 CSS自定义配色、布局、组件皮肤在导出产物中丢失。变更后导出流程会收集插件注入的样式与代码片段即自定义 CSS一并渲染进 PDF。该能力依托 Siyuan 的导出管线:导出入口实现位于 kernel/model/export.go前端导出渲染由 protyle 渲染层完成主题变量如前文的字体变量在导出时同样参与计算因此插件 CSS 中引用的--b3-*变量在导出产物中也能正确取值。对重度使用自定义样式的用户这一变更意味着打印版与屏幕版观感的一致性显著提升。插件开发:open-siyuan-url-plugin 事件总线与 siyuan:// 协议开发条目中“改进事件总线open-siyuan-url-plugin”PR #9256是插件兼容性问题的核心修复之一。Siyuan 支持通过siyuan://自定义协议唤起特定插件页面例如:siyuan://plugins/plugin-name/foo?barbaz siyuan://plugins/plugin-samplecustom_tab?title自定义页签iconiconFacedata{...}其前端处理链路在 app/src/util/uri.ts 中:URI 解析后按名称查找已加载插件命中则向该插件实例的事件总线发射open-siyuan-url-plugin事件并把完整url作为载荷传递:const plugin app.plugins.find(plugin pluginNameOrTabType plugin.name); if (plugin) { // siyuan://plugins/plugin-name/foo?barbaz plugin.eventBus.emit(open-siyuan-url-plugin, { url: uriObj.href }); } else { // 未命中插件名时按自定义页签custom tab处理 }“改进”之处在于分支处理与载荷规范化:当协议目标不是已安装插件而是自定义页签类型时走 else 分支构造页签数据title、icon、data。对插件开发者而言需要监听eventBus的open-siyuan-url-plugin事件并在url字段中自行解析路径与查询参数;事件名与载荷结构以 app/src/types/index.d.ts 中的类型声明为准。这类事件分发行为的调整正是本版“修复部分插件兼容性问题”#9397的技术落点之一——上一版本中协议分发行为的变化曾使依赖旧行为的插件失效v2.10.10 通过统一事件语义予以纠正。其余用户体验与开发侧变更块引用右键菜单#9383:在块引用block ref的右键菜单中加入“打开反向链接”与“打开关系图”把原本需要进入块所在笔记才能触达的两个入口前置到引用处缩短双向链接操作路径。复制块引超链接Markdown#9392:新增快捷键直接以 Markdown 形式复制块引用超链接便于在外部文档中粘贴引用。代码块语言提示#9396:改进代码块语言选择下拉的默认项选择逻辑减少误选;与字体变量变更#9386共同提升代码编辑观感。移动端选区工具栏#9393:修正移动端选中文本后弹出工具栏的坐标定位。数据库属性视图三项变更:“编辑器中的块显示数据库角标”#8894:被数据库视图引用/包含的块在编辑器中展示数据库标识,帮助用户识别块的复用关系“创建时间/更新时间列值”#9391:修正数据库表这两个系统列取值的正确性;“列过滤器包含空值”#9394与“启用过滤器后添加行覆盖数据”#9395:两者均属数据库过滤引擎的边界修复——过滤器条件作用于空值时的行为以及过滤器激活状态下新增行被既有数据覆盖的问题。数据库视图的布局实现可参考 kernel/av/layout_table.go 等属性视图布局文件从源码结构看表格/画廊/看板三种布局各自独立维护行渲染逻辑。数据导出失败#9389:修复“导出数据 Data 失败”缺陷恢复工作区备份/导出流程的可用性;导出实现位于 kernel/model/export.go。小结与验证路径v2.10.10 的变更虽然以“紧急修复”为名实际覆盖了四条主线:资产访问安全非回环来源鉴权、PDF 标注资产一致性.sya随 PDF 重命名、加密笔记本 fail-closed、插件协议兼容open-siyuan-url-plugin事件语义与导出保真插件 CSS 进 PDF。验证这些行为时可按以下路径对照当前仓库:主题变更日志源码落点非 127.0.0.1 鉴权#9388kernel/model/session.go.sya标注解析与加密#9390kernel/api/asset.go、kernel/model/pdf.gosiyuan://插件协议PR #9256app/src/util/uri.ts导出 PDF 样式#9376kernel/model/export.go字体变量体系#9385、#9386app/appearance/themes/daylight/theme.css、app/src/config/util/snippets.ts数据库视图#9391–#9395kernel/av/需要注意:本文所有行号与行为描述均以当前仓库检出状态为准;该版本日志本身属于 v2.10.x 系列后续版本v3.x在加密笔记本、属性视图等模块上已有进一步演进阅读源码时请以对应版本标签为准。【免费下载链接】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），仅供参考