@nocobase/plugin-ai 2.1.0-beta.43 → 2.1.0-beta.45

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)

package/dist/ai/docs/nocobase/quickstart/operations/manage-app.md

@@ -0,0 +1,166 @@
+# 管理应用
+
+如果你已经把一个 NocoBase 应用保存成 CLI env，日常管理基本都在 `nb app` 这一组命令里完成：启动、停止、重启、查看日志、升级，以及清理本地运行资源。
+
+大多数时候，你不需要记住所有参数。先分清楚自己要做的是“把应用跑起来”“看日志排查问题”，还是“彻底清理这个 env”，再选对应命令就行。
+
+## 快速索引
+
+| 我想要…… | 用哪个命令 |
+| --- | --- |
+| 启动或恢复应用运行 | [`nb app start`](../../api/cli/app/start.md) |
+| 临时停止应用 | [`nb app stop`](../../api/cli/app/stop.md) |
+| 连同 CLI 托管的内置数据库一起停掉 | [`nb app stop --with-db`](../../api/cli/app/stop.md) |
+| 修改配置后重新拉起应用 | [`nb app restart`](../../api/cli/app/restart.md) |
+| 实时查看应用日志 | [`nb app logs`](../../api/cli/app/logs.md) |
+| 升级到新的源码或镜像版本 | [`nb app upgrade`](../../api/cli/app/upgrade.md) |
+| 移除 env 配置，但保留 storage 和本地 app 文件 | [`nb env remove`](../../api/cli/env/remove.md) |
+| 连同本机托管资源一起彻底清理 | [`nb env remove --purge`](../../api/cli/env/remove.md) |
+
+:::tip 先确认当前 env
+
+`nb app` 命令默认作用在当前 env 上。如果你同时维护多个环境，默认推荐先切到目标 env，再执行启动、升级或清理操作。
+
+```bash
+nb env current
+nb env use app1
+```
+
+如果你显式传入了不同的 `--env`，CLI 通常会要求确认。脚本或非交互场景里，可以加 `--yes` 跳过这一步。
+
+:::
+
+## 启动应用
+
+把应用拉起来，默认用 `nb app start` 就行：
+
+```bash
+nb app start
+```
+
+如果你要操作的不是当前 env，可以显式指定：
+
+```bash
+nb app start --env app1 --yes
+```
+
+另外几个比较常用的启动参数：
+
+```bash
+nb app start --no-daemon
+```
+
+- `nb app start` 默认会先自动完成必要的安装或升级准备，再把服务拉起来
+- `--no-daemon` 只在本地 env 下有明显意义——应用会以前台模式运行，方便你直接看控制台输出
+
+本地 npm/Git env 会启动本地应用进程，Docker env 会按已保存配置重建应用容器。详细参数见 [`nb app start`](../../api/cli/app/start.md)。
+
+## 停止和重启
+
+只想临时把应用停掉，用 `nb app stop`：
+
+```bash
+nb app stop
+```
+
+如果你刚改完配置、依赖或代码，通常来说直接 `nb app restart` 更省事：
+
+```bash
+nb app restart
+nb app restart --env app1 --yes
+```
+
+`nb app restart` 会先执行停止，再按 `start` 的方式重新启动，所以它也支持 `--no-daemon` 这类启动参数。详细用法见 [`nb app stop`](../../api/cli/app/stop.md) 和 [`nb app restart`](../../api/cli/app/restart.md)。
+
+## 查看日志
+
+排查问题时，通常先看日志：
+
+```bash
+nb app logs
+```
+
+如果你只想多看一点最近输出，或者不想持续跟随日志，可以这样用：
+
+```bash
+nb app logs --tail 200
+nb app logs --no-follow
+nb app logs --env app1 --yes
+```
+
+本地 npm/Git env 读取的是 pm2 日志，Docker env 读取的是容器日志。默认情况下，`nb app logs` 会持续跟随新日志输出。详细参数见 [`nb app logs`](../../api/cli/app/logs.md)。
+
+## 升级应用
+
+升级命令是 `nb app upgrade`：
+
+```bash
+nb app upgrade
+```
+
+这个命令做的不只是“下载新版本”。默认流程通常包括：
+
+1. 停止当前应用
+2. 下载并替换已保存的源码或镜像
+3. 同步商业插件
+4. 升级并启动应用
+5. 刷新 env runtime 信息
+
+如果你已经提前更新好了源码或镜像，只想基于当前内容继续执行升级并启动应用，可以加 `--skip-download`：
+
+```bash
+nb app upgrade --skip-download
+```
+
+如果你想显式指定目标版本，也可以加 `--version`：
+
+```bash
+nb app upgrade --version beta
+```
+
+:::warning 注意
+
+`nb app upgrade` 在真正开始前通常还会要求你确认一次。脚本、CI 或其他非交互场景里，需要显式传入 `--force`。如果同时还是跨 env 操作，通常要一起带上 `--yes`。
+
+```bash
+nb app upgrade --env app1 --yes --force
+```
+
+:::
+
+更完整的参数说明见 [`nb app upgrade`](../../api/cli/app/upgrade.md)。
+
+## 清理运行资源和销毁 env
+
+这几种场景最容易混淆。可以先记住一个默认建议：
+
+- 只是想把应用停掉，用 `nb app stop`
+- 也想把当前机器上的内置数据库运行时一起停掉，用 `nb app stop --with-db`
+- 确定这个 env 不再需要了，但想先保留 storage 和本地 app 文件，用 `nb env remove`
+- 连本机托管资源也一起清理掉，再用 `nb env remove --purge`
+
+如果你只是想停掉应用和 CLI 托管的内置数据库，直接这样写就行：
+
+```bash
+nb app stop --env app1 --with-db
+```
+
+如果你要移除这个 env，但还想保留 storage 和本地 app 文件：
+
+```bash
+nb env remove app1 --force
+```
+
+如果你确实要把这个 env 的本机托管内容也一起清理掉，那么加上 `--purge`：
+
+```bash
+nb env remove app1 --purge --force
+```
+
+对于 CLI 下载管理的本地 npm/Git env，`--purge` 还会删除 CLI 托管的本地应用文件。对于 HTTP 或 SSH env，它只会删除 CLI 里保存的 env 配置，不会去删除外部服务本身。
+
+## 相关链接
+
+- [多环境管理](./multi-environment.md)
+- [`nb app` 命令参考](../../api/cli/app/index.md)
+- [`nb env` 命令参考](../../api/cli/env/index.md)

