@abtnode/core 1.17.8-beta-20260109-075740-5f484e08 → 1.17.8-beta-20260113-015027-32a1cec4

package/lib/util/blocklet.js

@@ -1,233 +1,89 @@
 /* eslint-disable camelcase */
-/* eslint-disable no-await-in-loop */
 
-const fs = require('fs-extra');
-const path = require('node:path');
-const shelljs = require('shelljs');
-const os = require('node:os');
-const tar = require('tar');
-const get = require('lodash/get');
-const isNil = require('lodash/isNil');
-const uniq = require('lodash/uniq');
-const cloneDeep = require('lodash/cloneDeep');
-const mergeWith = require('lodash/mergeWith');
-const toLower = require('lodash/toLower');
-const isEmpty = require('lodash/isEmpty');
-const omit = require('lodash/omit');
-const pick = require('lodash/pick');
-const streamToPromise = require('stream-to-promise');
-const { Throttle } = require('stream-throttle');
-const { slugify } = require('transliteration');
-const ssri = require('ssri');
-const diff = require('deep-diff');
-const createArchive = require('archiver');
-const isUrl = require('is-url');
-const semver = require('semver');
-const { chainInfo: chainInfoSchema } = require('@arcblock/did-connect-js/lib/schema');
-
-const { types } = require('@ocap/mcrypto');
-const { urlPathFriendly } = require('@blocklet/meta/lib/url-path-friendly');
-const { fromSecretKey, fromPublicKey } = require('@ocap/wallet');
-const { toHex, isHex, toDid, toAddress, toBuffer } = require('@ocap/util');
-const { isValid: isValidDid, isEthereumDid } = require('@arcblock/did');
 const logger = require('@abtnode/logger')('@abtnode/core:util:blocklet');
-const pm2 = require('@abtnode/util/lib/pm2/async-pm2');
-const sleep = require('@abtnode/util/lib/sleep');
-const { isCustomDomain } = require('@abtnode/util/lib/url-evaluation');
-const getPm2ProcessInfo = require('@abtnode/util/lib/get-pm2-process-info');
-const { formatEnv, getSecurityNodeOptions, decrypt } = require('@abtnode/util/lib/security');
-const ensureEndpointHealthy = require('@abtnode/util/lib/ensure-endpoint-healthy');
-const getFolderSize = require('@abtnode/util/lib/get-folder-size');
-const normalizePathPrefix = require('@abtnode/util/lib/normalize-path-prefix');
-const hashFiles = require('@abtnode/util/lib/hash-files');
-const didDocument = require('@abtnode/util/lib/did-document');
-const { DBCache } = require('@abtnode/db-cache');
-const {
-  BLOCKLET_MAX_MEM_LIMIT_IN_MB,
-  BLOCKLET_INSTALL_TYPE,
-  APP_STRUCT_VERSION,
-  BLOCKLET_CACHE_TTL,
-  AIGNE_CONFIG_ENCRYPT_SALT,
-  SLOT_FOR_IP_DNS_SITE,
-} = require('@abtnode/constant');
-const { BLOCKLET_THEME_LIGHT, BLOCKLET_THEME_DARK } = require('@blocklet/theme');
 const {
   parseComponents,
   ensureMeta,
   filterDuplicateComponents,
   validateBlockletMeta,
-  getComponentConfig,
-  parseOptionalComponents,
   filterRequiredComponents,
 } = require('@blocklet/resolver');
-const formatBackSlash = require('@abtnode/util/lib/format-back-slash');
-const { killProcessOccupiedPorts, isPortTaken } = require('@abtnode/util/lib/port');
-const { getComponentApiKey } = require('@abtnode/util/lib/blocklet');
-const { toSvg: createDidLogo } = require('@arcblock/did-motif');
-const { createBlockiesSvg } = require('@blocklet/meta/lib/blockies');
-const formatName = require('@abtnode/util/lib/format-name');
-const { hasMountPoint, getBlockletEngine } = require('@blocklet/meta/lib/engine');
-const { fixAvatar } = require('@blocklet/sdk/lib/util/user');
-
-const SCRIPT_ENGINES_WHITE_LIST = ['npm', 'npx', 'pnpm', 'yarn'];
-
+const { getBlockletEngine } = require('@blocklet/meta/lib/engine');
+const { forEachBlocklet, getDisplayName, findWebInterface, isExternalBlocklet } = require('@blocklet/meta/lib/util');
+const { getBlockletMetaFromUrl } = require('@blocklet/meta/lib/util-meta');
+const { findInterfacePortByName } = require('./index');
+const { getProcessInfo, getProcessState, shouldSkipComponent } = require('./blocklet/process-manager');
 const {
-  BlockletStatus,
-  BlockletSource,
-  BlockletGroup,
-  BLOCKLET_MODES,
-  BLOCKLET_BUNDLE_FILE,
-  BLOCKLET_ENTRY_FILE,
-  BLOCKLET_DEFAULT_PORT_NAME,
-  BLOCKLET_INTERFACE_TYPE_WEB,
-  BLOCKLET_CONFIGURABLE_KEY,
-  fromBlockletStatus,
-  BLOCKLET_PREFERENCE_FILE,
-  BLOCKLET_PREFERENCE_PREFIX,
-  BLOCKLET_RESOURCE_DIR,
-  BLOCKLET_TENANT_MODES,
-  PROJECT,
-  BLOCKLET_INTERFACE_TYPE_DOCKER,
-  STATIC_SERVER_ENGINE_DID,
-} = require('@blocklet/constant');
-const { validateBlockletEntry } = require('@blocklet/meta/lib/entry');
-const { getBlockletInfo } = require('@blocklet/meta/lib/info');
-const { getApplicationWallet: getBlockletWallet } = require('@blocklet/meta/lib/wallet');
+  getHealthyCheckTimeout,
+  shouldCheckHealthy,
+  isBlockletPortHealthy,
+  checkBlockletProcessHealthy: _checkBlockletProcessHealthy,
+} = require('./blocklet/health-check');
 const {
-  forEachBlocklet,
-  getDisplayName,
-  findWebInterface,
-  forEachBlockletSync,
-  forEachChildSync,
-  forEachComponentV2,
-  forEachComponentV2Sync,
-  getSharedConfigObj,
-  getComponentName,
-  getBlockletAppIdList,
-  getChainInfo,
-  isInProgress,
-  isRunning,
-  hasStartEngine,
-  isEnvShareable,
-  isExternalBlocklet,
-} = require('@blocklet/meta/lib/util');
-const { getComponentsInternalInfo } = require('@blocklet/meta/lib/blocklet');
-const { titleSchema, descriptionSchema, logoSchema } = require('@blocklet/meta/lib/schema');
-const { getBlockletMetaFromUrl } = require('@blocklet/meta/lib/util-meta');
-const { getComponentProcessId } = require('@blocklet/meta/lib/get-component-process-id');
-const { isInServerlessMode } = require('@abtnode/util/lib/serverless');
-const { getDidDomainForBlocklet } = require('@abtnode/util/lib/get-domain-for-blocklet');
-const md5 = require('@abtnode/util/lib/md5');
-const fetchPm2 = require('@abtnode/util/lib/pm2/fetch-pm2');
-
-const promiseSpawn = require('@abtnode/util/lib/promise-spawn');
-const { getAbtNodeRedisAndSQLiteUrl } = require('@abtnode/db-cache');
-const { validate: validateEngine, get: getEngine } = require('../blocklet/manager/engine');
-
-const isRequirementsSatisfied = require('./requirement');
+  expandTarball,
+  verifyIntegrity,
+  getAppDirs,
+  pruneBlockletBundle,
+  getTypeFromInstallParams,
+  getDiffFiles,
+  getBundleDir,
+  needBlockletDownload,
+} = require('./blocklet/install-utils');
+const { getDiskInfo, getRuntimeInfo } = require('./blocklet/runtime-info');
 const {
-  expandBundle,
-  findInterfacePortByName,
-  prettyURL,
-  templateReplace,
-  getServerDidDomain,
-  APP_CONFIG_IMAGE_KEYS,
-  replaceDomainSlot,
-} = require('./index');
-const { installExternalDependencies } = require('./install-external-dependencies');
-const parseDockerOptionsFromPm2 = require('./docker/parse-docker-options-from-pm2');
-const dockerRemoveByName = require('./docker/docker-remove-by-name');
-const getDockerRuntimeInfo = require('./docker/get-docker-runtime-info');
-const parseDockerName = require('./docker/parse-docker-name');
-const { createDockerNetwork } = require('./docker/docker-network');
-const { ensureBun } = require('./ensure-bun');
-const { getFromCache: getAccessibleExternalNodeIp } = require('./get-accessible-external-node-ip');
-
-/**
- * Get actual listening port from Docker container or process
- * @param {string} processId - PM2 process ID
- * @param {object} blocklet - Blocklet object with meta and env
- * @returns {Promise<number|null>} Actual port number or null if not found
- */
-const getActualListeningPort = async (processId, blocklet) => {
-  try {
-    // eslint-disable-next-line no-use-before-define
-    const info = await getProcessInfo(processId, { timeout: 3_000 });
-    const dockerName = info.pm2_env?.env?.dockerName;
-
-    if (dockerName) {
-      // For Docker containers, get actual port from docker inspect
-      try {
-        // Get port mapping from docker inspect
-        const inspectCmd = `docker inspect --format='{{range $p, $conf := .NetworkSettings.Ports}}{{$p}} {{end}}' ${dockerName}`;
-        const portMappings = await promiseSpawn(inspectCmd, { mute: true });
-
-        if (portMappings) {
-          const ports = portMappings.trim().split(/\s+/).filter(Boolean);
-          for (const portMapping of ports) {
-            const port = parseInt(portMapping.split('/')[0], 10);
-            if (port && !Number.isNaN(port)) {
-              try {
-                const portCmd = `docker port ${dockerName} ${portMapping}`;
-                const hostPortOutput = await promiseSpawn(portCmd, { mute: true });
-                const match = hostPortOutput.match(/:(\d+)$/);
-                if (match) {
-                  const actualPort = parseInt(match[1], 10);
-                  if (actualPort && !Number.isNaN(actualPort)) {
-                    logger.info('Got actual Docker port from container', {
-                      processId,
-                      dockerName,
-                      containerPort: port,
-                      hostPort: actualPort,
-                    });
-                    return actualPort;
-                  }
-                }
-              } catch (err) {
-                logger.debug('Failed to get port from docker port command', { error: err.message });
-              }
-            }
-          }
-        }
-
-        // Fallback: try to get from NetworkSettings.Ports directly
-        const inspectPortsCmd = `docker inspect --format='{{json .NetworkSettings.Ports}}' ${dockerName}`;
-        const portsJson = await promiseSpawn(inspectPortsCmd, { mute: true });
-        if (portsJson) {
-          const ports = JSON.parse(portsJson);
-          // Find the primary port (usually BLOCKLET_PORT)
-          const webInterface = (blocklet?.meta?.interfaces || []).find(
-            (x) => x.type === BLOCKLET_INTERFACE_TYPE_WEB || x.type === BLOCKLET_INTERFACE_TYPE_DOCKER
-          );
-          const expectedContainerPort = webInterface?.containerPort || webInterface?.port;
-
-          if (expectedContainerPort) {
-            const portKey = `${expectedContainerPort}/tcp`;
-            if (ports[portKey] && ports[portKey][0]) {
-              const hostPort = parseInt(ports[portKey][0].HostPort, 10);
-              if (hostPort && !Number.isNaN(hostPort)) {
-                logger.info('Got actual Docker port from NetworkSettings', {
-                  processId,
-                  dockerName,
-                  containerPort: expectedContainerPort,
-                  hostPort,
-                });
-                return hostPort;
-              }
-            }
-          }
-        }
-      } catch (error) {
-        logger.debug('Failed to get Docker port mapping', { error: error.message, processId, dockerName });
-      }
-    }
-
-    return null;
-  } catch (error) {
-    logger.debug('Failed to get actual listening port', { error: error.message, processId });
-    return null;
-  }
-};
+  validateBlocklet: _validateBlocklet,
+  validateBlockletChainInfo,
+  checkDuplicateComponents,
+  validateAppConfig,
+  checkDuplicateAppSk,
+  checkDuplicateMountPoint,
+  resolveMountPointConflict,
+  validateStore,
+  validateInServerless,
+  checkStructVersion,
+  checkVersionCompatibility,
+} = require('./blocklet/validation');
+const {
+  shouldEnableSlpDomain,
+  getSlpDid,
+  getBlockletKnownAs,
+  publishDidDocument,
+  updateDidDocument,
+  updateDidDocumentStateOnly,
+} = require('./blocklet/did-document');
+const {
+  getComponentDirs,
+  getComponentStartEngine,
+  getBlockletConfigObj,
+  getAppSystemEnvironments,
+  getAppOverwrittenEnvironments,
+  getComponentSystemEnvironments,
+  fillBlockletConfigs,
+  getRuntimeEnvironments,
+} = require('./blocklet/environment');
+const {
+  getConfigFromPreferences,
+  getAppConfigsFromComponent,
+  getConfigsFromInput,
+  removeAppConfigsFromComponent,
+  getPackComponent,
+  getPackConfig,
+  copyPackImages,
+} = require('./blocklet/config-manager');
+const { mergeMeta, getUpdateMetaList, getFixedBundleSource, getBlockletStatus } = require('./blocklet/meta-utils');
+const { updateBlockletFallbackLogo, ensureAppLogo } = require('./blocklet/logo');
+const {
+  createDataArchive,
+  isBlockletAppSkUsed,
+  isRotatingAppSk,
+  getBlockletURLForLauncher,
+  getBlockletDidDomainList,
+  getComponentNamesWithVersion,
+  isDevelopmentMode,
+  getHookArgs,
+} = require('./blocklet/app-utils');
+const { ensureBlockletExpanded, getBlocklet } = require('./blocklet/blocklet-loader');
+const { ensureAppPortsNotOccupied } = require('./blocklet/port-manager');
 
 /**
  * get blocklet engine info, default is node
@@ -236,2864 +92,41 @@ const getActualListeningPort = async (processId, blocklet) => {
  */
 const getBlockletEngineNameByPlatform = (meta) => getBlockletEngine(meta).interpreter;
 
