节点和 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 的元数据文件或捆绑包的 URL（URL 安装时必需）。
- file Upload — 要上传的 Blocklet 捆绑文件。
- 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 — 组件的元数据文件或捆绑包的 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 = '...'; // 来自 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"
}