@nocobase/plugin-ai 2.1.0-beta.46 → 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)

package/dist/ai/docs/nocobase/api/cli/env/proxy/caddy.md

@@ -1,108 +0,0 @@
----
-title: 'nb env proxy caddy'
-description: 'nb env proxy caddy command reference: generate a Caddy proxy config for one CLI-managed env.'
-keywords: 'nb env proxy caddy,NocoBase CLI,caddy,reverse proxy,proxy configuration'
----
-
-# nb env proxy caddy
-
-`nb env proxy caddy` generates a Caddy proxy config for one CLI-managed env. It fits these cases well: you already have a domain, want HTTPS running quickly, and do not want to maintain too many TLS details yourself.
-
-This command only works for managed envs whose runtime is reachable from the current machine, which means `local` or `docker`. It does not currently work for envs that only have a remote API connection or for SSH envs.
-
-## Usage
-
-```bash
-nb env proxy caddy [name] [flags]
-```
-
-## Parameters
-
-| Parameter | Type | Description |
-| --- | --- | --- |
-| `[name]` | string | Name of the configured env to generate a proxy config for. Uses the current env when omitted |
-| `--env`, `-e` | string | Explicitly specify the env name. This form is usually recommended |
-| `--output`, `-o` | string | Output file path. Only writes the generated route config and does not additionally create `app.caddy` or the shared main config |
-| `--host` | string | Host written into the entry config, such as `example.com` or `localhost` |
-| `--port` | string | Port written into the entry config. This is the proxy entry port, not the upstream NocoBase app port |
-| `--install` | boolean | Install the shared proxy config into the Caddy main config |
-| `--reload` | boolean | Validate and reload Caddy after writing files |
-| `--print` | boolean | Print the generated route config directly instead of writing files |
-
-## Default output
-
-If you do not pass `--output`, the CLI maintains these files under `~/.nocobase/proxy/caddy/`:
-
-| File | Purpose |
-| --- | --- |
-| `~/.nocobase/proxy/caddy/<env>/generated.caddy` | Actual reverse-proxy config managed by the CLI and overwritten on every run |
-| `~/.nocobase/proxy/caddy/<env>/app.caddy` | Editable site entry file where you can add site-level config |
-| `~/.nocobase/proxy/caddy/nocobase.caddy` | Shared main config that imports every env `app.caddy` |
-
-Where:
-
-- `generated.caddy` is only meant to be managed by the CLI and should not be edited manually
-- `app.caddy` is editable, but you should keep the managed import inserted by the CLI
-- `nocobase.caddy` is mainly used by `--install`
-
-:::warning Note
-
-If you need to add site-level Caddy config, edit `app.caddy`. `generated.caddy` will be overwritten the next time you run `nb env proxy caddy`.
-
-:::
-
-If you pass `--output`, the CLI only writes the generated config to that file and does not additionally create or update `app.caddy` or the shared main config.
-
-## Related configuration items
-
-These CLI configuration items directly affect the generated Caddy output:
-
-| Configuration item | Default value | Description |
-| --- | --- | --- |
-| `proxy.nb-cli-root` | CLI root, usually the current user's home directory | Map the `.nocobase` path to the root path that Caddy actually sees |
-| `proxy.upstream-host` | `127.0.0.1` | Host used when the proxy forwards traffic back to the NocoBase app |
-| `bin.caddy` | `caddy` | Path to the Caddy executable used by `--install` or `--reload` |
-
-Most setups do not need to change `proxy.nb-cli-root`. You usually need it only when Caddy runs in another container, mount root, or path view.
-
-## Notes
-
-- `--host` is important. Caddy decides whether to manage HTTPS based on the site address. In production, try to pass a domain that already resolves to the current server
-- `--port` must be an integer between `1` and `65535`
-- The upstream NocoBase app port comes from the saved env `appPort`, not from `--port`
-- If the command says the env is missing `appPort`, run `nb env update <name>` first, or explicitly save it with `nb env update <name> --app-port <port>`
-- If you change settings such as `app-port` or `app-public-path` with `nb env update`, you will usually need to rerun `nb env proxy caddy` afterward
-- `--print` cannot be combined with `--install` or `--reload`
-- `--output` cannot be combined with `--install` or `--reload`
-
-## Examples
-
-```bash
-# Generate a Caddy config for the current env
-nb env proxy caddy
-
-# Generate a config for one env
-nb env proxy caddy --env demo
-
-# Write the public host and port into the entry config
-nb env proxy caddy --env demo --host demo.local.nocobase.com --port 8080
-
-# Print the generated route config without writing files
-nb env proxy caddy --env demo --print
-
-# Write the generated route fragment to a custom file
-nb env proxy caddy --env demo --output ./generated.caddy
-
-# Map the .nocobase path when Caddy runs under another mount root
-nb config set proxy.nb-cli-root /workspace
-
-# Install the shared config into the Caddy main config and reload immediately
-nb env proxy caddy --env demo --install --reload
-```
-
-## Related commands
-
-- [`nb env proxy`](./index.md)
-- [`nb env proxy nginx`](./nginx.md)
-- [`nb env update`](../update.md)
-- [`nb config`](../../config/index.md)

