#安装与升级迁移指南：使用 NocoBase CLI

新版 NocoBase CLI (nb) 将安装、连接、启动、停止、查看日志、升级和清理等操作统一到一套命令中。相比旧文档中按 Docker、create-nocobase-app、Git 源码分别维护的流程，CLI 更适合本地开发、测试环境维护，以及 AI Agent 接入和协作。

本文适用于以下场景：

• 你正在按旧文档安装或升级 NocoBase，希望切换到新的 CLI 方式。
• 你已经有一个旧方式部署的 NocoBase，希望让 CLI 管理或连接它。
• 你需要给 AI Agent 准备一个可连接、可维护的 NocoBase 环境。

#旧方式与新方式的区别

旧方式按安装来源拆分文档，每种来源都需要分别执行下载、配置、安装、启动和升级命令。

旧安装文档

• Docker 安装
• create-nocobase-app 安装
• Git 源码安装

旧升级文档

• Docker 安装的升级
• create-nocobase-app 安装的升级
• Git 源码安装的升级

新方式以 nb init 为入口，用一个 CLI env 记录应用来源、运行目录、存储目录、数据库和 API 连接信息。后续无论是 Docker、npm 还是 Git 来源，都尽量使用同一套 nb app、nb source、nb db 命令维护。

#安装 CLI

npm install -g @nocobase/cli@beta
nb --version

安装后可以查看帮助：

nb --help
nb init --help

#使用新的方式安装 NocoBase

#推荐：使用可视化向导

nb init --ui

向导会引导你选择：

• 创建新应用或连接已有应用
• 安装来源：Docker、npm、Git
• NocoBase 版本
• 使用内置数据库或外部数据库
• 管理员账号和密码

#使用终端交互式向导

nb init

#使用非交互式命令

默认安装方式为 Docker，并使用内置 PostgreSQL 数据库：

nb init --yes --env app1

使用 Docker 安装指定版本：

nb init --yes --env app1 --source docker --version beta

使用 npm 安装：

nb init --yes --env app1 --source npm --version beta --app-port 13080

使用 Git 源码安装：

nb init --yes --env app1 --source git --version beta

使用 Git 源码并指定内置数据库类型：

nb init --yes --env app1 --source git --version beta --db-dialect mysql

连接已有 NocoBase 应用：

# 默认使用 OAuth 认证
nb init --yes --env app1 --api-base-url=http://next.v2.test.nocobase.com/nocobase/api

# 使用 token 认证
nb init --yes --env app1 \
  --api-base-url=http://next.v2.test.nocobase.com/nocobase/api \
  --auth-type=token \
  --access-token=<token>

#使用新的方式升级

旧方式中 Docker、create-nocobase-app、Git 源码的升级命令不同；新 CLI 统一为：

nb app upgrade -e app1

如果只想使用当前已经下载的源码或镜像执行升级流程，不拉取新的代码或镜像：

nb app upgrade -e app1 --skip-code-update

或使用简写：

nb app upgrade -e app1 -s

#常用维护命令

nb app down 默认会停止应用，并移除 CLI 管理的运行容器和本地应用文件，但会保留 storage 数据和 env 配置。删除全部内容时必须显式确认：

nb app down -e app1 --all --yes

#日常开发命令

nb source 用于管理本地源码工程，主要适用于 npm 和 Git source env。

#NB_CLI_ROOT 与目录结构

CLI 会在 NB_CLI_ROOT 对应的目录下保存全局配置和本地应用文件。

默认情况下，NB_CLI_ROOT 是当前用户的主目录，也就是 Node.js os.homedir() 返回的路径。例如 macOS 上通常是 /Users/<user>。因此，如果不做额外配置，nb init --yes --env app1 生成的文件通常会在：

~
├── .nocobase
│   └── config.json
└── app1
    ├── source
    └── storage

你也可以显式指定 NB_CLI_ROOT：

export NB_CLI_ROOT=/your/workspace

设置后，配置文件和默认的应用目录都会放在该目录下：

/your/workspace
├── .nocobase
│   └── config.json
└── app1
    ├── source
    └── storage

其中：

• .nocobase/config.json 保存 env、当前环境、API 地址、源码路径、storage 路径、数据库配置等信息。
• <envName>/source 是 CLI 管理的源码或应用目录。
• <envName>/storage 是 CLI 管理的应用存储目录。

