3文档
简体中文
GitHub ↗官网 ↗

部署指南

应用部署

通过 PM2 或 Docker 部署到自己的服务器，或将应用部署到 NocoBase Studio。选择一种方式，让 Agent 协助或按手动步骤完成部署。

让 Agent 协助部署查看手动步骤
从构建到上线PM2 / Docker / NocoBase Studio
  1. 构建生成应用包或镜像
  2. 部署配置与启动应用
  3. 检查健康检查与登录
部署产物dist.tar.gzDocker 镜像

PM2 / Docker 示例环境与访问

PM2 和 Docker 共用以下示例。执行命令前，请替换为自己的服务器、部署目录和访问地址。Studio 部署使用管理员已配置的环境，访问地址以目标 App 页面显示的为准。

运行环境
Linux x64 · SQLite
部署目录
/srv/apps/purchase
公开访问地址
https://purchase.example.com/main
反向代理目标
127.0.0.1:13000

配置公开访问

  1. 将 purchase.example.com 指向目标服务器，并配置 HTTPS 证书。
  2. 在同一台服务器上配置反向代理，转发至 127.0.0.1:13000，并保留 /main 路径。
  3. 反向代理需支持 WebSocket，并向应用传递公开 Host 和协议信息。

以下部署命令不会自动配置 DNS、证书或反向代理，请在验证公开访问前完成这些配置。

通过 PM2 部署应用

在本地构建部署包，使用 app-installer 通过 SSH 安装和更新，由 PM2 管理应用进程。

让 Agent 协助 PM2 部署

安装 nocobase-app-installer Skill，重新打开 Agent 会话，在 app 项目目录发送以下提示。外部数据库、回滚和 CI/CD 等进阶场景也可交给此 Skill。

本地 · app 项目根目录
npx skills@latest add nocobase/skills-v3 --skill nocobase-app-installer -g
发送给 Agent
使用 nocobase-app-installer Skill，通过 PM2 部署当前应用。
SSH：deploy@server.example.com
目录：/srv/apps/purchase
访问地址：https://purchase.example.com/main
数据库：SQLite
先检查环境和配置，再完成部署并验证。

准备 PM2 环境

本地安装 Node.js 24+、pnpm，并配置 SSH 登录。Linux 服务器安装 Node.js 24、tar，再以部署账号安装 PM2（4.3+）：

服务器 · 部署账号
npm install --global pm2

确保非交互 SSH 会话能找到 node 和 pm2。部署账号需对安装目录及父目录有写权限；首次安装使用新的或空目录。

构建并安装应用

本地 · app 项目根目录
pnpm install --frozen-lockfile
pnpm build --target linux-x64 --node-version 24 --tar

产物为 storage/exports/dist.tar.gz。将首次管理员密码注入本地环境变量 INITIAL_ADMIN_PASSWORD，然后安装：

本地 · app 项目根目录
npx --yes @nocobase/app-installer@beta install \
  --ssh deploy@server.example.com \
  --dir /srv/apps/purchase \
  --archive storage/exports/dist.tar.gz \
  --origin https://purchase.example.com \
  --base-path /main \
  --port 13000 --name nocobase-purchase \
  --set-from-env users.initialAdmin.password=INITIAL_ADMIN_PASSWORD \
  --json

安装器会上传部署包、生成配置、执行迁移并启动应用。示例使用 @beta；接入 CI 时建议固定已验证的安装器版本。

配置开机启动并检查

服务器 · 部署账号
pm2 startup

先执行输出中提示的系统服务配置命令，再以同一个部署账号保存进程列表：

服务器 · 部署账号
pm2 save

完成上面的 HTTPS 和反向代理配置后，检查应用状态和公开访问：

本地 · app 项目根目录
npx --yes @nocobase/app-installer@beta status \
  --ssh deploy@server.example.com \
  --dir /srv/apps/purchase --json

curl --fail --silent --show-error \
  https://purchase.example.com/main/api/healthz

确认 status 的 result.health.ok 为 true、result.pending 为 null，健康接口返回 ok: true，再打开应用验证登录。同时检查页面刷新、登录权限和一项主要业务操作；使用文件存储时检查上传与下载，涉及存储变更时验证重启后的持久化。

更新 PM2 应用

重新执行构建命令生成新包，先查询 status 确认没有未完成的操作，再运行升级预检：

本地 · app 项目根目录
npx --yes @nocobase/app-installer@beta upgrade \
  --ssh deploy@server.example.com \
  --dir /srv/apps/purchase \
  --archive storage/exports/dist.tar.gz \
  --json

检查预检结果并确认停机、备份安排后，在同一条命令中加上 --yes 执行更新，完成后重复状态和访问检查。安装器会备份 SQLite 和配置；上传文件需另行备份，外部数据库需先备份并加上 --backup-done。