@nocobase/plugin-ai 2.1.0-beta.47 → 2.1.0-beta.48

package/dist/ai/docs/nocobase/ai/install-upgrade-migration.mdx

@@ -1,402 +0,0 @@
----
-title: 'Installation and Upgrade Migration Guide: Using NocoBase CLI'
-description: 'Migrate from legacy Docker, create-nocobase-app, and Git source installation upgrade methods to the new NocoBase CLI workflow.'
-keywords: 'NocoBase CLI,installation migration,upgrade migration,nb init,nb app upgrade,Docker,create-nocobase-app,Git source'
----
-
-# Installation and Upgrade Migration Guide: Using NocoBase CLI
-
-:::danger
-The CLI's installation and application maintenance capabilities are still under development. At present, it is more suitable for local development, test environments, and AI Agent integration scenarios, and is not recommended for direct installation, upgrade, operation, and maintenance in production environments.
-:::
-
-The new NocoBase CLI (`nb`) unifies installation, connection, startup, shutdown, log viewing, upgrade, and cleanup into one set of commands. Compared with the separate workflows in the old documentation for Docker, create-nocobase-app, and Git source, the CLI is better suited for local development, test environment maintenance, and AI Agent integration and collaboration.
-
-This article applies to the following scenarios:
-
-- You are installing or upgrading NocoBase according to the old documentation and want to switch to the new CLI approach.
-- You already have a NocoBase deployed in a legacy way and want the CLI to manage or connect to it.
-- You need to prepare a connectable and maintainable NocoBase environment for an AI Agent.
-
-## Differences between the old and new approaches
-
-The old approach splits documentation by installation source, and each source requires separate download, configuration, installation, startup, and upgrade commands.
-
-**Old installation documentation**
-
-- [Docker installation](/get-started/installation/docker)
-- [create-nocobase-app installation](/get-started/installation/create-nocobase-app)
-- [Git source installation](/get-started/installation/git)
-
-**Old upgrade documentation**
-
-- [Upgrading a Docker installation](/get-started/upgrading/docker)
-- [Upgrading a create-nocobase-app installation](/get-started/upgrading/create-nocobase-app)
-- [Upgrading a Git source installation](/get-started/upgrading/git)
-
-The new approach uses `nb init` as the entry point and records the application source, runtime directory, storage directory, database, and API connection information in a CLI env. After that, whether the source is Docker, npm, or Git, maintenance uses the same set of `nb app`, `nb source`, and `nb db` commands as much as possible.
-
-| Scenario                            | Old approach                                              | New CLI approach                                  |
-| ----------------------------------- | --------------------------------------------------------- | ------------------------------------------------- |
-| Installation entry point            | `docker compose`, `create-nocobase-app`, `git clone`      | `nb init` or `nb init --ui`                       |
-| Application runtime management      | Switch directories, modify compose, run yarn/pm2 commands | `nb app start/stop/restart/logs`, `nb env remove` |
-| Upgrade                             | One set of commands per installation method               | `nb app upgrade -e <env>`                         |
-| Development mode                    | `yarn dev`                                                | `nb source dev -e <env>`                          |
-| Database status                     | Manually inspect containers or database services          | `nb db ps -e <env>`                               |
-| View environment status and details | Manually record paths, ports, and access URLs             | `nb env list`, `nb env info <env>`                |
-| Access existing applications        | Not covered uniformly in old installation docs            | `nb init --ui` or `nb init --api-base-url`        |
-
-## Install the CLI
-
-```bash
-npm install -g @nocobase/cli@beta
-nb --version
-```
-
-After installation, you can view the help:
-
-```bash
-nb --help
-nb init --help
-```
-
-## Install NocoBase using the new approach
-
-### Recommended: use the visual wizard
-
-```bash
-nb init --ui
-```
-
-The wizard will guide you to choose:
-
-- Create a new application or connect to an existing application
-- Installation source: Docker, npm, Git
-- NocoBase version
-- Use the built-in database or an external database
-- Administrator account and password
-
-### Use the terminal interactive wizard
-
-```bash
-nb init
-```
-
-### Use non-interactive commands
-
-The default installation method is Docker and uses the built-in PostgreSQL database:
-
-```bash
-nb init --yes --env app1
-```
-
-Install a specified version with Docker:
-
-```bash
-nb init --yes --env app1 --source docker --version beta
-```
-
-Install with npm:
-
-```bash
-nb init --yes --env app1 --source npm --version beta --app-port 13080
-```
-
-Install from Git source:
-
-```bash
-nb init --yes --env app1 --source git --version beta
-```
-
-Install from Git source and specify the built-in database type:
-
-```bash
-nb init --yes --env app1 --source git --version beta --db-dialect mysql
-```
-
-Connect to an existing NocoBase application:
-
-```bash
-# Uses OAuth authentication by default
-nb init --yes --env app1 --api-base-url=http://next.v2.test.nocobase.com/nocobase/api
-
-# Use token authentication
-nb init --yes --env app1 \
-  --api-base-url=http://next.v2.test.nocobase.com/nocobase/api \
-  --auth-type=token \
-  --access-token=<token>
-```
-
-:::tip
-`--env` is the environment name in the CLI. Subsequent commands such as startup, upgrade, and log viewing can all specify the target application with `-e app1`.
-:::
-
-## Upgrade using the new approach
-
-In the old approach, the upgrade commands for Docker, create-nocobase-app, and Git source were different; the new CLI unifies them as:
-
-```bash
-nb app upgrade -e app1
-```
-
-If you only want to run the upgrade process using the source code or image that has already been downloaded, without pulling new code or images:
-
-```bash
-nb app upgrade -e app1 --skip-code-update
-```
-
-Or use the short form:
-
-```bash
-nb app upgrade -e app1 -s
-```
-
-## Common maintenance commands
-
-| Operation                                          | Command                              |
-| -------------------------------------------------- | ------------------------------------ |
-| Start application                                  | `nb app start -e app1`               |
-| Stop application                                   | `nb app stop -e app1`                |
-| Restart application                                | `nb app restart -e app1`             |
-| View logs                                          | `nb app logs -e app1`                |
-| View env and API authentication status             | `nb env list`                        |
-| View env details                                   | `nb env info app1`                   |
-| View built-in database status                      | `nb db ps -e app1`                   |
-| Upgrade application                                | `nb app upgrade -e app1`             |
-| Stop application and built-in database             | `nb app stop -e app1 --with-db`      |
-| Completely remove env and locally hosted resources | `nb env remove app1 --purge --force` |
-
-If you just want to stop the application together with the built-in database managed by the CLI, the default is to simply use `nb app stop -e app1 --with-db`.
-
-If you are sure this env is no longer needed, then use `nb env remove app1 --purge --force`. It will remove hosted runtime resources, storage data, and, when applicable, local app files downloaded and managed by the CLI.
-
-## Daily development commands
-
-`nb source` is used to manage local source projects and is mainly suitable for npm and Git source envs.
-
-| Operation                           | Command                                             |
-| ----------------------------------- | --------------------------------------------------- |
-| Run application in development mode | `nb source dev -e app1`                             |
-| Build source code                   | `nb source build --cwd /your/workspace/app1/source` |
-| Run tests                           | `nb source test --cwd /your/workspace/app1/source`  |
-| Download or refresh source/image    | `nb source download --source git --version beta`    |
-
-:::tip
-Docker envs are usually managed through `nb app start`, `nb app logs`, and `nb app upgrade`, and do not use `nb source dev`.
-:::
-
-## NB_CLI_ROOT and directory structure
-
-The CLI stores global configuration and local application files in the directory corresponding to `NB_CLI_ROOT`.
-
-By default, `NB_CLI_ROOT` is the current user's home directory, that is, the path returned by Node.js `os.homedir()`. For example, on macOS it is usually `/Users/<user>`. Therefore, without additional configuration, the files generated by `nb init --yes --env app1` are usually located at:
-
-```text
-~
-├── .nocobase
-│   └── config.json
-└── app1
-    ├── source
-    └── storage
-```
-
-You can also explicitly specify `NB_CLI_ROOT`:
-
-```bash
-export NB_CLI_ROOT=/your/workspace
-```
-
-After setting it, the configuration file and default application directory will both be placed under that directory:
-
-```text
-/your/workspace
-├── .nocobase
-│   └── config.json
-└── app1
-    ├── source
-    └── storage
-```
-
-Where:
-
-- `.nocobase/config.json` stores information such as envs, current environment, API address, source path, storage path, and database configuration.
-- `<envName>/source` is the source code or application directory managed by the CLI.
-- `<envName>/storage` is the application storage directory managed by the CLI.
-
-:::warning
-After initializing the same application, keep using the same `NB_CLI_ROOT`. If you later change `NB_CLI_ROOT`, the CLI will look for `.nocobase/config.json` in the new directory, and relative `appRootPath` and `storagePath` will also be resolved against the new directory, which may cause the application to not be found or to read and write to the wrong directory.
-:::
-
-The CLI currently only uses the global configuration scope. If you need to adjust where configuration and local application files are stored, set `NB_CLI_ROOT`.
-
-When viewing and locating applications, prefer `nb env list` and `nb env info`:
-
-```bash
-# View configured envs and API authentication status
-nb env list
-
-# View detailed information for an env
-nb env info app1
-```
-
-`nb env list` is intended for a quick overview. Here, `App Status` is the authentication status obtained by accessing the application API with the saved Token/OAuth credentials, and no longer displays database status. To view the running status of the built-in database, use:
-
-```bash
-nb db ps -e app1
-```
-
-Only use this when you need to switch the default env:
-
-```bash
-nb env use app1
-```
-
-## Migrate from the old approach to CLI
-
-There are two migration strategies: **connect to an existing application**, or **bring a local application directory under CLI management**. If your old application is already running stably, it is recommended to first use "connect to an existing application", which has the lowest risk.
-
-### Method 1: connect to an existing application
-
-Suitable for NocoBase instances already running via Docker, create-nocobase-app, Git source, or server deployment.
-
-```bash
-# Uses OAuth authentication by default
-nb init --yes --env app1 --api-base-url=http://next.v2.test.nocobase.com/nocobase/api
-
-# Use token authentication
-nb init --yes --env "app$RANDOM" \
-  --api-base-url=http://next.v2.test.nocobase.com/nocobase/api \
-  --auth-type=token \
-  --access-token=<token>
-```
-
-This approach only stores the API connection. The CLI will not take over startup, shutdown, upgrade, source directory, or storage directory management of the old application. It is suitable for allowing AI Agents or CLI API commands to connect to existing applications.
-
-If you need to refresh authentication:
-
-```bash
-nb env auth app1
-```
-
-### Method 2: create a new CLI env and then migrate files
-
-Suitable for scenarios where you want to use `nb app` and `nb source` to manage local applications afterward.
-
-Before migration, complete the following first:
-
-1. Stop the old application.
-2. Back up the old database.
-3. Back up the old `storage` directory.
-4. Record the key environment variables of the old application, such as `APP_KEY`, `TZ`, `DB_*`, and `DB_UNDERSCORED`.
-
-#### Migrate from an old Docker installation
-
-The old Docker approach usually stores application data in the project's `storage` directory:
-
-```text
-/old-docker-project
-├── docker-compose.yml
-└── storage
-```
-
-It is recommended to first determine the new `NB_CLI_ROOT`, then use the CLI to create a new Docker env. The following example assumes that `NB_CLI_ROOT` is `/your/workspace`.
-
-```bash
-export NB_CLI_ROOT=/your/workspace
-nb init --yes --env app2 --source docker --version beta
-nb app stop -e app2
-```
-
-The new env will use the following directories by default:
-
-```text
-/your/workspace
-└── app2
-    ├── source
-    └── storage
-```
-
-Then copy the old `storage` to `/your/workspace/app2/storage`, and make sure the database connection, `APP_KEY`, and other configurations match the old environment.
-
-After the copy is complete and the database configuration is confirmed, start the application:
-
-```bash
-nb app start -e app2
-nb app logs -e app2
-```
-
-#### Migrate from an old create-nocobase-app or Git source installation
-
-The old npm/Git approach usually places the source code, `.env`, and `storage` in the same project directory:
-
-```text
-/old-nocobase
-├── .env
-├── package.json
-├── packages
-└── storage
-```
-
-It is recommended to first determine the new `NB_CLI_ROOT`, then create a new npm or Git env. The following example assumes that `NB_CLI_ROOT` is `/your/workspace`.
-
-```bash
-export NB_CLI_ROOT=/your/workspace
-nb init --yes --env app3 --source git --version beta
-nb app stop -e app3
-```
-
-Then migrate as needed:
-
-- Migrate custom plugin source code from the old project to the corresponding directory under `/your/workspace/app3/source`.
-- Copy the old project's `storage` to `/your/workspace/app3/storage`.
-- Sync key configurations from the old `.env` to the CLI env configuration or initialization parameters.
-- If using the original database, disable the built-in database during initialization and fill in the old database connection information.
-
-Example of initialization with an external database:
-
-```bash
-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
-```
-
-After migration, start it and view the logs:
-
-```bash
-nb app start -e app3
-nb app logs -e app3
-```
-
-:::warning
-Do not directly overwrite `source`, `storage`, or connect to the production database for upgrades without a backup. Before formal migration, it is recommended to do a full rehearsal once in a test environment.
-:::
-
-## Quick reference for old command migration
-
-| Old command                                           | New CLI command                                                                         |
-| ----------------------------------------------------- | --------------------------------------------------------------------------------------- |
-| `docker compose up -d app`                            | `nb app start -e app1`                                                                  |
-| `docker compose stop app`                             | `nb app stop -e app1`                                                                   |
-| `docker compose logs -f app`                          | `nb app logs -e app1`                                                                   |
-| `docker compose pull app && docker compose up -d app` | `nb app upgrade -e app1`                                                                |
-| `yarn create nocobase-app my-nocobase-app ...`        | `nb init --yes --env app1 --source npm --version beta`                                  |
-| `npx create-nocobase-app@beta my-nocobase-app ...`    | `nb init --yes --env app1 --source npm --version beta`                                  |
-| `git clone ... -b next --depth=1 my-nocobase`         | `nb init --yes --env app1 --source git --version beta`                                  |
-| `git clone ... -b develop --depth=1 my-nocobase`      | `nb init --yes --env app1 --source git --version alpha`                                 |
-| `yarn dev`                                            | `nb source dev -e app1`                                                                 |
-| `yarn nocobase upgrade`                               | `nb app upgrade -e app1`                                                                |
-| `yarn nocobase upgrade --skip-code-update`            | `nb app upgrade -e app1 -s`                                                             |
-| Manually record multiple application addresses        | `nb env list`, `nb env info app1`                                                       |
-| Manually connect to an existing application           | `nb init --yes --env app1 --api-base-url=http://next.v2.test.nocobase.com/nocobase/api` |
-
-## Related links
-
-- [AI Agent Integration Guide](/ai/quick-start)
-- [NocoBase CLI Command Reference](/api/cli)
-- [Installation methods and version comparison](/get-started/quickstart)
-- [Install and upgrade plugins](/get-started/install-upgrade-plugins)