節點與 Blocklet 管理

本節提供與管理 Blocklet Server 節點及其上執行的 Blocklet 的生命週期和組態相關的變更的詳細參考。這些操作允許您以程式化方式安裝、啟動、停止、設定和升級單個 Blocklet 和節點本身。

Blocklet 生命週期

這些變更控制 Blocklet 的基本生命週期，從安裝到移除。

installBlocklet

從商店、URL 或本地檔案等多種來源將新的 Blocklet 安裝到節點上。

參數

input object (required) — installBlocklet 變更的輸入物件。
- type string — 安裝類型。可以是 'store'、'url' 或 'upload'。
- did string — 要安裝的 Blocklet 的 DID（從商店安裝時為必填）。
- storeUrl string — Blocklet 商店的 URL。
- url string — Blocklet 的 meta 檔案或 bundle 的 URL（從 URL 安裝時為必填）。
- file Upload — 要上傳的 Blocklet bundle 檔案。
- diffVersion string — 在升級過程中應用差異比對的版本。
- deleteSet string[] — 在基於差異比對的升級過程中要刪除的檔案清單。
- title string — 新 Blocklet 實例的自訂標題。
- description string — 新 Blocklet 實例的自訂描述。
- startImmediately boolean — 若為 true，Blocklet 將在安裝後自動啟動。
- downloadTokenList DownloadTokenInput[] — 私有元件的下載權杖清單。
  - did string (required) — 需要權杖的元件的 DID。
  - token string (required) — 下載權杖。

範例：從商店安裝

Install from Store

import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function installMyBlocklet() {
  try {
    const { blocklet } = await client.installBlocklet({
      input: {
        did: 'z8ia1posN9ZcxGA2MAnsl62aT82gS7f5kCtUf',
        storeUrl: 'https://store.blocklet.dev',
        startImmediately: true,
      },
    });
    console.log(`Blocklet '${blocklet.meta.title}' installed successfully.`);
  } catch (error) {
    console.error('Failed to install blocklet:', error);
  }
}

installMyBlocklet();

範例回應

Response

{
  "code": "ok",
  "blocklet": {
    "meta": {
      "did": "z8ia1posN9ZcxGA2MAnsl62aT82gS7f5kCtUf",
      "name": "@blocklet/did-wallet-adapter",
      "version": "1.16.111",
      "title": "DID Wallet Adapter"
    },
    "status": "installed",
    "appDid": "z12A1B...",
    "appPid": "z8ia1posN9ZcxGA2MAnsl62aT82gS7f5kCtUf"
  }
}

此範例從官方商店安裝 DID Wallet Adapter Blocklet 並立即啟動它。回應包含新安裝的 Blocklet 的完整狀態物件。

startBlocklet

啟動一個或多個處於停止或錯誤狀態的 Blocklet 元件。

參數

input object (required) — startBlocklet 變更的輸入物件。
- did string (required) — Blocklet 的根 DID。
- componentDids string[] — 一個可選的要啟動的元件 DID 陣列。如果省略，將啟動所有元件。

範例

Start a Blocklet

import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();
const blockletDid = 'z8ia1posN9ZcxGA2MAnsl62aT82gS7f5kCtUf';

async function startMyBlocklet() {
  try {
    const { blocklet } = await client.startBlocklet({
      input: { did: blockletDid },
    });
    console.log(`Blocklet '${blocklet.meta.title}' is now ${blocklet.status}.`);
  } catch (error) {
    console.error('Failed to start blocklet:', error);
  }
}

startMyBlocklet();

範例回應

Response

{
  "code": "ok",
  "blocklet": {
    "meta": {
      "did": "z8ia1posN9ZcxGA2MAnsl62aT82gS7f5kCtUf"
    },
    "status": "running"
    // ... other properties
  }
}

stopBlocklet

停止一個或多個正在執行的 Blocklet 元件。

參數

input object (required) — stopBlocklet 變更的輸入物件。
- did string (required) — Blocklet 的根 DID。
- componentDids string[] — 一個可選的要停止的元件 DID 陣列。如果省略，將停止所有正在執行的元件。

