用途:在运行 NocoBase 的机器上安装并运行已构建的 NocoBase 3(生产环境),不进行本地开发。安装由 @nocobase/app-installer 完成,每个版本放在 releases/<version>_<build time>/app 下,由 pm2 运行;config.yml、app.env、storage/、backups/、logs/ 与 releases 并列,升级后保留。
两种来源(安装时固定):--template hub 在本机构建已发布的 Hub;--archive 使用应用项目构建的部署归档。所有命令通过 npx 并指定 registry 与 --json:npx --yes --registry="${NOCOBASE_REGISTRY:-https://npm.nocobase.ai}" @nocobase/app-installer <command> … --json。NocoBase 3 发布在 https://npm.nocobase.ai,直接 npx 会 404。--json 在 stdout 输出一个文档,进度在 stderr;需读取 ok、status、result 及失败时的 error.code、error.message、error.suggestions、error.details。退出码:0 完成或无需操作;1 失败且未动已运行应用;2 用法错误、预检失败或仍需确认;3 升级失败已回滚;4 回滚也失败,应用不可用。
选择路线:开发用 nocobase-create-app;安装 Hub 用本技能 --template hub;部署应用到生产用 --archive;发布应用到已有 Hub 用应用的 nocobase-deployment;Docker 见部署文档。工作目录已有 installer.json 说明已安装,先执行 status。
归档在源码所在机器构建:APP_BASE_PATH=/crm pnpm build --target linux-x64 --node-version 24 --tar,产物为 storage/exports/dist.tar.gz,需复制到运行机器。--target 与 --node-version 描述运行机器;非 SQLite 数据库需在构建前加入驱动。
安装前检查 node --version(24 及以上)与 command -v pm2(pm2 4.3 及以上需全局安装 npm install -g pm2),Windows 用 WSL。需与用户确认目标目录、公开 origin、是否前置反向代理、端口(默认 13000)与数据库(默认 SQLite)。默认监听 127.0.0.1;直接访问需 --host 0.0.0.0。密码用 --set-from-env,不要写在命令行。
归档安装:install <dir> --archive <file> --origin <origin> --json,无需 pnpm,一两分钟完成。模板安装:install <dir> --template hub --origin <origin> --json,需 pnpm 11 及以上,构建需数分钟,超时设 30 分钟以上。
成功后 result.started 为 true 表示健康检查通过;告知 result.url、初始管理员与 config.yml 中 users.initialAdmin 的密码(defaultPassword 为 true 时仍是 admin123,需登录后修改)、result.nextCommands(含 pm2 startup 与 sudo 命令)、反向代理需转发 WebSocket 升级头,Hub 还需 client_max_body_size 260m,以及 warnings。
同一机器多个安装各自目录与端口,pm2 进程名默认 nocobase-<目录名>;Hub 的 App Host 从 13010 起占用空闲端口,Hub 自身端口应避开该范围。
status --dir <root> --json 不改变状态,--offline 跳过查询新版本;node.matches 为 false 表示 Node 主版本已变,需重建归档并 upgrade --archive,或对 Hub 用 upgrade --rebuild。
升级与回滚都会停止应用(Hub 还会停止其托管应用),需用户确认:先不带 --yes 运行,得到 CONFIRMATION_REQUIRED 与 notes,转达并等待明确同意后再加 --yes。归档升级用 upgrade --dir <root> --archive <file> --json;模板升级用 upgrade --dir <root> --json(可 --to <version>)。安装器只备份 config.yml 声明的 SQLite 数据库及 config.yml、app.env,其他数据库需用户先备份并加 --backup-done。升级保留三个版本,可用 --keep <n>。rollback --dir <root> --json 回到上次升级来源,若升级迁移过数据库会恢复备份并丢失之后数据,--no-restore 保留当前数据库。OPERATION_INTERRUPTED 或 status 中 pending 表示中断,普通 rollback 可恢复,Hub 重建中断例外,需 upgrade --rebuild。
修改 origin 或端口无专用命令,需编辑 app.env 中 APP_PUBLIC_ORIGIN、APP_SERVER_HOST、APP_SERVER_PORT 三行后 pm2 restart <name>;APP_BASE_PATH 编译进客户端,不能这样改。根目录保存唯一配置、密钥与数据,除上述三行外都应通过 app-installer 修改,删除由用户决定,config.yml 内容不要放入对话。