对于静态网站托管、数据备份或协作资产管理等应用而言，保持本地目录与 DID Space 中的远程目录同步是一项常见需求。DID Space 客户端 SDK 通过两个强大的高级命令简化了这一过程：SyncFolderPushCommand 和 SyncFolderPullCommand。
本指南将通过实际示例，引导您了解如何使用这些命令。有关所有可用参数和选项的详细说明，请参阅 SyncFolderPushCommand 和 SyncFolderPullCommand API 参考文档。
同步原理
同步过程的核心是智能地确定需要传输哪些文件。执行同步命令时，它会在源目录和目标目录之间进行比较。如果满足以下任一条件，文件将被标记为需要同步：
- 文件存在于源目录但不存在于目标目录。
- 文件同时存在于源目录和目标目录，但大小不同。
- 文件同时存在于源目录和目标目录且大小相同，但源文件的修改时间更新。
默认情况下，同步命令只会添加或更新文件。您可以启用 strictSync 模式，以删除目标目录中源目录不存在的文件，从而确保完全镜像。
将本地文件夹推送到 DID Space
当您希望将本地目录的内容上传或更新到 DID Space 中的远程目录时，请使用 SyncFolderPushCommand。这非常适合部署静态网站或备份本地文件。
步骤 1：初始化客户端和命令
首先，设置您的 SpaceClient 并导入 SyncFolderPushCommand。
Initialize Client
import { SpaceClient, SyncFolderPushCommand } from '@blocklet/did-space-js';
import getWallet from '@blocklet/sdk/lib/wallet';
// 初始化钱包和客户端
const wallet = getWallet();
const client = new SpaceClient({
endpoint: 'https://www.didspaces.com/app/api/space/...', // 使用您的 Space 端点
wallet,
});步骤 2：定义命令输入
要推送文件夹，您需要指定本地 source 路径和远程 target 路径。
- source
string(required) — 要上传的本地目录路径。建议路径以“/”结尾。 - target
string(required) — 您 DID Space 中的目标路径。此路径也应以“/”结尾。 - strictSync
boolean(default:false) — 如果为 true，远程存在但本地源中不存在的文件将被删除。 - onProgress
function— 一个可选的回调函数，用于监控上传进度。
步骤 3：执行推送命令
现在，使用您的输入创建一个命令实例，并通过客户端发送它。
Push a Folder
async function pushMyWebsite() {
const command = new SyncFolderPushCommand({
source: './build/', // 您的本地构建文件夹路径
target: '/public/my-website/', // DID Space 中的目标位置
strictSync: true, // 精确镜像本地文件夹
onProgress: ({ completed, total }) => {
const percentage = total > 0 ? (completed / total) * 100 : 0;
console.log(`Upload progress: ${percentage.toFixed(2)}%`);
},
});
const output = await client.send(command);
if (output.statusCode === 200) {
console.log('Push successful!');
console.log(`Total files synced: ${output.data.count}`);
console.log(`Total size: ${output.data.size} bytes`);
console.log(`Duration: ${output.data.duration} seconds`);
} else {
console.error('Push failed:', output.statusMessage);
}
}
pushMyWebsite();此示例将本地 ./build/ 目录的内容上传到您 Space 中的 /public/my-website/。由于 strictSync 为 true，远程目录中任何不在 ./build/ 内的文件都将被删除。
从 DID Space 拉取远程文件夹
使用 SyncFolderPullCommand 将 DID Space 中远程目录的内容下载到您的本地文件系统。这对于恢复备份或检索共享项目非常有用。
步骤 1：定义命令输入
拉取操作的输入与推送类似，但 source 和 target 的角色相反。
- source
string(required) — 您 DID Space 中要下载的远程目录的路径。 - target
string(required) — 文件将被保存到的本地目标路径。 - strictSync
boolean(default:false) — 如果为 true，该命令将识别出远程不存在的本地文件。但为安全起见，拉取命令目前不会执行删除操作。
步骤 2：执行拉取命令
创建 SyncFolderPullCommand 实例并发送它。
Pull a Folder
import { SpaceClient, SyncFolderPullCommand } from '@blocklet/did-space-js';
import getWallet from '@blocklet/sdk/lib/wallet';
const wallet = getWallet();
const client = new SpaceClient({
endpoint: 'https://www.didspaces.com/app/api/space/...',
wallet,
});
async function pullMyBackup() {
const command = new SyncFolderPullCommand({
source: '/backups/latest/', // 您 DID Space 中的路径
target: './restored-backup/', // 本地目标文件夹
onProgress: ({ completed, total }) => {
const percentage = total > 0 ? (completed / total) * 100 : 0;
console.log(`Download progress: ${percentage.toFixed(2)}%`);
},
});
const output = await client.send(command);
if (output.statusCode === 200) {
console.log('Pull successful!');
console.log(`Total files synced: ${output.data.count}`);
console.log(`Total size: ${output.data.size} bytes`);
} else {
console.error('Pull failed:', output.statusMessage);
}
}
pullMyBackup();此脚本将您 Space 中 /backups/latest/ 的文件下载到本地的 ./restored-backup/ 目录。请注意，即使启用了 strictSync，此命令也不会删除您本地目录中可能存在的任何额外文件。
最佳实践
- 文件完整性： 在
push操作期间，文件会先被复制到临时目录再进行上传。这确保了即使文件在同步过程中被本地修改，上传的也是一个一致的版本，从而防止数据损坏。 - 性能： 您可以调整任一命令中的
concurrency参数，以控制同时传输的文件数量。默认值为4。在快速网络上增加此值可以提高速度，而在慢速连接上减少此值可以减轻负载。 - 筛选： 两个命令都在其输入中接受一个
filter函数。您可以使用它根据文件的属性（如名称或路径），在同步过程中选择性地包含或排除文件。
后续步骤
现在您已经对如何在本地计算机和 DID Space 之间同步文件夹有了扎实的理解。为了进一步增强您的应用程序，您可能希望探索如何管理文件夹的外观。