範例

Stop a Blocklet

import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();
const blockletDid = 'z8ia1posN9ZcxGA2MAnsl62aT82gS7f5kCtUf';

async function stopMyBlocklet() {
  try {
    const { blocklet } = await client.stopBlocklet({
      input: { did: blockletDid },
    });
    console.log(`Blocklet '${blocklet.meta.title}' is now ${blocklet.status}.`);
  } catch (error) {
    console.error('Failed to stop blocklet:', error);
  }
}

stopMyBlocklet();

範例回應

Response

{
  "code": "ok",
  "blocklet": {
    "meta": {
      "did": "z8ia1posN9ZcxGA2MAnsl62aT82gS7f5kCtUf"
    },
    "status": "stopped"
    // ... other properties
  }
}

reloadBlocklet

重新載入一個或多個正在執行的 Blocklet 元件，套用任何程式碼變更而無需完全重新啟動。這通常比重新啟動更快。

參數

input object (required) — reloadBlocklet 變更的輸入物件。
- did string (required) — Blocklet 的根 DID。
- componentDids string[] — 一個可選的要重新載入的元件 DID 陣列。如果省略，將重新載入所有可重新載入的元件。

範例

Reload a Blocklet

import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();
const blockletDid = 'z8ia1posN9ZcxGA2MAnsl62aT82gS7f5kCtUf';

async function reloadMyBlocklet() {
  try {
    const { blocklet } = await client.reloadBlocklet({
      input: { did: blockletDid },
    });
    console.log(`Blocklet '${blocklet.meta.title}' has been reloaded.`);
  } catch (error) {
    console.error('Failed to reload blocklet:', error);
  }
}

reloadMyBlocklet();

範例回應

Response

{
  "code": "ok",
  "blocklet": {
    "meta": {
      "did": "z8ia1posN9ZcxGA2MAnsl62aT82gS7f5kCtUf"
    },
    "status": "running"
    // ... other properties
  }
}

restartBlocklet

重新啟動一個或多個 Blocklet 元件。這相當於先停止再啟動它們。

參數

input object (required) — restartBlocklet 變更的輸入物件。
- did string (required) — Blocklet 的根 DID。
- componentDids string[] — 一個可選的要重新啟動的元件 DID 陣列。如果省略，將重新啟動所有元件。

範例

Restart a Blocklet

import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();
const blockletDid = 'z8ia1posN9ZcxGA2MAnsl62aT82gS7f5kCtUf';

async function restartMyBlocklet() {
  try {
    const { blocklet } = await client.restartBlocklet({
      input: { did: blockletDid },
    });
    console.log(`Blocklet '${blocklet.meta.title}' has been restarted.`);
  } catch (error) {
    console.error('Failed to restart blocklet:', error);
  }
}

restartMyBlocklet();

範例回應

Response

{
  "code": "ok",
  "blocklet": {
    "meta": {
      "did": "z8ia1posN9ZcxGA2MAnsl62aT82gS7f5kCtUf"
    },
    "status": "running"
    // ... other properties
  }
}

deleteBlocklet

從節點永久移除一個 Blocklet 及其元件。

參數

input object (required) — deleteBlocklet 變更的輸入物件。
- did string (required) — 要刪除的 Blocklet 的根 DID。
- keepData boolean (default: false) — 若為 true，將保留 Blocklet 的資料目錄。

範例

Delete a Blocklet

import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();
const blockletDid = 'z8ia1posN9ZcxGA2MAnsl62aT82gS7f5kCtUf';

async function deleteMyBlocklet() {
  try {
    await client.deleteBlocklet({ input: { did: blockletDid } });
    console.log('Blocklet deleted successfully.');
  } catch (error) {
    console.error('Failed to delete blocklet:', error);
  }
}

deleteMyBlocklet();

範例回應

Response

{
  "code": "ok",
  "blocklet": {
    "meta": {
      "did": "z8ia1posN9ZcxGA2MAnsl62aT82gS7f5kCtUf"
    },
    "status": "deleted"
    // ... other properties
  }
}

