dsh-cloud-sync

---

它解决了什么问题？

DSH Cloud Sync 的重点不是绑定某一种存储服务，而是让插件环境可以随时随地同步：在办公室、家里或新电脑上，都能用自己顺手的云服务保存配置和插件信息，再快速恢复出一致的 DSH 环境。

它把这件事变成一个清晰的流程：选择任意支持的云服务，上传可重建的配置和源码归档，把依赖安装交给 DSH / pnpm，在目标设备上恢复出一致的插件环境。

• 不复制会话、附件、node_modules、pnpm 缓存或明文凭据。
• 不绑定某一种云服务：WebDAV、Amazon S3、阿里云 OSS、腾讯云 COS、MinIO、七牛云 Kodo 和 GitHub Gist 都可以使用。
• 不把更新放在私有 WebDAV：插件本身通过公开 GitHub Releases 检查和安装更新。

实际效果

设置页提供三个清晰的工作区：云服务、配置与历史、同步状态。下面是当前版本的实际界面：

核心能力

能力	你得到的结果
多云同步渠道	WebDAV、Amazon S3、阿里云 OSS、腾讯云 COS、MinIO、七牛云 Kodo、GitHub Gist；同一时间只启用一个渠道，切换服务不需要改代码
GitHub 授权连接	复制设备授权码并打开 GitHub 确认，无需手动创建 Gist；也可绑定已有的空 Gist
轻量可重建快照	同步 package.json、lockfile、workspace、patch 和市场热更新 YAML，而不是打包整个运行环境
本地源码归档	自动发现可达的 file: / link: 插件源码，归档后换盘符、换电脑也能恢复
三种同步策略	智能合并、云端优先、本地优先；两端同时修改同一项时先展示差异再执行
历史与恢复	每次成功同步留下快照，支持预览、恢复远端版本和回滚到指定历史版本；历史备份数量上限可配置（默认 30），超出自动删除最旧备份
插件安装状态	对比远端快照与本机 Web Profile，直接安装或卸载缺失插件
GitHub 自更新	从 GitHub Releases 检查更新，下载 .tgz 后校验 SHA-256，再由用户确认安装
兼容加密和自动同步	保留已有 AES-256-GCM、设备名和定时同步配置；界面只保留更容易理解的核心操作

工作方式

下面这张图展示了双向同步的完整链路：两台设备围绕云端快照仓库同步，保留历史、支持回滚，并可按智能合并、云端优先或本地优先执行。

目标设备只需要相同的同步渠道和 DSH profile。恢复会先备份当前 profile，再写入快照；依赖安装等到完全重启 DSH 后执行，避免覆盖正在运行的 bundle。

快速开始

按推荐顺序，任选一种方式安装；无论哪种方式，安装完成后都需要完全退出并重启 DSH Web，然后在 设置 → 云同步 中开始配置。

方式一：让 AI 助手帮你安装（最省事）

把下面这段话发给 DSH 或 Codex，让它执行安装并重启 DSH Web：

请帮我安装 DSH Cloud Sync 插件（npm 包 @dickpy/dsh-cloud-sync），然后重启 DSH Web。

方式二：通过 npm 安装（推荐）

dsh plugin --profile web add @dickpy/dsh-cloud-sync

方式三：通过聚合包（.tgz）安装

从 GitHub Releases 下载最新的 dickpy-dsh-cloud-sync-*.tgz，然后执行：

dsh plugin --profile web add .\dickpy-dsh-cloud-sync-0.20.6.tgz

适合无法直接访问 npm registry 的内网或离线环境。

方式四：自己开发启动

git clone https://github.com/dickpy/dsh-cloud-sync.git
cd dsh-cloud-sync
npm install
npm run check
dsh plugin --profile web add .

适合需要修改插件源码、调试或贡献代码的场景。

第一次同步

1. 打开 云服务，选择 WebDAV、S3、OSS、COS、MinIO、七牛云 Kodo 或 GitHub Gist。Gist 可通过授权码连接，授权完成后会自动创建 secret Gist。
2. 进入 配置与历史，选择同步策略并点击 开始同步。
3. 需要手动补充本地插件源码时，在同一页填写源码目录并点击 备份源码。
4. 换到新设备后，在 同步状态 查看插件安装情况；可先预览远端快照，再应用恢复。

同一时间只有一个同步渠道处于启用状态。连接并启用新的渠道时，旧渠道会自动停用。

每种云服务会分别保存自己的 Endpoint、Region、Bucket、对象前缀和 Access Key ID。切换回已保存的渠道时，表单会自动填充这些信息；如果该渠道的密钥已保存在本机，密钥框留空即可直接复用，不需要再次输入。

GitHub Gist

GitHub Gist 很适合不涉及本地插件源码归档的配置同步：profile 配置、插件依赖、锁文件、市场 YAML、历史快照都很轻量，使用一个 secret Gist 即可完成多设备恢复。

