@nocobase/plugin-ai 2.1.0-alpha.46 → 2.1.0-alpha.47

package/dist/ai/docs/nocobase/quickstart/index.md

@@ -0,0 +1,27 @@
+# 快速开始
+
+NocoBase 的快速开始主要解决三件事：先把应用装起来，再把插件装起来，最后把应用稳定地跑起来。你不需要一次把所有文档都看完，按你当前所在的阶段往下走就够了。
+
+如果你还没决定用哪种方式安装，默认先看 [使用 CLI 安装（推荐）](./installation/cli.md)。如果你更习惯直接在服务器上用容器跑起来，继续看 [通过 Docker Compose 安装](./installation/docker-compose.md)。
+
+## 快速索引
+
+| 我想要…… | 去哪里看 |
+| --- | --- |
+| 直接安装一个新的 NocoBase 应用 | [使用 CLI 安装（推荐）](./installation/cli.md) |
+| 把旧的安装方式逐步迁移到 CLI | [从旧方式迁移到 CLI](./installation/migration.md) |
+| 用 Docker Compose 在服务器上部署 | [通过 Docker Compose 安装](./installation/docker-compose.md) |
+| 在无法访问公网的环境里安装 | [内网安装](./installation/airgap.md) |
+| 先确认应用运行需要的关键环境变量 | [应用环境变量](./installation/env.md) |
+| 激活商业插件或安装第三方插件 | [商业插件激活与升级](../api/cli/license/index.md) / [第三方插件安装与升级](./plugins/third-party.md) |
+| 给生产环境加上反向代理 | [Nginx](./production/reverse-proxy/nginx.md) / [Caddy](./production/reverse-proxy/caddy.md) |
+| 查看应用、切换环境、备份还原 | [管理应用](./operations/manage-app.md) / [多环境管理](./operations/multi-environment.md) / [备份还原](./operations/backup-restore.md) |
+
+## 默认路径
+
+如果你不确定该怎么选，通常来说按下面这条路径走最省心：
+
+1. 先看 [使用 CLI 安装（推荐）](./installation/cli.md)。
+2. 应用跑起来后，再确认 [应用环境变量](./installation/env.md)。
+3. 如果要正式上线，再补上 [Nginx](./production/reverse-proxy/nginx.md) 或 [Caddy](./production/reverse-proxy/caddy.md)。
+4. 后续日常维护时，再看 [管理应用](./operations/manage-app.md) 和 [备份还原](./operations/backup-restore.md)。

package/dist/ai/docs/nocobase/quickstart/installation/airgap.md

@@ -0,0 +1,67 @@
+# 内网安装
+
+如果你的服务器无法访问公网，安装方式就要提前准备好离线所需的镜像、依赖和插件包。默认推荐先用 Docker 方式，路径最短，也最容易复现。
+
+## 默认推荐：离线准备 Docker 镜像
+
+在一台可以访问公网的机器上，先把应用镜像和数据库镜像拉下来：
+
+```bash
+docker pull registry.cn-shanghai.aliyuncs.com/nocobase/nocobase:latest-full
+docker pull registry.cn-shanghai.aliyuncs.com/nocobase/postgres:16
+```
+
+然后导出为离线文件：
+
+```bash
+docker save -o nocobase-app.tar \
+  registry.cn-shanghai.aliyuncs.com/nocobase/nocobase:latest-full
+
+docker save -o nocobase-postgres.tar \
+  registry.cn-shanghai.aliyuncs.com/nocobase/postgres:16
+```
+
+如果你还需要商业插件，也建议在外网环境先准备好插件包，再一起带入内网。
+
+## 把文件拷贝到内网服务器
+
+至少准备这些文件：
+
+- `nocobase-app.tar`
+- `nocobase-postgres.tar`
+- `docker-compose.yml`
+- `.env` 或你自己的部署说明
+
+## 在内网服务器导入镜像
+
+```bash
+docker load -i nocobase-app.tar
+docker load -i nocobase-postgres.tar
+```
+
+## 启动应用
+
+准备好 `docker-compose.yml` 后，直接启动：
+
+```bash
+docker compose up -d
+docker compose logs -f app
+```
+
+如果你还没写 compose 文件，先看 [通过 Docker Compose 安装](./docker-compose.md)，把里面的示例保存到本地即可。
+
+## 不能使用 Docker 怎么办
+
+如果你的内网环境不能使用 Docker，也可以在外网环境先用 `create-nocobase-app` 创建完整项目、安装依赖并打包，再把整个项目拷贝到内网服务器。
+
+这条路径会更长，不过在没有容器能力的环境里更实用。整体流程通常是：
+
+1. 在外网环境创建项目并安装依赖。
+2. 把项目目录打包。
+3. 拷贝到内网服务器。
+4. 在内网解压、补齐 `.env` 后启动应用。
+
+## 下一步去哪里看
+
+- 如果你还没确认应用配置，继续看 [应用环境变量](./env.md)
+- 如果你准备把应用正式开放给业务用户，继续看 [Nginx](../production/reverse-proxy/nginx.md) 或 [Caddy](../production/reverse-proxy/caddy.md)