cancelDownloadBlocklet

取消一個正在進行中的 Blocklet 下載。

參數

input object (required) — cancelDownloadBlocklet 變更的輸入物件。
- did string (required) — 應取消下載的 Blocklet 的根 DID。

範例

Cancel a Download

import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();
const blockletDid = 'z8ia1posN9ZcxGA2MAnsl62aT82gS7f5kCtUf';

async function cancelDownload() {
  try {
    const { blocklet } = await client.cancelDownloadBlocklet({ input: { did: blockletDid } });
    console.log(`Download for blocklet '${blocklet.meta.title}' cancelled.`);
  } catch (error) {
    console.error('Failed to cancel download:', error);
  }
}

cancelDownload();

元件管理

這些變更用於管理 Blocklet 內的元件，包括安裝、升級和組態變更。

installComponent

將一個新元件安裝到現有的 Blocklet 中。

參數

input object (required) — installComponent 變更的輸入物件。
- rootDid string (required) — 父 Blocklet 的根 DID。
- mountPoint string (required) — 元件將被掛載的路徑。
- url string — 元件的 meta 檔案或 bundle 的 URL。
- did string — 要安裝的元件的 DID。
- title string — 元件的自訂標題。
- configs ConfigEntryInput[] — 元件的初始組態值陣列。

範例

Install a Component

import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();
const rootBlockletDid = 'z8ia1posN9ZcxGA2MAnsl62aT82gS7f5kCtUf';

async function installNewComponent() {
  try {
    const { blocklet } = await client.installComponent({
      input: {
        rootDid: rootBlockletDid,
        mountPoint: '/new-component',
        did: 'z8ibCciF3uW9i9f9tQ5A7n9e3s2W4f8Y6z1x',
        title: 'My New Component',
      },
    });
    console.log('Component installed successfully.');
  } catch (error) {
    console.error('Failed to install component:', error);
  }
}

installNewComponent();

deleteComponent

從一個 Blocklet 中永久移除一個元件。

參數

input object (required) — deleteComponent 變更的輸入物件。
- did string (required) — 要刪除的元件的 DID。
- rootDid string (required) — 父 Blocklet 的根 DID。
- keepData boolean (default: false) — 若為 true，將保留元件的資料。

範例

Delete a Component

import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();
const rootBlockletDid = 'z8ia1posN9ZcxGA2MAnsl62aT82gS7f5kCtUf';
const componentDid = 'z8ibCciF3uW9i9f9tQ5A7n9e3s2W4f8Y6z1x';

async function deleteMyComponent() {
  try {
    await client.deleteComponent({
      input: { did: componentDid, rootDid: rootBlockletDid },
    });
    console.log('Component deleted successfully.');
  } catch (error) {
    console.error('Failed to delete component:', error);
  }
}

deleteMyComponent();

checkComponentsForUpdates

檢查 Blocklet 內的元件是否有可用的更新。

參數

input object (required) — checkComponentsForUpdates 變更的輸入物件。
- did string (required) — 要檢查更新的 Blocklet 的根 DID。

傳回值

preUpdateInfo object — 有關可用更新的資訊。
- updateId string — 此更新會話的唯一 ID。
- updateList UpdateList[] — 有可用更新的元件清單。
  - id string — 元件的 DID。
  - meta BlockletMeta — 新版本的元資料。

範例

Check for Updates

import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();
const blockletDid = 'z8ia1posN9ZcxGA2MAnsl62aT82gS7f5kCtUf';

async function checkUpdates() {
  try {
    const { preUpdateInfo } = await client.checkComponentsForUpdates({ input: { did: blockletDid } });
    if (preUpdateInfo.updateList.length > 0) {
      console.log('Updates available:', preUpdateInfo.updateList);
    } else {
      console.log('All components are up to date.');
    }
  } catch (error) {
    console.error('Failed to check for updates:', error);
  }
}

checkUpdates();

upgradeComponents

