企业官网建设流程全解析

思源笔记 v3.5.5 更新全解析：数据库清理、移动端体验与磁盘 I/O 深度优化

【免费下载链接】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.5.5 是一次聚焦"细节打磨"的版本迭代，围绕数据管理、移动端体验、网络服务与磁盘性能四条主线展开。本篇文章以官方更新日志为骨架，结合仓库源码（Go 内核 + Electron 前端）逐项解析每处变更的实现原理与使用场景：你将了解如何清理未被引用的数据库、如何在局域网内以 HTTPS 安全访问 Web 服务、思源如何通过 mmap 减少磁盘写入，以及移动端工具栏在 Android、鸿蒙与 iOS 上的行为改进。读完本文，你可以基于源码路径自行验证每个新特性，并据此优化自己的使用与部署方式。

一、版本定位与更新总览

v3.5.5 位于 v3.5.x 系列的中后期，官方概述只有一句话："此版本改進了一些細節。"但细节之中包含 22 项功能改进、3 项缺陷修复和 1 项开发重构，覆盖内核（Kernel）、移动端与桌面端三端。

从变更结构看，本版重点集中在：

下文按"数据与性能 → 网络服务 → 编辑器与桌面端 → 移动端 → 修复与工程化"的顺序展开。

二、数据管理与磁盘 I/O 优化（内核级）

本版在存储层有四项相互关联的改进，共同目标是"减少磁盘读写、提升大库性能"。

2.1 支持清理未被引用的数据库

这是本版最受关注的数据管理功能（对应 issue #11569）。它允许用户扫描并清理"没有被任何块引用"的数据库（属性视图），避免属性视图无限堆积占用空间。

从源码结构看，未引用资源（assets）的清理逻辑位于 kernel/model/assets.go，而 kernel/api/asset.go 中列出了未引用资源的查询接口，并特意限制"每次仅列出 512 个未引用资源"，以避免一次性返回过多结果拖垮前端（参见List only 512 unreferenced assets）。清理时，内核还会忽略与custom-data-assets块属性关联的资源（见 kernel/model/assets.go 中关联 issue #12574 的处理注释），防止误删被属性声明引用但未出现在正文中的资源。

使用建议：在"设置 → 资源"中对未引用资源执行清理前，建议先使用"预览未引用"确认清单；对于属性视图/数据库，清理后引用关系会被更新，若之后需要恢复，可借助数据快照（历史）回滚。

2.2 写入文件数据通过 mmap 减少磁盘写入

这是本版最值得关注的性能改动之一（issue #16956）。思源在 kernel/util/mmap.go 中实现了WriteFileByMmap：通过内存映射（memory-mapped file）将数据"原地覆写"到文件。

其完整流程为（源码注释中明示）：

OpenFile(O_RDWR|O_CREATE) → Truncate 到精确长度 → mmap.Map(RDWR) → copy 写入 → Flush → Unmap

• 写入路径差异：传统写入走filelock.WriteFile（临时文件 + rename + fsync），会触发真实的 I/O 子系统写入；而 mmap 路径中copy(m, data)是纯内存写，不经过 I/O 子系统，只有Flush会产生极少量计入，因此在进程级 I/O 写入计数（IO Write Bytes）上几乎为零。
• 并发安全：全程持有 filelock 的进程内互斥锁，避免并发写冲突；Truncate先将文件截断到精确长度再映射，保证映射区间与数据长度严格一致。
• 失败回退：mmap 任一步骤（打开、截断、映射、刷新）出错时返回错误，由调用方回退到filelock.WriteFile，不影响数据正确性。

2.3 改进数据索引与缓存树数据

• 改进数据索引以减少磁盘读取（issue #16958）：针对大工作空间，索引阶段避免重复扫描未变化的文档块数据，从结构上降低冷启动与重建索引时的磁盘读取量。
• 缓存树数据以提升性能（issue #16961）：树（Tree）数据是文档块的逻辑载体，kernel/treenode/tree.go 与 kernel/treenode/blocktree.go 维护了块树的内存结构。缓存后，高频的树访问可直接命中内存，减少反复读盘。

可以推断：这两项与 2.2 的 mmap 写入共同构成一套"读缓存 + 写映射"的组合策略，目标是让大库在频繁编辑、搜索、重建索引时磁盘负载明显下降。官方在 v3.5.4 中曾提示"在非 SSD 硬盘上运行可能存在性能问题"（issue #16835），本版三项存储优化正是对这一方向的持续投入。

