NocoBase 2.2.29 常用 CLI 命令与工具详解

目标：把 NocoBase 2.2.29 的命令行工具一次讲透——应用内 nocobase CLI 的入口形态与运行机制、插件管理器 pm 的全部子命令（含 enable/disable 实操与还原）、install/upgrade 生命周期命令、PM2 进程管理工具在两种安装形态下的差异，以及宿主侧 docker compose 运维命令的分工对照。全部命令与回显在「Ubuntu 22.04.4 LTS / Docker Compose v5.5.1 / NocoBase 2.2.29 / PostgreSQL 16」环境实测取得，逐行照抄；部署基线见《NocoBase 2.2.29 Docker Compose 部署指南》，参数背景见《NocoBase 2.2.29 配置参数详解》。

一、环境信息

操作系统：Ubuntu 22.04.4 LTS（x86_64）
基础组件：Docker Engine 29.8.1、Docker Compose v5.5.1
实例版本：NocoBase 2.2.29（版本接口实测 {"data":{...,"version":"2.2.29",...}}，见 4.5）
应用运行时：Node.js v22.23.3、yarn 1.22.22（实例内 node -v / yarn -v 实测）
应用目录：/app/nocobase（官方发行版内的应用根目录，CLI 与数据目录都在其下）
数据目录：/app/nocobase/storage（宿主侧映射为部署目录 storage/）
初始管理员：admin@nocobase.com / admin123（官方初始值；本系列演示统一以 admin + q1w2e3r4 为改密后示例凭据）

二、工具概览

工具	所在位置	用途	适用形态
`nocobase`（经 `yarn nocobase` 调用）	`/app/nocobase/node_modules/.bin/`	应用生命周期与插件管理：install / upgrade / pm 等	全部安装形态
`pm2`	`/app/nocobase/node_modules/.bin/pm2`	Node.js 进程管理：启停、日志、多进程	Docker 形态下仅观察；create-nocobase-app / Git 形态下为日常进程工具
`docker compose`	宿主	编排层运维：状态、日志、重启、升级	Docker Compose 部署
`curl`	宿主/实例内均有	健康检查与版本接口验证	全部形态

命令形态约定：本篇统一从宿主部署目录（/opt/nocobase）执行 docker compose exec -T app sh -c 'cd /app/nocobase && <实例内命令>' 进入应用目录执行实例内命令。-T 关闭伪终端分配，脚本与定时任务场景必需；交互式会话中省略 -T 效果相同。实例内 PATH 不包含 node_modules/.bin，因此 nocobase 命令必须先 cd /app/nocobase 再以 yarn nocobase <子命令> 形态调用（package.json 中 scripts.nocobase 指向 nocobase-v1 包装器，实测直接执行 ./node_modules/.bin/nocobase 与 yarn nocobase 等价）。

三、前置条件

已按部署篇完成部署，实例健康（版本接口返回 200）：

cd /opt/nocobase
curl -s -o /dev/null -w 'HTTP %{http_code}\n' http://127.0.0.1:8140/api/app:getInfo

实测回显：

HTTP 200

理解 CLI 的通信机制（影响本篇所有命令的行为解读）：nocobase CLI 通过 IPC 与运行中的应用实例通信，命令结果由运行中实例执行后回传——这意味着 CLI 命令的输出与实例运行状态强相关，也是 4.1 排障实录中 -h 异常的根因。

四、各工具详解

4.1 nocobase CLI：入口形态与 -h 异常排障实录

预期中的帮助命令在 2.2.29 触发异常——这是本次实测最重要的排障沉淀，先给结论：顶层 -h 在 v2.2.29 存在缺陷，改用子命令级帮助（pm -h）与官方文档替代。

docker compose exec -T app sh -c 'cd /app/nocobase && yarn nocobase -h'

实测回显（完整）：

yarn run v1.22.22
$ nocobase-v1 -h
About to overwrite ArrayBuffer.prototype properties ["sliceToImmutable","immutable","transferToImmutable"]
2026-10-21 23:16:10 [error] callback is not a function|TypeError: callback is not a function
  at _PluginManager.loadCommands (/app/nocobase/node_modules/@nocobase/server/lib/plugin-manager/plugin-manager.js:383:7)
  at async IPCSocketServer.handleClientMessage (/app/nocobase/node_modules/@nocobase/server/lib/gateway/ipc-socket-server.js:124:9) reqId=20333f85-ac57-4cfe-a2d8-fef80be3a682
Done in 3.19s.