package/dist/ai/docs/nocobase/quickstart/installation/cli.md

@@ -0,0 +1,205 @@
+# 使用 CLI 安装（推荐）
+
+NocoBase 2.1.0 之后，官方提供了基于 CLI 的安装和管理方式。你可以用它完成安装、连接、升级和日常维护，也可以顺手给 AI Agent 准备一个可连接、可操作的环境。
+
+## 安装 NocoBase CLI
+
+仅在第一次安装 CLI 时执行。
+
+先全局安装 CLI：
+
+```bash
+npm install -g @nocobase/cli@beta
+nb --version
+```
+
+:::tip 建议先开启 session mode
+
+如果你会同时开多个终端、多个 shell，或者要让 AI Agent 和你自己并行操作，默认推荐先执行一次 [`nb session setup`](../../api/cli/session/setup.md)。这样每个会话都能维护自己的 `current env`，不容易互相影响。
+
+```bash
+nb session setup
+```
+
+:::
+
+如果你打算长期用中文界面，通常来说先把 locale 设好就够了：
+
+```bash
+nb config set locale zh-CN
+```
+
+CLI 默认会检查自更新。你可以按自己的习惯调整更新策略：
+
+- `prompt`：发现新版本时提示
+- `auto`：自动更新
+- `off`：关闭自动更新
+
+```bash
+nb config set update.policy prompt
+nb config set update.policy auto
+nb config set update.policy off
+```
+
+如果你准备把 NocoBase 部署到服务器上，并且希望从远程浏览器打开 `nb init --ui` 向导，建议先把 CLI 的默认 host 改成当前服务器 IP：
+
+```bash
+nb config set default-ui-host <server-ip>
+nb config set default-api-host <server-ip>
+```
+
+将 `<server-ip>` 替换为当前服务器对你可访问的实际 IP。
+
+`nb config` 是 CLI 的全局配置。通常只需要设置一次，后续再次运行 `nb init --ui` 时会自动沿用这些默认值，不需要每次重复配置。
+
+通常来说：
+
+- `default-ui-host` 用于 `nb init --ui` 启动向导页面时的默认监听地址
+- `default-api-host` 用于新安装时默认生成的 API 地址
+
+如果是在服务器上部署，这两个值通常都应该改成当前服务器可访问的 IP，而不是继续使用默认的本机地址。
+
+:::warning 这只是安装向导或临时访问方式，不是生产环境推荐入口
+
+把 `default-ui-host` / `default-api-host` 设成服务器 IP，主要是为了让你能从远程浏览器打开 `nb init --ui`，或者在安装完成后临时验证服务是否可访问。
+
+这不代表生产环境应该长期使用 `IP + port` 对外提供服务。正式部署时，仍然推荐使用域名，并通过 Nginx 或 Caddy 这类反向代理统一接入，再启用 HTTPS。
+
+:::
+
+## 安装 NocoBase
+
+### 方式一：通过 UI 向导安装
+
+这是默认推荐的入口。你只需要运行：
+
+```bash
+nb init --ui
+```
+
+如果你想给向导页面指定一个固定端口，可以直接加上 `--ui-port`，例如：
+
+```bash
+nb init --ui --ui-port 3000
+```
+
+![nb init UI 向导](https://static-docs.nocobase.com/2026-06-03-20-54-01.png)
+
+向导会根据当前场景，带你一步一步完成安装或连接所需的配置。
+
+### 方式二：通过终端交互
+
+如果你更习惯在终端里一步一步输入，可以直接运行：
+
+```bash
+nb init
+```
+
+![2026-06-03-21-36-33](https://static-docs.nocobase.com/2026-06-03-21-36-33.png)
+
+### 方式三：通过非交互命令
+
+如果你在脚本、CI/CD 或其他非交互环境里运行，直接用 `--yes` 就行。这个模式下必须显式传 `--env`，没有显式指定的参数会按默认值处理。
+
+最短的默认写法是：
+
+```bash
+nb init --yes --env app1
+```
+
+具体到不同安装来源、版本选择、`basic` 认证、CI/CD 连接已有应用，以及数据库命名这类常见组合，直接看 [`nb init` 命令参考的示例](../../api/cli/init.md#示例) 就行。
+
+## 安装完成后先确认什么
+
+`--env` 是 CLI 里的环境名。通常来说，安装完成后你接下来做的事都围绕这个 env 展开。
+
+通常建议先确认这 3 件事：
+
+1. env 是否已经创建并保存成功
+2. 应用是否可以正常启动、日志是否正常
+3. 如果准备正式对外开放，是否已经规划好生产环境入口，而不是继续直接使用 `IP + port`
+
+### 安装目录
+
+如果你刚用 `nb init --env app1` 新装了一个本地应用，可以通过 `nb env info app1 --field app.appPath` 查看完整路径。
+
+默认情况下，CLI 会在 `app-path` 下按下面这套约定组织本地文件：
+
+```text
+<app-path>/
+├── source/   # 应用源码或下载内容对应的默认目录
+├── storage/  # 运行时数据目录
+└── .env      # 可选的应用环境变量文件
+```
+
+通常来说：
+
+- `source/` 主要对应 npm / Git env 的本地应用目录。对于 Docker env，CLI 也会保留这套默认路径推导，不过大多数时候你不需要手动关心它
+- `storage/` 用来放运行时数据，比如内置数据库数据、插件、日志等内容
+- `.env` 是可选的应用环境变量文件。只有当你需要自定义环境变量时，才需要在 `<app-path>/.env` 里添加它；如果这个文件存在，Docker、npm 和 Git 这几种安装来源默认都会读取它
+
+更完整的说明见 [`nb init` 命令参考](../../api/cli/init.md)。
+
+### 生产环境部署提醒
+
+如果你现在只是刚装完，想先验证安装结果，那么用 `IP + port` 打开页面通常没有问题。
+
+但如果这个 env 接下来要正式对外提供服务，需要特别注意：
+
+- `nb init --ui` 本身只是安装向导的临时页面，用来完成安装或初始化，不是应用正式对外服务入口
+- 通过 `nb init` 安装完成后，应用当前暴露出来的 `IP + port` 更适合调试阶段、验证阶段或内网临时访问
+- 生产环境不建议直接把 NocoBase 应用端口暴露给公网长期使用
+- 正式对外访问时，推荐使用域名，并通过 Nginx 或 Caddy 反向代理到 NocoBase
+- 生产环境应优先启用 HTTPS，而不是长期使用裸露的 `http://IP:port`
+
+也就是说，`default-ui-host` 和 `default-api-host` 只是为了让安装向导和默认地址生成更方便，并不代表最终生产环境的访问入口。
+
+如果这个 env 准备正式上线，建议把“接入反向代理并启用 HTTPS”视为安装完成后的下一步，而不是可选优化项。
+
+如果你现在就准备继续做正式部署，建议先从 [生产环境部署](../production/index.md) 开始，再按需要继续看 [Nginx](../production/reverse-proxy/nginx.md) 或 [Caddy](../production/reverse-proxy/caddy.md) 的反向代理配置。
+
+### 日常操作
+
+你可以先确认这个 env 是否已经保存成功：
+
+```bash
+nb env current
+nb env list
+nb env status
+nb env info app1
+nb env info app1 --json
+```
+
+如果你想继续做安装后的后续操作，可以按下面这个索引往下看：
+
+| 我想要…… | 去哪里看 |
+| --- | --- |
+| 如果你准备把这个 env 正式对外开放，给它接上生产环境反向代理，并使用域名和 HTTPS 暴露服务。 | [Nginx](../production/reverse-proxy/nginx.md) / [Caddy](../production/reverse-proxy/caddy.md)。 |
+| 确认 env 是否保存成功、查看当前用了哪个 env、在多个 env 之间切换。 | [`nb env`](../../api/cli/env/index.md)、[多环境管理](../operations/multi-environment.md)。 |
+| 启动、停止、重启应用，查看日志，或者继续升级应用。 | [`nb app`](../../api/cli/app/index.md)、[管理应用](../operations/manage-app.md)。 |
+| 检查数据库连接、查看内置数据库状态，或者排查数据库容器问题。 | [`nb db`](../../api/cli/db/index.md)。 |
+| 查看已安装插件，启用或停用插件。 | [`nb plugin`](../../api/cli/plugin/index.md)。 |
+| 激活商业授权、查看授权状态、同步商业插件。 | [`nb license`](../../api/cli/license/index.md)。 |
+| 管理本地源码工程，比如下载源码、启动开发模式、构建或测试。这个通常用于 npm / Git env。 | [`nb source`](../../api/cli/source/index.md)。 |
+
+如果你刚装完一个本地应用，通常可以先跑这几条命令：
+
+```bash
+nb env use app1
+nb app start
+nb app logs
+nb plugin list
+```
+
+如果你同时维护多个 env，后续切换和查看状态的方式见 [多环境管理](../operations/multi-environment.md)。
+
+如果你后续要升级应用，直接看 [管理应用](../operations/manage-app.md) 和 [`nb app upgrade` 命令参考](../../api/cli/app/upgrade.md) 就行。
+
+## 相关链接
+
+- [`nb init` 命令参考](../../api/cli/init.md)
+- [`nb env info` 命令参考](../../api/cli/env/info.md)
+- [生产环境反向代理：Nginx](../production/reverse-proxy/nginx.md) / [Caddy](../production/reverse-proxy/caddy.md)
+- [从旧方式迁移到 CLI](./migration.md)
+- [多环境管理](../operations/multi-environment.md)
+- [管理应用](../operations/manage-app.md)

package/dist/ai/docs/nocobase/quickstart/installation/docker-compose.md

@@ -0,0 +1,123 @@
+# 通过 Docker Compose 安装
+
+如果你希望直接在服务器上把 NocoBase 跑起来，`docker compose` 仍然是最直接的方式。大部分场景用一份 `docker-compose.yml` 就够了。
+
+不过生产环境里，建议固定具体版本号，不要长期直接使用 `latest`。这样升级时更可控。
+
+## 前提条件
+
+- 已安装 Docker 和 Docker Compose
+- 确保 Docker 服务已经启动
+- 已准备好一个要对外开放的端口，比如 `13000`
+
+## 第一步：创建项目目录
+
+```bash
+mkdir my-nocobase-app
+cd my-nocobase-app
+```
+
+## 第二步：创建 `docker-compose.yml`
+
+下面这个示例使用 PostgreSQL，也是默认最省心的一种组合：
+
+```yml
+networks:
+  nocobase:
+    driver: bridge
+
+services:
+  app:
+    image: registry.cn-shanghai.aliyuncs.com/nocobase/nocobase:latest-full
+    restart: always
+    networks:
+      - nocobase
+    depends_on:
+      - postgres
+    environment:
+      - APP_KEY=replace-with-your-secret-key
+      - DB_DIALECT=postgres
+      - DB_HOST=postgres
+      - DB_PORT=5432
+      - DB_DATABASE=nocobase
+      - DB_USER=nocobase
+      - DB_PASSWORD=nocobase
+      - TZ=Asia/Shanghai
+    volumes:
+      - ./storage:/app/nocobase/storage
+    ports:
+      - '13000:80'
+
+  postgres:
+    image: registry.cn-shanghai.aliyuncs.com/nocobase/postgres:16
+    restart: always
+    command: postgres -c wal_level=logical
+    environment:
+      POSTGRES_USER: nocobase
+      POSTGRES_DB: nocobase
+      POSTGRES_PASSWORD: nocobase
+    volumes:
+      - ./storage/db/postgres:/var/lib/postgresql/data
+    networks:
+      - nocobase
+```
+
+其中：
+
+- `APP_KEY` 记得改成你自己的随机字符串
+- `13000:80` 代表把主机的 `13000` 端口映射到容器的 `80` 端口
+- 如果你已经有数据库服务，可以删掉 `postgres` 这一段，并把 `DB_HOST` 改成现有数据库地址
+
+如果你使用 MySQL 或 MariaDB，记得把 `DB_DIALECT` 改成对应类型，并补上：
+
+```bash
+DB_UNDERSCORED=true
+```
+
+## 第三步：启动应用
+
+```bash
+docker compose up -d
+```
+
+查看日志：
+
+```bash
+docker compose logs -f app
+```
+
+## 第四步：访问应用
+
+应用启动完成后，打开：
+
+```text
+http://<服务器IP>:13000
+```
+
+如果是第一次启动，按页面提示初始化管理员账号即可。
+
+## 常用命令
+
+启动或更新容器：
+
+```bash
+docker compose up -d
+```
+
+停止应用：
+
+```bash
+docker compose down
+```
+
+查看日志：
+
+```bash
+docker compose logs -f app
+```
+
+## 下一步去哪里看
+
+- 如果你要调整密钥、端口、数据库等配置，继续看 [应用环境变量](./env.md)
+- 如果你准备正式上线，继续看 [Nginx](../production/reverse-proxy/nginx.md) 或 [Caddy](../production/reverse-proxy/caddy.md)
+- 如果你后续要备份数据，继续看 [备份还原](../operations/backup-restore.md)

package/dist/ai/docs/nocobase/quickstart/installation/env.md

@@ -0,0 +1,101 @@
+# 应用环境变量
+
+大部分场景只需要先看这几类环境变量：`APP_KEY`、`TZ`、`APP_PORT`，以及数据库相关的 `DB_*`。如果你只是想把应用先跑起来，通常来说先把这几项确认好就够了。
+
+## 怎么设置环境变量
+
+### `create-nocobase-app` 或 Git 源码方式
+
+在项目根目录的 `.env` 文件里设置环境变量。修改完成后，重新启动应用。
+
+```bash
+APP_KEY=your-app-key
+TZ=Asia/Shanghai
+APP_PORT=13000
+DB_DIALECT=postgres
+DB_HOST=127.0.0.1
+DB_PORT=5432
+DB_DATABASE=nocobase
+DB_USER=nocobase
+DB_PASSWORD=nocobase
+```
+
+### Docker Compose 方式
+
+可以直接在 `docker-compose.yml` 的 `environment` 里设置：
+
+```yml
+services:
+  app:
+    image: nocobase/nocobase:latest
+    environment:
+      - APP_ENV=production
+      - APP_KEY=your-app-key
+      - TZ=Asia/Shanghai
+```
+
+也可以用 `env_file` 引入单独的 `.env` 文件：
+
+```yml
+services:
+  app:
+    image: nocobase/nocobase:latest
+    env_file: .env
+```
+
+修改完成后，重新创建应用容器：
+
+```bash
+docker compose up -d app
+```
+
+## 先确认哪些变量
+
+### `APP_KEY`
+
+应用密钥，用于生成 token 等敏感数据。部署到正式环境前，记得改成你自己的值，并妥善保管。
+
+:::warning 注意
+
+如果 `APP_KEY` 改了，旧的 token 也会随之失效。
+
+:::
+
+### `TZ`
+
+应用时区。和时间相关的处理都会受它影响。
+
+```bash
+TZ=Asia/Shanghai
+```
+
+### `APP_PORT`
+
+应用端口，默认值通常是 `13000`。
+
+```bash
+APP_PORT=13000
+```
+
+### `DB_*`
+
+如果你使用外部数据库，至少要确认这些变量：
+
+```bash
+DB_DIALECT=postgres
+DB_HOST=127.0.0.1
+DB_PORT=5432
+DB_DATABASE=nocobase
+DB_USER=nocobase
+DB_PASSWORD=nocobase
+```
+
+如果你使用 MySQL 或 MariaDB，并且数据库配置了 `lower_case_table_names=1`，还需要确认：
+
+```bash
+DB_UNDERSCORED=true
+```
+
+## 完整变量列表
+
+如果你需要查看全部环境变量说明，比如 `CLUSTER_MODE`、`CACHE_*`、`FILE_STORAGE`、插件相关变量等，继续看 [全局环境变量](/api/app/env)。

package/dist/ai/docs/nocobase/quickstart/installation/migration.md

@@ -0,0 +1,50 @@
+# 从旧方式迁移到 CLI
+
+如果你现在还是按旧文档使用 Docker、`create-nocobase-app` 或 Git 源码方式安装和维护 NocoBase，可以逐步切换到基于 CLI 的安装和管理方式。
+
+默认先迁移测试环境就够了。只有当你已经确认备份、环境变量和数据库配置都没问题时，再迁移生产环境。
+
+## 迁移前先确认
+
+1. 已备份数据库。
+2. 已备份 `storage` 目录。
+3. 已记录旧应用的关键环境变量，比如 `APP_KEY`、`TZ`、`DB_*`、`DB_UNDERSCORED`。
+
+## 方式一：连接已有应用
+
+如果你的旧应用已经稳定运行，默认先用这个方式。风险最低，CLI 只保存连接信息，不会直接接管旧应用的启动、停止和升级流程。
+
+```bash
+# 默认使用 OAuth 认证
+nb init --yes --env app1 \
+  --api-base-url=http://your-app-host/api
+
+# 使用 token 认证
+nb init --yes --env app1 \
+  --api-base-url=http://your-app-host/api \
+  --auth-type=token \
+  --access-token=<token>
+```
+
+如果后续需要重新认证，可以执行：
+
+```bash
+nb env auth app1
+```
+
+## 方式二：新建 CLI env 后迁移
+
+如果你希望后续统一用 `nb app`、`nb env`、`nb source` 管理本地应用，可以新建一个 CLI env，再把旧应用的数据和配置迁过去。
+
+先创建新的 CLI env：
+
+```bash
+nb init --yes --env app1
+```
+
+创建完成后，再根据你的旧安装方式迁移数据库、`storage` 和环境变量配置。
+
+## 下一步去哪里看
+
+- 如果你只是想开始用新的 CLI 方式安装和维护应用，继续看 [使用 CLI 安装（推荐）](./cli.md)
+- 如果你需要完整的迁移步骤，继续看 [安装与升级迁移指南：使用 NocoBase CLI](/ai/install-upgrade-migration#从旧方式迁移到-cli)

package/dist/ai/docs/nocobase/quickstart/operations/backup-restore.md

@@ -0,0 +1,94 @@
+# 备份还原
+
+如果你已经把一个 NocoBase 应用保存成 CLI env，日常备份和恢复基本都在 `nb backup` 这一组命令里完成。`nb backup create` 用来在目标 env 创建备份并下载到本地，`nb backup restore` 用来把本地备份文件恢复到目标 env。
+
+大多数时候，先记住一个默认建议就够了：升级、迁移、批量改数据前先备份；只有当你明确知道自己要覆盖当前数据时，再执行恢复。
+
+## 快速索引
+
+| 我想要…… | 用哪个命令 |
+| --- | --- |
+| 先把当前 env 备份到本地 | [`nb backup create`](../../api/cli/backup/create.md) |
+| 把备份保存到指定目录 | [`nb backup create --output ./backups`](../../api/cli/backup/create.md) |
+| 让脚本继续消费备份结果 | [`nb backup create --json-output`](../../api/cli/backup/create.md) |
+| 把本地备份恢复到当前 env | [`nb backup restore --file ./backups/xxx.nbdata --force`](../../api/cli/backup/restore.md) |
+| 把本地备份恢复到另一个 env | [`nb backup restore --env app1 --file ./backups/xxx.nbdata --yes --force`](../../api/cli/backup/restore.md) |
+
+:::tip 先确认当前 env
+
+`nb backup` 命令默认作用在当前 env 上。如果你同时维护多个环境，默认推荐先看一眼当前 env，再执行备份或恢复。
+
+```bash
+nb env current
+nb env use app1
+```
+
+如果你显式传入了不同的 `--env`，CLI 通常会要求确认。脚本或非交互场景里，可以加 `--yes` 跳过这一步。
+
+:::
+
+## 创建备份
+
+最简单的用法就是直接创建一个备份：
+
+```bash
+nb backup create
+```
+
+命令成功返回后，备份文件已经下载到本地。省略 `--output` 时，CLI 会把文件保存到当前工作目录，并沿用远端返回的文件名——通常是 `backup_*.nbdata`。
+
+如果你想把备份统一放到一个目录里，可以这样用：
+
+```bash
+nb backup create --output ./backups
+```
+
+如果 `./backups` 已经存在，而且它是一个目录，CLI 会自动把远端备份文件名拼到这个目录后面。只有当路径不存在时，CLI 才会把它当成目标文件路径。
+
+如果你要在脚本、CI 或 agent 链路里继续消费备份结果，可以加 `--json-output`：
+
+```bash
+nb backup create --env app1 --yes --json-output
+```
+
+这个模式下，CLI 不再输出进度文本，而是直接返回最终 JSON，里面通常会包含 `env`、`name` 和 `output` 三个字段。
+
+## 恢复备份
+
+恢复命令会把本地备份文件上传到目标 env，并覆盖当前应用数据：
+
+```bash
+nb backup restore --file ./backups/backup_20260520_190408_8397.nbdata --force
+```
+
+如果你要恢复到的不是当前 env，通常来说这样写更稳妥：
+
+```bash
+nb backup restore --env app1 --file ./backups/backup_20260520_190408_8397.nbdata --yes --force
+```
+
+:::warning 注意
+
+恢复是全量覆盖操作。默认推荐在恢复前，先对当前目标 env 再做一份备份。
+
+```bash
+nb backup create --env app1 --yes --output ./backups
+nb backup restore --env app1 --file ./backups/backup_20260520_190408_8397.nbdata --yes --force
+```
+
+:::
+
+`nb backup restore` 会先检查 `--file` 指向的路径是否存在，并确认它是一个普通文件。上传成功后，CLI 还会继续等待应用重新通过健康检查，所以命令成功返回时，应用通常已经恢复到可访问状态。
+
+如果没有传入 `--force`，交互终端会再要求你确认一次。在非交互终端、脚本和 AI agent 会话里，`--force` 是必需的。
+
+## 常见情况
+
+如果你更习惯在界面里操作，或者需要定时备份、云存储同步这类能力，可以直接看 [备份管理](../../ops-management/backup-manager/index.mdx)。这类场景下，Web UI 往往更合适。
+
+## 相关链接
+
+- [`nb backup` 命令参考](../../api/cli/backup/index.md)
+- [`nb env` 命令参考](../../api/cli/env/index.md)
+- [多环境管理](./multi-environment.md)
+- [备份管理](../../ops-management/backup-manager/index.mdx)