對於靜態網站託管、資料備份或協作資產管理等應用程式而言，保持本地目錄與 DID Space 中的遠端目錄同步是一項常見需求。DID Space Client 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 之間同步資料夾有了紮實的瞭解。為了進一步增強您的應用程式，您可能想要探索如何管理資料夾的外觀。