根據 checkComponentsForUpdates 的 updateId 將選定的元件升級到其最新版本。

參數

input object (required) — upgradeComponents 變更的輸入物件。
- updateId string (required) — 來自 checkComponentsForUpdates 的更新會話 ID。
- rootDid string (required) — Blocklet 的根 DID。
- selectedComponents string[] (required) — 要升級的元件 DID 陣列。

範例

Upgrade Components

import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();
const updateId = '...'; // from checkComponentsForUpdates
const rootDid = 'z8ia1posN9ZcxGA2MAnsl62aT82gS7f5kCtUf';
const componentsToUpgrade = ['z8ibCciF3uW9i9f9tQ5A7n9e3s2W4f8Y6z1x'];

async function performUpgrade() {
  try {
    await client.upgradeComponents({
      input: {
        updateId,
        rootDid,
        selectedComponents: componentsToUpgrade,
      },
    });
    console.log('Components upgraded successfully.');
  } catch (error) {
    console.error('Failed to upgrade components:', error);
  }
}

performUpgrade();

updateComponentTitle

更新 Blocklet 內特定元件的顯示標題。

參數

did string (required) — 要更新的元件的 DID。
rootDid string (required) — 父 Blocklet 的根 DID。
title string (required) — 元件的新標題。

updateComponentMountPoint

變更 Blocklet 內特定元件的 URL 路徑（掛載點）。

參數

did string (required) — 要更新的元件的 DID。
rootDid string (required) — 父 Blocklet 的根 DID。
mountPoint string (required) — 元件的新掛載點（例如，'/new-path'）。

設定與組態

這些變更處理 Blocklet 和節點的動態組態。

configBlocklet

更新 Blocklet 或其元件之一的組態（環境變數）。

參數

input object (required) — configBlocklet 變更的輸入物件。
- did string[] (required) — 一個包含根 DID 和可選的元件 DID 的陣列。
- configs ConfigEntryInput[] (required) — 要更新的組態物件陣列。
  - key string (required) — 環境變數名稱。
  - value string (required) — 變數的新值。

範例

Configure a Blocklet

import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();
const blockletDid = 'z8ia1posN9ZcxGA2MAnsl62aT82gS7f5kCtUf';

async function updateConfiguration() {
  try {
    await client.configBlocklet({
      input: {
        did: [blockletDid],
        configs: [
          { key: 'API_ENDPOINT', value: 'https://api.new.com' },
          { key: 'API_KEY', value: 'new-secret-key' },
        ],
      },
    });
    console.log('Blocklet configuration updated.');
  } catch (error) {
    console.error('Failed to configure blocklet:', error);
  }
}

updateConfiguration();

updateBlockletSettings

更新特定 Blocklet 的各種設定，例如閘道策略、邀請設定和 AI 服務組態。

參數

input object (required) — updateBlockletSettings 變更的輸入物件。
- did string (required) — 要更新的 Blocklet 的 DID。
- enableSessionHardening boolean — 啟用或停用會話強化以增強安全性。
- invite InviteSettingsInput — 與使用者邀請相關的設定。
  - enabled boolean — 啟用或停用邀請功能。
- gateway BlockletGatewayInput — Blocklet 閘道的組態，包括速率限制和安全策略。
- aigne AigneConfigInput — AIGNE 服務整合的組態。

updateAutoBackup

啟用或停用 Blocklet 的自動備份功能。

參數

input object (required) — updateAutoBackup 變更的輸入物件。
- did string (required) — Blocklet 的 DID。
- autoBackup AutoBackupInput (required) — 自動備份組態。
  - enabled boolean (required) — 設定為 true 以啟用自動備份，false 以停用。

updateAutoCheckUpdate

啟用或停用 Blocklet 的自動檢查更新功能。

參數

input object (required) — updateAutoCheckUpdate 變更的輸入物件。
- did string (required) — Blocklet 的 DID。
- autoCheckUpdate AutoCheckUpdateInput (required) — 自動檢查更新組態。
  - enabled boolean (required) — 設定為 true 以啟用自動更新檢查，false 以停用。