2.4 导出包含大量引用的文件时减少内存使用

针对"引用密集"的文档（大量块引用、资源引用），导出时（issue #16982）改为流式/分批处理而非整体驻留内存，降低大文档导出时的峰值内存占用。导出链路相关代码位于 kernel/model/export.go 与 kernel/model/export_merge.go。

三、网络服务：支持通过 HTTPS 提供网络服务

v3.5.5 通过 PR #16930 支持了"通过 HTTPS 提供网络服务"。需要区分的是，思源内核实际上自 v3.x 起就已为本地内核服务自动生成 TLS 证书，本版新增的是将固定端口网络伺服（网络伺服）也升级为 HTTPS的能力。

3.1 本地内核的 HTTPS/HTTP2 支持

在内核启动流程 kernel/server/serve.go 中：

1. 启动时调用util.GetOrCreateTLSCert()生成/获取本地 TLS 证书；
2. 证书可用时，ServerURL解析为https://127.0.0.1:<port>，否则回退http://；
3. 证书不可用仅告警（LogWarnf），不影响内核启动。

3.2 同一端口上的 HTTP/HTTPS 复用（cmux）

思源在同一监听端口上同时承载 HTTP 与 HTTPS（含 HTTP/2），实现位于 kernel/util/cmux.go 的ServeMultiplexed：

• 使用cmux按协议拆分连接：m.Match(cmux.TLS())匹配 TLS 握手流量，m.Match(cmux.Any())承接其余 HTTP 流量；
• TLS 配置指定NextProtos: []string{"h2", "http/1.1"}，即支持 HTTP/2；
• 代码注释特别强调：HTTP 与 HTTPS 必须使用各自的*http.Server，不能共用，否则共用 server 的 Close 会把底层 root listener 一并关闭。

3.3 开启 HTTPS 网络伺服

配置项定义在 kernel/conf/system.go：

NetworkServe bool `json:"networkServe"` // 是否开启网络伺服 NetworkServeTLS bool `json:"networkServeTLS"` // 是否开启 HTTPS 网络伺服

对应的 API 入口为POST /api/system/setNetworkServeTLS（路由注册见 kernel/api/router.go，处理函数见 kernel/api/system.go），它会校验管理员权限并写回配置。内核启动时，kernel/server/serve.go 依据NetworkServeTLS && NetworkServe决定是否在固定端口代理（fixed port proxy）上启用 TLS。

使用方式：在"设置 → 关于 → 网络伺服"中开启网络伺服后，勾选"使用 HTTPS"，局域网内的其他设备即可通过https://<主机IP>:<端口>访问；同一端口仍可回退 HTTP，兼容旧客户端。

说明：思源本地生成的 TLS 证书为自签名证书，浏览器首次访问时需手动信任；这是自托管场景的常见预期行为。

四、编辑器与桌面端体验改进

4.1 改进 Ctrl+Shift+T 打开最近关闭文件

此前"最近关闭文件"功能存在丢失或顺序错乱的问题（issue #16879），本版改进其维护逻辑。相关代码分布在 app/src/layout/ 的页签（tab）管理模块中，桌面端快捷键通过编辑器快捷键映射触发。

4.2 清单项末尾 Delete 的编辑结果

在列表项末尾按 Delete 时，光标行为与内容合并的结果被修正（issue #16895）：此前可能产生多余空行或错误合并，本版保证与思源块级编辑模型一致——Delete 在块末尾会正确合并到相邻块，kernel/model/listitem.go 定义了列表项的块级处理逻辑。

4.3 提示块内编辑公式块的体验

在提示块（如闪卡、引用内容预览）中直接编辑公式块时（issue #16917），此前会出现工具栏遮挡或焦点错乱，本版修正了提示块内公式编辑的弹层与焦点行为，相关逻辑位于 app/src/protyle/ 的公式渲染与编辑组件中。

4.4 保存查询条件包含"搜索方式"

全局搜索的"保存查询条件"现在会同时保存"搜索方式"（如按块、按文件等，issue #16927），kernel/search/find.go 定义了搜索方式的枚举与解析，前端保存/恢复时不再丢失方式维度。

4.5 看板视图默认创建分组选择字段

创建看板（Kanban）视图时，若数据库没有现成可分组字段，会自动创建一个用于分组的"选择"类型字段（issue #16940），避免新用户在看板视图中无字段可分组。看板渲染实现见 kernel/av/layout_kanban.go。

