Remotely Save 插件调试指南：从同步计划导出到控制台日志的完整排查方案

数据同步【免费下载链接】remotely-saveSync notes between local and cloud with smart conflict: S3 (Amazon S3/Cloudflare R2/Backblaze B2/...), Dropbox, webdav (NextCloud/InfiniCLOUD/Synology/...), OneDrive, Google Drive (GDrive), Box, pCloud, Yandex Disk, Koofr, Azure Blob Storage.项目地址https://gitcode.com/gh_mirrors/re/remotely-save点击查看免费下载理想情况下Remotely Save 插件的同步应当是零维护的配置好远程服务后自动同步会静默完成一切。但一旦出现文件丢失、冲突异常或同步停滞用户就必须深入细节定位根因。本指南围绕仓库docs/how_to_debug/目录下的四篇调试文档按由易到难的四个层级系统讲解如何在 Obsidian 桌面端、iOS 与 Android 移动端上排查 Remotely Save 的同步问题先导出并解读同步计划Sync Plans再通过控制台日志观察插件内部行为最终借助第三方插件拿到移动端的完整日志。读完本文你将掌握一套完整的、可操作的插件侧调试流程并能理解同步计划中每个关键字段的含义。调试手段按难度分为四档对应原文档 docs/how_to_debug/README.md 的整体结构难度场景手段详细文档简单全平台通用导出同步计划Sync Plansdocs/how_to_debug/export_sync_plans.md中等桌面端与 Android直接查看 Obsidian 控制台docs/how_to_debug/check_console_output.md中等移动端iOS / Android使用Obsidian vConsole插件查看控制台docs/how_to_debug/check_vconsole_output.md高级全平台尤其 iOS使用Logstravaganza插件把日志导出到笔记docs/how_to_debug/use_logstravaganza.md第一层简单导出同步计划定位决策是否正确什么是同步计划每次插件启动一次同步时都会先收集所有必要信息为每个文件、每个文件夹生成一个同步计划sync plan它列出针对每个对象的每一项操作并分配对应的实际动作。换言之同步计划是插件在动手之前想清楚要做什么的完整决策记录。因此如果同步出了问题第一步应当检查同步计划——先确认插件打算做什么再判断是决策错了还是执行阶段出了问题。这能从源头上把问题区间缩小一半。导出同步计划的操作步骤首先关闭自动同步。进入插件设置关闭自动同步auto sync避免调试过程中有意外同步任务插队运行干扰观察结果。确保至少手动同步过一次。同步计划只有在同步发生时才会生成并保存。如果此前从未同步过当前 vault请先手动触发一次同步让插件产生至少一份计划如果此前已经同步过插件通常已保存了若干历史同步计划可直接进入下一步。导出到文件。进入插件设置向下滚动到 Debug调试分区找到 Export sync plans导出同步计划选项并点击导出按钮。插件会在 vault 根目录下新建一个_debug_remotely_save/文件夹并在其中生成一份名为sync_plans_hist_exported_on_{时间戳}.md的文件。说明原文档中该文件名写作sync_plans_hist_exported_on_{a_timestamp},md.其中包含笔误。仓库源码 src/baseTypes.ts 明确给出常量定义DEFAULT_DEBUG_FOLDER _debug_remotely_save/、DEFAULT_SYNC_PLANS_HISTORY_FILE_PREFIX sync_plans_hist_exported_on_因此实际生成的文件名为sync_plans_hist_exported_on_{时间戳}.md扩展名是.md。导出按钮的多个选项源码细节在 src/settings.ts 的 Debug 分区实现中Export sync plans 并非只有一个按钮而是提供了五个导出按钮对应不同的导出范围按钮调用参数含义导出最近 1 条仅变更howMany1, onlyChangetrue只导出最近 1 条计划且仅保留有变更的对象导出最近 5 条仅变更howMany5, onlyChangetrue只导出最近 5 条计划仅保留有变更的对象导出最近 1 条全部howMany1, onlyChangefalse导出最近 1 条计划的完整内容导出最近 5 条全部howMany5, onlyChangefalse导出最近 5 条计划的完整内容导出全部howMany0导出历史中全部同步计划这些按钮均调用 src/debugMode.ts 中的exportVaultSyncPlansToFiles函数。该函数从本地数据库读取同步计划历史记录readAllSyncPlanRecordTextsByVault随后拼接成 Markdown 文件写入 vault。其中onlyChangetrue时会通过getSubsetOfSyncPlan过滤掉change false的对象/$meta元数据条目始终保留只输出发生过变更的文件/文件夹便于快速聚焦问题点若历史记录为空文件内容则只有一行提示 No sync plans history found。如何阅读同步计划用任意 Markdown 编辑器打开导出的sync_plans_hist_exported_on_{时间戳}.md里面是一个或多个 JSON 代码块每个 JSON 代表一次同步计划。典型的计划结构如下{ ts: 1646960867560, remoteType: onedrive, mixedStates: { abc.md: { key: abc.md, existRemote: true, mtimeRemote: 1646566632000, sizeRemote: 56797, remoteEncryptedKey: abc.md, changeMtimeUsingMapping: true, existLocal: true, mtimeLocal: 1646566632000, sizeLocal: 56797, decision: skipUploading, decisionBranch: 1 }, New folder/: { key: New folder/, deltimeRemote: 1646925354372, existLocal: false, existRemote: false, decision: keepRemoteDelHistFolder, decisionBranch: 9 } } }顶层字段中ts是该次同步的时间戳Unix 毫秒remoteType是远程服务类型示例中为onedrive实际可能是s3、webdav、dropbox等对应 src/baseTypes.ts 中定义的各种远程类型。排查时通常只需要关心mixedStates属性其中的每一项代表一个文件或一个文件夹键名如abc.md、New folder/就是其在同步体系中的唯一标识key。这与源码 pro/src/sync.ts 中SyncPlanType Recordstring, MixedEntity的类型定义一致——同步计划本质上就是路径 key → 实体状态 MixedEntity的映射表。找到你怀疑出问题的那个文件/文件夹然后重点核对以下属性decision 插件对该文件/文件夹做出的决策。 decisionBranch 同步代码中实际逻辑分支的标记编号用于调试定位走到了哪一条判断路径。 existRemote 该文件/文件夹是否存在于远程服务上。 mtimeRemote 远程服务上的最后修改时间。 deltimeRemote 远程记录中的删除时间。 existLocal 该文件/文件夹是否存在于本地。 mtimeLocal 本地的最后修改时间与创建时间二者中的较大值。 deltimeLocal 本地的删除时间。这些字段与 src/baseTypes.ts 中MixedEntity接口的成员一一对应还包括sizeLocal/sizeRemote本地与远程文件大小、sizeLocalEnc/sizeRemoteEnc加密场景下的大小、remoteEncryptedKey远程加密后的键名、changeRemoteMtimeUsingMapping/changeLocalMtimeUsingMapping是否使用映射机制改写时间戳以及syncDone等。其中mtimeLocal的定义值得注意——它不是单纯的最后修改时间而是修改时间与创建时间的最大值这是 Remotely Save 为兼容不同文件系统时间戳行为而采取的策略。decision 与 decisionBranch决策从何而来decision应当由修改时间与删除时间共同决定逻辑详见 同步算法文档。简而言之插件会收集四个时间戳mtimeRemote、deltimeRemote、mtimeLocal、deltimeLocal以四个时间戳中的最大值对应的那个操作作为最终决策。例如示例中的abc.mdmtimeRemote与mtimeLocal相等均为 1646566632000existRemote与existLocal均为 true于是插件判定两侧内容一致做出skipUploading跳过上传的决策decisionBranch为 1。decisionBranch是一个纯调试用的整数编号指向 pro/src/sync.ts 中具体的判断分支。源码中可见decisionBranch从 1、2、9、26 一直到 101138 等大量取值每一档都对应一套存在性 × 时间戳大小关系的组合。当向开发者报告 bug 时同时提供decision和decisionBranch能极大加速问题定位。常见问题操作系统时间戳异常一些用户反馈其操作系统的最后修改时间或创建时间没有被正确设置。在这种情形下插件无能为力——因为同步计划完全建立在时间戳比较之上时间戳本身不可信一切决策都会失真。建议此时检查操作系统的相关设置或者排查是否有其他程序在偷偷改动文件例如同步盘客户端、备份软件、杀毒软件对文件的触碰等。第二层中等桌面端与 Android 直接查看 Obsidian 控制台如果你在桌面端Windows / Linux / macOS或 Android 上使用 Obsidian可以直接打开 Obsidian 的控制台查看插件日志。步骤 1先关闭自动同步与导出同步计划一样调试前先禁用自动同步避免意外同步任务干扰日志观察。步骤 2把日志级别改为 debug进入插件设置向下滚动到 Debug 分区找到 alter console log level调整控制台日志级别选项将其从默认的info改为debug。这一设置在源码 src/settings.ts 中实现为settings_debuglevel下拉框提供info与debug两个选项选择结果写入this.plugin.settings.currLogLevel并持久化保存。切换为debug后插件会输出更细粒度的调试日志覆盖同步过程中的中间状态与详细决策过程。步骤 3打开控制台并触发同步桌面端Windows / Linux / macOS按下快捷键CtrlShiftIWindows / Linux或CmdShiftImacOS即可打开 Obsidian 的开发者控制台。console.info、console.debug等输出都会显示在这里。Android有两种方式查看控制台借助桌面 Chrome 查看首先在 Android 手机上启用 USB 调试USB debugging需在系统开发者选项中开启然后用 USB 线连接手机与电脑在桌面 Chrome 浏览器中打开特殊页面chrome://inspect该页面内会出现可用的 inspect 链接点击即可打开手机端 Obsidian 的控制台。调试完毕后记得关闭 USB 调试以保障设备安全。直接在手机上查看参考下一节的Obsidian vConsole方案见 docs/how_to_debug/check_vconsole_output.md。控制台就绪后点击侧边栏 Ribbon 上的同步图标手动触发一次同步。控制台中会出现但愿是有用的输出据此可以更直观地判断发生了什么、哪里出了问题。第三层中等移动端使用Obsidian vConsole查看控制台在手机上调试相当困难——既没有桌面端的 DevTools 快捷键网络请求也不易抓取。好在有第三方插件Obsidian vConsole可以帮忙它适用于 iOSiPhone / iPad和 Android 两端。步骤 1先关闭自动同步与前述一致调试前先禁用自动同步。步骤 2把日志级别改为 debug同样进入插件设置 Debug 分区把 alter console log level 从info改为debug。步骤 3安装并启用Obsidian vConsole安装第三方插件Obsidian vConsole可在 Obsidian 社区插件市场搜索安装。启用该插件后Obsidian 移动端界面右下角会出现一个绿色按钮可以拖拽到任意位置。触发同步然后立刻点击这个绿色按钮其面板中会展示控制台日志更妙的是面板里还能查看浏览器网络请求Network和本地存储LocalStorage——当怀疑远程请求失败或配置存储异常时这两项非常有用。每条日志行旁有一个小的磁盘图标点击即可复制该条日志也可以直接截图。将日志或截图提交给 Remotely Save 的 GitHub 仓库来报告 bug。不需要看日志时点击面板中的 Hide 即可隐藏面板。调试结束后如果不再需要可禁用Obsidian vConsole插件绿色按钮随之消失。第四层高级使用Logstravaganza把日志导出到笔记在 iOS 上直接查看控制台日志相当困难此时可以借助第三方插件Logstravaganza作者 Carlo Zottmann——它能把控制台输出重定向写入一篇笔记中让日志落地为可检索、可复制的文本。使用方法非常简单在 Obsidian 社区插件市场安装Logstravaganza。启用它。做点操作触发一些控制台日志例如手动触发一次同步。打开 vault 根目录下的LOGGING-NOTE (设备名).md即可看到被重定向写入的日志内容。由于它不依赖屏幕取词或 DevTools在 iOS 上尤为实用把日志以笔记形式保存后既可以直接在 Obsidian 内阅读、搜索也可以方便地复制出来提交给开发者。该方案的详细说明见 docs/how_to_debug/use_logstravaganza.md。调试路径速查与小结面对一次同步异常推荐的排查顺序是先看同步计划全平台通用成本最低导出sync_plans_hist_exported_on_{时间戳}.md核对问题文件/文件夹的decision、decisionBranch与四个时间戳字段判断是决策阶段还是执行阶段出了问题再看控制台日志桌面端 / Android 直接用 Obsidian 控制台移动端用Obsidian vConsole或Logstravaganza把日志级别调到debug手动触发同步观察插件实际执行的调用链与报错报 bug 时带上证据导出文件、decisionBranch编号、控制台日志或截图一并提交能显著提升开发者定位问题的效率。以上所有调试入口均集中在插件设置的 Debug 分区并在 src/settings.ts 中有完整实现同步计划的生成与导出逻辑分别位于 pro/src/sync.ts 与 src/debugMode.ts。值得再次提醒的是同步决策完全依赖操作系统提供的时间戳若本地文件系统时间戳本身不准确任何调试手段都无法得出正确结论——请先从操作系统层面确认时间戳的可靠性。赞分享数据同步【免费下载链接】remotely-saveSync notes between local and cloud with smart conflict: S3 (Amazon S3/Cloudflare R2/Backblaze B2/...), Dropbox, webdav (NextCloud/InfiniCLOUD/Synology/...), OneDrive, Google Drive (GDrive), Box, pCloud, Yandex Disk, Koofr, Azure Blob Storage.项目地址https://gitcode.com/gh_mirrors/re/remotely-save点击查看免费下载上一篇Neo4j Graph Data Science 项目常见问题解决方案下一篇OpenChamber 1.0.1 首发解析monorepo 架构、GitHub Actions 发布流水线与 OpenCode 聊天体验创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考