思源筆記 v2.11.2 版本解析內核穩定性、雲端資料安全與資料庫表格視圖分頁【免费下载链接】siyuanAn open-source, privacy-first, self-hosted knowledge workspace where humans and AI agents work together 开源、隐私优先、自托管的知识工作空间让人与智能体在此协作项目地址: https://gitcode.com/GitHub_Trending/si/siyuan思源筆記SiYuanv2.11.2 是一次以「穩定與安全」為核心的 v2 系列版本更新重點解決插入大資源檔案、OCR 與資料同步過程中的操作掛起問題並修復了一個可能導致雲端資料損壞的同步缺陷。同時本版面向開發者為資料庫表格視圖引入了分頁載入、data-wrap折行控制與新的核心 API/api/setting/refreshVirtualBlockRef。閱讀本文後你將能掌握本次更新的完整變更脈絡、雲端資料重置的應對操作以及表格視圖新機制的底層實現原理。本文基於倉庫中的官方變更記錄 v2.11.2 繁體中文變更記錄 與 英文變更記錄 整理並結合當前倉庫kernel 與 app 目錄中的實現代碼進行交叉驗證。版本總覽一次以可靠性為主題的迭代官方變更記錄的開篇概述直接點明了本次更新的兩個核心目標解決部分操作的掛起Hanging問題涉及插入大資源檔案、執行 OCR、資料同步三個場景官方將其歸因為需要「提升核心程式內核的穩定性」。修復一個雲端資料損壞缺陷該問題發生在使用者「重置了本地資料倉儲但未重置雲端目錄」後繼續進行資料同步的情境下。從變更清單的分類看本版共涉及四大類變更改進功能Enhancement、移除功能Abolishment、修復缺陷Bugfix、開發者Development其中開發者相關條目佔比最高且高度集中在資料庫屬性視圖 Attribute View的表格視圖上說明 v2 系列末期已將大量精力投向資料庫能力的穩固與接口開放。雲端資料安全重置同步引起的資料損壞與處置建議問題成因變更記錄指出資料損壞的觸發條件是「重置了本地資料倉儲但沒有重置雲端目錄然後進行資料同步」。在思源的同步模型中本地資料倉儲與雲端目錄是一對被嚴格校驗的映射關係若兩者的基線狀態不一致本地已重建、雲端仍是舊資料同步過程就可能基於錯誤的差異推斷覆寫資料最終造成雲端資料損壞。雲端同步的完整狀態機與上傳/下載邏輯可在 kernel/model/sync.go 一探究竟。官方雲端同步自動校驗機制如果你使用的是官方雲端資料同步即訂閱會員的官方雲同步服務本版開始啟動後進行的第一次同步會自動執行雲端資料校驗校驗通過正常繼續同步校驗發現雲端資料損壞介面會彈出提示此時需要重置本地資料倉儲並同時重置雲端目錄二者必須一起執行才能建立一致的同步基線。S3 / WebDAV 自建同步手動重置建議如果你使用的是S3 或 WebDAV 等自建同步目標由於沒有思源官方伺服器參與協調無法自動完成雲端資料校驗。變更記錄明確建議為了保險起見即使沒有看到錯誤提示也應手動重置一次本地資料倉儲和雲端目錄以消除潛在的隱性損壞。操作對照表同步方式是否能自動校驗雲端資料出現損壞時的操作官方雲端同步是啟動後第一次同步自動校驗根據提示同時重置本地資料倉儲與雲端目錄S3 / WebDAV 同步否建議主動手動重置一次本地資料倉儲與雲端目錄以防萬一提示設定入口位於「設定 → 帳號 → 雲端資料同步」重置會清空對應端的資料快照操作前請確認本機已有最新備份。內核穩定性改進掛起問題的來源與化解大資源插入與檔案讀寫鎖插入大資源檔案時出現的掛起與底層檔案讀寫鎖的設計直接相關本版為此專門提出了 改進檔案讀取和寫入鎖issue #9748。思源的資料目錄由內核進程Go 實現持有所有文件操作都通過統一的檔案鎖機制進行內核中大量檔案操作均由filelock系列函數保證執行緒安全例如 kernel/model/template.go 中的filelock.Remove、filelock.Walk。當鎖粒度过粗或持有時間過長時一個大檔案的寫入就會阻塞其他需要同一鎖的操作表現為使用者感知的「卡死」。此版本優化了鎖的行為降低了互相等待造成的掛起概率。OCR 不再阻塞文件載入OCR光學字元辨識是一項典型的耗時任務舊版中若 OCR 與文件載入共用同一執行路徑辨識大圖或 PDF 時會拖住文件載入。本版issue #9230將 OCR 調整為後臺任務不再阻塞文件載入。從當前倉庫的 kernel/model/ocr.go 可以印證其實現方式OCRAssetsJob()通過task.AppendTaskWithTimeout(task.OCRImage, 30*time.Second, autoOCRAssets)將 OCR 圖片處理包裝為帶 30 秒超時的後臺任務隊列執行而不是在請求處理的同步路徑中完成因此即使 OCR 隊列繁忙也不會影響文件的讀取與展示。消除資料競態在 Go 內核中資料競態Data Race是造成偶發性掛起、崩潰或狀態錯亂的常見根源。本版提出「透過消除資料競態以提升內核穩定性」issue #9842。從程式碼結構看思源內核大量使用全域配置物件model.Conf並在多個 goroutine 中並發訪問例如 kernel/api/setting.go 中多個 API 在修改設定後都會呼叫util.BroadcastByType(main, setConf, 0, , model.Conf)向所有前端廣播最新配置這類讀寫交錯正是競態的高發區域配合檔案鎖優化本版針對此類並發訪問做了收斂降低了內核層面的不確定行為。同步過程掛起與雲端資料損壞修復配套同步流程中的掛起問題也一併處理。同步涉及本機資料夾掃描、差異計算與檔案傳輸任一環節的鎖等待或網路阻塞都可能造成同步卡住建議升級本版後同步異常使用者按上文「重置」方案重建基線。編輯器與介面互動改進拖拽滾動與唯讀保護文件樹拖拽滾動issue #9516與編輯器拖拽區塊滾動issue #9813改善了將條目/區塊拖到文件樹或文件頂部、底部邊緣時的自動滾動節奏讓長文檔內的長距離拖拽更順手。唯讀模式禁止拖動區塊issue #9835修復了唯讀文件仍可拖拽區塊造成誤操作的問題與文件層級的唯讀狀態保持一致。圖片載入引起高度變化跳轉定位issue #9856圖片非同步載入會改變文檔高度可能導致滾動位置「跳走」本版對載入過程中的定位進行了校正避免閱讀位置漂移。列表結尾按Delete刪除時游標保持不變issue #9863修正了在列表最後一項結尾刪除時游標跳到前一行/前一區塊的體驗問題。取消釘住圖示與搜尋高亮新增「取消釘住」圖示issue #9819思源支援將頁籤「釘住」以固定常用文件此前釘住後缺少明確的取消入口本版在釘住狀態下提供了可見的取消圖示。對應的多語言鍵值存在於 zh-CN 語言檔pin: 钉住、unpin: 取消钉住。搜尋預覽高亮foo等標籤文字issue #9821全文搜尋預覽中對foo這類含尖括號的文字進行了正確高亮避免 HTML 標記語法干擾高亮比對。貼上與快捷鍵修復貼上後修改行級元素導致錯位issue #9839貼上內容後立即對行內元素如加粗、代碼進行編輯可能產生游標錯位本版修正了貼上操作的狀態還原邏輯。CtrlD行為異常issue #9841CtrlD對應的刪除/選中語義在不同平台下表現不一致本版統一了其行為。桌面端與行動端修復桌面端與平板端主選單新增「退出應用程式」issue #9840桌面端與平板端可在主選單直接退出程式而不再需要透過系統托盤或視窗關閉按鈕。不再強制使用獨立顯示卡issue #9845屬於移除功能。此前桌面端為了圖形渲染效能會嘗試強制調用獨立 GPU但在雙顯示卡筆電上反而可能造成高功耗或相容問題本版移除該強制行為改由系統根據負載自動選擇顯示卡。行動端軟換行失效issue #9822行動端鍵盤的換行/軟換行鍵ShiftEnter語義失效已修復。反鏈箭頭顯示不正確issue #9833行動端反向連結入口處的箭頭圖示樣式異常已修正。表情面板無法跳轉issue #9837編輯器中開啟表情符號面板後無法正常跳轉/定位已修復。iOS 端雲端收集箱圖片與文字排版異常issue #9844iOS 上從雲端收集箱轉移內容時圖片與文字混排錯位已修正。資源檔案與剪藏相關調整微信小助手傳輸上限提升至 20MB微信小助手是思源官方提供的微信傳送助手透過它可將微信中的內容直接轉存到思源。本版issue #9816將其單次檔案傳輸大小上限由原本的較小值提升至 20MB方便傳送更大的圖片或文件。網路資源轉本地與雲端收集箱策略調整支援將網路資源檔案轉換為本地issue #9826對於插入的遠端圖片等網路資源提供了轉為本地資源的能力避免外鏈失效。資源檔案的本地化管理與資產查詢邏輯可參考 kernel/api/asset.go。雲端收集箱移動到文件時不再自動轉換網路資源到本機issue #9827移除功能這是與上一項配套的策略調整——為了避免雲端收集箱大量資源被意外下載到本機造成儲存膨脹移動收集箱內容到文件時不再自動下載轉換使用者可視需要手動轉換。其他資源改進旋轉的 PDF 檔案註解issue #9831修復了對已旋轉方向的 PDF 頁面新增文件註解File Annotation時定位偏移的問題該功能與 kernel/model/pdf.go 所維護的 PDF 頁面錨點體系相關。網頁剪藏程式碼塊內容轉換issue #9865改進網頁剪藏Web Clipper時對pre/程式碼塊內容的 Markdown 轉換減少縮排與空白字元被破壞的情況。開發者向資料庫表格視圖的體系化升級本版「開發者」類別集中展示了資料庫屬性視圖 Attribute View表格視圖的接口與渲染能力升級這些能力對外掛與主題開發者尤其重要。表格視圖支援分頁載入在大資料量表格中一次性渲染所有資料列會造成明顯的效能與記憶體壓力本版issue #9424為表格視圖引入了**分頁載入Paged Loading**機制僅載入當前頁所需的資料列。從內核程式碼可以確認分頁機制的資料模型基礎在 kernel/av/av.go 中視圖結構體定義了PageSize int欄位json:pageSize即每頁條目數並以常數ViewDefaultPageSize 50作為預設每頁 50 條的分頁大小在視圖初始化NewView等構造流程與舊資料修復流程kernel/av/av_fix.go中都會檢查並兜底ViewDefaultPageSize確保分頁參數始終合法。前端在表格視圖操作列時會按此參數分批拉取與渲染從而在保持「即點即得」的同時控制 DOM 規模。使用data-wrap控制表格單元格折行本版透過 PR #9814 引入了標準化方案使用 HTML 屬性data-wrap來控制資料庫表格視圖單元格是否折行。這對主題開發者尤為重要因為它提供了一個穩定的 CSS 掛載點data-wraptrue允許單元格內容折行顯示data-wrapfalse單元格內容不折行預設值超長內容以省略或橫向滾動方式呈現。在渲染層前端在生成儲存格與列頭時會將該屬性寫入 DOM例如 col.ts 中列頭儲存格的模板帶有data-wrapfalse預設值row.ts 在渲染表格/看板等佈局時會以欄位的wrap配置動態輸出data-wrap${column.wrap}在樣式層app/src/assets/scss/business/_av.scss 中對[data-wraptrue]與[data-wrapfalse]分別定義了折行與不折行的規則。也就是說主題作者可以直接基於data-wrap屬性撰寫更精確的表格儲存格樣式而無需依賴脆弱的結構選擇器。表格視圖交互與介面細節選擇列過濾器改進issue #9820表格視圖的「選擇Select」型別列過濾器體驗最佳化。區分綁定與未綁定列issue #9849表格視圖 UI 開始明確區分「綁定列對應具體文件/區塊」與「未綁定列」降低使用者對資料來源的誤解。撤銷編輯後不再滾動到頂部issue #9862修復表格視圖中撤銷Undo操作會把捲動位置強行拉回頂部的問題保持編輯上下文。編輯表格視圖儲存格時可觸發全域快捷鍵issue #9848見英文變更記錄此前焦點進入儲存格編輯後全域快捷鍵失效本版放開限制讓快捷鍵在儲存格編輯場景下也能正常觸發。新增日期相關模板函數思源的模板引擎同時支援 Gotext/template語法模板文件經由 kernel/model/template.go 的RenderGoTemplate()解析執行——該函數先取得filesys.BuiltInTemplateFuncs()內建函數集再合併 SQL 模板函數後注入模板上下文。本版PR #9815在這一函數集中新增了一個與日期相關的模板函數擴充模板中生成日期/星期資訊的能力。從 kernel/filesys/template.go 可以看到內建函數集的組織方式以sprig.TxtFuncMap()為基底出於安全原因移除env、expandenv、getHostByName等危險函數再疊加思源自有的Weekday、WeekdayCN、ISOWeek、ISOYear、parseTime、now等日期時間工具模板作者可以像使用普通函數一樣在模板中組合出「當前 ISO 週」「本週中文名」等輸出用於日誌、彙總或自訂報告類模板。新增內部核心 API/api/setting/refreshVirtualBlockRef開發者向的另一項重點是新增內部核心 API/api/setting/refreshVirtualBlockRefissue #9829。其作用是即時重新整理「虛擬引用Virtual Block Reference」快取讓搜尋關鍵字相關的虛擬引用立即生效而不必等待後臺定時重建。從路由與實現看路由註冊於 kernel/api/router.go以POST方法掛載並套用model.CheckAuth、model.CheckAdminRole、model.CheckReadonly三層中間件即需要登入、管理員角色且非唯讀狀態才能呼叫。實際處理函式位於 kernel/api/setting.go 的refreshVirtualBlockRef先呼叫model.ResetVirtualBlockRefCache()清空並重建快取再BroadcastByType(main, setConf, ...)將更新後的配置廣播給所有前端視窗保證各端設定同步。底層快取實現位於 kernel/model/virutalref.go常規的虛擬引用快取使用帶 TTL10 分鐘的記憶體快取virtualBlockRefCache.SetWithTTL(key, ret, 1, 10*time.Minute)而ResetVirtualBlockRefCache()會先Clear()全部快取再根據「搜尋設定中的虛擬引用名稱/別名/錨文字/文件文字」開關透過sql.QueryVirtualRefKeywords(...)重新查詢關鍵字並寫回virtualBlockRefCache。該 API 被標註為「內部核心 API」意味著它主要面向需要與核心深度整合的官方或高階擴展場景一般使用者與主題開發者無需直接呼叫——在思源中修改虛擬引用相關設定時核心也會在 kernel/api/setting.go 的設定變更分支中同步觸發ResetVirtualBlockRefCache()。總結思源筆記 v2.11.2 雖然是 v2 系列的一個小版本但其價值集中在三層資料安全層修復了「重置本地但未重置雲端目錄」導致的雲端資料損壞並給出官方雲與 S3/WebDAV 兩套處置路徑穩定性層透過優化檔案讀寫鎖、將 OCR 移入帶超時的後臺任務隊列、消除資料競態化解了大資源插入、OCR、同步場景的掛起能力層則為資料庫表格視圖補齊了分頁載入與data-wrap折行契約並新增日期模板函數與/api/setting/refreshVirtualBlockRef內部 API為後續 v3 系列資料庫能力的大規模演進埋下伏筆。對一般使用者建議重點執行變更記錄中關於同步重置的兩條提示對主題與外掛開發者則可以優先研究data-wrap屬性、表格分頁參數kernel/av/av.go 中ViewDefaultPageSize 50以及虛擬引用快取重建kernel/model/virutalref.go這三處接口化改動它們至今仍是思源資料庫體系的重要組成部分。【免费下载链接】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），仅供参考