-const startLock = new DBCache(() => ({
-  ...getAbtNodeRedisAndSQLiteUrl(),
-  prefix: 'blocklet-start-locks2',
-  ttl: 1000 * 60 * 3,
-}));
-
-// Lock for port assignment to prevent race conditions in multi-process environment
-const portAssignLock = new DBCache(() => ({
-  ...getAbtNodeRedisAndSQLiteUrl(),
-  prefix: 'blocklet-port-assign-lock',
-  ttl: 1000 * 30, // 30 seconds timeout
-}));
-
-const blockletCache = new DBCache(() => ({
-  prefix: 'blocklet-state',
-  ttl: BLOCKLET_CACHE_TTL,
-  ...getAbtNodeRedisAndSQLiteUrl(),
-}));
-
-const getVersionScope = (meta) => {
-  if (meta.dist?.integrity) {
-    const safeHash = meta.dist.integrity
-      .replace('sha512-', '')
-      .slice(0, 8)
-      .replace(/[^a-zA-Z0-9]/g, '');
-    return `${meta.version}-${safeHash}`;
-  }
-
-  return meta.version;
-};
-
-const deleteBlockletCache = async (did) => {
-  await blockletCache.del(did);
-};
-
-const noop = () => {
-  //
-};
-const noopAsync = async () => {
-  //
-};
-
-const statusMap = {
-  online: BlockletStatus.running,
-  launching: BlockletStatus.starting,
-  errored: BlockletStatus.error,
-  stopping: BlockletStatus.stopping,
-  stopped: BlockletStatus.stopped,
-  'waiting restart': BlockletStatus.restarting,
-};
-
-const PRIVATE_NODE_ENVS = [
-  'ABT_NODE_UPDATER_PORT',
-  'ABT_NODE_SESSION_TTL',
-  'ABT_NODE_ROUTER_PROVIDER',
-  'ABT_NODE_DATA_DIR',
-  'ABT_NODE_TOKEN_SECRET',
-  'ABT_NODE_SK',
-  'ABT_NODE_SESSION_SECRET',
-  'ABT_NODE_BASE_URL',
-  'ABT_NODE_LOG_LEVEL',
-  'ABT_NODE_LOG_DIR',
-  // in /core/cli/bin/blocklet.js
-  'CLI_MODE',
-  'ABT_NODE_HOME',
-  'PM2_HOME',
-  'ABT_NODE_CONFIG_FILE',
-];
-
-/**
- * @returns { dataDir, logsDir, cacheDir, appDir }
- * dataDir: dataDirs.data/name (root component) or dataDirs.data/name/childName (child component)
- * logsDir: dataDirs.log/name
- * cacheDir: dataDirs.cache/name (root component) or dataDirs.cache/name/childName (child component)
- * appDir: component bundle dir
- */
-const getComponentDirs = (component, { dataDirs, ensure = false, ancestors = [] } = {}) => {
-  const componentName = getComponentName(component, ancestors);
-
-  const logsDir = path.join(dataDirs.logs, componentName);
-  const dataDir = path.join(dataDirs.data, componentName);
-  const cacheDir = path.join(dataDirs.cache, componentName);
-
-  let appDir = null;
-  if (component.source === BlockletSource.local) {
-    appDir = component.deployedFrom;
-  } else {
-    // eslint-disable-next-line no-use-before-define
-    appDir = getBundleDir(dataDirs.blocklets, component.meta);
-  }
-
-  if (!appDir) {
-    throw new Error('Can not determine blocklet directory, maybe invalid deployment from local blocklets');
-  }
-
-  if (ensure) {
-    try {
-      fs.mkdirSync(dataDir, { recursive: true });
-      fs.mkdirSync(path.join(dataDir, PROJECT.DIR), { recursive: true });
-      fs.mkdirSync(logsDir, { recursive: true });
-      fs.mkdirSync(cacheDir, { recursive: true });
-      fs.mkdirSync(appDir, { recursive: true }); // prevent getDiskInfo failed from custom blocklet
-    } catch (err) {
-      logger.error('make blocklet dir failed', { error: err });
-    }
-  }
-
-  return { dataDir, logsDir, cacheDir, appDir };
-};
-
-/**
- * @param component {import('@blocklet/server-js').ComponentState & { environmentObj: {[key: string]: string } } }
- * @returns {{cwd, script, args, environmentObj, interpreter, interpreterArgs}: { args: []}}
- * @return {*}
- */
-const getComponentStartEngine = (component, { e2eMode = false } = {}) => {
-  if (!hasStartEngine(component.meta)) {
-    return {};
-  }
-
-  const { appDir } = component.env;
-
-  const cwd = appDir;
-
-  // get app dirs
-  const { group } = component.meta;
-
-  let startFromDevEntry = '';
-  if (component.mode === BLOCKLET_MODES.DEVELOPMENT && component.meta.scripts) {
-    startFromDevEntry = component.meta.scripts.dev;
-    if (e2eMode && component.meta.scripts.e2eDev) {
-      startFromDevEntry = component.meta.scripts.e2eDev;
-    }
-  }
-
-  const blockletEngineInfo = getBlockletEngine(component.meta);
-  if (blockletEngineInfo.interpreter === 'blocklet') {
-    return {};
-  }
-
-  let script = null;
-  let interpreter;
-  let interpreterArgs = [];
-  const environmentObj = {};
-  let args = [];
-
-  if (startFromDevEntry) {
-    script = startFromDevEntry;
-  } else if (group === 'dapp') {
-    script = blockletEngineInfo.source || BLOCKLET_ENTRY_FILE;
-    args = blockletEngineInfo.args || [];
-  }
-
-  if (component.mode !== BLOCKLET_MODES.DEVELOPMENT) {
-    const engine = getEngine(blockletEngineInfo.interpreter);
-    interpreter = engine.interpreter === 'node' ? undefined : engine.interpreter;
-    interpreterArgs = interpreterArgs.concat(engine.args ? [engine.args] : []);
-  }
-
-  return {
-    cwd,
-    script,
-    args,
-    environmentObj,
-    interpreter,
-    interpreterArgs: interpreterArgs.join(' ').trim(),
-  };
-};
-
-const getBlockletConfigObj = (blocklet, { excludeSecure } = {}) => {
-  const obj = (blocklet?.configs || [])
-    .filter((x) => {
-      if (excludeSecure) {
-        return !x.secure;
-      }
-      return true;
-    })
-    .reduce((acc, x) => {
-      acc[x.key] = templateReplace(x.value, blocklet);
-      return acc;
-    }, {});
-
-  return obj;
-};
-
-const getAppSystemEnvironments = (blocklet, nodeInfo, dataDirs) => {
-  const { did, name, title, description } = blocklet.meta;
-  const keys = Object.keys(BLOCKLET_CONFIGURABLE_KEY);
-  const result = getBlockletInfo(
-    {
-      meta: blocklet.meta,
-      environments: keys.map((key) => ({ key, value: blocklet.configObj[key] })).filter((x) => x.value),
-    },
-    nodeInfo.sk
-  );
-
-  const { wallet } = result;
-  const appSk = toHex(wallet.secretKey);
-  const appPk = toHex(wallet.publicKey);
-
-  const appId = wallet.address;
-  const appName = title || name || result.name;
-  const appDescription = description || result.description;
-
-  const isMigrated = Array.isArray(blocklet.migratedFrom) && blocklet.migratedFrom.length > 0;
-  const appPid = blocklet.appPid || appId;
-  const appPsk = toHex(isMigrated ? blocklet.migratedFrom[0].appSk : appSk);
-
-  /* 获取 did domain 方式:
-   * 1. 先从 site 里读
-   * 2. 如果没有，再拼接
-   */
-
-  const pidDomain = getDidDomainForBlocklet({ did: appPid, didDomain: nodeInfo.didDomain });
-  const domainAliases = get(blocklet, 'site.domainAliases') || [];
-
-  let didDomain = domainAliases.find((item) => toLower(item.value) === toLower(pidDomain));
-
-  if (!didDomain) {
-    didDomain = domainAliases.find(
-      (item) => item.value.endsWith(nodeInfo.didDomain) || item.value.endsWith('did.staging.arcblock.io') // did.staging.arcblock.io 是旧 did domain, 但主要存在于比较旧的节点中, 需要做兼容
-    );
-  }
-
-  const appUrl = didDomain ? prettyURL(didDomain.value, true) : `https://${pidDomain}`;
-
-  return {
-    BLOCKLET_DID: did, // BLOCKLET_DID is always same as BLOCKLET_APP_PID in structV2 application
-    BLOCKLET_APP_PK: appPk,
-    BLOCKLET_APP_SK: appSk,
-    BLOCKLET_APP_ID: appId,
-    BLOCKLET_APP_PSK: appPsk, // permanent sk even the blocklet has been migrated
-    BLOCKLET_APP_PID: appPid, // permanent did even the blocklet has been migrated
-    BLOCKLET_APP_NAME: appName,
-    BLOCKLET_APP_NAME_SLUG: urlPathFriendly(slugify(appName)),
-    BLOCKLET_APP_DESCRIPTION: appDescription,
-    BLOCKLET_APP_URL: appUrl,
-    BLOCKLET_APP_DATA_DIR: path.join(dataDirs.data, blocklet.meta.name),
-    BLOCKLET_APP_TENANT_MODE: result.tenantMode || BLOCKLET_TENANT_MODES.SINGLE,
-    BLOCKLET_APP_SALT: blocklet.settings?.session?.salt || '',
-  };
-};
-
-const getAppOverwrittenEnvironments = (blocklet, nodeInfo) => {
-  const result = {};
-  if (!blocklet || !blocklet.configObj) {
-    return result;
-  }
-
-  Object.keys(BLOCKLET_CONFIGURABLE_KEY).forEach((x) => {
-    if (!blocklet.configObj[x]) {
-      return;
-    }
-
-    result[x] = blocklet.configObj[x];
-  });
-
-  const keys = ['BLOCKLET_APP_SK', 'BLOCKLET_APP_CHAIN_TYPE', 'BLOCKLET_WALLET_TYPE'];
-  const isAppDidRewritten = keys.some((key) => blocklet.configObj[key]);
-  if (!isAppDidRewritten) {
-    return result;
-  }
-
-  // We use user configuration here without any validation since the validation is done during update phase
-  const { wallet } = getBlockletInfo(
-    {
-      meta: blocklet.meta,
-      environments: keys.map((key) => ({ key, value: blocklet.configObj[key] })).filter((x) => x.value),
-    },
-    nodeInfo.sk
-  );
-  result.BLOCKLET_APP_ID = wallet.address;
-
-  return result;
-};
-
-const getComponentSystemEnvironments = (blocklet) => {
-  const { port, ports } = blocklet;
-  const portEnvironments = {};
-  if (port) {
-    portEnvironments[BLOCKLET_DEFAULT_PORT_NAME] = port;
-  }
-
-  if (ports) {
-    Object.assign(portEnvironments, ports);
-  }
-
-  return {
-    BLOCKLET_REAL_DID: blocklet.env.id, // <appDid>/componentDid> e.g. xxxxx/xxxxx
-    BLOCKLET_REAL_NAME: blocklet.env.name,
-    BLOCKLET_COMPONENT_DID: blocklet.meta.did, // component meta did e.g. xxxxxx
-    BLOCKLET_COMPONENT_VERSION: blocklet.meta.version,
-    BLOCKLET_DATA_DIR: blocklet.env.dataDir,
-    BLOCKLET_LOG_DIR: blocklet.env.logsDir,
-    BLOCKLET_CACHE_DIR: blocklet.env.cacheDir,
-    BLOCKLET_APP_DIR: blocklet.env.appDir,
-    ...portEnvironments,
-  };
-};
-
-/**
- * set 'configs', configObj', 'environmentObj' to blocklet TODO
- * @param {*} blocklet
- * @param {*} configs
- * @param {*} options - Optional: { rootBlocklet, nodeInfo, dataDirs }
- */
-const fillBlockletConfigs = (blocklet, configs, options = {}) => {
-  blocklet.configs = configs || [];
-  blocklet.configObj = getBlockletConfigObj(blocklet);
-  blocklet.environments = blocklet.environments || [];
-  blocklet.environmentObj = blocklet.environments.reduce((acc, x) => {
-    acc[x.key] = templateReplace(x.value, blocklet);
-    return acc;
-  }, {});
-
-  // After migration: ensure all component system environments are set from blocklet.env if available
-  // This ensures children loaded from blocklet_children table have all required env vars in environmentObj
-  if (blocklet.env) {
-    try {
-      const componentSystemEnvs = getComponentSystemEnvironments(blocklet);
-      // Only set env vars that are not already set
-      Object.entries(componentSystemEnvs).forEach(([key, value]) => {
-        if (value !== undefined && value !== null && !blocklet.environmentObj[key]) {
-          blocklet.environmentObj[key] = value;
-        }
-      });
-    } catch (error) {
-      // If getting component system environments fails, log warning but continue
-      logger.warn('fillBlockletConfigs: failed to get component system environments', {
-        blockletDid: blocklet.meta?.did,
-        error: error.message,
-      });
-    }
-  }
-
-  // For children: also set app-level environment variables from root blocklet
-  // This ensures children have app-level env vars like BLOCKLET_APP_ID
-  const { rootBlocklet, nodeInfo, dataDirs } = options;
-  if (rootBlocklet && nodeInfo && dataDirs && blocklet !== rootBlocklet) {
-    try {
-      const appSystemEnvs = getAppSystemEnvironments(rootBlocklet, nodeInfo, dataDirs);
-      const appOverwrittenEnvs = getAppOverwrittenEnvironments(rootBlocklet, nodeInfo);
-      // Only set env vars that are not already set
-      Object.entries({ ...appSystemEnvs, ...appOverwrittenEnvs }).forEach(([key, value]) => {
-        if (value !== undefined && value !== null && !blocklet.environmentObj[key]) {
-          blocklet.environmentObj[key] = value;
-        }
-      });
-    } catch (error) {
-      // If getting app system environments fails, log warning but continue
-      logger.warn('fillBlockletConfigs: failed to get app system environments', {
-        blockletDid: blocklet.meta?.did,
-        rootDid: rootBlocklet.meta?.did,
-        error: error.message,
-      });
-    }
-  }
-};
-
-const ensureBlockletExpanded = async (_meta, appDir) => {
-  const bundlePath = path.join(appDir, BLOCKLET_BUNDLE_FILE);
-  if (fs.existsSync(bundlePath)) {
-    try {
-      const nodeModulesPath = path.join(appDir, 'node_modules');
-      if (fs.existsSync(nodeModulesPath)) {
-        await fs.remove(nodeModulesPath);
-      }
-      await expandBundle(bundlePath, appDir);
-      await fs.remove(bundlePath);
-    } catch (err) {
-      throw new Error(`Failed to expand blocklet bundle: ${err.message}`);
-    }
-  }
-};
-
-const getRuntimeEnvironments = (blocklet, nodeEnvironments, ancestors, isGreen = false) => {
-  const root = (ancestors || [])[0] || blocklet;
-
-  const initialized = root?.settings?.initialized;
-
-  const environmentObj = { ...(blocklet.environmentObj || {}) };
-  if (isGreen && blocklet.greenPorts) {
-    Object.entries(blocklet.greenPorts).forEach(([key, value]) => {
-      if (!value) {
-        return;
-      }
-      environmentObj[key] = value;
-      if (key === BLOCKLET_DEFAULT_PORT_NAME || key === 'BLOCKLET_PORT') {
-        environmentObj[BLOCKLET_DEFAULT_PORT_NAME] = value;
-      }
-    });
-  }
-
-  // pm2 will force inject env variables of daemon process to blocklet process
-  // we can only rewrite these private env variables to empty
-  const safeNodeEnvironments = PRIVATE_NODE_ENVS.reduce((o, x) => {
-    o[x] = '';
-    return o;
-  }, {});
-
-  // get devEnvironments, when blocklet is in dev mode
-  const devEnvironments =
-    blocklet.mode === BLOCKLET_MODES.DEVELOPMENT
-      ? {
-          BLOCKLET_DEV_MOUNT_POINT: blocklet?.mountPoint || '',
-        }
-      : {};
-
-  // BLOCKLET_DEV_PORT should NOT in components of production mode
-  if (process.env.BLOCKLET_DEV_PORT) {
-    devEnvironments.BLOCKLET_DEV_PORT =
-      blocklet.mode === BLOCKLET_MODES.DEVELOPMENT ? process.env.BLOCKLET_DEV_PORT : '';
-  }
-
-  const ports = {};
-  forEachBlockletSync(root, (x) => {
-    const webInterface = findWebInterface(x);
-    const envObj = x.meta?.did === blocklet.meta?.did ? environmentObj : x.environmentObj;
-    if (webInterface && envObj?.[webInterface.port]) {
-      ports[envObj.BLOCKLET_REAL_NAME] = envObj[webInterface.port];
-    }
-  });
-
-  const componentsInternalInfo = getComponentsInternalInfo(root);
-
-  // use index 1 as the path to derive deterministic encryption key for blocklet
-  const tmp = get(nodeEnvironments, 'ABT_NODE_SK')
-    ? getBlockletWallet(blocklet.meta.did, nodeEnvironments.ABT_NODE_SK, undefined, 1)
-    : null;
-
-  // For Access Key authentication, components should use root app's wallet
-  // This ensures consistent accessKeyId across parent and child components
-  const accessWallet = get(nodeEnvironments, 'ABT_NODE_SK')
-    ? getBlockletWallet(root.appDid || root.meta.did, nodeEnvironments.ABT_NODE_SK, undefined, 2)
-    : null;
-
-  const BLOCKLET_APP_IDS = getBlockletAppIdList(root).join(',');
-
-  const componentApiKey = getComponentApiKey({
-    serverSk: nodeEnvironments.ABT_NODE_SK,
-    app: root,
-    component: blocklet,
-  });
-
-  const blockletInfo = getBlockletInfo(blocklet, nodeEnvironments.ABT_NODE_SK, { returnWallet: true });
-
-  const rootBlockletInfo =
-    blocklet === root ? blockletInfo : getBlockletInfo(root, nodeEnvironments.ABT_NODE_SK, { returnWallet: true });
-
-  const { wallet } = rootBlockletInfo;
-  const appSk = toHex(wallet.secretKey);
-  const appPk = toHex(wallet.publicKey);
-
-  const ethWallet = fromSecretKey(appSk.slice(0, 66), 'ethereum');
-  const ethPk = toHex(ethWallet.publicKey);
-
-  const isMigrated = Array.isArray(root.migratedFrom) && root.migratedFrom.length > 0;
-  const appPsk = toHex(isMigrated ? root.migratedFrom[0].appSk : appSk);
-
-  // Calculate permanent public key (PPK)
-  const appPpk = isMigrated ? toHex(fromSecretKey(appPsk, wallet.type).publicKey) : appPk;
-  const ethPermanentWallet = fromSecretKey(appPsk.slice(0, 66), 'ethereum');
-  const appPpkEth = toHex(ethPermanentWallet.publicKey);
-
-  const env = {
-    ...blocklet.configObj,
-    ...getSharedConfigObj((ancestors || [])[0], blocklet, true),
-    ...environmentObj,
-    ...devEnvironments,
-    BLOCKLET_MOUNT_POINTS: JSON.stringify(componentsInternalInfo),
-    BLOCKLET_MODE: blocklet.mode || BLOCKLET_MODES.PRODUCTION,
-    BLOCKLET_APP_EK: tmp?.secretKey,
-    // for login token authentication
-    BLOCKLET_SESSION_SECRET: rootBlockletInfo.secret,
-    BLOCKLET_APP_VERSION: root.meta.version,
-    BLOCKLET_APP_IDS,
-    BLOCKLET_COMPONENT_API_KEY: componentApiKey,
-    BLOCKLET_APP_ASK: accessWallet?.secretKey,
-    ...nodeEnvironments,
-    ...safeNodeEnvironments,
-    BLOCKLET_APP_PPK: appPpk, // permanent pk corresponding to PSK
-    BLOCKLET_APP_PPK_ETH: appPpkEth, // permanent pk corresponding to PSK for ethereum
-    BLOCKLET_APP_PK: appPk,
-    BLOCKLET_APP_PK_ETH: ethPk,
-  };
-
-  const aigne = get(root, 'settings.aigne', {});
-  const salt = root.meta.did || AIGNE_CONFIG_ENCRYPT_SALT;
-  if (!isNil(aigne) && aigne.provider) {
-    const { key, accessKeyId, secretAccessKey, provider } = aigne;
-    const selectedModel = !aigne.model || aigne.model === 'auto' ? undefined : aigne.model;
-    env.BLOCKLET_AIGNE_API_MODEL = selectedModel;
-    env.BLOCKLET_AIGNE_API_PROVIDER = aigne.provider;
-    const credential = {
-      apiKey: key ? decrypt(key, salt, '') : key || '',
-      accessKeyId: accessKeyId && provider === 'bedrock' ? decrypt(accessKeyId, salt, '') : accessKeyId || '',
-      secretAccessKey:
-        secretAccessKey && provider === 'bedrock' ? decrypt(secretAccessKey, salt, '') : secretAccessKey || '',
-    };
-    env.BLOCKLET_AIGNE_API_CREDENTIAL = JSON.stringify(credential);
-    env.BLOCKLET_AIGNE_API_URL = aigne.url || '';
-  }
-
-  if (root?.environmentObj?.BLOCKLET_APP_DATA_DIR) {
-    env.BLOCKLET_APP_SHARE_DIR = path.join(root.environmentObj.BLOCKLET_APP_DATA_DIR, '.share');
-    env.BLOCKLET_SHARE_DIR = path.join(root.environmentObj.BLOCKLET_APP_DATA_DIR, '.share', blocklet.meta.did);
-    if (!fs.existsSync(env.BLOCKLET_APP_SHARE_DIR) && process.env.ABT_NODE_DATA_DIR) {
-      fs.mkdirSync(env.BLOCKLET_APP_SHARE_DIR, { recursive: true });
-    }
-  }
-
-  if (initialized) {
-    env.initialized = initialized;
-  }
-
-  if (isGreen && blocklet.greenPorts?.[BLOCKLET_DEFAULT_PORT_NAME]) {
-    env[BLOCKLET_DEFAULT_PORT_NAME] = blocklet.greenPorts[BLOCKLET_DEFAULT_PORT_NAME];
-  }
-
-  // ensure all envs are literals and do not contain line breaks
-  Object.keys(env).forEach((key) => {
-    env[key] = formatEnv(env[key]);
-  });
-
-  return env;
-};
-
-const isUsefulError = (err) =>
-  err &&
-  err.message !== 'process or namespace not found' &&
-  !/id unknown/.test(err.message) &&
-  !/^Process \d+ not found$/.test(err.message);
-
-const getHealthyCheckTimeout = (blocklet, { checkHealthImmediately, componentDids } = {}) => {
-  let minConsecutiveTime = 3000;
-  if (process.env.NODE_ENV === 'test' && process.env.ABT_NODE_TEST_MIN_CONSECUTIVE_TIME !== undefined) {
-    minConsecutiveTime = +process.env.ABT_NODE_TEST_MIN_CONSECUTIVE_TIME;
-  } else if (checkHealthImmediately) {
-    minConsecutiveTime = 3000;
-  }
-
-  if (process.env.BLOCKLET_START_TIMEOUT) {
-    return {
-      startTimeout: +process.env.BLOCKLET_START_TIMEOUT * 1000,
-      minConsecutiveTime,
-    };
-  }
-  if (blocklet.mode === BLOCKLET_MODES.DEVELOPMENT) {
-    return {
-      startTimeout: 3600 * 1000,
-      minConsecutiveTime: 3000,
-    };
-  }
-
-  const children = componentDids?.length
-    ? blocklet.children.filter((child) => componentDids.includes(child.meta.did))
-    : blocklet.children;
-
-  // Let's wait for at least 1 minute for the blocklet to go live
-  let startTimeout =
-    Math.max(
-      get(blocklet, 'meta.timeout.start', 60),
-      ...(children || []).map((child) => child.meta?.timeout?.start || 0)
-    ) * 1000;
-
-  if (process.env.NODE_ENV === 'test') {
-    startTimeout = 10 * 1000;
-  }
-
-  return {
-    startTimeout,
-    minConsecutiveTime,
-  };
-};
-
-/**
- * Start all precesses of a blocklet
- * @param {*} blocklet should contain env props
- */
-const startBlockletProcess = async (
-  blocklet,
-  {
-    preFlight = noop,
-    preStart = noop,
-    postStart = noopAsync,
-    nodeEnvironments,
-    nodeInfo,
-    e2eMode,
-    skippedProcessIds = [],
-    componentDids,
-    configSynchronizer,
-    onlyStart = false,
-    isGreen = false,
-  } = {}
-) => {
-  if (!blocklet) {
-    throw new Error('blocklet should not be empty');
-  }
-
-  const dockerNetworkName = parseDockerName(blocklet?.meta?.did, 'docker-network');
-  await createDockerNetwork(dockerNetworkName);
-
-  blocklet.children.forEach((component) => {
-    if (!componentDids.includes(component.meta.did)) {
-      return;
-    }
-    for (const envItem of component.environments) {
-      const envKey = envItem.key || envItem.name;
-      if (envKey !== 'BLOCKLET_PORT') {
-        continue;
-      }
-      if (isGreen) {
-        if (component.greenPorts?.BLOCKLET_PORT) {
-          envItem.value = component.greenPorts.BLOCKLET_PORT;
-        }
-      } else if (component.ports?.BLOCKLET_PORT) {
-        envItem.value = component.ports.BLOCKLET_PORT;
-      }
-    }
-  });
-
-  const startBlockletTask = async (b, { ancestors }) => {
-    // 需要在在这里传入字符串类型，否则进程中如法转化成 Date 对象
-    const now = `${new Date()}`;
-    if (b.meta.group === BlockletGroup.gateway) {
-      return;
-    }
-
-    if (!hasStartEngine(b.meta)) {
-      return;
-    }
-
-    const { processId, logsDir, appDir } = b.env;
-
-    if (skippedProcessIds.includes(processId)) {
-      logger.info('skip start skipped process', { processId });
-      return;
-    }
-
-    // eslint-disable-next-line no-use-before-define
-    if (shouldSkipComponent(b.meta.did, componentDids)) {
-      logger.info('skip start process not selected', { processId });
-      return;
-    }
-
-    if (b.mode !== BLOCKLET_MODES.DEVELOPMENT) {
-      validateBlockletEntry(appDir, b.meta);
-    }
-
-    const { cwd, script, args, environmentObj, interpreter, interpreterArgs } = getComponentStartEngine(b, {
-      e2eMode,
-    });
-    if (!script) {
-      logger.info('skip start process without script', { processId });
-      return;
-    }
-
-    // get env
-    const env = getRuntimeEnvironments(b, nodeEnvironments, ancestors, isGreen);
-    const startedAt = Date.now();
-
-    await installExternalDependencies({ appDir: env?.BLOCKLET_APP_DIR, nodeInfo });
-    await preFlight(b, { env: { ...env } });
-    await preStart(b, { env: { ...env } });
-
-    // kill process if port is occupied
-    try {
-      const { ports, greenPorts } = b;
-      await killProcessOccupiedPorts({
-        ports: isGreen ? greenPorts : ports,
-        pm2ProcessId: processId,
-        printError: logger.error.bind(logger),
-      });
-    } catch (error) {
-      logger.error('Failed to killProcessOccupiedPorts', { error });
-    }
-
-    // start process
-    const maxMemoryRestart = get(nodeInfo, 'runtimeConfig.blockletMaxMemoryLimit', BLOCKLET_MAX_MEM_LIMIT_IN_MB);
-    const processIdName = isGreen ? `${processId}-green` : processId;
-    /**
-     * @type {pm2.StartOptions}
-     */
-    const options = {
-      namespace: 'blocklets',
-      name: processIdName,
-      cwd,
-      log_date_format: '(YYYY-MM-DD HH:mm:ss)',
-      output: path.join(logsDir, 'output.log'),
-      error: path.join(logsDir, 'error.log'),
-      // wait_ready: process.env.NODE_ENV !== 'test',
-      wait_ready: false,
-      listen_timeout: 3000,
-      max_memory_restart: `${maxMemoryRestart}M`,
-      max_restarts: b.mode === BLOCKLET_MODES.DEVELOPMENT ? 0 : 3,
-      min_uptime: 10_000,
-      exp_backoff_restart_delay: 300,
-      env: omit(
-        {
-          ...environmentObj,
-          ...env,
-          NODE_ENV: 'production',
-          BLOCKLET_START_AT: now,
-          NODE_OPTIONS: await getSecurityNodeOptions(b, nodeInfo.enableFileSystemIsolation),
-        },
-        // should only inject appSk and appPsk to the blocklet environment when unsafe mode enabled
-        ['1', 1].includes(env.UNSAFE_MODE) ? [] : ['BLOCKLET_APP_SK', 'BLOCKLET_APP_PSK']
-      ),
-      script,
-      args,
-      interpreter,
-      interpreterArgs,
-    };
-
-    const clusterMode = get(b.meta, 'capabilities.clusterMode', false);
-    if (clusterMode && b.mode !== BLOCKLET_MODES.DEVELOPMENT) {
-      const clusterSize = Number(blocklet.configObj.BLOCKLET_CLUSTER_SIZE) || +process.env.ABT_NODE_MAX_CLUSTER_SIZE;
-      options.execMode = 'cluster';
-      options.mergeLogs = true;
-      options.instances = Math.max(Math.min(os.cpus().length, clusterSize), 1);
-      options.env.BLOCKLET_CLUSTER_SIZE = options.instances;
-      if (options.instances !== clusterSize) {
-        logger.warn(`Fallback cluster size to ${options.instances} for ${processId}, ignore custom ${clusterSize}`);
-      }
-    } else {
-      delete options.env.BLOCKLET_CLUSTER_SIZE;
-    }
-
-    if (b.mode === BLOCKLET_MODES.DEVELOPMENT) {
-      options.env.NODE_ENV = e2eMode ? 'e2e' : 'development';
-      options.env.IS_E2E = e2eMode ? '1' : undefined;
-      options.env.BROWSER = 'none';
-      options.env.PORT = options.env[BLOCKLET_DEFAULT_PORT_NAME];
-
-      if (process.platform === 'win32') {
-        const [cmd, ...argList] = options.script.split(' ').filter(Boolean);
-
-        if (!SCRIPT_ENGINES_WHITE_LIST.includes(cmd)) {
-          throw new Error(`${cmd} script is not supported, ${SCRIPT_ENGINES_WHITE_LIST.join(', ')} are supported`);
-        }
-
-        const { stdout: nodejsBinPath } = shelljs.which('node');
-
-        const cmdPath = path.join(path.dirname(nodejsBinPath), 'node_modules', cmd);
-
-        const pkg = JSON.parse(fs.readFileSync(path.join(cmdPath, 'package.json'), 'utf8'));
-        const cmdBinPath = pkg.bin[cmd];
-
-        options.script = path.resolve(cmdPath, cmdBinPath);
-        options.args = [...argList].join(' ');
-      }
-    }
-
-    await configSynchronizer.syncComponentConfig(b.meta.did, blocklet.meta.did, {
-      serverSk: nodeEnvironments.ABT_NODE_SK,
-    });
-
-    if (options.interpreter === 'bun') {
-      options.exec_interpreter = await ensureBun();
-      options.exec_mode = 'fork';
-      delete options.instances;
-      delete options.mergeLogs;
-    }
-
-    let nextOptions;
-    if (b.mode === BLOCKLET_MODES.DEVELOPMENT) {
-      nextOptions = options;
-    } else {
-      nextOptions = await parseDockerOptionsFromPm2({
-        options,
-        nodeInfo,
-        isExternal: isExternalBlocklet(b),
-        meta: b.meta,
-        ports: isGreen ? b.greenPorts : b.ports,
-        onlyStart,
-        dockerNetworkName,
-        rootBlocklet: blocklet,
-      });
-    }
-
-    await fetchPm2({ ...nextOptions, pmx: false }, nodeEnvironments.ABT_NODE_SK);
-
-    // eslint-disable-next-line no-use-before-define
-    const status = await getProcessState(processIdName);
-    if (status === BlockletStatus.error) {
-      throw new Error(`process ${processIdName} is not running within 3 seconds`);
-    }
-    logger.info('done start blocklet', { processId: processIdName, status, time: Date.now() - startedAt });
-
-    if (nextOptions.env.connectInternalDockerNetwork) {
-      try {
-        await promiseSpawn(nextOptions.env.connectInternalDockerNetwork, { mute: true });
-      } catch (err) {
-        logger.warn('blocklet connect internal docker network failed', { processId: processIdName, error: err });
-      }
-    }
-
-    // run hook
-    postStart(b, { env }).catch((err) => {
-      logger.error('blocklet post start failed', { processId: processIdName, error: err });
-    });
-  };
-
-  await forEachBlocklet(
-    blocklet,
-    /**
-     *
-     * @param {import('@blocklet/server-js').BlockletState} b
-     * @param {*} param1
-     * @returns
-     */
-    async (b, { ancestors }) => {
-      const lockName = `${blocklet.meta.did}-${b.meta.did}`;
-
-      // 如果锁存在，则跳过执行
-      if (!(await startLock.hasExpired(lockName))) {
-        return;
-      }
-      await startLock.acquire(lockName);
-
-      try {
-        await startBlockletTask(b, { ancestors });
-      } finally {
-        startLock.releaseLock(lockName);
-      }
-    },
-    { parallel: true, concurrencyLimit: 3 }
-  );
-};
-
 /**
- * Stop all precesses of a blocklet
- * @param {*} blocklet should contain env props
+ * Wrapper for startBlockletProcess - injects local dependencies
  */
