跳到主要內容

SyncFolderPushCommand

SyncFolderPushCommand 是一個高階指令，旨在高效地將本地目錄與您 DID Space 中的遠端目錄同步。它會智慧地比較本地和遠端狀態，上傳新的或修改過的檔案，並可選擇性地刪除本地已不存在的遠端檔案。此指令簡化了常見任務，如部署靜態網站、備份重要資料或分發數位資產。

它處理了並行、重試和一致性檢查等複雜性，提供了一種強大而直接的方式來管理資料夾同步。

使用案例

  • 部署靜態網站：將您的本地建置目錄（例如 ./dist、./build）推送到您 DID Space 中的公共資料夾，以部署或更新網站。
  • 資料備份：定期將包含重要文件或使用者資料的本地資料夾同步到您的 DID Space，以進行安全備份。
  • 資產分發：上傳一個包含您的應用程式需要提供給使用者的圖片、影片或其他資產的資料夾。

輸入參數

SyncFolderPushCommand 在其輸入物件中接受以下參數。

  • source string | SourceObject[] (required) — 指定要同步的本地來源。可以是一個表示本地目錄路徑的字串，或是一個用於更精細控制的物件陣列。
  • target string (required) — 檔案將同步到您 DID Space 中的目標路徑。該路徑應以「/」結尾。
  • metadata ObjectMetadata — 附加到目標資料夾物件的自訂元資料。
  • preview PreviewTemplate — 為目標資料夾設定的預覽範本。更多詳情請參閱 管理資料夾預覽 指南。
  • strictSync boolean (default: false) — 如果為 true，遠端目標中存在但本地來源中不存在的檔案將被刪除。請謹慎使用。
  • filter (object: Object) => boolean — 一個函式，用於過濾應包含在同步中的本地物件。返回 true 以包含物件，返回 false 以排除它。
  • onProgress (progress: OnProgressInput) => void — 一個回呼函式，會定期觸發以報告同步進度。
  • onAfterUpload (result: OnAfterUploadInput) => void — 一個回呼函式，在每個單獨檔案上傳完成後觸發。
  • concurrency number (default: 4) — 平行上傳的檔案數量。最大值為 CPU 核心數。
  • retryCount number (default: 3) — 單一檔案上傳失敗時的重試次數。最大值為 10。
  • tmpDir string — 用於處理檔案的暫存目錄路徑。預設為系統生成的暫存目錄。
  • debug boolean (default: false) — 如果為 true，則啟用向控制台輸出的詳細偵錯日誌。

輸出

此指令返回一個 Promise，其解析後的物件如下。

  • statusCode number — 整體操作的 HTTP 狀態碼。200 表示成功。
  • statusMessage string — 提供有關操作結果更多詳細資訊的訊息。
  • data object — 一個包含同步過程結果的物件。
  • size number — 所有成功上傳檔案的總大小，單位為位元組。
  • count number — 嘗試的操作總數（上傳和刪除）。
  • errorCount number — 失敗的操作數量。
  • duration number — 同步所花費的總時間，單位為秒。

範例

此範例示範如何將名為 ./my-blog-dist 的本地資料夾同步到 DID Space 中的 /blog/ 目錄。

同步本地資料夾

typescript
import { SpaceClient, SyncFolderPushCommand } from '@blocklet/did-space-js';
import getWallet from '@blocklet/sdk/lib/wallet';
import path from 'path';
import fs from 'fs-extra';

// 確保範例所需的來源目錄和一些檔案存在
const sourceDir = path.join(__dirname, 'my-blog-dist');
fs.ensureDirSync(sourceDir);
fs.writeFileSync(path.join(sourceDir, 'index.html'), '<h1>Hello World</h1>');
fs.ensureDirSync(path.join(sourceDir, 'assets'));
fs.writeFileSync(path.join(sourceDir, 'assets', 'style.css'), 'body { color: #333; }');

async function syncWebsite() {
  const wallet = getWallet();
  const client = new SpaceClient({
    endpoint: 'https://www.didspaces.com/app/api/space/...',
    wallet,
  });

  const command = new SyncFolderPushCommand({
    source: sourceDir,
    target: '/blog/',
    strictSync: true, // 刪除遠端不存在於來源中的檔案
    onProgress: ({ completed, total }) => {
      const percentage = total > 0 ? ((completed / total) * 100).toFixed(2) : 0;
      console.log(`同步進度：${completed}/${total} 個檔案 (${percentage}%)`);
    },
  });

  const output = await client.send(command);

  if (output.statusCode === 200) {
    console.log('同步成功完成！');
    console.log(`處理的檔案總數：${output.data.count}`);
    console.log(`錯誤：${output.data.errorCount}`);
    console.log(`持續時間：${output.data.duration}s`);
  } else {
    console.error('同步失敗：', output.statusMessage);
  }

  // 清理建立的目錄
  fs.removeSync(sourceDir);
}

syncWebsite();

範例回應（成功）

回應資料

json
{
  "statusCode": 200,
  "data": {
    "size": 48,
    "errorCount": 0,
    "count": 2,
    "duration": 1.25
  }
}

最佳實踐

確保資料一致性

在同步檔案時，特別是從一個可能正在被頻繁寫入的目錄同步時，存在上傳不完整或損壞檔案的風險。為防止這種情況，SyncFolderPushCommand 會先將每個檔案複製到一個暫存目錄，然後再進行上傳。這確保了上傳時使用的是檔案的穩定快照，從而防止 Unexpected end of form 錯誤並確保資料完整性。

安全使用 strictSync

strictSync: true 選項功能強大，可確保遠端目錄與本地來源完全一致。然而，這是一個破壞性操作。遠端伺服器上任何不存在於本地來源目錄中的檔案都將被永久刪除。在啟用此選項之前，請務必再次檢查您的 source 和 target 路徑。

自訂過濾

您可以使用 filter 函式對要同步的檔案進行精細控制。例如，您可以排除點開頭的檔案、日誌檔案或特定目錄。

過濾檔案

typescript
const command = new SyncFolderPushCommand({
  source: './project',
  target: '/my-project/',
  filter: (object) => {
    // 排除所有以點開頭的檔案（例如 .DS_Store, .env）
    if (object.name.startsWith('.')) {
      return false;
    }
    // 排除 node_modules 目錄
    if (object.key.includes('/node_modules/')) {
      return false;
    }
    return true;
  },
});