CLI 目前只使用全局配置 scope。如果需要调整配置和本地应用文件的保存位置，请设置 NB_CLI_ROOT。

查看和定位应用时，优先使用 nb env list 和 nb env info：

# 查看已配置 env 及 API 认证状态
nb env list

# 查看某个 env 的详细信息
nb env info app1

nb env list 面向快速总览，其中 App Status 是通过已保存的 Token/OAuth 凭证访问应用 API 后得到的认证状态，不再展示数据库状态。需要查看内置数据库运行状态时，请使用：

nb db ps -e app1

只有在需要切换默认 env 时，再使用：

nb env use app1

#从旧方式迁移到 CLI

迁移有两种策略：连接已有应用，或 把本地应用目录纳入 CLI 管理。如果你的旧应用已经稳定运行，推荐先使用“连接已有应用”，风险最低。

#方式一：连接已有应用

适用于已经通过 Docker、create-nocobase-app、Git 源码或服务器部署运行的 NocoBase。

# 默认使用 OAuth 认证
nb init --yes --env app1 --api-base-url=http://next.v2.test.nocobase.com/nocobase/api

# 使用 token 认证
nb init --yes --env "app$RANDOM" \
  --api-base-url=http://next.v2.test.nocobase.com/nocobase/api \
  --auth-type=token \
  --access-token=<token>

这种方式只保存 API 连接，CLI 不会接管旧应用的启动、停止、升级、源码目录或 storage 目录。适合让 AI Agent 或 CLI API 命令连接已有应用。

如果需要刷新认证：

nb env auth app1

#方式二：新建 CLI env 后迁移文件

适用于希望后续用 nb app 和 nb source 管理本地应用的场景。

迁移前请先完成：

1. 停止旧应用。
2. 备份旧数据库。
3. 备份旧 storage 目录。
4. 记录旧应用的关键环境变量，例如 APP_KEY、TZ、DB_*、DB_UNDERSCORED。

#旧 Docker 安装迁移

旧 Docker 方式通常把应用数据放在项目目录的 storage 中：

/old-docker-project
├── docker-compose.yml
└── storage

建议先确定新的 NB_CLI_ROOT，然后用 CLI 创建一个新的 Docker env。下面示例假设 NB_CLI_ROOT 是 /your/workspace。

export NB_CLI_ROOT=/your/workspace
nb init --yes --env app2 --source docker --version beta
nb app stop -e app2

新 env 默认会使用以下目录：

/your/workspace
└── app2
    ├── source
    └── storage

然后将旧 storage 复制到 /your/workspace/app2/storage，并确保数据库连接和 APP_KEY 等配置与旧环境一致。

复制完成并确认数据库配置后，再启动应用：

nb app start -e app2
nb app logs -e app2

#旧 create-nocobase-app 或 Git 源码安装迁移

旧 npm/Git 方式通常是源码、.env 和 storage 放在同一个项目目录中：

/old-nocobase
├── .env
├── package.json
├── packages
└── storage

建议先确定新的 NB_CLI_ROOT，然后创建新的 npm 或 Git env。下面示例假设 NB_CLI_ROOT 是 /your/workspace。

export NB_CLI_ROOT=/your/workspace
nb init --yes --env app3 --source git --version beta
nb app stop -e app3

然后按需迁移：

• 将旧项目中的自定义插件源码迁移到 /your/workspace/app3/source 对应目录。
• 将旧项目中的 storage 复制到 /your/workspace/app3/storage。
• 将旧 .env 中的关键配置同步到 CLI env 配置或初始化参数中。
• 使用原数据库时，请在初始化时关闭内置数据库并填写旧数据库连接信息。

使用外部数据库初始化的示例：

nb init --yes --env app3 --source git --version beta \
  --no-builtin-db \
  --db-dialect postgres \
  --db-host 127.0.0.1 \
  --db-port 5432 \
  --db-database nocobase \
  --db-user nocobase \
  --db-password nocobase

迁移完成后启动并查看日志：

nb app start -e app3
nb app logs -e app3

#旧命令迁移速查

#相关链接

• AI Agent 接入指南
• NocoBase CLI 命令参考
• 安装方式和版本对比
• 安装与升级插件