Remotely Save 多云同步全流程解析：从环境搭建到社区发布

1 背景介绍：Obsidian 同步方案的技术选型

Obsidian 作为知识管理工具的核心价值在于本地文件优先的存储理念，但跨设备同步需求始终存在。Remotely Save 插件通过抽象化云服务接口，实现了 10+ 种存储服务的统一适配，其核心优势在于：

• 多云架构：同时支持对象存储（S3 兼容）、WebDAV 协议和专有云 API
• 增量同步：基于文件哈希比对的差异同步算法
• 端到端加密：支持 OpenSSL 和 RClone 双重加密方案

该插件采用 TypeScript 开发，通过模块化设计实现不同云服务的解耦，核心代码组织在 src/fs* 系列文件中，如 fsS3.ts、fsWebdav.ts 等，分别对应不同存储类型的实现。

[!NOTE] 项目采用 MIT 许可协议，源码可通过以下命令获取：

git clone https://gitcode.com/gh_mirrors/re/remotely-save
cd remotely-save

2 核心功能：插件架构与技术实现

2.1 构建系统：双引擎编译策略

项目提供 Webpack 和 esbuild 两种构建方案，满足不同开发场景需求：

构建工具	命令	适用场景	构建时间	产物优化
Webpack	npm run build	生产环境	30-60秒	代码分割、tree-shaking
esbuild	npm run build2	开发环境	2-5秒	快速热更新

Webpack 配置示例（关键部分）：

// webpack.config.js 核心配置
module.exports = {
  entry: './src/main.ts',
  output: {
    filename: 'main.js',
    path: path.resolve(__dirname, 'dist')
  },
  module: {
    rules: [
      {
        test: /\.ts$/,
        use: 'ts-loader',
        exclude: /node_modules/
      }
    ]
  },
  resolve: {
    extensions: ['.ts', '.js']
  }
}

2.2 云服务适配：抽象工厂模式实现

插件采用抽象工厂模式设计文件系统接口，通过 fsGetter.ts 统一管理不同云服务的实例化：

// src/fsGetter.ts 核心逻辑
export function getFileSystem(type: string, config: any): IFileSystem {
  switch(type) {
    case 's3':
      return new S3FileSystem(config);
    case 'webdav':
      return new WebDAVFileSystem(config);
    case 'dropbox':
      return new DropboxFileSystem(config);
    // 其他云服务类型...
    default:
      throw new Error(`Unsupported filesystem type: ${type}`);
  }
}

这种设计使新增云服务支持只需实现 IFileSystem 接口并注册到工厂，符合开闭原则。

2.3 加密模块：双重方案保障数据安全

插件实现两种加密方案，可在设置中切换：

1. OpenSSL 加密：使用 aes-256-cbc 算法，适合小文件快速加密

   // src/encryptOpenSSL.ts 核心方法
   export async function encryptData(data: Uint8Array, password: string): Promise<Uint8Array> {
     const key = await deriveKey(password);
     const iv = crypto.getRandomValues(new Uint8Array(16));
     const cipher = crypto.createCipheriv('aes-256-cbc', key, iv);
     // 加密逻辑实现...
   }
   

2. RClone 加密：支持更复杂的加密策略，通过 Web Worker 避免主线程阻塞

   // src/encryptRClone.worker.ts
   self.onmessage = async (e) => {
     const { action, data, password } = e.data;
     if (action === 'encrypt') {
       const result = await rcloneEncrypt(data, password);
       self.postMessage(result);
     }
   };
   

3 实施步骤：从源码到社区发布

3.1 开发环境配置

前置依赖：

• Node.js 16+
• npm 7+
• TypeScript 4.5+

环境变量配置： 创建 .env 文件存储敏感信息：

# 云服务API密钥配置
DROPBOX_APP_KEY=your_secure_key
ONEDRIVE_CLIENT_ID=your_client_identifier
GOOGLEDRIVE_CLIENT_SECRET=your_secret_value

执行依赖安装：

npm install
# 预期结果：node_modules目录生成，依赖包安装完成

3.2 构建与测试流程

生产构建：

npm run build
# 预期结果：dist目录生成main.js、manifest.json和styles.css

测试执行：

npm test
# 预期结果：所有测试用例通过，显示测试覆盖率报告

关键测试文件说明：

• tests/configPersist.test.ts：验证配置持久化机制
• tests/encryptOpenSSL.test.ts：测试加密算法正确性
• tests/metadataOnRemote.test.ts：验证远程元数据管理

3.3 版本管理与发布

版本更新：

npm version minor  # 升级次要版本号
# 预期结果：package.json和manifest.json版本同步更新

Git标签推送：

git tag -a v0.6.0 -m "Add support for S3 compatible storage"
git push origin v0.6.0
# 预期结果：标签推送至远程仓库，触发自动构建流程

社区发布包准备： 需打包三个核心文件：

1. main.js - 压缩后的主程序
2. manifest.json - 插件元数据
3. styles.css - 样式定义

[!NOTE] manifest.json 必须包含以下字段：

{
  "id": "remotely-save",
  "name": "Remotely Save",
  "version": "0.6.0",
  "minAppVersion": "0.15.0",
  "description": "Multi-cloud synchronization for Obsidian",
  "author": "fyears",
  "isDesktopOnly": false
}

4 质量保障：测试与优化策略

4.1 测试覆盖策略

项目采用多层次测试策略：

• 单元测试：覆盖核心工具函数，如 misc.test.ts
• 集成测试：验证模块间协作，如 fsWebdis.test.ts
• 端到端测试：模拟真实用户场景的同步流程

测试覆盖率目标：

• 核心业务逻辑：≥90%
• 工具函数：≥85%
• 界面组件：≥70%

4.2 性能优化实践

关键优化点：

1. 文件分块上传：大文件采用 5MB 分块传输
2. 元数据缓存：本地存储文件哈希值减少重复计算
3. Web Worker：加密操作使用 Worker 避免界面阻塞

性能测试方法：

npm run profile  # 生成性能分析报告
# 预期结果：profiler_exported.png 文件包含性能时间线

5 经验总结：插件开发最佳实践

5.1 架构设计经验

1. 接口抽象：定义清晰的 IFileSystem 接口，确保各云服务实现一致性
2. 配置隔离：敏感信息使用环境变量，避免硬编码
3. 错误处理：统一的错误码体系，便于问题定位

5.2 常见问题速查表

问题现象	可能原因	解决方案
同步卡在"正在验证"	网络超时或API限制	检查网络连接，减少同步文件数量
加密文件无法解密	密码错误或算法不匹配	确认使用相同加密方案和密码
大文件同步失败	存储服务限制	配置分块大小为5MB以下
OAuth认证失败	重定向URL不匹配	检查manifest中的回调配置

5.3 未来发展方向

1. 增量同步算法优化：实现基于内容的差异同步
2. 多账户支持：允许同时配置多个同类型云服务
3. 同步冲突可视化：提供交互式冲突解决界面

通过遵循以上开发流程和最佳实践，Remotely Save 插件持续为 Obsidian 用户提供可靠的多云同步体验，其模块化设计也为后续功能扩展奠定了坚实基础。