package/dist/ai/docs/nocobase/api/cli/env/proxy/index.md

@@ -1,54 +0,0 @@
----
-title: 'nb env proxy'
-description: 'nb env proxy command-group reference: view and choose the Nginx and Caddy proxy subcommands.'
-keywords: 'nb env proxy,NocoBase CLI,nginx,caddy,reverse proxy,proxy configuration'
----
-
-# nb env proxy
-
-In NocoBase CLI, `nb env proxy` is the entry point for reverse-proxy related commands. You mainly use it to discover and choose the Nginx and Caddy provider subcommands.
-
-If your app has already been saved as a CLI-managed env, and that env is `local` or `docker`, picking one provider subcommand is usually enough.
-
-## Usage
-
-```bash
-nb env proxy
-```
-
-## Which subcommand should you open first
-
-| I want to... | Go here |
-| --- | --- |
-| Keep using Nginx for sites, certificates, caching, or access control | [`nb env proxy nginx`](./nginx.md) |
-| Get HTTPS running quickly and maintain fewer TLS details | [`nb env proxy caddy`](./caddy.md) |
-| Adjust env settings that may affect proxy output, such as `app-port` or `app-public-path` | [`nb env update`](../update.md) |
-
-## Notes
-
-- `nb env proxy` does not have its own flags
-- Use `nb env proxy nginx` or `nb env proxy caddy` when you want to generate configs
-- Both subcommands only work for managed envs whose runtime is reachable from the current machine, which means `local` or `docker`
-- If you change settings such as `app-port` or `app-public-path` with `nb env update`, you will usually need to rerun the matching proxy subcommand afterward
-- This command group does not currently work for envs that only have a remote API connection or for SSH envs
-
-## Examples
-
-```bash
-# Show command-group help
-nb env proxy
-
-# Generate an Nginx config for one env
-nb env proxy nginx --env demo --host demo.local.nocobase.com
-
-# Generate a Caddy config for one env
-nb env proxy caddy --env demo --host demo.local.nocobase.com
-```
-
-## Related commands
-
-- [`nb env proxy nginx`](./nginx.md)
-- [`nb env proxy caddy`](./caddy.md)
-- [`nb env update`](../update.md)
-- [`nb env info`](../info.md)
-- [`nb config`](../../config/index.md)

package/dist/ai/docs/nocobase/api/cli/env/proxy/nginx.md