4.6 输入法兼容性

通过 PR #16937 改进输入法（IME）兼容性，涉及编辑器组合输入（composition）期间的光标与撤销栈处理。思源编辑器对 IME 的底层支持位于 app/src/editor/ 的键盘事件处理中，本版修正了若干语言输入法下组合态异常的问题。

五、移动端改进（Android / 鸿蒙 / iOS）

本版移动端改动密度很高，共涉及 7 项：

1. 浏览器输入工具栏（issue #12789）：移动端浏览器中访问思源 Web 界面时，提供可用的输入工具栏，弥补移动浏览器无实体键盘场景下的编辑不便。
2. 侧边栏面板滑出检测（issue #13915）：改进手势滑出侧边栏的触发判定，减少误触与失效。
3. 导出相关设置（issue #14757）：移动端现在可访问导出设置（如导出包含子文档、包含关联文件等选项，相关设置项于 v3.5.4 引入）。
4. 批量粘贴图片到数据库（issue #15128）：在数据库资源字段中批量粘贴图片时，按顺序/分组正确写入，避免串图。
5. 代码块内工具栏缩进按钮（issue #15381）：光标位于移动端代码块内时，工具栏动态显示增加/减少缩进按钮。
6. 块图标消失（issue #16074）：修复移动端块图标（block icon）偶发不显示的问题。
7. iOS 暗色应用图标（issue #16110）：为 iOS 提供适配暗色模式的苹果风格应用图标。
8. Android 与鸿蒙软键盘工具栏弹出（issue #16548）：改进软键盘弹出时工具栏的避让与弹出时机，防止遮挡输入区域。
9. Android 与鸿蒙标题块复制（issue #16946）：修正标题块复制时内容缺失的问题。
10. 兼容 HarmonyOS 6.1（issue #16974）：内核与外壳针对鸿蒙 6.1 的运行环境适配，相关构建入口见 kernel/harmony/kernel.go。

移动端核心逻辑集中在 app/src/mobile/（共 22 个 TypeScript 模块），内核侧对应 kernel/mobile/kernel.go。

六、缺陷修复与开发重构

6.1 缺陷修复

• 设置键盘快捷键时发生错误（issue #16877）：修复快捷键设置面板中部分组合键无法保存或误报错误的问题；快捷键配置与校验逻辑见 kernel/model/shortcuts.go。
• 提示块中编辑列表块后插入位置不正确（issue #16916）：修复在提示块内编辑列表块后，后续内容插入位置偏移的问题。
• 改进 AI 继续写入数据库块（issue #16944）：AI 生成内容向数据库块继续写入时，按行/按字段正确落位。AI 相关处理位于 kernel/agent/（对话与工具执行）与 kernel/api/ai.go。

6.2 开发重构：升级 Electron v39.5.1

本版将桌面端 Electron 升级至 v39.5.1（issue #16966），主要收益为安全补丁与稳定性修复。Electron 主进程入口见 app/electron/main.js，构建配置见 app/electron-builder.yml 及各平台变体（如 app/electron-builder-linux.yml）。

七、版本间衔接与升级建议

• v3.5.4 → v3.5.5 的连续迭代显示：v3.5.4 引入的"导出设置项、非 SSD 性能提示、Pandoc 参数、资源大小上限提升到 16G"等能力在 v3.5.5 中得到移动端承接（如移动端导出设置）与存储层深化（mmap 写入）。
• 升级前建议：对包含大量未引用资源/数据库的工作空间先做一次数据快照；升级后可在"设置 → 资源"中体验未引用数据库清理。
• 若使用网络伺服，升级后可在设置中按需开启 HTTPS；自签名证书需在客户端手动信任。

结语

思源笔记 v3.5.5 用 26 项变更再次验证了其"细节打磨"的迭代节奏：mmap 写入、树数据缓存与索引改进共同压低磁盘 I/O；HTTPS 网络伺服让自托管访问更安全；移动端十余处体验修正覆盖 Android、鸿蒙与 iOS。本文所引用的所有实现均可直接在仓库中验证——从 kernel/util/mmap.go 的内存映射写路径，到 kernel/util/cmux.go 的 HTTP/HTTPS 复用，再到 kernel/conf/system.go 的配置模型，构成了理解这一版本的技术全景图。

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