排障过程与结论：错误栈落在 PluginManager.loadCommands 且经由 IPCSocketServer.handleClientMessage 触发——CLI 把 -h 请求经 IPC 转给了运行中实例，实例在装载命令清单时的回调注册存在缺陷（v2.2.29 实测行为）。实际影响仅限顶层 -h：所有实际子命令（pm、install 等）均正常执行（见 4.2–4.4 实测），升级新版本后可复测该行为。日常查帮助的替代路径：

docker compose exec -T app sh -c 'cd /app/nocobase && yarn nocobase pm -h'

实测回显（完整，子命令级帮助正常）：

yarn run v1.22.22
$ nocobase-v1 pm -h
About to overwrite ArrayBuffer.prototype properties ["sliceToImmutable","immutable","transferToImmutable"]
Usage: nocobase pm [options] [command]

Options:
  -h, --help                          display help for command

Commands:
  list
  create [options] <plugin>
  pull [options] <packageNames...>
  add [options] <packageNames...>
  update [options] <packageNames...>
  enable-all
  enable <plugins...>
  disable <plugins...>
  remove [options] <plugins...>
  help [command]                      display help for command
Done in 2.99s.

💡 说明：回显中的 About to overwrite ArrayBuffer.prototype properties [...] 是 Node.js Secure Transform 运行时的提示输出，每条 CLI 命令都会打印，属正常现象而非错误。

4.2 pm：插件管理器（全部子命令）

pm 是 NocoBase「全功能插件化」架构的运维入口（架构背景见《NocoBase 介绍与选型指南》第三章）。子命令清单即 4.1 的 pm -h 实测输出，逐个说明用途与实测形态：

子命令	语法	用途
`list`	`nocobase pm list`	列出全部插件与启用状态（JSON）
`enable`	`nocobase pm enable <plugins...>`	启用插件
`disable`	`nocobase pm disable <plugins...>`	停用插件
`enable-all`	`nocobase pm enable-all`	启用全部已安装插件
`add`	`nocobase pm add <packageNames...>`	添加已存在于 node_modules 的插件到应用
`remove`	`nocobase pm remove [options] <plugins...>`	从应用移除插件
`create`	`nocobase pm create [options] <plugin>`	生成插件脚手架（二开场景）
`pull`	`nocobase pm pull [options] <packageNames...>`	从注册源下载插件包
`update`	`nocobase pm update [options] <packageNames...>`	升级插件包

pm list 实测（输出为两行标记之间的 JSON 数组，本篇节选首尾，完整清单一次列出 81 项）：

docker compose exec -T app sh -c 'cd /app/nocobase && yarn nocobase pm list'

实测回显（节选，首部）：

yarn run v1.22.22
$ nocobase-v1 pm list
About to overwrite ArrayBuffer.prototype properties ["sliceToImmutable","immutable","transferToImmutable"]
--- BEGIN_PLUGIN_LIST_JSON ---
[{"displayName":"Access control","packageName":"@nocobase/plugin-acl","enabled":true,"description":"Based on roles, resources, and actions, access control can precisely manage interface configuration permissions, data operation permissions, menu access permissions, and plugin permissions."},{"displayName":"Action: Batch edit","packageName":"@nocobase/plugin-action-bulk-edit","enabled":true,...},...

实测回显（节选，尾部）：

...,{"displayName":"Workflow: Dynamic calculation node","packageName":"@nocobase/plugin-workflow-dynamic-calculation","enabled":false,...}]
--- END_PLUGIN_LIST_JSON ---
Done in 3.22s.

清单解读（基于完整输出统计）：enabled: true 的内置启用插件覆盖权限（plugin-acl）、认证（plugin-auth）、工作流全家桶（plugin-workflow 与 18 个 workflow-* 节点插件）、数据可视化、文件管理、备份（plugin-backups）、AI 员工（plugin-ai）、AI MCP server（plugin-mcp-server）、API 文档（plugin-api-doc）、日志（plugin-logger）等；enabled: false 的待启用插件包括 ECharts 图表（plugin-data-visualization-echarts）、部门（plugin-departments）、地图（plugin-map）、公开表单（plugin-public-forms）、本地化（plugin-localization）等。界面里的「插件管理器」页与这份清单同源。

pm enable / pm disable 实操（以 ECharts 插件为例，先启用验证、后停用还原）：

docker compose exec -T app sh -c 'cd /app/nocobase && yarn nocobase pm enable data-visualization-echarts'

实测回显：

About to overwrite ArrayBuffer.prototype properties ["sliceToImmutable","immutable","transferToImmutable"]
{"level":"info","message":"run static import","extra":{"packageName":"@nocobase/plugin-multi-app-manager"},"meta":{"packageName":"@nocobase/plugin-multi-app-manager"},"module":"cli","submodule":"","method":"","app":"main","dataSourceKey":"main","timestamp":"2026-10-21 23:17:03"}
2026-10-21 23:17:05 [info]  success                                      reqId=2dca0230-1bce-4ef9-b1a7-36bb260e5044
Done in 5.06s.