• 在设置中选择 GitHub Gist，复制显示的授权码并在打开的 GitHub 页面确认授权；插件会自动创建一个受管 secret Gist。
• Gist API 的单个同步对象限制为约 700 KiB，受管 Gist 最多 200 个文件。超过限制时同步会明确失败，不会截断数据。
• 连接 Gist 后会自动切换为“仅配置同步”，本地插件源码不会上传。需要同步源码时请使用 WebDAV、S3、OSS、COS、MinIO 或七牛云 Kodo。
• secret Gist 并不等同于端到端私密存储，持有链接的人可读取内容；建议启用本插件的客户端 AES-256-GCM 加密。

GitHub 授权码连接会使用本项目的 OAuth App，只请求 gist 权限；当授权服务暂不可用时，界面会自动提供拥有 gist 权限的 GitHub Token 作为备用连接方式。

WebDAV 目标目录不存在时，保存连接或首次同步会自动创建该目录；嵌套目录以及包含空格或非 ASCII 字符的目录也无需手动预先创建。

支持的同步渠道

渠道	适合场景	配置要点
WebDAV	坚果云、Nextcloud、NAS 等	填写 DAV 地址、用户名和应用密码
Amazon S3	AWS 或兼容 S3 的对象存储	Endpoint、Region、Bucket、Access Key
阿里云 OSS	阿里云对象存储	使用 OSS 的 S3 兼容 Endpoint
腾讯云 COS	腾讯云对象存储	Bucket 通常包含 APPID，填写对应 Region
MinIO	自建对象存储、内网或本地开发	填写 MinIO Endpoint、Bucket 和密钥
七牛云 Kodo	七牛云对象存储（新用户有免费额度）	Bucket 填写控制台中的 S3 空间名（全局唯一），Region 用七牛云 S3 Region ID（如 cn-east-1）

公共网络上的存储服务建议使用 HTTPS。MinIO 在本机或可信内网中可以使用 HTTP。

同步策略

策略	行为
智能合并（默认）	合并两端的插件依赖、Bundle 和源码归档；发现同一项目被两端修改时，先让你确认
云端优先	使用远端快照覆盖当前 profile，适合新设备恢复
本地优先	使用当前 profile 覆盖远端快照，适合把本机状态作为最新版本

安全边界

• 快照、历史和源码归档可使用 AES-256-GCM 客户端加密；每个对象使用新的 KDF salt。
• 密码和派生密钥不会写入明文设置文件；Windows 使用当前用户 DPAPI 保护已保存凭据。
• 恢复前自动备份当前 profile，源码归档恢复会做 SHA-256 校验并拒绝路径穿越。
• 加密保护的是远端内容，不替代对象存储本身的权限控制；请为 Bucket、Endpoint 以及 MinIO / Kodo 管理员账号配置最小权限。

GitHub 自更新

打开云同步设置页时，插件会直接检查 GitHub Releases，不依赖任何 WebDAV 或对象存储配置。发现新版本后：

1. 用户点击 更新；
2. 插件下载对应的 .tgz 到本机 release 缓存；
3. 使用 GitHub 提供的 SHA-256 资产摘要校验；
4. 用户确认后安装到 web profile，重启 DSH 完成切换。

更新始终是显式操作，不会在同步时静默替换正在运行的 Cloud Sync。

开发与测试

环境要求：Node.js 18 或更高版本、pnpm。

npm install
npm run check
npm test
npm pack

项目结构：

lib/index.js       bundle 入口和本地 API 路由
lib/core.js        存储渠道、快照、加密和插件生命周期
lib/client.js      设置页 UI
test/core.test.mjs 核心流程集成测试
docs/screenshots/  README 界面截图

发布

1. 更新 package.json 版本号并添加 CHANGELOG.md 条目；
2. 执行 npm run check 和 npm test；
3. 执行 npm pack 生成 .tgz；
4. 创建同版本的 GitHub Release 并上传 .tgz；
5. 其他设备会在设置页检测到更新，并由用户显式安装。

常见问题

没有 WebDAV，也能检查插件更新吗？

可以。插件更新来自 GitHub Releases，与同步渠道完全独立；WebDAV、S3、OSS、COS、MinIO 和七牛云 Kodo 只负责你的配置快照和源码归档。

会不会复制整个 node_modules？

不会。同步的是可重建的 profile 文件和必要的本地插件源码，依赖由目标设备上的 DSH / pnpm 重新安装。

为什么恢复后要重启 DSH？

恢复会修改 profile 配置。重启可以让 pnpm 和 DSH 从新的 profile 重新建立依赖，避免在运行中的 bundle 上热替换。

如何排除不想同步的文件？

在 DSH 同步目录创建 .dshsyncignore，每行填写一个要排除的文件或目录名。

许可证

MIT © 2025 dickpy