package/dist/ai/docs/nocobase/quickstart/operations/multi-environment.md

@@ -0,0 +1,171 @@
+# 多环境管理
+
+如果你同时维护 `dev`、`test`、`staging`、`prod` 等多个 NocoBase 应用，可以把它们分别保存成 CLI env。之后大多数 `nb` 命令都会默认作用在当前 env 上，所以在执行 `nb app`、`nb api`、`nb db` 这类命令前，先确认自己正在用哪个 env 很重要。
+
+CLI 从这一版开始把概念拆成了 `current env` 和 `last env`。你通常只需要关心 `current env`——也就是当前 shell 或 agent runtime 正在使用的环境。只有在没有开启 session mode 时，CLI 才会回退到全局 `last env`。
+
+## 快速索引
+
+| 我想要…… | 用哪个命令 |
+| --- | --- |
+| 新建一个本地 env，并顺手完成初始化 | [`nb init`](../../api/cli/init.md) |
+| 把一个已有应用登记成 CLI env | [`nb env add`](../../api/cli/env/add.md) |
+| 看本地保存了哪些 env | [`nb env list`](../../api/cli/env/list.md) |
+| 检查所有 env 的连通性和认证状态 | [`nb env status --all`](../../api/cli/env/status.md) |
+| 切换后续命令要使用的 env | [`nb env use`](../../api/cli/env/use.md) |
+| 确认当前命令会落到哪个 env | [`nb env current`](../../api/cli/env/current.md) 和 [`nb env status`](../../api/cli/env/status.md) |
+| 查看某个 env 保存了哪些详细配置 | [`nb env info`](../../api/cli/env/info.md) |
+| 更新已保存的 env 配置，必要时让 CLI 重新同步当前状态 | [`nb env update`](../../api/cli/env/update.md) |
+| 登录态过期后重新认证，或者改用新的认证方式 | [`nb env auth`](../../api/cli/env/auth.md) |
+| 删除不用的 env 配置，必要时连本机托管资源一起清理 | [`nb env remove`](../../api/cli/env/remove.md) |
+
+:::tip 建议先开启 session mode
+
+默认推荐先执行一次 [`nb session setup`](../../api/cli/session/setup.md)。这样不同终端、不同 shell，或者不同 agent runtime 可以各自维护自己的 `current env`，并行操作时不容易互相影响。
+
+如果没有开启 session mode，那么 `nb env use` 会回退到更新全局 `last env`。这种情况下，一个终端切走环境，另一个终端也可能跟着受影响。
+
+```bash
+nb session setup
+```
+
+:::
+
+## 创建多个环境
+
+如果你要新建或恢复一个本地应用，用 `nb init` 就行。它会完成初始化，并把结果保存成一个新的 CLI env。
+
+```bash
+nb init --env dev
+nb init --env test
+```
+
+如果应用已经存在，只是想把它接入 CLI，通常来说用 `nb env add` 更直接：
+
+```bash
+nb env add staging --api-base-url http://staging.example.com/api --auth-type oauth
+nb env add prod --api-base-url https://api.example.com/api --auth-type token --access-token <token>
+```
+
+前者偏“初始化一个环境”，后者偏“登记一个已有环境”。如果你只是连接已有应用，默认用 `nb env add` 就行。
+
+## 查看已经配置的环境
+
+先用 `nb env list` 看看本地已经保存了哪些 env：
+
+```bash
+nb env list
+```
+
+这个命令只展示配置本身，不主动检查应用状态。想同时看连通性和认证状态时，用 `nb env status --all`：
+
+```bash
+nb env status --all
+```
+
+你通常会看到 `ok`、`auth failed`、`unreachable` 这类状态值。
+
+## 切换当前环境
+
+切换环境用 `nb env use`：
+
+```bash
+nb env use dev
+```
+
+切换完成后，后续省略 `--env` 的命令都会默认使用这个 env。
+
+## 查看当前环境
+
+如果你不确定当前命令会落到哪个环境上，先执行这两个命令：
+
+```bash
+nb env current
+nb env status
+```
+
+`nb env current` 用来看名称，`nb env status` 用来看当前 env 是否可访问、认证是否正常。
+
+## 查看单个 env 的详细信息
+
+想看某个 env 保存了哪些配置，用 `nb env info`：
+
+```bash
+nb env info dev
+nb env info dev --json
+nb env info dev --field app.url
+nb env info dev --show-secrets
+```
+
+其中，`--field` 适合在脚本里只取一个值。`--show-secrets` 会明文显示 token、密码这类敏感信息，只有在你明确需要排查时再用。
+
+## 更新 env 配置
+
+`nb env update` 用来调整一个已保存 env 的配置。比如 API 地址、认证方式、源码来源、应用端口和数据库参数。更新完成后，CLI 会根据变更自动处理后续事宜。
+
+如果你只是想让 CLI 按当前 env 的最新状态重新同步，直接这样写就行：
+
+```bash
+nb env update
+nb env update prod
+```
+
+如果你要修改这个 env 保存的连接信息或本地配置，可以显式带上参数：
+
+```bash
+nb env update prod --api-base-url https://api.example.com/api
+nb env update prod --access-token <token>
+nb env update dev --app-port 13080 --timezone Asia/Shanghai
+```
+
+这里可以先记住一个默认判断：
+
+- 要修改 env 保存的连接信息或本地配置，用 `nb env update`
+- 应用接口、插件或 CLI 可用能力刚发生变化，也可以再执行一次 `nb env update`
+- 登录态过期了，或者要重新走一遍认证流程，用 `nb env auth`
+- 只是想看当前保存了什么，用 `nb env info`
+
+如果你改的是 `app-port`、`timezone`、`db-*` 这类本地运行配置，`update` 只会改保存值，不会自动重启应用。通常来说后续还要再执行 `nb app restart --env <name>`；如果变更涉及 CLI 托管的内置数据库，则用 `nb app restart --env <name> --with-db`。
+
+## 重新认证
+
+如果 env 已经保存，只是登录态过期了，或者你想切换认证方式，可以重新认证：
+
+```bash
+nb env auth
+nb env auth prod
+nb env auth prod --auth-type oauth
+nb env auth prod --auth-type basic --username admin --password secret
+nb env auth prod --auth-type token --access-token <api-key>
+```
+
+省略环境名时，CLI 会使用当前 env。认证完成后，CLI 会自动处理后续同步。
+
+## 移除环境
+
+如果你只想移除保存的 env 配置：
+
+```bash
+nb env remove staging
+```
+
+如果是本地或 Docker 托管的 env，并且你还想一起清理本机上的运行资源和 storage 数据，可以加上 `--purge`：
+
+```bash
+nb env remove test --purge
+```
+
+在非交互模式下，`nb env remove` 需要显式传入 `--force`：
+
+```bash
+nb env remove test --purge --force
+```
+
+`--purge` 只会清理当前机器上的 CLI 托管资源。对于远程 API env，它不会去删除远端服务本身。
+
+## 相关链接
+
+- [`nb env` 命令参考](../../api/cli/env/index.md)
+- [`nb env update`](../../api/cli/env/update.md)
+- [`nb session` 命令参考](../../api/cli/session/index.md)
+- [管理应用](./manage-app.md)

