NocoBase 插件生命周期管理实战nb pluginCLI 命令全解析import / list / enable / disable【免费下载链接】nocobaseNocoBase is an open-source AI no-code platform for building business systems fast. Instead of generating everything from scratch, AI works on top of production-proven infrastructure and a WYSIWYG no-code interface, so you get both speed and reliability.项目地址: https://gitcode.com/GitHub_Trending/no/nocobaseNocoBase 是一款开源的 AI 无代码业务系统搭建平台其插件化架构允许开发者通过独立插件包扩展系统能力。nb plugin是 NocoBase CLI 中专门负责插件生命周期管理的命令族覆盖导入插件包 → 查看已安装插件 → 启用 / 停用插件的完整流程。读完本文你将掌握如何针对不同的 NocoBase env本地、Docker、HTTP安全地导入第三方插件、正确地重启应用并启用插件以及理解底层 CLI 是如何完成这些工作的。命令总览nb plugin commandnb plugin命令用于管理选中 NocoBase env 的插件。这里所说的env是 NocoBase CLI 对运行环境本地目录、npm 包、Git 仓库、Docker 容器、远程 HTTP 服务的抽象nb plugin会根据 env 类型自动选择执行方式npm / Git env在本地执行插件命令例如调用本地应用内的pm子命令Docker env在已保存的应用容器内执行HTTP env在可用时回退到 API 方式执行如通过应用后台 API 启停插件。其通用用法为nb plugin commandnb plugin提供四个子命令完整清单如下命令说明nb plugin import导入插件压缩包或 npm 插件包nb plugin list列出已安装插件nb plugin enable启用一个或多个插件nb plugin disable停用一个或多个插件一个典型的完整操作序列nb plugin import ./plugin-auth-cas-1.4.0.tgz --storage-path ./storage nb plugin list -e local nb plugin enable nocobase/plugin-sample nb plugin disable -e local nocobase/plugin-sample与nb plugin高度相关的命令还包括nb env info查看当前 env 的应用 / 数据库 / API / 认证配置和nb scaffold plugin生成新插件脚手架。前者用于在操作前确认目标环境后者用于创建自己的插件——先scaffold创建、再import/enable部署构成插件开发的完整闭环。子命令详解一nb plugin importnb plugin import负责把插件压缩包或 npm 插件包导入storage/plugins。需要特别强调的是这个命令只负责把插件放到目标目录不会自动启用插件。用法与参数nb plugin import archive [flags]参数类型说明archivestring插件来源必填。支持本地.tgz路径、远程http(s)压缩包地址或者 npm 包名 / tag--env,-estringCLI env 名称。省略时通常使用当前 env如果显式传了--storage-path也可以不传--yes,-yboolean当显式--env指向的 env 与当前 env 不一致时跳过交互确认--storage-pathstring覆盖目标 storage 根目录。实际导入目录是storage-path/plugins--npm-registrystring当来源是 npm 包名或 tag 时指定要使用的 npm registry三种来源的导入示例# 远程压缩包 nb plugin import https://github.com/nocobase/plugin-auth-cas/releases/download/v1.4.0/plugin-auth-cas-1.4.0.tgz # 本地压缩包 nb plugin import /your/path/plugin-auth-cas-1.4.0.tgz # npm 包名或 tag nb plugin import my-scope/plugin-auth-casbeta # 私有 npm 源 nb plugin import my-scope/plugin-auth-casbeta --npm-registryhttps://registry.example.com # 不依赖当前 env直接写入一个本地 storage 路径 nb plugin import ./plugin-auth-cas-1.4.0.tgz --storage-path ./storage导入目标如何确定如果你已经选好了目标 env默认直接导入这个 env 的storage/plugins即可。如果你只想把插件放进某个本地 storage 目录可以显式传--storage-path。此时--env可以省略CLI 会直接把插件写入storage-path/plugins。从源码看当同时给出--storage-path与 env 配置时显式传入的--storage-path优先级更高见 packages/core/cli/src/commands/plugin/import.ts。导入之后做什么导入完成后通常来说下一步是重启应用再决定是否启用插件第一次安装插件通常先执行nb app restart见nb app restart再执行nb plugin enable重新导入一个新版本通常先重启再继续验证插件是否已经正常加载。如果来源是私有 npm registry通常先登录再执行导入npm login --registryhttps://registry.example.com nb plugin import my-scope/plugin-auth-casbeta --npm-registryhttps://registry.example.com:::warning 注意 这里不需要手动解压到storage/plugins。nb plugin import会自动把插件放到正确目录。 :::面向 HTTP / SSH env 的限制从源码实现packages/core/cli/src/commands/plugin/import.ts可以确认当前版本对两种 env 的导入能力做了显式限制HTTP env错误信息明确指出 HTTP env 没有向 CLI 暴露可写的storage/plugins路径nb plugin import目前只支持 local 或 Docker envSSH envSSH 支持已被预留但尚未实现。这是由 env 的运行机制决定的——插件导入需要直接向文件系统写入解压后的包内容远程 API 与 SSH 通道在当前版本中尚未提供对应的写入口。子命令详解二nb plugin listnb plugin list用于列出选中 env 的已安装插件。nb plugin list [flags]参数类型说明--env,-estringCLI env 名称省略时使用当前 env--yes,-yboolean当显式--env指向的 env 与当前 env 不一致时跳过交互确认nb plugin list nb plugin list -e local nb plugin list -e local --yes nb plugin list -e local-docker从源码实现packages/core/cli/src/commands/plugin/list.ts可以看到 list 命令如何按 env 类型分发local env在本地执行pm listDocker env在容器内执行pm listHTTP env回退调用api:pm:list子命令通过应用 API 获取插件摘要--modesummarySSH env与 import 类似当前版本会报错提示预留但未实现。也就是说nb plugin list是所有 env 类型都能使用的查看入口这也是它与其他三个命令在 env 支持度上最明显的差异。子命令详解三nb plugin enable与nb plugin disable启用与停用插件的用法完全对称都支持一次操作多个插件。nb plugin enable packages... [flags] nb plugin disable packages... [flags]参数类型说明packages...string[]插件包名必填支持传入多个--env,-estringCLI env 名称省略时使用当前 env--yes,-yboolean当显式--env指向的 env 与当前 env 不一致时跳过交互确认nb plugin enable nocobase/plugin-sample nb plugin enable nocobase/plugin-a nocobase/plugin-b nb plugin enable -e local nocobase/plugin-sample nb plugin enable -e local --yes nocobase/plugin-sample nb plugin disable nocobase/plugin-sample nb plugin disable nocobase/plugin-a nocobase/plugin-b nb plugin disable -e local nocobase/plugin-sample nb plugin disable -e local --yes nocobase/plugin-sample从源码packages/core/cli/src/commands/plugin/enable.ts可以看到 enable 的执行路径local env 执行pm enable packages...Docker env 在容器内执行同样的命令HTTP env 则回退到api:pm:enable并通过--await-response --filter-by-tk等待应用侧确认。disable 的实现与 enable 完全对称。关于--env与--yes的交互约定四个子命令以及nb app restart共享同一个环境确认逻辑只有在你显式传入--env时CLI 才会检查它是否与当前 env 一致。如果显式指定了不同的 env交互终端会先弹出确认在非交互终端或 AI agent 场景下需要由你自己显式追加--yes或者先执行nb env use name切换环境再重试。这一点在nb app restart的文档中同样有说明是 NocoBase CLI 各命令间统一的行为约定。实战工作流第三方插件的安装与升级结合 NocoBase 官方指南第三方插件安装与升级nb plugin命令族最常见的完整场景如下。1. 先确认目标环境如果你本地管理了多个应用先切到目标 env 再操作nb env use app12. 导入插件包# 远程压缩包 nb plugin import https://github.com/nocobase/plugin-auth-cas/releases/download/v1.4.0/plugin-auth-cas-1.4.0.tgz # 本地压缩包 nb plugin import /your/path/plugin-auth-cas-1.4.0.tgz # npm 包名或 tag nb plugin import my-scope/plugin-auth-casbeta私有 npm 源先登录再指定 registrynpm login --registryhttps://registry.example.com nb plugin import my-scope/plugin-auth-casbeta --npm-registryhttps://registry.example.com如果已经知道目标应用的storage根目录也可以不依赖当前 env直接传--storage-pathnb plugin import /your/path/plugin-auth-cas-1.4.0.tgz --storage-path ./storageCLI 会把插件写入storage-path/plugins此时不需要先执行nb env use也不需要传--env。3. 导入之后先重启nb app restart如果没有先切换当前 env可以在命令里显式传入-e env。nb app restart在适用时还会先同步当前授权允许使用的商业插件并在应用就绪后通过__health_check接口做健康检查每 10 秒输出一条进度提示直到应用可用或超时。4. 第一次安装重启后再启用nb plugin enable nocobase/plugin-auth-cas第一次启用时会自动完成安装。5. 升级只需要导入 重启如果插件已经启用而这次只是换成一个新版本通常两步即可nb plugin import /your/path/plugin-auth-cas-1.5.0.tgz nb app restart导入 npm 包同理nb plugin import my-scope/plugin-auth-caslatest nb app restart也就是说升级场景不需要再额外执行nb plugin enable。把新包导入进去然后重启应用即可——CLI 检测到目标目录已存在同名插件时会以updated更新而非installed新装的动作完成覆盖。6. 不能直接联网时如果目标机器不能直接访问插件下载地址可以先把.tgz文件上传到目标机器的任意目录再在目标机器执行本地导入nb plugin import /your/path/plugin-auth-cas-1.4.0.tgz nb app restart源码级原理nb plugin import是如何工作的nb plugin import的核心逻辑集中在 packages/core/cli/src/lib/plugin-import.ts整个流程可以拆解为五个阶段。阶段一判定来源类型并打开数据流openPluginSourcepackages/core/cli/src/lib/plugin-import.ts按顺序做三类判定http(s) URLisHttpArchiveSource通过new URL(value)校验协议头命中后直接用fetch拉取远程压缩包支持认证重定向保留本地文件path.resolve(process.cwd(), source)解析为绝对路径pathExists确认文件存在后以fs.createReadStream读取npm 包名 / taglooksLikeLocalArchivePath判定它不是本地路径非绝对路径、不以.//../开头、不以.tgz/.tar.gz结尾后走packNpmPluginSource——在临时目录中执行npm pack --silent可附加--registryregistry把 npm 包打成 tarball再从临时目录中读取唯一的.tgz文件。对于 npm 打包NPM_PACK_TIMEOUT_MS 30_000限定了单次打包的等待上限打包失败时会根据 stderr / stdout 内容做错误分类并给出针对性提示详见下文排错一节。阶段二解压并定位包根目录拿到数据流后CLI 用pipeline(stream, createGunzip(), tar.extract(...))完成 gzip 解压与 tar 解包落盘到一个临时 staging 目录。resolveArchivePackageRootpackages/core/cli/src/lib/plugin-import.ts随后处理两种常见的压缩包形态npm 风格 tarballnpm pack/ registry 下载所有内容被包裹在一个顶层目录惯例为package/中NocoBase 自产压缩包yarn build plugin --tar条目直接位于压缩包根。由于两种形态混用strip: 1会静默丢失后者根目录下的文件CLI 选择原样解压 事后探测先看解压根有没有package.json没有则检查是否恰好存在一个含package.json的唯一子目录否则回退到解压根目录让后续元数据读取报错。阶段三读取元数据并安全落盘readPluginMetadata从包根读取package.json校验name字段是否存在。resolvePluginOutputDirpackages/core/cli/src/lib/plugin-import.ts则是一个安全校验点它以storage-plugins-path/packageName计算目标目录并校验相对路径不得跳出插件存储根目录relative.startsWith(..)等场景直接抛错防止恶意包名把文件写到storage/plugins之外。最终动作若目标目录已存在 →action updated先删除旧目录再重命名原子覆盖若不存在 →action installed直接重命名。finally块保证 staging 目录与 npm 临时目录在任何路径下都会被清理。阶段四storage 路径的解析优先级resolvePluginStoragePathpackages/core/cli/src/lib/plugin-storage.ts的取值优先级从高到低为显式传入的--storage-path或STORAGE_PATH环境变量拼上plugins子目录PLUGIN_STORAGE_PATH环境变量直接作为 plugins 目录兜底默认值cwd/storage/plugins。这解释了为何--storage-path ./storage会把插件放进storage-path/plugins——根目录与plugins子目录的拼接发生在 lib 层而非命令层。阶段五命令收尾与引导提示导入成功后命令输出Imported/Updated nameversion into outputDir并打印插件存储路径随后根据是否解析到运行时环境给出下一步引导有 env 时提示nb app restart --env env否则提示重启使用该插件存储路径的应用。从 packages/core/cli/src/commands/plugin/import.ts 可以看到这一交互设计——CLI 始终把重启作为启用前的显式步骤呈现给用户。排错参考npm 导入失败时的三类提示nb plugin import针对 npm 包来源的失败场景做了错误分类packages/core/cli/src/lib/plugin-import.ts当npm pack失败时CLI 会根据错误关键词给出对应提示失败类别关键词示例提示方向认证 / 权限e401、e403、unauthorized、forbidden、requires authentication私有 registry 先执行npm login --registryregistry再重试包不存在e404、etarget、not found、no matching version found检查包名 / tag 在指定 registry 中是否存在网络问题enotfound、etimedout、econnreset、fetch failed、timed out检查 registry 从当前机器是否可达这种设计让非交互终端如 CI 或 AI agent也能从单条错误消息中直接定位问题。小结nb plugin命令族以import → list → enable → disable四条命令覆盖了插件从进入应用到上线 / 下线的完整生命周期import只负责把包放进storage/plugins三类来源 可覆盖 storage 路径list负责核对已安装状态全 env 类型可用enable/disable负责运行时启停支持多包批量操作。贯穿始终的--env/--yes约定、local / Docker / HTTP 三种执行通道的分发以及 import 命令内部的来源判定 → 解压探测 → 元数据校验 → 安全落盘流水线共同构成了一个既适合人机交互、也适合自动化脚本与 AI agent 场景的插件管理入口。要深入阅读实现可以继续查看 packages/core/cli/src/commands/plugin/ 下的四个命令文件以及 packages/core/cli/src/lib/plugin-import.ts 和 packages/core/cli/src/lib/plugin-storage.ts 两个核心库文件。【免费下载链接】nocobaseNocoBase is an open-source AI no-code platform for building business systems fast. Instead of generating everything from scratch, AI works on top of production-proven infrastructure and a WYSIWYG no-code interface, so you get both speed and reliability.项目地址: https://gitcode.com/GitHub_Trending/no/nocobase创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考