看到 success 即启用成功（实例内同步生效，无需重启）；复跑 pm list 可见对应插件的 enabled 已翻为 true。停用还原：

docker compose exec -T app sh -c 'cd /app/nocobase && yarn nocobase pm disable data-visualization-echarts'

实测回显：

About to overwrite ArrayBuffer.prototype properties ["sliceToImmutable","immutable","transferToImmutable"]
{"level":"info","message":"run static import","extra":{"packageName":"@nocobase/plugin-multi-app-manager"},"meta":{"packageName":"@nocobase/plugin-multi-app-manager"},"module":"cli","submodule":"","method":"","app":"main","dataSourceKey":"main","timestamp":"2026-10-21 23:17:08"}
2026-10-21 23:17:09 [info]  success                                      reqId=204bd6aa-e65e-46b7-a755-25ac9df3d860
Done in 3.71s.

⚠️ 注意：插件名用短名（data-visualization-echarts）而非完整包名（@nocobase/plugin-data-visualization-echarts），与 pm list 输出中 packageName 去掉前缀后的部分一致；写全名会报找不到插件。

4.3 install 与 upgrade：生命周期命令

nocobase install：初始化安装（建表、写入初始数据）。Docker 方式首次启动时自动执行（部署篇 4.3 日志可见 ... index.js install -s 的自动安装行），手工执行场景是 create-nocobase-app / Git 源码安装与重新初始化。实测在已安装实例上重跑——命令幂等，不会破坏数据：

docker compose exec -T app sh -c 'cd /app/nocobase && yarn nocobase install'

实测回显（已安装实例重跑）：

yarn run v1.22.22
$ nocobase-v1 install
$ nocobase-v1 pkg download-pro
2026-10-21 23:16:42 [info] License key not found
{"level":"info","message":"run static import","extra":{"packageName":"@nocobase/plugin-backups"},"meta":{"packageName":"@nocobase/plugin-backups"},"module":"cli","submodule":"","method":"","app":"main","dataSourceKey":"main","timestamp":"2026-10-21 23:16:44"}
{"level":"info","message":"run static import","extra":{"packageName":"@nocobase/plugin-file-manager"},"meta":{"packageName":"@nocobase/plugin-file-manager"},"module":"cli","submodule":"","method":"","app":"main","dataSourceKey":"main","timestamp":"2026-10-21 23:16:44"}
About to overwrite ArrayBuffer.prototype properties ["sliceToImmutable","immutable","transferToImmutable"]
{"level":"info","message":"run static import","extra":{"packageName":"@nocobase/plugin-multi-app-manager"},"meta":{"packageName":"@nocobase/plugin-multi-app-manager"},"module":"cli","submodule":"","method":"","app":"main","dataSourceKey":"main","timestamp":"2026-10-21 23:16:45"}
2026-10-21 23:16:45 [info]  success                                      reqId=baffd90b-8947-48ca-bc5c-d2f8799df849
Done in 3.43s.

回显解读：License key not found 是商业版许可检测的正常提示（开源使用无需许可键，不阻断流程）；随后对 plugin-backups/plugin-file-manager/plugin-multi-app-manager 做静态导入校验后返回 success——未安装的全新库上执行同命令则会完成完整初始化，此时可配临时环境变量定制初始管理员（INIT_APP_LANG/INIT_ROOT_EMAIL/INIT_ROOT_PASSWORD/INIT_ROOT_NICKNAME，语法与默认值见配置篇 5.7）。

nocobase upgrade：升级命令（迁移数据库结构、升级内置插件，实验性的 APPEND_PRESET_* 插件也在该时机生效）。两种形态的分工：Docker 方式的版本升级由新版发行物首次启动自动完成（pull + up -d 流程已在部署篇第九章实测，无需手工执行）；手工 yarn nocobase upgrade 用于 create-nocobase-app 与 Git 源码形态的代码更新后升级。参数与执行细节以官方文档为准。

4.4 pm2：进程管理工具

NocoBase 应用进程由 PM2 托管，但托管形态随安装方式不同而不同，这是 pm2 命令能否管理到进程的分水岭：

Docker Compose 形态（本篇实测环境）：应用由 pm2-runtime 以前台方式托管为应用主进程，pm2 客户端连接不到独立守护进程，pm2 ls 返回空表：

docker compose exec -T app sh -c 'cd /app/nocobase && ./node_modules/.bin/pm2 ls'

