数据同步【免费下载链接】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 插件Obsidian 笔记同步插件中的 Koofr PRO 付费功能讲解如何完成 Remotely Save 在线账号订阅、Koofr OAuth2 授权、连接配置与首次同步并从源码角度剖析 Koofr 原生 API而非 WebDAV带来的修改时间保留优势。阅读完本文你将能够独立完成 Koofr 的授权接入、理解其 token 刷新与路径映射机制并规避 beta 阶段的使用风险。Koofr 同步功能概述Koofr 同步是 Remotely Save 插件的PRO付费功能之一。它由 Remotely Save 团队基于 Koofr 公开 API 开发并非 Koofr 官方产品。这一点在官方说明和插件设置界面中均有明确声明见 pro/src/langs/en.json 中settings_koofr_disclaimer1的文案“This app is NOT an official Koofr product. The app just uses Koofrs public api.”。在 Remotely Save 的付费功能体系中Koofr 与 Google Drive、Box、pCloud、Yandex Disk、Azure Blob Storage 等并列均通过各自的原生 API 实现参见 pro/README.md 的功能列表。这意味着仅使用免费基础功能如 WebDAV、S3、Dropbox、OneDrive 等的用户不需要 Koofr 功能也无需在线账号与付费只有需要将仓库同步到 Koofr 网盘时才需要订阅该 PRO 功能。使用前提订阅 Remotely Save PRO 功能由于插件本身无法内嵌支付流程Koofr 功能的使用需要一套“在线账号”机制用户先注册 Remotely Save 在线账号将插件与该账号连接再在网站上订阅 “sync with Koofr” 功能最后回到 Obsidian 内刷新功能状态。第一步注册并连接在线账号打开 Remotely Save 官方网站并注册登录可直接从插件设置页跳转也可访问官方 signupin 页面。在 Obsidian 的 Remotely Save 插件设置页点击 “Connect” 按钮启动连接流程。浏览器中会打开一个特殊授权地址在网站上点击 “allow” 允许。授权流程结束后网站会显示一个 code将其复制回插件弹出的模态框并确认即可完成插件与在线账号的绑定。详细流程可参考 docs/pro/README.md。需要说明的是该在线账号与 Obsidian 账号无关二者互不隶属。第二步在线订阅 Koofr 功能登录 Remotely Save 官网的用户 profile 页面。在功能列表中订阅 “sync with Koofr” 功能价格以网站实际显示为准。回到 Obsidian 的 Remotely Save 插件 PRO 设置区点击 “Check again”重新检查按钮让插件感知到已启用的功能。从源码看这一“感知”机制通过enabledProFeatures数组实现baseTypesPro.ts 中定义了PRO_FEATURE_TYPEKoofr 对应的功能名称为feature-koofrsettingsKoofr.ts 中通过plugin.settings.pro?.enabledProFeatures.filter((x) x.featureName feature-koofr).length 1判断是否允许展示 Koofr 设置区块。未订阅时设置区会显示 “Koofr Settings Not Available” 提示并引导用户跳转到 PRO 设置页#settings-pro。连接你的 Koofr 账号在 Remotely Save 设置中确认 Koofr 功能已启用后即可开始连接 Koofr 账号完整步骤如下在 Remotely Save 设置中将同步服务切换为Koofr (PRO) (beta)。点击Auth授权按钮弹出授权模态框内含授权链接可一键复制到剪贴板。在浏览器中访问该链接进入 Koofr 官网完成授权流程。按照 Koofr 页面提示操作允许 Remotely Save 连接你的账号。授权完成后页面会跳转回 Remotely Save 插件。插件会弹出通知告知你是否连接成功。开始同步插件会在你的 Koofr 根目录自动创建一个与库vault同名的文件夹并将笔记上传到该文件夹内。务必阅读下文的风险提示。授权背后的 OAuth2 流程连接流程本质上是标准的OAuth2 Authorization Code流程其实现集中在 pro/src/fsKoofr.tsgenerateAuthUrl()构造授权地址${apiAddr}/oauth2/auth携带response_typecode、client_id、redirect_uri、scopepublic及随机生成的statenanoid()。其中redirect_uri分为两种有回调能力hasCallbacktrue时使用obsidian://remotely-save-cb-koofr这类 Obsidian 自定义协议协议名定义在 baseTypesPro.ts 的COMMAND_CALLBACK_KOOFR否则回退到 OAuth 2.0 的 out-of-band 方式urn:ietf:wg:oauth:2.0:oob。sendAuthReq()携带code、grant_typeauthorization_code、client_id、client_secret与redirect_uri向${apiAddr}/oauth2/token发起 POST换取access_token、refresh_token与expires_in。sendRefreshTokenReq()在访问令牌过期后使用grant_typerefresh_token刷新令牌。默认的 API 地址为https://app.koofr.net见DEFAULT_KOOFR_CONFIG的api字段Koofr 开发者文档入口位于其官网的/developers路径。令牌的存储与刷新机制授权成功后插件会将凭证写入本地的KoofrConfig定义见 pro/src/baseTypesPro.ts关键字段包括字段含义accessToken短期访问令牌Bearer TokenrefreshToken长期刷新令牌用于自动续期accessTokenExpiresInMs访问令牌有效期毫秒accessTokenExpiresAtTimeMs访问令牌的过期时间点毫秒时间戳credentialsShouldBeDeletedAtTimeMs本地凭证的强制清理时间点remoteBaseDirKoofr 上的远程根目录名apiAPI 基地址默认https://app.koofr.netmountID目标挂载点place的 IDkind固定为koofr在setConfigBySuccessfullAuthInplace()中插件将过期时间点设为Date.now() expires_in * 1000 - 5 * 60 * 1000提前 5 分钟到期避免临界过期并将本地凭证的强制删除时间设为约 59 天后——即无论是否使用本地保存的登录凭证最迟约 59 天会被要求重新授权这是一个安全设计。FakeFsKoofr构造时通过createClientpaths创建 API 客户端并注入getAuthMiddleware()中间件每次请求前检查accessTokenExpiresAtTimeMs是否已过期若过期则自动调用sendRefreshTokenReq()刷新令牌并写回配置见 pro/src/fsKoofr.ts 的getAuthMiddleware实现。连接校验与远程目录设置页提供 “Check connection” 按钮底层调用checkConnect()该方法先尝试_init()失败即判定无法连接_init()的逻辑是校验refreshToken非空未授权则报错 “You have not auth yet!”。若mountID为空调用/api/v2.1/places获取账号的主 place IDisPrimary。检查远程根目录remoteBaseDir默认为当前库名是否存在若不存在则调用/api/v2.1/mounts/{mountId}/files/folder自动创建。这与设置界面文案一致“We will create and sync inside the folder {{remoteBaseDir}} on your Koofr.DO NOT create this folder by yourself manually.” 也就是说远程目录由插件自动创建用户无需也不应手工预建。同步行为与路径映射自动创建的库文件夹同步时插件默认以 Obsidian 库名app.vault.getName()作为 Koofr 根目录下的文件夹名。如果你希望使用自定义目录名可在 Koofr 设置区修改 “Remote base dir” 输入框并确认底层复用ChangeRemoteBaseDirModal见 settingsKoofr.ts。所有同步文件都会放在该文件夹内避免污染 Koofr 根目录。本地路径与 Koofr 路径的转换fsKoofr.ts 中的getKoofrPath()负责把插件内部的相对路径转换为 Koofr API 所需的绝对路径常规文件/a/b.md会转换为/remoteBaseDir/a/b.md根目录特殊处理为/remoteBaseDir。反向的getNormPathFromBasedir()则把 API 返回的/xxx形式的路径还原为插件内部使用的相对路径文件直接去掉前导/目录追加尾部/。核心 API 调用Koofr 类型定义由 OpenAPI 自动生成保存在 pro/src/koofrApi.d.ts共约 9953 行。FakeFsKoofr实现的接口与底层端点对应关系如下插件操作Koofr API 端点全量遍历walk()GET /content/api/v2.1/mounts/{mountId}/files/listrecursive单层遍历walkPartial()GET /api/v2.1/mounts/{mountId}/files/list文件元信息stat()GET /api/v2.1/mounts/{mountId}/files/info上传writeFile()POST /content/api/v2.1/mounts/{mountId}/files/put下载readFile()GET /content/api/v2.1/mounts/{mountId}/files/get删除rm()DELETE /api/v2.1/mounts/{mountId}/files/remove创建目录mkdir()POST /api/v2.1/mounts/{mountId}/files/folder其中listrecursive端点返回的是NDJSON 流Content-Type: application/x-ndjson插件在walk()中将其按行拆分、拼接为 JSON 数组后解析见walk()中的data.trim().split(\n).join(,)处理并对type error的条目抛出异常。writeFile()上传时显式传入modified: mtime参数这正是后文“保留修改时间”能力的关键同时携带overwrite: true、autorename: false与info: true确保覆盖旧文件且返回文件信息。已映射的文件元数据无论遍历还是 stat插件都会把 Koofr 返回的modified、size、hash映射为统一的Entity结构mtimeCli/mtimeSvr/size/hash等字段见fromItemToEntity()与fromFileToEntity()供同步算法比对本地与远程状态。风险提示Caveats截至 2024 年 6 月该功能仍处于beta 阶段。使用前请务必备份你的 Obsidian 库vault以降低 beta 阶段潜在问题带来的数据丢失风险。该应用不是 Koofr 官方产品仅使用其公开 API若在 Koofr 账号中发现非预期的访问请立即在 Koofr 账号的 Security 设置页断开该应用的授权。凭证信息保存在本地理论上存在被其他恶意/故障插件读取的可能详见 en.json 中settings_koofr_disclaimer2的说明。撤销授权设置页提供 “Revoke Auth” 按钮弹出模态框分两步操作先在浏览器打开 Koofr 账号的 Security 设置页删除连接授权再点击 “Clean” 按钮清除插件本地保存的登录凭证底层将配置重置为DEFAULT_KOOFR_CONFIG见 settingsKoofr.ts 的KoofrRevokeAuthModal。为什么不用 WebDAVKoofr 本身支持 WebDAV 接口但 Remotely Save 的 “sync with Koofr” 功能选择使用Koofr 原生 API而非 WebDAV其核心收益是文件的最后修改时间last modified time可以被完整保留。这一点在同步场景中非常关键修改时间通常是同步算法判断文件新旧的重要依据。若通过 WebDAV 上传服务器端时间戳往往会被覆盖为上传时刻导致多端同步时出现无谓的冲突或误判。而使用原生 API 的put上传接口并显式携带modified参数见上文writeFile()可以从源头保证时间语义一致这也是该项目在 README.md 中给出的明确设计理由。从源码结构看pCloud、Yandex Disk 等 PRO 网盘同步同样采用“原生 API 而非 WebDAV”的路线参见 pro/README.md。小结Remotely Save 的 Koofr 同步是一个需要在线订阅的 PRO 功能使用链路为注册连接 Remotely Save 在线账号 → 订阅 “sync with Koofr” → 在 Obsidian 内刷新并授权 Koofr → 自动创建库文件夹并同步。底层实现基于 Koofr OAuth2 授权码流程、自动化的 token 刷新中间件、NDJSON 递归列目录与带modified参数的上传接口从而在 beta 阶段即实现了“保留修改时间”这一优于 WebDAV 路径的核心能力。使用前请务必备份库并留意本地凭证约 59 天的自动过期设计。如需了解更多同步算法与冲突处理机制可继续阅读 docs/sync_algorithm/README.md 与 pro/README.md。赞分享数据同步【免费下载链接】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 连接 BoxPRO 功能完整指南订阅、OAuth 授权与同步原理Remotely Save 连接 BoxPRO 功能完整指南订阅、OAuth 授权与同步原理 导读 本文面向 Obsidian 用户讲解如何为 Remo数据同步Obsidian云同步终极指南免费插件remotely-save实战教程Obsidian云同步终极指南免费插件remotely save实战教程 还在为Obsidian笔记在不同设备间同步而烦恼官方同步服务价格昂贵第三方工具配数据同步上一篇如何使用React95打造怀旧Windows 95风格的现代React应用下一篇浏览器盒子BrowserBox项目教程创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考