節點管理

這些變更用於管理 Blocklet Server 節點本身。

updateNodeInfo

更新 Blocklet Server 節點的一般資訊和設定。

參數

input object (required) — updateNodeInfo 變更的輸入物件。
- name string — 節點的新名稱。
- description string — 節點的新描述。
- autoUpgrade boolean — 啟用或停用節點自動升級。
- enableWelcomePage boolean — 啟用或停用歡迎頁面。
- webWalletUrl string — 要與節點一起使用的網頁錢包的 URL。
- enableBetaRelease boolean — 啟用或停用更新的 Beta 發行通道。

範例

Configure Node

import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function configureNode() {
  try {
    const { info } = await client.updateNodeInfo({
      input: {
        name: 'My Production Node',
        autoUpgrade: true,
      },
    });
    console.log(`Node name updated to: ${info.name}`);
  } catch (error) {
    console.error('Failed to update node info:', error);
  }
}

configureNode();

範例回應

Response

{
  "code": "ok",
  "info": {
    "did": "z12A1B...",
    "name": "My Production Node",
    "autoUpgrade": true
    // ... other properties
  }
}

upgradeNodeVersion

啟動將 Blocklet Server 升級到下一個可用版本的操作。

參數

input object — upgradeNodeVersion 變更的輸入物件。
- sessionId string — 用於追蹤升級過程的可選會話 ID。

範例

Upgrade Node

import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function upgradeMyNode() {
  try {
    const { sessionId } = await client.upgradeNodeVersion({});
    console.log(`Node upgrade started with session ID: ${sessionId}`);
  } catch (error) {
    console.error('Failed to start node upgrade:', error);
  }
}

upgradeMyNode();

範例回應

Response

{
  "code": "ok",
  "sessionId": "unique-session-id-for-upgrade"
}

restartServer

重新啟動 Blocklet Server 守護程序。這將暫時中斷所有正在執行的 Blocklet 和服務。

範例

Restart Server

import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function restartMyServer() {
  try {
    const { sessionId } = await client.restartServer();
    console.log(`Server restart initiated with session ID: ${sessionId}`);
  } catch (error) {
    console.error('Failed to restart server:', error);
  }
}

restartMyServer();

範例回應

Response

{
  "code": "ok",
  "sessionId": "unique-session-id-for-restart"
}

resetNode

重設節點的各個部分的組態和資料。這是一個破壞性操作，應謹慎使用。

參數

input object (required) — resetNode 變更的輸入物件。
- owner boolean — 重設節點擁有者。
- blocklets boolean — 刪除所有已安裝的 Blocklet。
- webhooks boolean — 刪除所有 Webhook。
- certificates boolean — 刪除所有 SSL 憑證。
- accessKeys boolean — 刪除所有存取金鑰。
- routingRules boolean — 刪除所有路由規則。
- users boolean — 刪除除擁有者外的所有使用者。
- invitations boolean — 刪除所有待處理的邀請。

範例

Reset Node Data

import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function resetNodeData() {
  try {
    await client.resetNode({
      input: {
        blocklets: true,
        users: true,
      },
    });
    console.log('Node blocklets and users have been reset.');
  } catch (error) {
    console.error('Failed to reset node:', error);
  }
}

resetNodeData();

範例回應

Response

{
  "code": "ok"
}

restartAllContainers

重新啟動由 Blocklet Server 管理的所有正在執行的 Docker 容器。這對於應用影響 Docker 環境的系統級變更很有用。

範例

Restart All Containers

import BlockletServerClient from '@blocklet/server-js';

const client = new BlockletServerClient();

async function restartContainers() {
  try {
    const { sessionId } = await client.restartAllContainers();
    console.log(`Restarting all containers with session ID: ${sessionId}`);
  } catch (error) {
    console.error('Failed to restart containers:', error);
  }
}

restartContainers();

範例回應

Response

{
  "code": "ok",
  "sessionId": "unique-session-id-for-restart-all"
}