实测回显（banner 与进程表，尾部节选）：

        PM2 is a Production Process Manager for Node.js applications
                     with a built-in Load Balancer.
        ...
┌────┬───────────┬─────────────┬─────────┬─────────┬──────────┬────────┬──────┬───────────┬──────────┬──────────┬──────────┐
│ id │ name      │ namespace   │ version │ mode    │ pid      │ uptime │ ↺    │ status    │ cpu      │ mem      │ user     │ watching │
└────┴───────────┴─────────────┴─────────┴─────────┴──────────┴────────┴──────┴───────────┴──────────┴──────────┴──────────┴──────────┘
host metrics | cpu: 0% | ram usage: 39.6% | disk: ⇓ 0mb/s ⇑ 0mb/s

空进程表是预期行为而非故障——此形态下进程生命周期交给 compose 管理：重启用 docker compose restart app（部署篇第十章实测），日志用 docker compose logs，不需要也不应该在实例内用 pm2 客户端操作。

create-nocobase-app / Git 源码形态：应用以常规方式启动，PM2 为标准守护进程，官方文档「常用运维命令」给出的 pm2 日常命令为（来源：官方文档，2026-10-21 查询）：

pm2 start pm2.json      # 按 pm2.json 配置启动
pm2 stop pm2.json       # 停止
pm2 restart pm2.json    # 重启
pm2 logs                # 跟踪日志
pm2 flush               # 清空 pm2 日志缓冲

4.5 宿主侧 docker compose 运维命令与版本验证

Docker Compose 形态的日常运维命令（均在部署目录执行，完整说明与实测回显见部署篇第十、五章）：

docker compose ps                      # 状态与端口
docker compose logs --tail=50 app      # 应用日志
docker compose restart app             # 重启应用
docker compose pull && docker compose up -d   # 升级

版本与健康的标准验证（本篇实例基线）：

curl -s http://127.0.0.1:8140/api/app:getInfo

实测回显：

{"data":{"database":{"dialect":"postgres"},"version":"2.2.29","lang":"en-US","name":"main","theme":"default"}}

五、注意事项

CLI 必须在应用目录下执行：实例内 PATH 不含 node_modules/.bin，直接敲 nocobase 会报 command not found；统一 cd /app/nocobase && yarn nocobase ...。
插件名用短名：pm enable/disable/remove 的插件参数是去前缀短名（见 4.2 ⚠️），与 pm list 的 packageName 字段核对后再操作。
顶层 -h 异常不影响功能：v2.2.29 实测 yarn nocobase -h 报 callback is not a function，子命令均正常（4.1 排障实录），勿因帮助命令异常误判实例故障。
Docker 形态下进程管理归 compose：pm2 客户端空表是预期（4.4），启停重启走 docker compose，避免两套进程管理叠加造成状态混乱。
install 幂等但 upgrade 有迁移语义：已安装实例重跑 install 安全（4.3 实测）；upgrade 涉及数据库迁移，执行前按部署篇升级清单先备份 storage/。

六、常见问题（FAQ）

Q1：command not found: nocobase？ 未在应用目录执行。实例内统一入口：cd /app/nocobase && yarn nocobase <子命令>；从宿主则用本篇的 docker compose exec -T app sh -c '...' 形态。

Q2：CLI 命令卡住无输出？ CLI 经 IPC 与运行中实例通信，实例启动未完成（初始化或迁移中）时命令会等待。先确认版本接口 200 再执行 CLI 命令；实例未就绪时 docker compose logs -f app 观察 app has been started 日志行。

Q3：pm enable 报插件不存在？ 两种可能：插件未下载到 node_modules（需先 pm add/pm pull）；或把包名写全了——用短名 data-visualization-echarts 而非 @nocobase/plugin-data-visualization-echarts。

Q4：License key not found 是错误吗？ 不是。开源使用场景的商业版许可检测提示，命令继续执行并以 success 结束（4.3 实测回显为证），可安全忽略。

Q5：想重启应用，pm2 restart 却「无进程可重启」？ Docker 形态下 pm2 托管为前台主进程（4.4），客户端无进程表。正确命令是宿主侧 docker compose restart app，实测回显与重启后验证见部署篇第十章。

七、参考链接

官方常用运维命令（docker compose / pm2）：https://docs.nocobase.com/get-started/deployment/common-commands
官方插件安装与升级文档：https://docs.nocobase.com/get-started/installation/plugins
官方环境变量文档：https://docs.nocobase.com/get-started/installation/env
本系列相关篇目：《NocoBase 介绍与选型指南》、《NocoBase 2.2.29 Docker Compose 部署指南》、《NocoBase 2.2.29 配置参数详解》