@@ -1,104 +0,0 @@
----
-title: 'nb env proxy nginx'
-description: 'nb env proxy nginx command reference: generate Nginx proxy config files and helper files for one CLI-managed env.'
-keywords: 'nb env proxy nginx,NocoBase CLI,nginx,reverse proxy,proxy configuration'
----
-
-# nb env proxy nginx
-
-`nb env proxy nginx` generates Nginx proxy config files and helper files for one CLI-managed env. It fits these cases well: you already use Nginx to manage sites, or you still want to manage certificates, caching, or access control yourself.
-
-This command only works for managed envs whose runtime is reachable from the current machine, which means `local` or `docker`. It does not currently work for envs that only have a remote API connection or for SSH envs.
-
-## Usage
-
-```bash
-nb env proxy nginx [name] [flags]
-```
-
-## Parameters
-
-| Parameter | Type | Description |
-| --- | --- | --- |
-| `[name]` | string | Name of the configured env to generate a proxy config for. Uses the current env when omitted |
-| `--env`, `-e` | string | Explicitly specify the env name. This form is usually recommended |
-| `--host` | string | Host written into the entry config, such as `example.com` or `localhost` |
-| `--port` | string | Port written into the entry config. This is the proxy entry port, not the upstream NocoBase app port |
-| `--install` | boolean | Install the shared proxy config into the Nginx main config |
-| `--reload` | boolean | Validate and reload Nginx after writing files |
-| `--print` | boolean | Print the rendered `app.conf` directly instead of writing files |
-
-## Default output
-
-`nb env proxy nginx` maintains these files under `~/.nocobase/proxy/nginx/`:
-
-| File | Purpose |
-| --- | --- |
-| `~/.nocobase/proxy/nginx/<env>/app.conf` | Editable site entry file. The CLI refreshes the managed block inside it, and you can add site-level config around that block |
-| `~/.nocobase/proxy/nginx/<env>/public/index-v1.html` | v1 SPA fallback page generated from the current active client's `index.html` |
-| `~/.nocobase/proxy/nginx/<env>/public/index-v2.html` | v2 SPA fallback page generated from the current active client's `v/index.html` |
-| `~/.nocobase/proxy/nginx/nocobase.conf` | Shared main config that includes every env `app.conf` |
-| `~/.nocobase/proxy/nginx/snippets/` | Shared snippets directory copied from built-in templates |
-
-Where:
-
-- `app.conf` is editable, but you should keep the managed block between `# BEGIN NocoBase managed config` and `# END NocoBase managed config`
-- `index-v1.html` and `index-v2.html` automatically rewrite asset URLs according to the current env subpath, active client version, and `CDN_BASE_URL`
-- `nocobase.conf` is mainly used by `--install`
-- Files under `public/` and `snippets/` are usually not meant to be edited manually and will be resynced the next time you run the command
-
-:::warning Note
-
-If you need to add site-level Nginx config, edit `app.conf`. Do not manually edit managed files under `public/` or `snippets/`, because they will be overwritten the next time you run `nb env proxy nginx`.
-
-:::
-
-## Related configuration items
-
-These CLI configuration items directly affect the generated Nginx output:
-
-| Configuration item | Default value | Description |
-| --- | --- | --- |
-| `proxy.nb-cli-root` | CLI root, usually the current user's home directory | Map the `.nocobase` path to the root path that Nginx actually sees |
-| `proxy.upstream-host` | `127.0.0.1` | Host used when the proxy forwards traffic back to the NocoBase app |
-| `bin.nginx` | `nginx` | Path to the Nginx executable used by `--install` or `--reload` |
-
-Most setups do not need to change `proxy.nb-cli-root`. You usually need it only when Nginx runs in another container, mount root, or path view.
-
-## Notes
-
-- `--port` must be an integer between `1` and `65535`
-- The upstream NocoBase app port comes from the saved env `appPort`, not from `--port`
-- If the command says the env is missing `appPort`, run `nb env update <name>` first, or explicitly save it with `nb env update <name> --app-port <port>`
-- If you change settings such as `app-port` or `app-public-path` with `nb env update`, you will usually need to rerun `nb env proxy nginx` afterward
-- `--print` cannot be combined with `--install` or `--reload`
-- The Nginx provider does not support `--output`
-
-## Examples
-
-```bash
-# Generate an Nginx config for the current env
-nb env proxy nginx
-
-# Generate a config for one env
-nb env proxy nginx --env demo
-
-# Write the public host and port into the entry config
-nb env proxy nginx --env demo --host demo.local.nocobase.com --port 8080
-
-# Print the rendered app.conf without writing files
-nb env proxy nginx --env demo --print
-
-# Map the .nocobase path when Nginx runs under another mount root
-nb config set proxy.nb-cli-root /workspace
-
-# Install the shared config into the Nginx main config and reload immediately
-nb env proxy nginx --env demo --install --reload
-```
-
-## Related commands
-
-- [`nb env proxy`](./index.md)
-- [`nb env proxy caddy`](./caddy.md)
-- [`nb env update`](../update.md)
-- [`nb config`](../../config/index.md)