package/dist/ai/docs/nocobase/quickstart/plugins/third-party.md

@@ -0,0 +1,86 @@
+# 第三方插件安装与升级
+
+如果你拿到的是第三方插件包，通常来说先把它导入目标应用的 `storage/plugins`，然后先重启应用，再继续启用或验证插件是否生效。
+
+## 快速索引
+
+| 我想要…… | 去哪里看 |
+| --- | --- |
+| 先切到目标 env，再开始导入或重启插件 | [先确认目标环境](#先确认目标环境) |
+| 从远程压缩包、本地压缩包或 npm 导入第三方插件 | [用 `nb plugin import` 导入插件包](#用-nb-plugin-import-导入插件包) |
+| 导入完成后让应用重新加载插件目录 | [`nb app restart`](../../api/cli/app/restart.md) |
+| 第一次安装后正式启用插件 | [`nb plugin enable`](../../api/cli/plugin/enable.md) |
+| 想确认插件是否已经出现在当前应用里 | [`nb plugin list`](../../api/cli/plugin/list.md) |
+| 目标机器不能直接联网，只能手动上传 `.tgz` 再导入 | [不能直接联网时](#不能直接联网时) |
+
+## 先确认目标环境
+
+如果你本地管理了多个应用，先切到目标 env 再操作：
+
+```bash
+nb env use app1
+```
+
+## 用 `nb plugin import` 导入插件包
+
+`nb plugin import` 支持三类来源：远程压缩包、本地压缩包、npm 包名。这个命令只负责把插件导入 `storage/plugins`，不会自动启用插件。
+
+如果你已经拿到了插件包下载地址、本地文件路径，或者插件已经发布到 npm，可以执行：
+
+```bash
+# 远程压缩包
+nb plugin import https://github.com/nocobase/plugin-auth-cas/releases/download/v1.4.0/plugin-auth-cas-1.4.0.tgz
+
+# 本地压缩包
+nb plugin import /your/path/plugin-auth-cas-1.4.0.tgz
+
+# npm 包名或 tag
+nb plugin import @my-scope/plugin-auth-cas@beta
+```
+
+如果你用的是私有 npm 源，通常来说先登录，再指定 registry：
+
+```bash
+npm login --registry=https://registry.example.com
+nb plugin import @my-scope/plugin-auth-cas@beta --npm-registry=https://registry.example.com
+```
+
+## 导入之后先重启
+
+导入完成后，先重启目标应用：
+
+```bash
+nb app restart
+```
+
+如果你没有先切换当前 env，也可以在命令里显式传入 `-e <env>`。
+
+## 重启之后再启用或验证
+
+如果这是第一次安装，重启后再启用插件：
+
+```bash
+nb plugin enable @nocobase/plugin-auth-cas
+```
+
+第一次启用时会自动完成安装。
+
+如果插件已经启用，而你这次只是更新压缩包或重新导入一个新版本，通常来说重启完成后就可以继续验证插件是否正常工作，不需要再用 `upgrade` 的做法。
+
+
+## 不能直接联网时
+
+如果目标机器不能直接访问插件下载地址，可以先把 `.tgz` 文件上传到目标机器的任意目录，再在目标机器执行本地导入。
+
+比如：
+
+```bash
+nb plugin import /your/path/plugin-auth-cas-1.4.0.tgz
+nb app restart
+```
+
+:::warning 注意
+
+这里不需要手动解压到 `storage/plugins`。`nb plugin import` 会自动把插件放到正确目录。
+
+:::