@abtnode/core 1.16.52-beta-20251003-083412-fdfc4e36 → 1.16.52-beta-20251005-235515-42ad5caf

package/lib/util/blocklet.js

@@ -116,7 +116,6 @@ const fetchPm2 = require('@abtnode/util/lib/pm2/fetch-pm2');
 
 const promiseSpawn = require('@abtnode/util/lib/promise-spawn');
 const { getAbtNodeRedisAndSQLiteUrl } = require('@abtnode/db-cache');
-const xbytes = require('xbytes');
 const { validate: validateEngine, get: getEngine } = require('../blocklet/manager/engine');
 
 const isRequirementsSatisfied = require('./requirement');
@@ -184,6 +183,7 @@ const statusMap = {
   errored: BlockletStatus.error,
   stopping: BlockletStatus.stopping,
   stopped: BlockletStatus.stopped,
+  'waiting restart': BlockletStatus.restarting,
 };
 
 const PRIVATE_NODE_ENVS = [
@@ -449,6 +449,7 @@ const getComponentSystemEnvironments = (blocklet) => {
   if (port) {
     portEnvironments[BLOCKLET_DEFAULT_PORT_NAME] = port;
   }
+
   if (ports) {
     Object.assign(portEnvironments, ports);
   }
@@ -466,11 +467,24 @@ const getComponentSystemEnvironments = (blocklet) => {
   };
 };
 
-const getRuntimeEnvironments = (blocklet, nodeEnvironments, ancestors) => {
+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) => {
@@ -495,8 +509,9 @@ const getRuntimeEnvironments = (blocklet, nodeEnvironments, ancestors) => {
   const ports = {};
   forEachBlockletSync(root, (x) => {
     const webInterface = findWebInterface(x);
-    if (webInterface && x.environmentObj[webInterface.port]) {
-      ports[x.environmentObj.BLOCKLET_REAL_NAME] = x.environmentObj[webInterface.port];
+    const envObj = x.meta?.did === blocklet.meta?.did ? environmentObj : x.environmentObj;
+    if (webInterface && envObj?.[webInterface.port]) {
+      ports[envObj.BLOCKLET_REAL_NAME] = envObj[webInterface.port];
     }
   });
 
@@ -518,7 +533,7 @@ const getRuntimeEnvironments = (blocklet, nodeEnvironments, ancestors) => {
   const env = {
     ...blocklet.configObj,
     ...getSharedConfigObj((ancestors || [])[0], blocklet, true),
-    ...blocklet.environmentObj,
+    ...environmentObj,
     ...devEnvironments,
     BLOCKLET_MOUNT_POINTS: JSON.stringify(componentsInternalInfo),
     BLOCKLET_MODE: blocklet.mode || BLOCKLET_MODES.PRODUCTION,
@@ -559,6 +574,10 @@ const getRuntimeEnvironments = (blocklet, nodeEnvironments, ancestors) => {
     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]);
@@ -573,7 +592,7 @@ const isUsefulError = (err) =>
   !/id unknown/.test(err.message) &&
   !/^Process \d+ not found$/.test(err.message);
 
-const getHealthyCheckTimeout = (blocklet, { checkHealthImmediately } = {}) => {
+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;
@@ -594,11 +613,15 @@ const getHealthyCheckTimeout = (blocklet, { checkHealthImmediately } = {}) => {
     };
   }
 
+  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),
-      ...(blocklet?.children || []).map((child) => child.meta?.timeout?.start || 0)
+      ...(children || []).map((child) => child.meta?.timeout?.start || 0)
     ) * 1000;
 
   if (process.env.NODE_ENV === 'test') {
@@ -628,6 +651,7 @@ const startBlockletProcess = async (
     componentDids,
     configSynchronizer,
     onlyStart = false,
+    isGreen = false,
   } = {}
 ) => {
   if (!blocklet) {
@@ -637,6 +661,25 @@ const startBlockletProcess = async (
   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()}`;
@@ -674,7 +717,7 @@ const startBlockletProcess = async (
     }
 
     // get env
-    const env = getRuntimeEnvironments(b, nodeEnvironments, ancestors);
+    const env = getRuntimeEnvironments(b, nodeEnvironments, ancestors, isGreen);
     const startedAt = Date.now();
 
     await installExternalDependencies({ appDir: env?.BLOCKLET_APP_DIR, nodeInfo });
@@ -683,8 +726,12 @@ const startBlockletProcess = async (
 
     // kill process if port is occupied
     try {
-      const { ports } = b;
-      await killProcessOccupiedPorts({ ports, pm2ProcessId: processId, printError: logger.error.bind(logger) });
+      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 });
     }
@@ -692,12 +739,13 @@ const startBlockletProcess = async (
     // 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: processId,
+      name: processIdName,
       cwd,
       // FIXME @linchen [] does not work, so use () here
       log_date_format: '(YYYY-MM-DD HH:mm:ss)',
@@ -772,34 +820,36 @@ const startBlockletProcess = async (
       delete options.mergeLogs;
     }
 
-    const nextOptions =
-      b.mode === BLOCKLET_MODES.DEVELOPMENT
-        ? options
-        : await parseDockerOptionsFromPm2({
-            options,
-            nodeInfo,
-            isExternal: isExternalBlocklet(b),
-            meta: b.meta,
-            ports: b.ports,
-            onlyStart,
-            dockerNetworkName,
-            rootBlocklet: blocklet,
-          });
+    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(processId);
+    const status = await getProcessState(processIdName);
     if (status === BlockletStatus.error) {
-      throw new Error(`process ${processId} is not running within 3 seconds`);
+      throw new Error(`process ${processIdName} is not running within 3 seconds`);
     }
-    logger.info('done start blocklet', { processId, status, time: Date.now() - startedAt });
+    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.error('blocklet connect internal docker network failed', { processId, error: err });
+        logger.error('blocklet connect internal docker network failed', { processId: processIdName, error: err });
       }
     }
 
@@ -807,7 +857,7 @@ const startBlockletProcess = async (
     try {
       await postStart(b, { env });
     } catch (err) {
-      logger.error('blocklet post start failed', { processId, error: err });
+      logger.error('blocklet post start failed', { processId: processIdName, error: err });
     }
   };
 
@@ -842,16 +892,28 @@ const startBlockletProcess = async (
  * Stop all precesses of a blocklet
  * @param {*} blocklet should contain env props
  */
-const stopBlockletProcess = (blocklet, { preStop = noop, skippedProcessIds = [], componentDids } = {}) => {
+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 });
+  return deleteBlockletProcess(blocklet, {
+    preDelete: preStop,
+    skippedProcessIds,
+    componentDids,
+    isGreen,
+    isStopGreenAndBlue,
+  });
 };
 
 /**
  * Delete all precesses of a blocklet
  * @param {*} blocklet should contain env props
  */
-const deleteBlockletProcess = async (blocklet, { preDelete = noop, skippedProcessIds = [], componentDids } = {}) => {
+const deleteBlockletProcess = async (
+  blocklet,
+  { preDelete = noop, skippedProcessIds = [], componentDids, isGreen = false, isStopGreenAndBlue = false } = {}
+) => {
   await forEachBlocklet(
     blocklet,
     async (b, { ancestors }) => {
@@ -875,8 +937,16 @@ const deleteBlockletProcess = async (blocklet, { preDelete = noop, skippedProces
         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(b.env.processId);
+      await deleteProcess(processId);
     },
     { parallel: true }
   );
@@ -975,57 +1045,10 @@ const validateBlockletChainInfo = (blocklet) => {
   return chainInfo;
 };
 
-const checkBlockletProcessHealthy = async (
-  blocklet,
-  { minConsecutiveTime, timeout, componentDids, setBlockletRunning } = {}
-) => {
-  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();
-
-      // eslint-disable-next-line no-use-before-define
-      await _checkProcessHealthy(b, { minConsecutiveTime, timeout, logToTerminal });
-      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 _checkProcessHealthy = async (blocklet, { minConsecutiveTime, timeout, logToTerminal }) => {
-  const { meta, ports, env } = blocklet;
+const _checkProcessHealthy = async (blocklet, { minConsecutiveTime, timeout, logToTerminal, isGreen = false }) => {
+  const { meta, ports, greenPorts, env } = blocklet;
   const { name } = meta;
-  const { processId } = env;
+  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);
@@ -1048,6 +1071,7 @@ const _checkProcessHealthy = async (blocklet, { minConsecutiveTime, timeout, log
     };
 
     let status = await getStatus();
+
     for (let i = 0; i < 20 && status !== 'online'; i++) {
       const t = process.env.NODE_ENV !== 'test' ? 500 : 30;
       await sleep(t);
@@ -1058,7 +1082,10 @@ const _checkProcessHealthy = async (blocklet, { minConsecutiveTime, timeout, log
       throw new Error('process not start within 10s');
     }
 
-    const port = findInterfacePortByName({ meta, ports }, (webInterface || dockerInterface).name);
+    const port = findInterfacePortByName(
+      { meta, ports: isGreen ? greenPorts : ports },
+      (webInterface || dockerInterface).name
+    );
     if (logToTerminal) {
       // eslint-disable-next-line no-console
       console.log(
@@ -1087,6 +1114,52 @@ const _checkProcessHealthy = async (blocklet, { minConsecutiveTime, timeout, log
   }
 };
 
+const checkBlockletProcessHealthy = async (
+  blocklet,
+  { minConsecutiveTime, timeout, componentDids, setBlockletRunning, isGreen = false } = {}
+) => {
+  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 });
+      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;
@@ -1108,8 +1181,9 @@ const isBlockletPortHealthy = async (blocklet, { minConsecutiveTime = 3000, time
   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 = environments?.find((e) => e.key === 'BLOCKLET_PORT')?.value;
+  let port = blocklet.greenStatus === BlockletStatus.running ? blocklet.greenPorts?.[key] : blocklet.ports?.[key];
 
   if (!port) {
     const keyPort = webInterface?.port || dockerInterface?.port;
@@ -1354,26 +1428,6 @@ const getRuntimeInfo = async (processId) => {
   };
 };
 
-/**
- *
- *
- * @param {string} dockerName
- * @return {Promise<{ memoryUsage?: number }>}
- */
-const getDockerRuntimeInfoByDockerName = async (dockerName) => {
-  try {
-    const proc = await promiseSpawn(`docker stats --no-stream --format "{{json .}}" ${dockerName}`, { mute: true });
-    const stats = JSON.parse(proc);
-    return {
-      cpuUsage: stats.CPUPerc ? parseFloat(stats.CPUPerc.replace('%', '').trim()) : 0,
-      memoryUsage: stats.MemUsage ? xbytes.parseSize(stats.MemUsage.split('/')[0].trim()) : 0,
-    };
-  } catch (error) {
-    logger.error('Get docker runtime info by docker name failed', { dockerName, error });
-    return {};
-  }
-};
-
 /**
  * merge services
  * from meta.children[].mountPoints[].services, meta.children[].services
@@ -1449,7 +1503,7 @@ const getUpdateMetaList = (oldBlocklet = {}, newBlocklet = {}) => {
   const res = [];
 
   forEachChildSync(newBlocklet, (b, { id }) => {
-    if (b.bundleSource && semver.gt(b.meta.version, oldMap[id])) {
+    if ((b.bundleSource && semver.gt(b.meta.version, oldMap[id])) || process.env.TEST_UPDATE_ALL_BLOCKLET === 'true') {
       res.push({ id, meta: b.meta });
     }
   });
@@ -2254,8 +2308,8 @@ const getBlockletStatus = (blocklet) => {
       return;
     }
 
-    if (isRunning(component.status)) {
-      runningStatus = component.status;
+    if (isRunning(component.status) || isRunning(component.greenStatus)) {
+      runningStatus = BlockletStatus.running;
       return;
     }
 
@@ -2289,25 +2343,35 @@ const ensureAppPortsNotOccupied = async ({
   states,
   manager,
   checkPortsFn = isPortsOccupiedByOtherProcess,
+  isGreen = false,
 }) => {
   const { did } = blocklet.meta;
-  const componentDids = [];
+  const dids = new Set();
   await forEachComponentV2(blocklet, async (b) => {
     try {
       if (shouldSkipComponent(b.meta.did, inputDids)) {
         return;
       }
-
       const { processId } = b.env;
-      const { ports } = b;
+      const { ports, greenPorts } = b;
+
+      if (
+        await checkPortsFn({
+          ports: greenPorts || ports,
+          pm2ProcessId: isGreen ? `${processId}-green` : processId,
+          printError: logger.error.bind(logger),
+        })
+      ) {
+        dids.add(b.meta.did);
+      }
       if (
         await checkPortsFn({
           ports,
-          pm2ProcessId: processId,
+          pm2ProcessId: !isGreen ? `${processId}-green` : processId,
           printError: logger.error.bind(logger),
         })
       ) {
-        componentDids.push(b.meta.did);
+        dids.add(b.meta.did);
       }
     } catch (error) {
       logger.error('Failed to check ports occupied', { error });
@@ -2315,8 +2379,9 @@ const ensureAppPortsNotOccupied = async ({
   });
 
   let newBlocklet = blocklet;
+  const componentDids = Array.from(dids);
   if (componentDids.length) {
-    await states.blocklet.refreshBlockletPorts(did, componentDids);
+    await states.blocklet.refreshBlockletPorts(did, componentDids, isGreen);
     logger.info('refresh component ports', { did, componentDids });
     await manager._updateBlockletEnvironment(did);
     newBlocklet = await manager.ensureBlocklet(did);
@@ -2521,6 +2586,16 @@ const copyPackImages = async ({ appDataDir, packDir, packConfig = {} }) => {
  */
 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,
@@ -2532,6 +2607,7 @@ module.exports = {
   getAppOverwrittenEnvironments,
   getComponentSystemEnvironments,
   getRuntimeEnvironments,
+  getHookArgs,
   validateBlocklet,
   validateBlockletChainInfo,
   fillBlockletConfigs,
@@ -2551,7 +2627,6 @@ module.exports = {
   pruneBlockletBundle,
   getDiskInfo,
   getRuntimeInfo,
-  getDockerRuntimeInfoByDockerName,
   mergeMeta,
   getUpdateMetaList,
   getTypeFromInstallParams,

package/lib/util/docker/is-docker-only-single-instances.js

@@ -0,0 +1,17 @@
+// 是否是自定义 docker 镜像, 并且是否挂载了数据卷
+function isDockerOnlySingleInstance(meta = {}) {
+  if (!meta.docker) {
+    return false;
+  }
+  // 保留字段, 用于描述 docker 镜像支持多实例运行
+  if (meta.docker.allowMultipleInstances) {
+    return false;
+  }
+  if (meta.docker.RunBaseScript && meta.docker.installNodeModules) {
+    return false;
+  }
+
+  return !!meta.docker.volume;
+}
+
+module.exports = { isDockerOnlySingleInstance };

package/lib/util/org.js

@@ -0,0 +1,99 @@
+const { ROLES, SERVER_ROLES } = require('@abtnode/constant');
+const { getAppUrl } = require('@blocklet/meta/lib/util');
+const { CustomError } = require('@blocklet/error');
+const { joinURL, withQuery } = require('ufo');
+const { WELLKNOWN_SERVICE_PATH_PREFIX } = require('@abtnode/constant');
+const get = require('lodash/get');
+
+const { isAdminPath, getEndpoint } = require('./verify-access-key-user');
+
+const MAX_PAGE_SIZE = 100;
+
+const formatPaging = (paging) => {
+  const { pageSize = 20, page = 1 } = paging || {};
+  const newPageSize = Math.max(1, Math.min(MAX_PAGE_SIZE, parseInt(pageSize, 10)));
+  const newPage = Math.max(1, parseInt(page, 10));
+  return { pageSize: newPageSize, page: newPage };
+};
+
+const isAdminUser = (user) => {
+  const { role = '' } = user || {};
+  if (!role) {
+    return false;
+  }
+  return [ROLES.ADMIN, ROLES.OWNER, SERVER_ROLES.BLOCKLET_ADMIN, SERVER_ROLES.BLOCKLET_OWNER].includes(role);
+};
+
+const isOrgOwner = (user, org) => {
+  const { did } = user || {};
+  if (!org) {
+    throw new CustomError(403, 'Org not found');
+  }
+  return org.ownerDid === did;
+};
+
+const isAdmingPath = (context = {}) => {
+  try {
+    const pathname = getEndpoint(context);
+    return isAdminPath(pathname);
+  } catch (error) {
+    return false;
+  }
+};
+
+const getOrgInviteLink = (inviteInfo, blocklet) => {
+  const { inviteId } = inviteInfo || {};
+  const appUrl = getAppUrl(blocklet);
+  if (!inviteId || !appUrl) {
+    throw new CustomError(500, 'Invitation link creation failed, please try again later');
+  }
+  return withQuery(joinURL(appUrl, WELLKNOWN_SERVICE_PATH_PREFIX, 'invite'), { inviteId });
+};
+
+const createOrgValidators = (blocklet = {}) => {
+  function getOrgSettings() {
+    const org = get(blocklet, 'settings.org', { enabled: false, maxMemberPerOrg: 100, maxOrgPerUser: 10 });
+    return org || { enabled: false, maxMemberPerOrg: 100, maxOrgPerUser: 10 };
+  }
+
+  const org = getOrgSettings();
+
+  function verifyOrgEnabled() {
+    if (!org?.enabled) {
+      throw new CustomError(403, 'Org is not enabled');
+    }
+    return true;
+  }
+
+  function veriftMaxMemberPerOrg(number) {
+    verifyOrgEnabled();
+    if (number >= org.maxMemberPerOrg) {
+      throw new CustomError(403, `The current org can invite up to ${org.maxMemberPerOrg} members`);
+    }
+    return true;
+  }
+
+  function veriftMaxOrgPerUser(number) {
+    verifyOrgEnabled();
+    if (number >= org.maxOrgPerUser) {
+      throw new CustomError(403, `You can create up to ${org.maxOrgPerUser} orgs`);
+    }
+    return true;
+  }
+
+  return {
+    verifyOrgEnabled,
+    veriftMaxMemberPerOrg,
+    veriftMaxOrgPerUser,
+    getOrgSettings,
+  };
+};
+
+module.exports = {
+  formatPaging,
+  isAdminUser,
+  isOrgOwner,
+  isAdmingPath,
+  getOrgInviteLink,
+  createOrgValidators,
+};

package/lib/validators/org.js

@@ -0,0 +1,19 @@
+const { Joi } = require('@arcblock/validator');
+
+const createOrgInputSchema = Joi.object({
+  name: Joi.string().required().trim().min(1).max(20),
+  description: Joi.string().optional().allow('').trim().min(1).max(255),
+  ownerDid: Joi.DID().optional().allow('').allow(null),
+});
+
+/**
+ * 只允许更新 name 和 description
+ */
+const updateOrgInputSchema = Joi.object({
+  id: Joi.string().required(),
+  name: Joi.string().required().trim().min(1).max(20),
+  description: Joi.string().optional().allow('').trim().min(1).max(255),
+});
+
+exports.createOrgInputSchema = createOrgInputSchema;
+exports.updateOrgInputSchema = updateOrgInputSchema;