-const stopBlockletProcess = (
-  blocklet,
-  { preStop = noop, skippedProcessIds = [], componentDids, isGreen = false, isStopGreenAndBlue = false } = {}
-) => {
-  // eslint-disable-next-line no-use-before-define
-  return deleteBlockletProcess(blocklet, {
-    preDelete: preStop,
-    skippedProcessIds,
-    componentDids,
-    isGreen,
-    isStopGreenAndBlue,
+const _startBlockletProcess = (blocklet, options = {}) => {
+  // eslint-disable-next-line global-require
+  const processManager = require('./blocklet/process-manager');
+  return processManager.startBlockletProcess(blocklet, {
+    ...options,
+    getComponentStartEngine,
+    getRuntimeEnvironments,
   });
 };
 
-/**
- * Delete all precesses of a blocklet
- * @param {*} blocklet should contain env props
- */
-const deleteBlockletProcess = async (
-  blocklet,
-  { preDelete = noop, skippedProcessIds = [], componentDids, isGreen = false, isStopGreenAndBlue = false } = {}
-) => {
-  await forEachBlocklet(
-    blocklet,
-    async (b, { ancestors }) => {
-      // NOTICE: 如果不判断 group, 在 github action 中测试 disk.spec.js 时会报错, 但是在 mac 中跑测试不会报错
-      if (b.meta?.group === BlockletGroup.gateway) {
-        return;
-      }
-
-      if (skippedProcessIds.includes(b.env.processId)) {
-        logger.info(`skip delete skipped process ${b.env.processId}`);
-        return;
-      }
-
-      // eslint-disable-next-line no-use-before-define
-      if (shouldSkipComponent(b.meta?.did, componentDids)) {
-        logger.info(`skip delete process not selected: ${b.meta.did}`, { processId: b.env.processId });
-        return;
-      }
-
-      if (!hasStartEngine(b.meta)) {
-        return;
-      }
-
-      // Skip deleting static-server engine processes since they were never started
-      if (b.meta?.group === 'static') {
-        return;
-      }
-      const engine = getBlockletEngine(b.meta);
-      if (engine.interpreter === 'blocklet' && engine.source?.name === STATIC_SERVER_ENGINE_DID) {
-        return;
-      }
-
-      await preDelete(b, { ancestors });
-      if (isStopGreenAndBlue) {
-        // eslint-disable-next-line no-use-before-define
-        await deleteProcess(`${b.env.processId}-green`);
-        // eslint-disable-next-line no-use-before-define
-        await deleteProcess(b.env.processId);
-        return;
-      }
-      const processId = isGreen ? `${b.env.processId}-green` : b.env.processId;
-      // eslint-disable-next-line no-use-before-define
-      await deleteProcess(processId);
-    },
-    { parallel: true }
-  );
-};
-
-/**
- * Reload all precesses of a blocklet
- * @param {*} blocklet should contain env props
- */
-const reloadBlockletProcess = (blocklet, { componentDids } = {}) =>
-  forEachBlocklet(
-    blocklet,
-    async (b) => {
-      if (b.meta.group === BlockletGroup.gateway) {
-        return;
-      }
-
-      // eslint-disable-next-line no-use-before-define
-      if (shouldSkipComponent(b.meta.did, componentDids)) {
-        logger.info('skip reload process', { processId: b.env.processId });
-        return;
-      }
-
-      // Skip reloading static-server engine processes since they were never started
-      if (b.meta?.group === 'static') {
-        return;
-      }
-      const engine = getBlockletEngine(b.meta);
-      if (engine.interpreter === 'blocklet' && engine.source?.name === STATIC_SERVER_ENGINE_DID) {
-        return;
-      }
+const {
+  stopBlockletProcess: _stopBlockletProcess,
+  deleteBlockletProcess: _deleteBlockletProcess,
+  reloadBlockletProcess: _reloadBlockletProcess,
+} = require('./blocklet/process-manager');
 
-      // eslint-disable-next-line no-use-before-define
-      await reloadProcess(b.env.processId);
-      logger.info('done reload process', { processId: b.env.processId });
-    },
-    { parallel: false }
-  );
+const validateBlocklet = (blocklet) => _validateBlocklet(blocklet, getBlockletEngineNameByPlatform);
 
 /**
- * @param {*} processId
- * @returns {BlockletStatus}
+ * Wrapper for checkBlockletProcessHealthy - injects local dependency findInterfacePortByName
  */
-const getProcessState = async (processId) => {
-  // eslint-disable-next-line no-use-before-define
-  const info = await getProcessInfo(processId);
-  if (!statusMap[info.pm2_env.status]) {
-    logger.error('Cannot find the blocklet status for pm2 status mapping', {
-      pm2Status: info.pm2_env.status,
-    });
-
-    return BlockletStatus.error;
-  }
-
-  return statusMap[info.pm2_env.status];
-};
-
-const getProcessInfo = (processId, { throwOnNotExist = true, timeout = 10_000 } = {}) =>
-  getPm2ProcessInfo(processId, { printError: logger.error.bind(logger), throwOnNotExist, timeout });
-
-const deleteProcess = (processId) => {
-  return new Promise((resolve, reject) => {
-    pm2.delete(processId, async (err) => {
-      if (isUsefulError(err)) {
-        logger.error('blocklet process delete failed', { processId, error: err });
-        return reject(err);
-      }
-      await dockerRemoveByName(processId);
-      return resolve(processId);
-    });
-  });
-};
-
-const reloadProcess = (processId) =>
-  new Promise((resolve, reject) => {
-    pm2.reload(processId, (err) => {
-      if (err) {
-        if (isUsefulError(err)) {
-          logger.error('blocklet reload failed', { processId, error: err });
-        }
-        return reject(err);
-      }
-      return resolve(processId);
-    });
-  });
-
-const validateBlocklet = (blocklet) =>
-  forEachComponentV2(blocklet, (b) => {
-    isRequirementsSatisfied(b.meta.requirements);
-    validateEngine(getBlockletEngineNameByPlatform(b.meta));
-  });
-
-const validateBlockletChainInfo = (blocklet) => {
-  const chainInfo = getChainInfo({
-    CHAIN_TYPE: blocklet.configObj[BLOCKLET_CONFIGURABLE_KEY.BLOCKLET_APP_CHAIN_TYPE],
-    CHAIN_ID: blocklet.configObj[BLOCKLET_CONFIGURABLE_KEY.BLOCKLET_APP_CHAIN_ID],
-    CHAIN_HOST: blocklet.configObj[BLOCKLET_CONFIGURABLE_KEY.BLOCKLET_APP_CHAIN_HOST],
+const checkBlockletProcessHealthy = (blocklet, options = {}) =>
+  _checkBlockletProcessHealthy(blocklet, {
+    ...options,
+    findInterfacePortByName,
   });
 
-  const { error } = chainInfoSchema.validate(chainInfo);
-  if (error) {
-    throw error;
-  }
-
-  return chainInfo;
-};
-
-const _checkProcessHealthy = async (
-  blocklet,
-  { minConsecutiveTime, timeout, logToTerminal, isGreen = false, appDid }
-) => {
-  const { meta, ports, greenPorts, env } = blocklet;
-  const { name } = meta;
-  const processId = isGreen ? `${env.processId}-green` : env.processId;
-
-  const webInterface = (meta.interfaces || []).find((x) => x.type === BLOCKLET_INTERFACE_TYPE_WEB);
-  const dockerInterface = (meta.interfaces || []).find((x) => x.type === BLOCKLET_INTERFACE_TYPE_DOCKER);
-
-  if (!webInterface && !dockerInterface) {
-    // TODO: how do we check healthy for service interfaces
-    throw new Error(`Blocklet ${name} does not have any web interface`);
-  }
-
-  try {
-    // ensure pm2 status is 'online'
-    const getStatus = async () => {
-      try {
-        const info = await getProcessInfo(processId, { timeout: 3_000 });
-        return { status: info.pm2_env.status, envPort: info.pm2_env.BLOCKLET_PORT };
-      } catch (err) {
-        logger.error('blocklet checkStart error', { appDid, error: err, processId, name });
-        return { status: '', envPort: null };
-      }
-    };
-
-    // eslint-disable-next-line prefer-const
-    let { status, envPort } = await getStatus();
-
-    for (let i = 0; i < 20 && status !== 'online'; i++) {
-      const t = process.env.NODE_ENV !== 'test' ? 500 : 30;
-      await sleep(t);
-      ({ status, envPort } = await getStatus());
-    }
-
-    if (status !== 'online') {
-      throw new Error('process not start within 10s');
-    }
-
-    // ⚠️ 关键修复：优先从进程实际监听的端口获取
-    // 对于 Docker 容器，从 Docker 端口映射获取实际端口
-    // 这样可以避免端口刷新后，健康检查使用错误的端口
-    const actualPort = await getActualListeningPort(processId, blocklet);
-
-    // 端口优先级：实际端口 > pm2 环境变量端口 > 数据库中的端口
-    const port =
-      actualPort ||
-      envPort ||
-      findInterfacePortByName({ meta, ports: isGreen ? greenPorts : ports }, (webInterface || dockerInterface).name);
-
-    if (logToTerminal) {
-      // eslint-disable-next-line no-console
-      logger.info(
-        // eslint-disable-next-line no-nested-ternary
-        `Checking endpoint healthy for ${meta.title}, port: ${port}${actualPort ? ' (actual)' : envPort ? ' (from pm2 env)' : ' (from db)'}, minConsecutiveTime: ${
-          minConsecutiveTime / 1000
-        }s, timeout: ${timeout / 1000}s`
-      );
-    }
-
-    if (
-      actualPort &&
-      actualPort !== envPort &&
-      actualPort !==
-        (isGreen
-          ? greenPorts?.[webInterface?.port || dockerInterface?.port]
-          : ports?.[webInterface?.port || dockerInterface?.port])
-    ) {
-      logger.info('Port mismatch detected, using actual port for health check', {
-        processId,
-        appDid,
-        actualPort,
-        envPort,
-        dbPort: isGreen
-          ? greenPorts?.[webInterface?.port || dockerInterface?.port]
-          : ports?.[webInterface?.port || dockerInterface?.port],
-      });
-    }
-
-    try {
-      await ensureEndpointHealthy({
-        port,
-        protocol: webInterface ? 'http' : 'tcp',
-        minConsecutiveTime,
-        timeout,
-        doConsecutiveCheck: blocklet.mode !== BLOCKLET_MODES.DEVELOPMENT,
-        waitTCP: !webInterface,
-        shouldAbort: async () => {
-          // Check if pm2 process exists and is online
-          try {
-            const info = await getProcessInfo(processId, { timeout: 3_000 });
-            const currentStatus = info.pm2_env.status;
-            if (currentStatus !== 'online') {
-              throw new Error(`pm2 process ${processId} status is ${currentStatus}, not online`);
-            }
-          } catch (err) {
-            // If process doesn't exist or has error, abort immediately
-            logger.error('pm2 process check failed in shouldAbort', { appDid, error: err, processId, name });
-            const isProcessNotExist =
-              err.message &&
-              (err.message.includes('not found') ||
-                err.message.includes('does not exist') ||
-                err.message.includes('not running'));
-            if (isProcessNotExist) {
-              throw new Error(`pm2 process ${processId} (${name}) died or does not exist: ${err.message}`);
-            }
-            throw new Error(`pm2 process ${processId} (${name}) check failed: ${err.message}`);
-          }
-        },
-      });
-    } catch (error) {
-      const isProcessDead =
-        error.message &&
-        (error.message.includes('pm2 process') ||
-          error.message.includes('died') ||
-          error.message.includes('does not exist'));
-      if (isProcessDead) {
-        logger.error('blocklet process died during health check', {
-          appDid,
-          processId,
-          name,
-          port,
-          error: error.message,
-        });
-        throw error;
-      }
-      logger.error('ensure endpoint healthy failed', {
-        appDid,
-        port,
-        minConsecutiveTime,
-        timeout,
-        error: error.message,
-      });
-      throw error;
-    }
-  } catch (error) {
-    logger.error('start blocklet failed', { processId, name });
-    throw error;
-  }
-};
-
-const checkBlockletProcessHealthy = async (
-  blocklet,
-  { minConsecutiveTime, timeout, componentDids, setBlockletRunning, isGreen = false, appDid } = {}
-) => {
-  // if (process.env.NODE_ENV === 'test' && process.env.ABT_NODE_TEST_MIN_CONSECUTIVE_TIME) {
-  //   // need bigger than minConsecutiveTime in test env
-  //   // eslint-disable-next-line no-param-reassign
-  //   timeout = Math.max(+process.env.ABT_NODE_TEST_MIN_CONSECUTIVE_TIME * 10, minConsecutiveTime + 3000);
-  // }
-  await forEachBlocklet(
-    blocklet,
-    async (b) => {
-      if (b.meta.group === BlockletGroup.gateway) {
-        return;
-      }
-
-      // components that relies on another engine component should not be checked
-      const engine = getBlockletEngine(b.meta);
-      if (engine.interpreter === 'blocklet') {
-        return;
-      }
-
-      if (!hasStartEngine(b.meta)) {
-        return;
-      }
-
-      // eslint-disable-next-line no-use-before-define
-      if (shouldSkipComponent(b.meta.did, componentDids)) {
-        logger.info('skip check component healthy', { processId: b.env.processId });
-        return;
-      }
-
-      const logToTerminal = [blocklet.mode, b.mode].includes(BLOCKLET_MODES.DEVELOPMENT);
-
-      const startedAt = Date.now();
-
-      await _checkProcessHealthy(b, { minConsecutiveTime, timeout, logToTerminal, isGreen, appDid });
-
-      logger.info('done check component healthy', { processId: b.env.processId, time: Date.now() - startedAt });
-
-      if (setBlockletRunning) {
-        try {
-          await setBlockletRunning(b.meta.did);
-        } catch (error) {
-          logger.error(`Failed to set blocklet as running for DID: ${b.meta.name || b.meta.did}`, { error });
-        }
-      }
-    },
-    { parallel: true }
-  );
-};
-
-const shouldCheckHealthy = (blocklet) => {
-  if (blocklet.meta.group === BlockletGroup.gateway) {
-    return false;
-  }
-
-  // components that relies on another engine component should not be checked
-  const engine = getBlockletEngine(blocklet.meta);
-  if (engine.interpreter === 'blocklet') {
-    return false;
-  }
-
-  return hasStartEngine(blocklet.meta);
-};
-
-const isBlockletPortHealthy = async (blocklet, { minConsecutiveTime = 3000, timeout = 10 * 1000 } = {}) => {
-  if (!blocklet) {
-    return;
-  }
-  const { environments } = blocklet;
-  const webInterface = (blocklet.meta?.interfaces || []).find((x) => x.type === BLOCKLET_INTERFACE_TYPE_WEB);
-  const dockerInterface = (blocklet.meta?.interfaces || []).find((x) => x.type === BLOCKLET_INTERFACE_TYPE_DOCKER);
-  const key = webInterface?.port || dockerInterface?.port || 'BLOCKLET_PORT';
-
-  let port = blocklet.greenStatus === BlockletStatus.running ? blocklet.greenPorts?.[key] : blocklet.ports?.[key];
-
-  if (!port) {
-    const keyPort = webInterface?.port || dockerInterface?.port;
-    port = environments?.find((e) => e.key === keyPort)?.value;
-  }
-
-  if (!port) {
-    return;
-  }
-
-  await ensureEndpointHealthy({
-    port,
-    protocol: webInterface ? 'http' : 'tcp',
-    minConsecutiveTime,
-    timeout,
-    doConsecutiveCheck: false,
-  });
-};
-
-const expandTarball = async ({ source, dest, strip = 1 }) => {
-  logger.info('expand blocklet', { source, dest });
-
-  if (!fs.existsSync(source)) {
-    throw new Error(`Blocklet tarball ${source} does not exist`);
-  }
-
-  fs.mkdirSync(dest, { recursive: true });
-
-  await streamToPromise(
-    fs
-      .createReadStream(source)
-      .pipe(new Throttle({ rate: 1024 * 1024 * 20 })) // 20MB
-      .pipe(tar.x({ C: dest, strip }))
-  );
-
-  return dest;
-};
-
-const verifyIntegrity = async ({ file, integrity: expected }) => {
-  const stream = fs.createReadStream(file);
-  const result = await ssri.checkStream(stream, ssri.parse(expected));
-  logger.debug('verify integrity result', { result });
-  stream.destroy();
-  return true;
-};
-
-/**
- * @param {string} installDir
- * @returns {Promise<Array<{ key: string, dir: string }>>} key is <[scope/]name/version>, dir is appDir
- */
-const getAppDirs = async (installDir) => {
-  const appDirs = [];
-
-  const getNextLevel = (level, name) => {
-    if (level === 'root') {
-      if (name.startsWith('@')) {
-        return 'scope';
-      }
-      return 'name';
-    }
-    if (level === 'scope') {
-      return 'name';
-    }
-    if (level === 'name') {
-      return 'version';
-    }
-    throw new Error(`Invalid level ${level}`);
-  };
-
-  const fillAppDirs = async (dir, level = 'root') => {
-    if (level === 'version') {
-      appDirs.push({
-        key: formatBackSlash(path.relative(installDir, dir)),
-        dir,
-      });
-
-      return;
-    }
-
-    const nextDirs = [];
-    for (const x of await fs.promises.readdir(dir)) {
-      if (!fs.lstatSync(path.join(dir, x)).isDirectory()) {
-        logger.error('pruneBlockletBundle: invalid file in bundle storage', { dir, file: x });
-        // eslint-disable-next-line no-continue
-        continue;
-      }
-      nextDirs.push(x);
-    }
-
-    for (const x of nextDirs) {
-      await fillAppDirs(path.join(dir, x), getNextLevel(level, x));
-    }
-  };
-
-  await fillAppDirs(installDir, 'root');
-
-  return appDirs;
-};
-
-const pruneBlockletBundle = async ({ blocklets, installDir, blockletSettings }) => {
-  for (const blocklet of blocklets) {
-    if (
-      [
-        BlockletStatus.waiting,
-        BlockletStatus.installing,
-        BlockletStatus.upgrading,
-        BlockletStatus.downloading,
-      ].includes(blocklet.status)
-    ) {
-      logger.info('There are blocklet activities in progress, abort pruning', {
-        bundleName: blocklet.meta.bundleName,
-        status: fromBlockletStatus(blocklet.status),
-      });
-      return;
-    }
-  }
-
-  // blockletMap: { <[scope/]name/version>: true }
-  const blockletMap = {};
-  for (const blocklet of blocklets) {
-    forEachBlockletSync(blocklet, (component) => {
-      blockletMap[`${component.meta.bundleName}/${component.meta.version}`] = true;
-      blockletMap[`${component.meta.bundleName}/${getVersionScope(component.meta)}`] = true;
-    });
-  }
-  for (const setting of blockletSettings) {
-    for (const child of setting.children || []) {
-      if (child.status !== BlockletStatus.deleted) {
-        forEachBlockletSync(child, (component) => {
-          blockletMap[`${component.meta.bundleName}/${component.meta.version}`] = true;
-          blockletMap[`${component.meta.bundleName}/${getVersionScope(component.meta)}`] = true;
-        });
-      }
-    }
-  }
-
-  // fill appDirs
-  let appDirs = [];
-  try {
-    appDirs = await getAppDirs(installDir);
-  } catch (error) {
-    logger.error('fill app dirs failed', { error });
-  }
-
-  const ensureBundleDirRemoved = async (dir) => {
-    const relativeDir = path.relative(installDir, dir);
-    const arr = relativeDir.split(path.sep).filter(Boolean);
-    const { length } = arr;
-    const bundleName = arr[length - 2];
-    const scopeName = length > 2 ? arr[length - 3] : '';
-    const bundleDir = path.join(installDir, scopeName, bundleName);
-    const isDirEmpty = (await fs.promises.readdir(bundleDir)).length === 0;
-    if (isDirEmpty) {
-      logger.info('Remove bundle folder', { bundleDir });
-      await fs.remove(bundleDir);
-    }
-    if (scopeName) {
-      const scopeDir = path.join(installDir, scopeName);
-      const isScopeEmpty = (await fs.promises.readdir(scopeDir)).length === 0;
-      if (isScopeEmpty) {
-        logger.info('Remove scope folder', { scopeDir });
-        await fs.remove(scopeDir);
-      }
-    }
-  };
-
-  // remove trash
-  for (const app of appDirs) {
-    if (!blockletMap[app.key]) {
-      logger.info('Remove app folder', { dir: app.dir });
-      await fs.remove(app.dir);
-      await ensureBundleDirRemoved(app.dir);
-    }
-  }
-
-  logger.info('Blocklet source folder has been pruned');
-};
-
-const _diskInfoTasks = {};
-const _getDiskInfo = async (blocklet) => {
-  try {
-    const { env } = blocklet;
-    const [app, cache, log, data] = await Promise.all([
-      getFolderSize(env.appDir),
-      getFolderSize(env.cacheDir),
-      getFolderSize(env.logsDir),
-      getFolderSize(env.dataDir),
-    ]);
-    return { app, cache, log, data };
-  } catch (error) {
-    logger.error('Get disk info failed', { name: getDisplayName(blocklet), error });
-    return { app: 0, cache: 0, log: 0, data: 0 };
-  }
-};
-
-const getDiskInfo = (blocklet, { useFakeDiskInfo } = {}) => {
-  if (useFakeDiskInfo) {
-    return { app: 0, cache: 0, log: 0, data: 0 };
-  }
-
-  const { appDid } = blocklet;
-
-  // Cache disk info results for 5 minutes
-  _diskInfoTasks[appDid] ??= _getDiskInfo(blocklet).finally(() => {
-    setTimeout(
-      () => {
-        delete _diskInfoTasks[appDid];
-      },
-      5 * 60 * 1000
-    );
-  });
-
-  return new Promise((resolve) => {
-    _diskInfoTasks[appDid].then(resolve).catch(() => {
-      resolve({ app: 0, cache: 0, log: 0, data: 0 });
-    });
-  });
-};
-
-const getRuntimeInfo = async (processId) => {
-  const proc = await getProcessInfo(processId);
-  const dockerName = proc.pm2_env?.env?.dockerName;
-  if (dockerName) {
-    const dockerInfo = await getDockerRuntimeInfo(dockerName);
-    return {
-      ...dockerInfo,
-      pid: proc.pid,
-      uptime: proc.pm2_env ? Date.now() - Number(proc.pm2_env.pm_uptime) : 0,
-      port: proc.pm2_env ? proc.pm2_env.BLOCKLET_PORT : null,
-      status: proc.pm2_env ? proc.pm2_env.status : null,
-      runningDocker: !!dockerName,
-    };
-  }
-  return {
-    pid: proc.pid,
-    uptime: proc.pm2_env ? Date.now() - Number(proc.pm2_env.pm_uptime) : 0,
-    memoryUsage: proc.monit.memory,
-    cpuUsage: proc.monit.cpu,
-    status: proc.pm2_env ? proc.pm2_env.status : null,
-    port: proc.pm2_env ? proc.pm2_env.BLOCKLET_PORT : null,
-    runningDocker: false,
-  };
-};
-
-/**
- * merge services
- * from meta.children[].mountPoints[].services, meta.children[].services
- * to childrenMeta[].interfaces[].services
- *
- * @param {array<child>|object{children:array}} source e.g. [<config>] or { children: [<config>] }
- * @param {array<meta|{meta}>} childrenMeta e.g. [<meta>] or [{ meta: <meta> }]
- */
-
-const mergeMeta = (source, childrenMeta = []) => {
-  // configMap
-  const configMap = {};
-  (Array.isArray(source) ? source : getComponentConfig(source) || []).forEach((x) => {
-    configMap[x.name] = x;
-  });
-
-  // merge service from config to child meta
-  childrenMeta.forEach((child) => {
-    const childMeta = child.meta || child;
-    const config = configMap[childMeta.name];
-    if (!config) {
-      return;
-    }
-
-    (config.mountPoints || []).forEach((mountPoint) => {
-      if (!mountPoint.services) {
-        return;
-      }
-
-      const childInterface = childMeta.interfaces.find((y) => y.name === mountPoint.child.interfaceName);
-      if (childInterface) {
-        // merge
-        const services = childInterface.services || [];
-        mountPoint.services.forEach((x) => {
-          const index = services.findIndex((y) => y.name === x.name);
-          if (index >= 0) {
-            services.splice(index, 1, x);
-          } else {
-            services.push(x);
-          }
-        });
-        childInterface.services = services;
-      }
-    });
-
-    if (config.services) {
-      const childInterface = findWebInterface(childMeta);
-      if (childInterface) {
-        // merge
-        const services = childInterface.services || [];
-        config.services.forEach((x) => {
-          const index = services.findIndex((y) => y.name === x.name);
-          if (index >= 0) {
-            services.splice(index, 1, x);
-          } else {
-            services.push(x);
-          }
-        });
-        childInterface.services = services;
-      }
-    }
-  });
-};
-
-const getUpdateMetaList = (oldBlocklet = {}, newBlocklet = {}) => {
-  const oldMap = {};
-  forEachChildSync(oldBlocklet, (b, { id }) => {
-    if (b.bundleSource) {
-      oldMap[id] = b.meta.version;
-    }
-  });
-
-  const res = [];
-
-  forEachChildSync(newBlocklet, (b, { id }) => {
-    if ((b.bundleSource && semver.gt(b.meta.version, oldMap[id])) || process.env.TEST_UPDATE_ALL_BLOCKLET === 'true') {
-      res.push({ id, meta: b.meta });
-    }
-  });
-
-  return res;
-};
-
-/**
- * @returns BLOCKLET_INSTALL_TYPE
- */
-const getTypeFromInstallParams = (params) => {
-  if (params.type) {
-    if (!Object.values(BLOCKLET_INSTALL_TYPE).includes(params.type)) {
-      throw new Error(`Can only install blocklet from ${Object.values(BLOCKLET_INSTALL_TYPE).join('/')}`);
-    }
-    return params.type;
-  }
-
-  if (params.url) {
-    return BLOCKLET_INSTALL_TYPE.URL;
-  }
-
-  if (params.file) {
-    throw new Error('install from upload is not supported');
-  }
-
-  if (params.did) {
-    return BLOCKLET_INSTALL_TYPE.STORE;
-  }
-
-  if (params.title && params.description) {
-    return BLOCKLET_INSTALL_TYPE.CREATE;
-  }
-
-  throw new Error(`Can only install blocklet from ${Object.values(BLOCKLET_INSTALL_TYPE).join('/')}`);
-};
-
-const checkDuplicateComponents = (components = []) => {
-  const duplicates = components.filter(
-    (item, index) => components.findIndex((x) => x.meta.did === item.meta.did) !== index
-  );
-  if (duplicates.length) {
-    throw new Error(
-      `Cannot add duplicate component${duplicates.length > 1 ? 's' : ''}: ${duplicates
-        .map((x) => getDisplayName(x, true))
-        .join(', ')}`
-    );
-  }
-};
-
-const getDiffFiles = async (inputFiles, sourceDir) => {
-  if (!fs.existsSync(sourceDir)) {
-    throw new Error(`${sourceDir} does not exist`);
-  }
-
-  const files = inputFiles.reduce((obj, item) => {
-    obj[item.file] = item.hash;
-    return obj;
-  }, {});
-
-  const { files: sourceFiles } = await hashFiles(sourceDir, {
-    filter: (x) => x.indexOf('node_modules') === -1,
-    concurrentHash: 1,
-  });
-
-  const addSet = [];
-  const changeSet = [];
-  const deleteSet = [];
-
-  const diffFiles = diff(sourceFiles, files);
-  if (diffFiles) {
-    diffFiles.forEach((item) => {
-      if (item.kind === 'D') {
-        deleteSet.push(item.path[0]);
-      }
-      if (item.kind === 'E') {
-        changeSet.push(item.path[0]);
-      }
-      if (item.kind === 'N') {
-        addSet.push(item.path[0]);
-      }
-    });
-  }
-
-  return {
-    addSet,
-    changeSet,
-    deleteSet,
-  };
-};
-
-const checkCompatibleOnce = {};
-
-// TODO: 梁柱， 这里为了兼容旧版的 blocklet，需要暂时保留，未来所有 blocklet 都使用新路径了可以删除
-const compatibleWithOldBlocklets = (dir) => {
-  if (checkCompatibleOnce[dir] !== undefined) {
-    return checkCompatibleOnce[dir];
-  }
-
-  checkCompatibleOnce[dir] = !!fs.existsSync(path.join(dir, 'blocklet.yml'));
-
-  return checkCompatibleOnce[dir];
-};
-
-const getBundleDir = (installDir, meta) => {
-  const oldDir = path.join(installDir, meta.bundleName || meta.name, meta.version);
-  if (compatibleWithOldBlocklets(oldDir)) {
-    return oldDir;
-  }
-
-  return path.join(installDir, meta.bundleName || meta.name, getVersionScope(meta));
-};
-
-const needBlockletDownload = (blocklet, oldBlocklet) => {
-  if ([BlockletSource.upload, BlockletSource.local, BlockletSource.custom].includes(blocklet.source)) {
-    return false;
-  }
-
-  if (!get(oldBlocklet, 'meta.dist.integrity')) {
-    return true;
-  }
-
-  return get(oldBlocklet, 'meta.dist.integrity') !== get(blocklet, 'meta.dist.integrity');
-};
-
-const formatBlockletTheme = (rawTheme) => {
-  let themeConfig = {};
-
-  if (rawTheme) {
-    if (Array.isArray(rawTheme.concepts) && rawTheme.currentConceptId) {
-      const concept = rawTheme.concepts.find((x) => x.id === rawTheme.currentConceptId);
-      themeConfig = {
-        ...concept.themeConfig,
-        prefer: concept.prefer,
-        name: concept.name,
-      };
-    } else {
-      // 兼容旧数据
-      themeConfig = {
-        light: rawTheme.light || {},
-        dark: rawTheme.dark || {},
-        common: rawTheme.common || {},
-        prefer: rawTheme.prefer || 'system',
-        name: rawTheme.name || 'Default',
-      };
-    }
-  }
-
-  const result = mergeWith(
-    // 至少提供 palette 色板值（客户端会使用）
-    cloneDeep({
-      light: { palette: BLOCKLET_THEME_LIGHT.palette },
-      dark: { palette: BLOCKLET_THEME_DARK.palette },
-      prefer: 'system',
-    }),
-    themeConfig,
-    // 数组值直接替换
-    (_, srcValue) => {
-      if (Array.isArray(srcValue)) {
-        return srcValue;
-      }
-      return undefined;
-    }
-  );
-
-  // 保留原始数据，用于 settings 保存
-  Object.defineProperty(result, 'raw', {
-    value: rawTheme,
-    enumerable: false,
-    writable: false,
-  });
-
-  return result;
-};
-
-const _getBlocklet = async ({
-  did,
-  dataDirs,
-  states,
-  e2eMode = false,
-  throwOnNotExist = true,
-  ensureIntegrity = false,
-  getOptionalComponents = false,
-} = {}) => {
-  if (!did) {
-    throw new Error('Blocklet did does not exist');
-  }
-  if (!isValidDid(did)) {
-    logger.error('Blocklet did is invalid', { did });
-    throw new Error('Blocklet did is invalid');
-  }
-
-  if (!dataDirs) {
-    throw new Error('dataDirs does not exist');
-  }
-
-  if (!states) {
-    throw new Error('states does not exist');
-  }
-
-  const blocklet = await states.blocklet.getBlocklet(did);
-  if (!blocklet) {
-    if (throwOnNotExist || ensureIntegrity) {
-      logger.error('can not find blocklet in database by did', { did });
-      throw new Error('can not find blocklet in database by did');
-    }
-    return null;
-  }
-
-  // 优化：并行查询独立数据（只查询一次 extraDoc，然后从内存中同步提取）
-  const [extraDoc, nodeInfo, site] = await Promise.all([
-    states.blockletExtras.getExtraByDid(blocklet.meta.did),
-    states.node.read(),
-    states.site.findOneByBlocklet(blocklet.meta.did),
-  ]);
-
-  // 从 extraDoc 中同步提取 settings（不需要再次查询数据库）
-  const extrasMeta = extraDoc ? pick(extraDoc, ['did', 'meta', 'controller']) : null;
-  const settings = states.blockletExtras.getFromDoc({ doc: extraDoc, dids: [blocklet.meta.did], name: 'settings' });
-
-  // app settings
-  // FIXME: @zhanghan 在 server 开发模式下，使用 `node /workspace/arcblock/blocklet-server/core/cli/tools/dev.js` 运行的 blocklet，blocklet.meta.did 和 blocklet.appPid 是不一致的
-  blocklet.trustedPassports = get(settings, 'trustedPassports') || [];
-  blocklet.trustedFactories = (get(settings, 'trustedFactories') || []).map((x) => {
-    if (!x.passport.ttlPolicy) {
-      x.passport.ttlPolicy = 'never';
-      x.passport.ttl = 0;
-    }
-    if (x.factoryAddress) {
-      x.factoryAddress = toAddress(x.factoryAddress);
-    }
-    return x;
-  });
-  blocklet.enablePassportIssuance = get(settings, 'enablePassportIssuance', true);
-  blocklet.settings = settings || {};
-
-  if (extrasMeta) {
-    blocklet.controller = extrasMeta.controller;
-  }
-
-  blocklet.settings.storeList = blocklet.settings.storeList || [];
-  blocklet.settings.theme = formatBlockletTheme(blocklet.settings.theme);
-  blocklet.settings.languages = blocklet.settings.languages || [];
-
-  // 移除第一个版本中 from 为 tmpl 的导航
-  if (blocklet?.settings?.navigations && Array.isArray(blocklet.settings.navigations)) {
-    blocklet.settings.navigations = (blocklet.settings.navigations || []).filter(
-      (item) => !(item?.parent === '/team' && ['tmpl'].includes(item.from))
-    );
-  }
-
-  (nodeInfo?.blockletRegistryList || []).forEach((store) => {
-    if (!blocklet.settings.storeList.find((x) => x.url === store.url)) {
-      blocklet.settings.storeList.push({
-        ...store,
-        protected: true,
-      });
-    }
-  });
-
-  blocklet.site = site;
-  blocklet.enableDocker = nodeInfo.enableDocker;
-  blocklet.enableDockerNetwork = nodeInfo.enableDockerNetwork;
-
-  // 第一次 forEachBlockletSync：收集所有组件的 dids
-  const componentConfigRequests = [];
-  forEachBlockletSync(blocklet, (component, { ancestors }) => {
-    const dids = [...ancestors.map((x) => x.meta.did), component.meta.did];
-    componentConfigRequests.push({
-      componentDid: component.meta.did,
-      dids,
-    });
-  });
-
-  // 基于缓存文档，为每个组件提取 configs（同步操作，不需要再次查询数据库）
-  const configsMap = new Map();
-  componentConfigRequests.forEach(({ componentDid, dids }) => {
-    const configs = states.blockletExtras.getFromDoc({ doc: extraDoc, dids, name: 'configs' });
-    configsMap.set(componentDid, configs);
-  });
-
-  // 第二次 forEachBlockletSync：填充组件
-  forEachBlockletSync(blocklet, (component, { id, level, ancestors }) => {
-    // component env
-    try {
-      // Validate component has required meta fields for getComponentDirs
-      if (!component.meta) {
-        throw new Error(`Component missing meta field: ${component.meta?.did || id}`);
-      }
-      if (!component.meta.name && !component.meta.bundleName) {
-        throw new Error(
-          `Component missing meta.name and meta.bundleName: ${component.meta.did || id}. ` +
-            'This may indicate a migration issue with blocklet_children table.'
-        );
-      }
-
-      component.env = {
-        id,
-        name: getComponentName(component, ancestors),
-        processId: getComponentProcessId(component, ancestors),
-        ...getComponentDirs(component, {
-          dataDirs,
-          ensure: ensureIntegrity,
-          ancestors,
-          e2eMode: level === 0 ? e2eMode : false,
-        }),
-      };
-    } catch (error) {
-      logger.error('Failed to set component env in _getBlocklet', {
-        componentDid: component.meta?.did,
-        componentName: component.meta?.name,
-        componentBundleName: component.meta?.bundleName,
-        error: error.message,
-        stack: error.stack,
-      });
-      throw error;
-    }
-
-    // component config - 从预取的 configsMap 中获取
-    const configs = configsMap.get(component.meta.did) || [];
-    const rootBlocklet = ancestors.length > 0 ? ancestors[0] : blocklet;
-    fillBlockletConfigs(component, configs, { rootBlocklet, nodeInfo, dataDirs });
-  });
-
-  if (getOptionalComponents) {
-    const optionalComponents = await parseOptionalComponents(blocklet);
-    blocklet.optionalComponents = optionalComponents;
-  } else {
-    blocklet.optionalComponents = [];
-  }
-
-  return blocklet;
-};
-
-const getBlocklet = ({
-  did,
-  ensureIntegrity = false,
-  getOptionalComponents = false,
-  useCache = false,
-  ...rest
-} = {}) => {
-  let cacheKey = '';
-
-  if (useCache) {
-    cacheKey = JSON.stringify({
-      ensureIntegrity,
-      getOptionalComponents,
-    });
-  }
-
-  return blockletCache.autoCacheGroup(did, cacheKey, () => {
-    return _getBlocklet({ did, ensureIntegrity, getOptionalComponents, ...rest });
-  });
-};
-
-const fromProperty2Config = (properties = {}, result) => {
-  Object.keys(properties).forEach((key) => {
-    const prop = properties[key];
-    if (prop.properties && ['ArrayTable', 'ArrayCards'].includes(prop['x-component']) === false) {
-      fromProperty2Config(prop.properties, result);
-    } else if (prop['x-decorator'] === 'FormItem') {
-      const secure = prop['x-component'] === 'Password';
-      result.push({
-        default: prop.default || '',
-        description: prop.title || key,
-        name: `${BLOCKLET_PREFERENCE_PREFIX}${key}`,
-        required: prop.required || false,
-        secure,
-        // eslint-disable-next-line no-nested-ternary
-        shared: secure ? false : typeof prop.shared === 'undefined' ? true : prop.shared,
-      });
-    }
-  });
-};
-const getConfigFromPreferences = (blocklet) => {
-  const result = [];
-  const schemaFile = path.join(blocklet.env.appDir, BLOCKLET_PREFERENCE_FILE);
-  if (fs.existsSync(schemaFile)) {
-    try {
-      const schema = JSON.parse(fs.readFileSync(schemaFile, 'utf8'));
-      fromProperty2Config(schema.schema?.properties, result);
-    } catch {
-      // do nothing
-    }
-  }
-
-  return result;
-};
-
-const shouldEnableSlpDomain = (mode) => {
-  if (process.env.ABT_NODE_ENABLE_SLP_DOMAIN === 'true') {
-    return true;
-  }
-
-  if (process.env.ABT_NODE_ENABLE_SLP_DOMAIN === 'false') {
-    return false;
-  }
-
-  return isInServerlessMode({ mode });
-};
-
-const getBlockletURLForLauncher = ({ blocklet, nodeInfo }) => {
-  const enableSlpDomain = shouldEnableSlpDomain(nodeInfo.mode);
-  let didDomain = '';
-  if (enableSlpDomain) {
-    didDomain = getDidDomainForBlocklet({
-      // eslint-disable-next-line no-use-before-define
-      did: getSlpDid(nodeInfo.did, blocklet.appPid),
-      didDomain: nodeInfo.slpDomain,
-    });
-  } else {
-    didDomain = getDidDomainForBlocklet({
-      did: blocklet.appPid,
-      didDomain: nodeInfo.didDomain,
-    });
-  }
-
-  return `https://${didDomain}`;
-};
-const createDataArchive = (dataDir, fileName) => {
-  const zipPath = path.join(os.tmpdir(), fileName);
-  if (fs.existsSync(zipPath)) {
-    fs.removeSync(zipPath);
-  }
-
-  const archive = createArchive('zip', { zlib: { level: 9 } });
-  const stream = fs.createWriteStream(zipPath);
-
-  return new Promise((resolve, reject) => {
-    archive
-      .directory(dataDir, false)
-      .on('error', (err) => reject(err))
-      .pipe(stream);
-
-    stream.on('close', () => resolve(zipPath));
-    archive.finalize();
-  });
-};
-
-const isBlockletAppSkUsed = ({ environments, migratedFrom = [] }, appSk) => {
-  const isUsedInEnv = environments.find((e) => e.key === BLOCKLET_CONFIGURABLE_KEY.BLOCKLET_APP_SK)?.value === appSk;
-  const isUsedInHistory = migratedFrom.some((x) => x.appSk === appSk);
-  return isUsedInEnv || isUsedInHistory;
-};
-
-const isRotatingAppSk = (newConfigs, oldConfigs, externalSk) => {
-  const newSk = newConfigs.find((x) => BLOCKLET_CONFIGURABLE_KEY.BLOCKLET_APP_SK === x.key);
-  if (!newSk) {
-    // If no newSk found, we are not rotating the appSk
-    return false;
-  }
-
-  const oldSk = oldConfigs.find((x) => BLOCKLET_CONFIGURABLE_KEY.BLOCKLET_APP_SK === x.key);
-  if (!oldSk) {
-    // If we have no oldSk, we are setting the initial appSk for external managed apps
-    // If we have no oldSk, but we are not external managed apps, we are rotating the appSk
-    return !externalSk;
-  }
-
-  // Otherwise, we must be rotating the appSk
-  // eslint-disable-next-line sonarjs/prefer-single-boolean-return
-  if (oldSk.value !== newSk.value) {
-    return true;
-  }
-
-  return false;
-};
-
-/**
- * this function has side effect on config.value
- * @param {{ key: string, value?: string }} config
- */
-const validateAppConfig = async (config, states) => {
-  const x = config;
-
-  // sk should be force secured while other app prop should not be secured
-  config.secure = x.key === BLOCKLET_CONFIGURABLE_KEY.BLOCKLET_APP_SK;
-
-  if (x.key === BLOCKLET_CONFIGURABLE_KEY.BLOCKLET_APP_SK) {
-    if (x.value) {
-      let wallet;
-      try {
-        wallet = fromSecretKey(x.value, { role: types.RoleType.ROLE_APPLICATION });
-      } catch {
-        try {
-          wallet = fromSecretKey(x.value, 'eth');
-        } catch {
-          throw new Error('Invalid custom blocklet secret key');
-        }
-      }
-
-      // Ensure sk is not used by existing blocklets, otherwise we may encounter appDid collision
-      const exist = await states.blocklet.hasBlocklet(wallet.address);
-      if (exist) {
-        throw new Error('Invalid custom blocklet secret key: already used by existing blocklet');
-      }
-    } else {
-      delete x.value;
-    }
-  }
-
-  if (x.key === BLOCKLET_CONFIGURABLE_KEY.BLOCKLET_APP_URL) {
-    if (isEmpty(x.value)) {
-      throw new Error(`${x.key} can not be empty`);
-    }
-
-    if (!isUrl(x.value)) {
-      throw new Error(`${x.key}(${x.value}) is not a valid URL`);
-    }
-  }
-
-  if (x.key === BLOCKLET_CONFIGURABLE_KEY.BLOCKLET_APP_NAME) {
-    x.value = await titleSchema.validateAsync(x.value);
-  }
-
-  if (x.key === BLOCKLET_CONFIGURABLE_KEY.BLOCKLET_APP_DESCRIPTION) {
-    x.value = await descriptionSchema.validateAsync(x.value);
-  }
-
-  if (
-    [
-      BLOCKLET_CONFIGURABLE_KEY.BLOCKLET_APP_LOGO,
-      BLOCKLET_CONFIGURABLE_KEY.BLOCKLET_APP_LOGO_RECT,
-      BLOCKLET_CONFIGURABLE_KEY.BLOCKLET_APP_LOGO_RECT_DARK,
-      BLOCKLET_CONFIGURABLE_KEY.BLOCKLET_APP_LOGO_SQUARE,
-      BLOCKLET_CONFIGURABLE_KEY.BLOCKLET_APP_LOGO_SQUARE_DARK,
-      BLOCKLET_CONFIGURABLE_KEY.BLOCKLET_APP_LOGO_FAVICON,
-      BLOCKLET_CONFIGURABLE_KEY.BLOCKLET_APP_SPLASH_PORTRAIT,
-      BLOCKLET_CONFIGURABLE_KEY.BLOCKLET_APP_SPLASH_LANDSCAPE,
-    ].includes(x.key)
-  ) {
-    x.value = await logoSchema.validateAsync(x.value);
-  }
-
-  if (x.key === BLOCKLET_CONFIGURABLE_KEY.BLOCKLET_APP_CHAIN_TYPE) {
-    if (['arcblock', 'ethereum'].includes(x.value) === false) {
-      throw new Error('Invalid blocklet wallet type, only "default" and "eth" are supported');
-    }
-  }
-
-  if (x.key === BLOCKLET_CONFIGURABLE_KEY.BLOCKLET_DELETABLE) {
-    if (['yes', 'no'].includes(x.value) === false) {
-      throw new Error('BLOCKLET_DELETABLE must be either "yes" or "no"');
-    }
-  }
-
-  if (x.key === BLOCKLET_CONFIGURABLE_KEY.BLOCKLET_PASSPORT_COLOR) {
-    if (x.value && x.value !== 'auto') {
-      if (x.value.length !== 7 || !isHex(x.value.slice(-6))) {
-        throw new Error('BLOCKLET_PASSPORT_COLOR must be a hex encoded color, eg. #ffeeaa');
-      }
-    }
-  }
-
-  if (x.key === BLOCKLET_CONFIGURABLE_KEY.BLOCKLET_APP_SPACE_ENDPOINT) {
-    // @note: value 置空以表删除
-    if (x.value && !isUrl(x.value)) {
-      throw new Error(`${x.key}(${x.value}) is not a valid URL`);
-    }
-  }
-
-  if (x.key === BLOCKLET_CONFIGURABLE_KEY.BLOCKLET_APP_SPACES_URL) {
-    if (isEmpty(x.value)) {
-      throw new Error(`${x.key} can not be empty`);
-    }
-
-    if (!isUrl(x.value)) {
-      throw new Error(`${x.key}(${x.value}) is not a valid URL`);
-    }
-  }
-
-  if (x.key === BLOCKLET_CONFIGURABLE_KEY.BLOCKLET_APP_BACKUP_ENDPOINT) {
-    // @note: value 置空以表删除
-    if (isEmpty(x.value)) {
-      x.value = '';
-    }
-
-    if (!isEmpty(x.value) && !isUrl(x.value)) {
-      throw new Error(`${x.key}(${x.value}) is not a valid URL`);
-    }
-  }
-
-  if (x.key === BLOCKLET_CONFIGURABLE_KEY.BLOCKLET_CLUSTER_SIZE) {
-    if (isEmpty(x.value)) {
-      x.value = '';
-    }
-
-    const v = Number(x.value);
-    if (Number.isNaN(v)) {
-      throw new Error(`${x.key} must be number`);
-    }
-    if (!Number.isInteger(v)) {
-      throw new Error(`${x.key} must be integer`);
-    }
-  }
-};
-
-const checkDuplicateAppSk = async ({ sk, did, states }) => {
-  if (!sk && !did) {
-    throw new Error('sk and did is empty');
-  }
-
-  let appSk = sk;
-  if (!sk) {
-    const nodeInfo = await states.node.read();
-    const blocklet = await states.blocklet.getBlocklet(did);
-    const configs = await states.blockletExtras.getConfigs([did]);
-    const { wallet } = getBlockletInfo(
-      {
-        meta: blocklet.meta,
-        environments: (configs || []).filter((x) => x.value),
-      },
-      nodeInfo.sk
-    );
-    appSk = wallet.secretKey;
-  }
-
-  let wallet;
-  try {
-    wallet = fromSecretKey(appSk, { role: types.RoleType.ROLE_APPLICATION });
-  } catch {
-    try {
-      wallet = fromSecretKey(appSk, 'eth');
-    } catch {
-      throw new Error('Invalid custom blocklet secret key');
-    }
-  }
-
-  const exist = await states.blocklet.hasBlocklet(wallet.address);
-  if (exist) {
-    throw new Error(`blocklet secret key already used by ${exist.meta.title || exist.meta.name}`);
-  }
-};
-
-const checkDuplicateMountPoint = (app, mountPoint) => {
-  const err = new Error(`cannot add duplicate mount point, ${mountPoint || '/'} already exist`);
-
-  for (const component of app.children || []) {
-    if (
-      hasStartEngine(component.meta) &&
-      normalizePathPrefix(component.mountPoint) === normalizePathPrefix(mountPoint)
-    ) {
-      throw err;
-    }
-  }
-};
-
-const resolveMountPointConflict = (comp, blocklet) => {
-  try {
-    if (!comp?.mountPoint) return comp;
-
-    const children = (blocklet?.children || []).filter((x) => x?.meta && hasMountPoint(x.meta));
-
-    const existingComponent = children.find((x) => x.mountPoint === comp.mountPoint && x.meta?.did !== comp.meta?.did);
-    if (!existingComponent) return comp;
-
-    const baseName = formatName(comp?.meta?.name) || formatName(comp?.meta?.title);
-    comp.mountPoint = children.some((x) => x.mountPoint === `/${baseName}`)
-      ? comp.meta.did
-      : baseName.toLocaleLowerCase();
-
-    return comp;
-  } catch (error) {
-    logger.error('Failed to resolve mount point:', error);
-    comp.mountPoint = comp.meta.did;
-    return comp;
-  }
-};
-
-const validateStore = (nodeInfo, storeUrl) => {
-  if (nodeInfo.mode !== 'serverless') {
-    return;
-  }
-
-  const storeUrlObj = new URL(storeUrl);
-
-  // Check trusted blocklet sources from environment variable first
-  const trustedSources = process.env.ABT_NODE_TRUSTED_SOURCES;
-  if (trustedSources) {
-    const trustedHosts = trustedSources
-      .split(',')
-      .map((url) => url.trim())
-      .filter(Boolean)
-      .map((url) => new URL(url).host);
-
-    if (trustedHosts.includes(storeUrlObj.host)) {
-      return;
-    }
-  }
-
-  const registerUrlObj = new URL(nodeInfo.registerUrl);
-
-  // 信任 Launcher 打包的应用
-  if (registerUrlObj.host === storeUrlObj.host) {
-    return;
-  }
-
-  const inStoreList = nodeInfo.blockletRegistryList.find((item) => {
-    const itemURLObj = new URL(item.url);
-
-    return itemURLObj.host === storeUrlObj.host;
-  });
-
-  if (!inStoreList) {
-    throw new Error('Must be installed from the compliant blocklet store list');
-  }
-};
-
-const validateInServerless = ({ blockletMeta }) => {
-  const { interfaces } = blockletMeta;
-  const externalPortInterfaces = (interfaces || []).filter((item) => !!item.port?.external);
-
-  if (externalPortInterfaces.length > 0) {
-    throw new Error('Blocklets with exposed ports cannot be installed');
-  }
-};
-
-const checkStructVersion = (blocklet) => {
-  if (blocklet.structVersion !== APP_STRUCT_VERSION) {
-    throw new Error('You should migrate the application first');
-  }
-};
-
-const isVersionCompatible = (actualVersion, expectedRange) =>
-  !expectedRange || expectedRange === 'latest' || semver.satisfies(actualVersion, expectedRange);
-
-const checkVersionCompatibility = (components) => {
-  for (const component of components) {
-    // eslint-disable-next-line no-loop-func
-    forEachBlockletSync(component, (x) => {
-      const dependencies = x.dependencies || [];
-      dependencies.forEach((dep) => {
-        const { did, version: expectedRange } = dep;
-        const exist = components.find((y) => y.meta.did === did);
-        if (exist && !isVersionCompatible(exist.meta.version, expectedRange)) {
-          throw new Error(
-            `Check version compatible failed: ${component.meta.title || component.meta.did} expects ${
-              exist.meta.title || exist.meta.did
-            }'s version to be ${expectedRange}, but actual is ${exist.meta.version}`
-          );
-        }
-      });
-    });
-  }
-};
-
-const getBlockletKnownAs = (blocklet) => {
-  const alsoKnownAs = [blocklet.appDid];
-  if (Array.isArray(blocklet.migratedFrom)) {
-    blocklet.migratedFrom.filter((x) => x.appDid !== blocklet.appPid).forEach((x) => alsoKnownAs.push(x.appDid));
-  }
-
-  return alsoKnownAs.filter(Boolean).map(toDid);
-};
-
-const getFixedBundleSource = (component) => {
-  if (!component) {
-    return null;
-  }
-
-  if (component.bundleSource) {
-    return component.bundleSource;
-  }
-
-  const { source, deployedFrom, meta: { bundleName } = {} } = component;
-
-  if (!deployedFrom) {
-    return null;
-  }
-
-  if (source === BlockletSource.registry && bundleName) {
-    return {
-      store: deployedFrom,
-      name: bundleName,
-      version: 'latest',
-    };
-  }
-
-  if (source === BlockletSource.url) {
-    return {
-      url: deployedFrom,
-    };
-  }
-
-  return null;
-};
-
-const updateBlockletFallbackLogo = async (blocklet) => {
-  if (isEthereumDid(blocklet.meta.did)) {
-    await fs.writeFile(path.join(blocklet.env.dataDir, 'logo.svg'), createBlockiesSvg(blocklet.meta.did));
-  } else {
-    await fs.writeFile(path.join(blocklet.env.dataDir, 'logo.svg'), createDidLogo(blocklet.meta.did));
-  }
-};
-
-const ensureAppLogo = async (blocklet, blockletsDir) => {
-  if (!blocklet) {
-    return;
-  }
-
-  if (
-    blocklet.source === BlockletSource.custom &&
-    (blocklet.children || [])[0]?.meta?.logo &&
-    blocklet.children[0].env.appDir
-  ) {
-    const fileName = blocklet.children[0].meta.logo;
-    const src = path.join(blocklet.children[0].env.appDir, fileName);
-    const dist = path.join(getBundleDir(blockletsDir, blocklet.meta), fileName);
-
-    if (fs.existsSync(src)) {
-      await fs.copy(src, dist);
-    }
-  }
-};
-
-const getBlockletDidDomainList = (blocklet, nodeInfo) => {
-  const domainAliases = [];
-  const alsoKnownAs = getBlockletKnownAs(blocklet);
-
-  const dids = [blocklet.appPid, blocklet.appDid, ...alsoKnownAs].filter(Boolean).map((did) => toAddress(did));
-
-  uniq(dids).forEach((did) => {
-    const domain = getDidDomainForBlocklet({ did, didDomain: nodeInfo.didDomain });
-
-    domainAliases.push({ value: domain, isProtected: true });
-  });
-
-  // eslint-disable-next-line no-use-before-define
-  const enableSlpDomain = shouldEnableSlpDomain(nodeInfo.mode);
-  if (enableSlpDomain) {
-    // eslint-disable-next-line no-use-before-define
-    const slpDid = getSlpDid(nodeInfo.did, blocklet.appPid);
-    const domain = getDidDomainForBlocklet({ did: slpDid, didDomain: nodeInfo.slpDomain });
-
-    domainAliases.push({ value: domain, isProtected: true });
-  }
-
-  return domainAliases;
-};
-
-const getBlockletStatus = (blocklet) => {
-  const fallbackStatus = BlockletStatus.stopped;
-
-  if (!blocklet) {
-    return fallbackStatus;
-  }
-
-  if (!blocklet.children?.length) {
-    if (blocklet.meta?.group === BlockletGroup.gateway) {
-      return blocklet.status;
-    }
-
-    if (blocklet.status === BlockletStatus.added) {
-      return BlockletStatus.added;
-    }
-
-    // for backward compatibility
-    if (!blocklet.structVersion) {
-      return blocklet.status;
-    }
-
-    return fallbackStatus;
-  }
-
-  let inProgressStatus;
-  let runningStatus;
-  let status;
-
-  forEachComponentV2Sync(blocklet, (component) => {
-    if (component.meta?.group === BlockletGroup.gateway) {
-      return;
-    }
-
-    if (isInProgress(component.status)) {
-      if (!inProgressStatus) {
-        inProgressStatus = component.status;
-      }
-      return;
-    }
-
-    if (isRunning(component.status) || isRunning(component.greenStatus)) {
-      runningStatus = BlockletStatus.running;
-      return;
-    }
-
-    if (status === BlockletStatus.stopped) {
-      return;
-    }
-
-    status = component.status;
-  });
-
-  return inProgressStatus || runningStatus || status;
-};
-
-const shouldSkipComponent = (componentDid, whiteList) => {
-  if (!whiteList || !Array.isArray(whiteList)) {
-    return false;
-  }
-
-  const arr = whiteList.filter(Boolean);
-
-  if (!arr.length) {
-    return false;
-  }
-
-  return !arr.includes(componentDid);
-};
-
-const ensurePortsShape = (_states, portsA, portsB) => {
-  if (!portsA || Object.keys(portsA).length === 0) {
-    return;
-  }
-  if (Object.keys(portsB).length === 0) {
-    for (const key of Object.keys(portsA)) {
-      portsB[key] = portsA[key];
-    }
-  }
-};
-
-const ensureAppPortsNotOccupied = async ({ blocklet, componentDids: inputDids, states, manager, isGreen = false }) => {
-  const { did } = blocklet.meta;
-  const lockName = `port-check-${did}`;
-
-  // ⚠️ 关键修复：使用 DBCache 锁确保端口分配的原子性
-  // 在多进程环境下，防止多个进程同时检查同一个端口
-  await portAssignLock.acquire(lockName);
-
-  try {
-    const occupiedDids = new Set();
-
-    await forEachComponentV2(blocklet, async (b) => {
-      try {
-        if (shouldSkipComponent(b.meta.did, inputDids)) return;
-
-        if (!b.greenPorts) {
-          occupiedDids.add(b.meta.did);
-          b.greenPorts = {};
-        }
-        const { ports = {}, greenPorts } = b;
-        ensurePortsShape(states, ports, greenPorts);
-
-        const targetPorts = isGreen ? greenPorts : ports;
-
-        let currentOccupied = false;
-        for (const port of Object.values(targetPorts)) {
-          currentOccupied = await isPortTaken(port);
-          if (currentOccupied) {
-            break;
-          }
-        }
-
-        if (currentOccupied) {
-          occupiedDids.add(b.meta.did);
-        }
-      } catch (error) {
-        logger.error('Failed to check ports occupied', { error, blockletDid: b.meta.did, isGreen });
-      }
-    });
-
-    if (occupiedDids.size === 0) {
-      logger.info('No occupied ports detected, no refresh needed', { did, isGreen });
-      return blocklet;
-    }
-
-    const componentDids = Array.from(occupiedDids);
-    const {
-      refreshed,
-      componentDids: actuallyRefreshedDids,
-      isInitialAssignment,
-    } = await states.blocklet.refreshBlockletPorts(did, componentDids, isGreen);
-
-    // 只有真正刷新了端口才打印日志和更新环境
-    if (refreshed && actuallyRefreshedDids.length > 0) {
-      // 区分首次分配和冲突刷新，使用不同的日志信息
-      if (isInitialAssignment) {
-        logger.info('Assigned green ports for blue-green deployment', {
-          did,
-          componentDids: actuallyRefreshedDids,
-          isGreen,
-        });
-      } else {
-        logger.info('Refreshed component ports due to conflict', {
-          did,
-          componentDids: actuallyRefreshedDids,
-          isGreen,
-        });
-      }
-
-      await manager._updateBlockletEnvironment(did);
-      const newBlocklet = await manager.ensureBlocklet(did);
-
-      return newBlocklet;
-    }
-
-    logger.info('Ports were detected as occupied but not actually occupied during refresh, no refresh needed', {
-      did,
-      componentDids,
-      isGreen,
-    });
-
-    return blocklet;
-  } finally {
-    await portAssignLock.releaseLock(lockName);
-  }
-};
-
-const getComponentNamesWithVersion = (app = {}, componentDids = []) => {
-  const str = uniq(componentDids)
-    .map((x) => {
-      const component = (app.children || []).find((y) => y.meta.did === x);
-      return `${component.meta.title}@${component.meta.version}`;
-    })
-    .join(', ');
-  return str;
-};
-
-const getSlpDid = (serverDid, appPid) => {
-  if (!serverDid || !appPid) {
-    throw new Error('serverDid and appPid is required');
-  }
-
-  const buffer = Buffer.concat([toBuffer(serverDid), toBuffer(appPid)]);
-  const md5Str = md5(buffer);
-
-  const wallet = fromPublicKey(md5Str);
-  return wallet.address;
-};
-
-// eslint-disable-next-line require-await
-const publishDidDocument = async ({ blocklet, ownerInfo, nodeInfo }) => {
-  const alsoKnownAs = getBlockletKnownAs(blocklet);
-  logger.debug('updateDidDocument blocklet info', { blocklet });
-
-  const { wallet } = getBlockletInfo(blocklet, nodeInfo.sk);
-  const { mode, did: serverDid } = nodeInfo;
-
-  let slpDid = null;
-  const enableSlpDomain = shouldEnableSlpDomain(mode);
-  if (enableSlpDomain) {
-    slpDid = getSlpDid(serverDid, blocklet.appPid);
-
-    if (alsoKnownAs.indexOf(slpDid) === -1) {
-      alsoKnownAs.push(toDid(slpDid));
-    }
-  }
-
-  logger.info('update did document', {
-    blockletDid: blocklet.meta.did,
-    alsoKnownAs,
-    slpDid,
-    daemonDidDomain: getServerDidDomain(nodeInfo),
-    didRegistryUrl: nodeInfo.didRegistry,
-    domain: nodeInfo.didDomain,
-    slpDomain: nodeInfo.slpDomain,
-  });
-
-  const name = blocklet.meta?.title || blocklet.meta?.name;
-  const state = fromBlockletStatus(blocklet.status);
-
-  let launcher;
-  if (!isEmpty(blocklet.controller)) {
-    launcher = {
-      did: toDid(blocklet.controller.did || nodeInfo.registerInfo.appPid), // 目前 controller 没有 launcher 的元信息, 默认在 nodeInfo 中存储
-      name: blocklet.controller.launcherName || nodeInfo.registerInfo.appName || '',
-      url: blocklet.controller.launcherUrl || nodeInfo.registerInfo.appUrl || '',
-      userDid: toDid(blocklet.controller.nftOwner),
-    };
-  }
-
-  const isPrimaryDomain = (d) => {
-    const appUrl = blocklet.environments.find((x) => x.key === BLOCKLET_CONFIGURABLE_KEY.BLOCKLET_APP_URL)?.value;
-    try {
-      const url = new URL(appUrl);
-      return url.hostname === d;
-    } catch (error) {
-      logger.error('failed to get primary domain', { error, domain: d, appUrl });
-      return false;
-    }
-  };
-
-  const domains = await Promise.all(
-    (blocklet.site?.domainAliases || []).map(async (item) => {
-      let type = isCustomDomain(item.value) ? 'custom' : 'internal';
-      // 如果域名是 appUrl，则设置为 primary
-      if (isPrimaryDomain(item.value)) {
-        type = 'primary';
-      }
-
-      if (item.value.includes(SLOT_FOR_IP_DNS_SITE)) {
-        const nodeIp = await getAccessibleExternalNodeIp();
-        item.value = replaceDomainSlot({ domain: item.value, nodeIp });
-      }
-
-      return {
-        type,
-        host: item.value,
-        url: `https://${item.value}`,
-        source: 'dnsRecords', // 固定为 dnsRecords
-      };
-    })
-  );
-
-  let owner;
-  if (ownerInfo) {
-    owner = {
-      did: toDid(ownerInfo.did),
-      name: ownerInfo.fullName,
-      avatar: fixAvatar(ownerInfo.avatar),
-    };
-  }
-
-  return didDocument.updateBlockletDocument({
-    blocklet,
-    wallet,
-    alsoKnownAs,
-    slpDid,
-    daemonDidDomain: getServerDidDomain(nodeInfo),
-    didRegistryUrl: nodeInfo.didRegistry,
-    domain: nodeInfo.didDomain,
-    slpDomain: nodeInfo.slpDomain,
-    serverDid,
-    blockletServerVersion: nodeInfo.version,
-    name,
-    state,
-    owner,
-    launcher,
-    domains,
-  });
-};
-
-const updateDidDocument = async ({ did, nodeInfo, teamManager, states }) => {
-  const blocklet = await states.blocklet.getBlocklet(did);
-  const blockletExtra = await states.blockletExtras.findOne({ did });
-
-  blocklet.site = await states.site.findOneByBlocklet(did);
-  blocklet.settings = await states.blockletExtras.getSettings(did);
-  blocklet.controller = blockletExtra?.controller;
-
-  const ownerDid = blocklet.settings?.owner?.did;
-  let ownerInfo;
-  if (ownerDid) {
-    logger.info('get owner info', { ownerDid, teamDid: blocklet.appPid });
-    const userState = await teamManager.getUserState(blocklet.appPid);
-    ownerInfo = await userState.getUser(ownerDid);
-  }
-
-  return publishDidDocument({ blocklet, ownerInfo, nodeInfo });
-};
-
-// Update DID document state only (e.g., to 'deleted') without fetching from database
-// Used when blocklet is being removed and database data may not be available
-const updateDidDocumentStateOnly = ({ did, blocklet, state, nodeInfo }) => {
-  logger.debug('update did document state only', { did, state });
-
-  const { wallet } = getBlockletInfo(blocklet, nodeInfo.sk);
-
-  return didDocument.updateBlockletStateOnly({
-    did,
-    state,
-    didRegistryUrl: nodeInfo.didRegistry,
-    wallet,
-    blockletServerVersion: nodeInfo.version,
-  });
-};
-
-const getAppConfigsFromComponent = (meta, configsInApp = [], configsInComponent = []) => {
-  const configs = [];
-  for (const configInMeta of meta?.environments || []) {
-    if (isEnvShareable(configInMeta)) {
-      const configInApp = (configsInApp || []).find((x) => x.key === configInMeta.name);
-      if (!configInApp) {
-        const configInComponent = configsInComponent.find((y) => y.key === configInMeta.name);
-        if (configInComponent && isEnvShareable(configInComponent)) {
-          configs.push(configInComponent);
-        }
-      }
-    }
-  }
-  return configs;
-};
-
-const getConfigsFromInput = (configs = [], oldConfigs = []) => {
-  const sharedConfigs = [];
-  const selfConfigs = [];
-
-  configs.forEach((config) => {
-    const oldConfig = oldConfigs.find((y) => y.key === config.key);
-    if (!config.key.startsWith(BLOCKLET_PREFERENCE_PREFIX) && (isEnvShareable(config) || isEnvShareable(oldConfig))) {
-      sharedConfigs.push(config);
-    } else {
-      selfConfigs.push(config);
-    }
-  });
-
-  return { sharedConfigs, selfConfigs };
-};
-
-// remove app configs if no component use it
-const removeAppConfigsFromComponent = async (componentConfigs, app, blockletExtraState) => {
-  const appConfigs = app.configs || [];
-  const remainedConfigs = [].concat(...(app.children || []).map((x) => x.configs || []));
-  const removedAppConfigs = [];
-
-  componentConfigs.forEach((config) => {
-    const appConfig = appConfigs.find((x) => x.key === config.key);
-    if (
-      appConfig &&
-      !appConfig.custom &&
-      !(app.meta.environments || []).find((x) => x.name === config.key) &&
-      !remainedConfigs.find((x) => x.key === config.key && isEnvShareable(x))
-    ) {
-      removedAppConfigs.push({ key: appConfig.key, value: undefined });
-    }
-  });
-
-  if (removedAppConfigs.length) {
-    await blockletExtraState.setConfigs(app.meta.did, removedAppConfigs);
-  }
-};
-
-const getPackComponent = (app) => {
-  return (app?.children || []).find((x) => x.meta.group === BlockletGroup.pack);
-};
-
-const getPackConfig = (app) => {
-  const packComponent = getPackComponent(app);
-  if (!packComponent) {
-    return null;
-  }
-
-  const resource = (packComponent.meta.resource?.bundles || []).find(
-    (x) => x.did === packComponent.meta.did && x.type === 'config'
-  );
-
-  if (!resource) {
-    return null;
-  }
-
-  const { appDir } = packComponent.env;
-  const configFile = path.join(appDir, BLOCKLET_RESOURCE_DIR, resource.did, resource.type, 'config.json');
-
-  if (!fs.existsSync(configFile)) {
-    return null;
-  }
-
-  return fs.readJSON(configFile);
-};
-
-/** 复制打包文件中的图片
- * @param {string} appDataDir
- * @param {string} packDir
- * @param {{ navigations: Array<{ section: string | string[], icon: string }>, configObj: Record<string, string> }} packConfig
- */
-const copyPackImages = async ({ appDataDir, packDir, packConfig = {} }) => {
-  const mediaDir = path.join(appDataDir, 'media', 'blocklet-service');
-  const { navigations = [], configObj = {} } = packConfig;
-  await fs.ensureDir(mediaDir);
-
-  // 过滤出 bottomNavigation 的图标
-  const bottomNavItems = navigations.filter((item) => {
-    // 处理 section 字段为数组的情况
-    const sections = Array.isArray(item.section) ? item.section : [item.section];
-    return sections.includes('bottomNavigation') && item.icon;
-  });
-
-  // 复制 tabbar 导航图标
-  if (bottomNavItems.length > 0) {
-    await Promise.all(
-      bottomNavItems.map(async (item) => {
-        const iconFileName = path.basename(item.icon);
-        const iconInImages = path.join(packDir, 'images', iconFileName);
-
-        if (fs.existsSync(iconInImages)) {
-          await fs.copy(iconInImages, path.join(mediaDir, iconFileName));
-        }
-      })
-    );
-  }
-
-  // 复制品牌相关图片
-  await Promise.all(
-    APP_CONFIG_IMAGE_KEYS.map(async (key) => {
-      const value = configObj[key];
-      if (value) {
-        const imgFile = path.join(packDir, 'images', value);
-        if (fs.existsSync(imgFile)) {
-          await fs.copy(imgFile, path.join(appDataDir, value));
-        }
-      }
-    })
-  );
-};
-
-/**
- * @param {import('@blocklet/server-js').BlockletState} blocklet
- * @returns {boolean}
- */
-const isDevelopmentMode = (blocklet) => blocklet?.mode === BLOCKLET_MODES.DEVELOPMENT;
-
-const getHookArgs = (blocklet) => ({
-  output: blocklet.mode === BLOCKLET_MODES.DEVELOPMENT ? '' : path.join(blocklet.env.logsDir, 'output.log'),
-  error: blocklet.mode === BLOCKLET_MODES.DEVELOPMENT ? '' : path.join(blocklet.env.logsDir, 'error.log'),
-  timeout:
-    Math.max(
-      get(blocklet, 'meta.timeout.script', 120),
-      ...(blocklet?.children || []).map((child) => child.meta?.timeout?.script || 0)
-    ) * 1000,
-});
-
 module.exports = {
   updateBlockletFallbackLogo,
   forEachBlocklet,
+  getDisplayName,
+  isExternalBlocklet,
   getBlockletMetaFromUrl: (url) => getBlockletMetaFromUrl(url, { logger }),
   parseComponents,
   filterRequiredComponents,
@@ -3107,10 +140,10 @@ module.exports = {
   validateBlockletChainInfo,
   fillBlockletConfigs,
   ensureBlockletExpanded,
-  startBlockletProcess,
-  stopBlockletProcess,
-  deleteBlockletProcess,
-  reloadBlockletProcess,
+  startBlockletProcess: _startBlockletProcess,
+  stopBlockletProcess: _stopBlockletProcess,
+  deleteBlockletProcess: _deleteBlockletProcess,
+  reloadBlockletProcess: _reloadBlockletProcess,
   checkBlockletProcessHealthy,
   isBlockletPortHealthy,
   shouldCheckHealthy,
@@ -3169,5 +202,4 @@ module.exports = {
   getBlockletConfigObj,
   isDevelopmentMode,
   resolveMountPointConflict,
-  deleteBlockletCache,
 };