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

package/dist/ai/docs/nocobase/api/cli/config/get.md

@@ -1,12 +1,12 @@
 ---
-title: "nb config get"
-description: "nb config get command reference: get the effective value for a CLI configuration key."
-keywords: "nb config get,NocoBase CLI,configuration"
+title: 'nb config get'
+description: 'nb config get command reference: read the effective value of a CLI configuration item.'
+keywords: 'nb config get,NocoBase CLI,read configuration'
 ---
 
 # nb config get
 
-Get the effective value for a CLI configuration key. If no explicit value is set, the default value is returned.
+Read the effective value of the specified CLI configuration item. If it has not been explicitly set, the default value is returned.
 
 ## Usage
 
@@ -16,9 +16,9 @@ nb config get <key>
 
 ## Parameters
 
-| Parameter | Type | Description |
-| --- | --- | --- |
-| `<key>` | string | Configuration key: `locale`, `update.policy`, `license.pkg-url`, `docker.network`, `docker.container-prefix`, `bin.docker`, `bin.git`, or `bin.yarn` |
+| Parameter | Type   | Description                                                                                                                             |
+| --------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------- |
+| `<key>` | string | Configuration item name. See [`nb config`](./index.md) for supported values |
 
 ## Examples
 
@@ -28,10 +28,13 @@ nb config get update.policy
 nb config get license.pkg-url
 nb config get docker.network
 nb config get docker.container-prefix
+nb config get proxy.nb-cli-root
+nb config get proxy.upstream-host
+nb config get bin.nginx
 nb config get bin.git
 ```
 
-## Related Commands
+## Related commands
 
 - [`nb config set`](./set.md)
 - [`nb config list`](./list.md)

package/dist/ai/docs/nocobase/api/cli/config/index.md

@@ -1,34 +1,34 @@
 ---
-title: "nb config"
-description: "nb config command reference: manage NocoBase CLI default configuration."
-keywords: "nb config,NocoBase CLI,configuration,defaults"
+title: 'nb config'
+description: 'nb config command reference: manage the default configuration items of the NocoBase CLI.'
+keywords: 'nb config,NocoBase CLI,configuration,default configuration'
 ---
 
 # nb config
 
-Manage CLI configuration defaults. Supported keys:
+Manage the default CLI configuration. The current configuration items mainly fall into these groups:
 
-- `locale`
-- `update.policy`
-- `license.pkg-url`
-- `docker.network`
-- `docker.container-prefix`
-- `bin.docker`
-- `bin.git`
-- `bin.yarn`
+- CLI itself: `locale`, `update.policy`, `license.pkg-url`
+- Docker runtime: `docker.network`, `docker.container-prefix`
+- External executables: `bin.docker`, `bin.caddy`, `bin.git`, `bin.nginx`, `bin.yarn`
+- Proxy generation: `proxy.nb-cli-root`, `proxy.upstream-host`
 
-## Common Keys
+## Common configuration items
 
-| Key | Default | Description |
+| Configuration item | Default value | Description |
 | --- | --- | --- |
-| `locale` | current CLI locale resolution | Override the CLI locale |
-| `update.policy` | `prompt` | Startup update behavior: `prompt`, `auto`, or `off` |
-| `license.pkg-url` | `https://pkg.nocobase.com/` | Package registry for commercial packages |
-| `docker.network` | `nocobase` | Default Docker network used by CLI-managed Docker apps |
-| `docker.container-prefix` | `nb` | Default container prefix used by CLI-managed Docker apps |
+| `locale` | Resolved according to the CLI's current rules | Override the language used by the CLI |
+| `update.policy` | `prompt` | Update policy at startup: `prompt`, `auto`, or `off` |
+| `license.pkg-url` | `https://pkg.nocobase.com/` | Override the commercial extension package download URL |
+| `docker.network` | `nocobase` | Default network for Docker applications managed by the CLI |
+| `docker.container-prefix` | `nb` | Default prefix for Docker containers managed by the CLI |
 | `bin.docker` | `docker` | Override the Docker executable path |
+| `bin.caddy` | `caddy` | Override the Caddy executable path |
 | `bin.git` | `git` | Override the Git executable path |
+| `bin.nginx` | `nginx` | Override the Nginx executable path |
 | `bin.yarn` | `yarn` | Override the Yarn executable path |
+| `proxy.nb-cli-root` | CLI root, usually the current user's home directory | Map the `.nocobase` path to the root path visible to the proxy process |
+| `proxy.upstream-host` | `127.0.0.1` | Host used when the proxy forwards traffic back to the NocoBase app |
 
 ## Usage
 
@@ -40,10 +40,10 @@ nb config <command>
 
 | Command | Description |
 | --- | --- |
-| [`nb config get`](./get.md) | Get the effective value for a configuration key |
-| [`nb config set`](./set.md) | Set a configuration value |
-| [`nb config delete`](./delete.md) | Delete an explicitly configured value |
-| [`nb config list`](./list.md) | List explicitly configured values |
+| [`nb config get`](./get.md)       | Read the effective value of a configuration item               |
+| [`nb config set`](./set.md)       | Set a configuration item                                       |
+| [`nb config delete`](./delete.md) | Delete an explicitly configured item                           |
+| [`nb config list`](./list.md)     | List the configuration items that are currently explicitly set |
 
 ## Examples
 
@@ -51,13 +51,17 @@ nb config <command>
 nb config list
 nb config get update.policy
 nb config set update.policy auto
+nb config get proxy.nb-cli-root
+nb config set proxy.nb-cli-root /workspace
+nb config set proxy.upstream-host host.docker.internal
 nb config get docker.network
 nb config set docker.network nocobase
+nb config set bin.nginx /usr/sbin/nginx
 nb config set bin.git /usr/bin/git
 nb config delete docker.container-prefix
 ```
 
-## Related Commands
+## Related commands
 
 - [`nb init`](../init.md)
 - [`nb license`](../license/index.md)

package/dist/ai/docs/nocobase/api/cli/config/set.md

@@ -1,12 +1,12 @@
 ---
-title: "nb config set"
-description: "nb config set command reference: set a CLI configuration value."
-keywords: "nb config set,NocoBase CLI,configuration"
+title: 'nb config set'
+description: 'nb config set command reference: set a CLI configuration item.'
+keywords: 'nb config set,NocoBase CLI,set configuration'
 ---
 
 # nb config set
 
-Set a CLI configuration value. Supported keys are `locale`, `update.policy`, `license.pkg-url`, `docker.network`, `docker.container-prefix`, `bin.docker`, `bin.git`, and `bin.yarn`.
+Set a CLI configuration item. See [`nb config`](./index.md) for the supported configuration keys.
 
 ## Usage
 
@@ -16,10 +16,10 @@ nb config set <key> <value>
 
 ## Parameters
 
-| Parameter | Type | Description |
-| --- | --- | --- |
-| `<key>` | string | Configuration key: `locale`, `update.policy`, `license.pkg-url`, `docker.network`, `docker.container-prefix`, `bin.docker`, `bin.git`, or `bin.yarn` |
-| `<value>` | string | Configuration value; must not be empty |
+| Parameter | Type   | Description                                                                                                                             |
+| --------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------- |
+| `<key>` | string | Configuration item name. See [`nb config`](./index.md) for supported values |
+| `<value>` | string | Configuration value, cannot be empty                                                                                                    |
 
 ## Examples
 
@@ -30,17 +30,19 @@ nb config set license.pkg-url https://pkg.nocobase.com/
 nb config set docker.network nocobase
 nb config set docker.container-prefix nb
 nb config set bin.docker /usr/local/bin/docker
+nb config set bin.caddy /opt/homebrew/bin/caddy
 nb config set bin.git /usr/bin/git
+nb config set bin.nginx /usr/sbin/nginx
+nb config set proxy.nb-cli-root /workspace
+nb config set proxy.upstream-host host.docker.internal
 nb config set bin.yarn yarn
 ```
 
 ## Notes
 
-When setting `license.pkg-url`, the CLI normalizes the URL so it ends with `/`.
+`update.policy` supports `prompt`, `auto`, and `off`, and the default value is `prompt`.
 
-`update.policy` supports `prompt`, `auto`, and `off`. The default is `prompt`.
-
-## Related Commands
+## Related commands
 
 - [`nb config get`](./get.md)
 - [`nb config delete`](./delete.md)

package/dist/ai/docs/nocobase/api/cli/db/stop.md

@@ -1,12 +1,12 @@
 ---
-title: "nb db stop"
-description: "nb db stop command reference: stop the built-in database container for a selected env."
-keywords: "nb db stop,NocoBase CLI,stop database,Docker"
+title: 'nb db stop'
+description: 'nb db stop command reference: Stop the built-in database container for the specified env.'
+keywords: 'nb db stop,NocoBase CLI,stop database,Docker'
 ---
 
 # nb db stop
 
-Stop the built-in database container for a selected env. This command only applies to envs created with a CLI-managed built-in database.
+Stop the built-in database container for the specified env. This command only applies to envs with CLI-managed built-in databases enabled.
 
 ## Usage
 
@@ -14,12 +14,12 @@ Stop the built-in database container for a selected env. This command only appli
 nb db stop [flags]
 ```
 
-## Parameters
+## Options
 
-| Parameter | Type | Description |
-| --- | --- | --- |
-| `--env`, `-e` | string | CLI env name whose built-in database should stop; uses the current env if omitted |
-| `--verbose` | boolean | Show underlying Docker command output |
+| Option        | Type    | Description                                                                                    |
+| ------------- | ------- | ---------------------------------------------------------------------------------------------- |
+| `--env`, `-e` | string  | Name of the CLI env whose built-in database should be stopped; uses the current env if omitted |
+| `--verbose`   | boolean | Show the underlying Docker command output                                                      |
 
 ## Examples
 
@@ -29,8 +29,7 @@ nb db stop --env app1
 nb db stop --env app1 --verbose
 ```
 
-## Related Commands
+## Related commands
 
 - [`nb db start`](./start.md)
 - [`nb app stop`](../app/stop.md)
-- [`nb app down`](../app/down.md)

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

@@ -1,17 +1,17 @@
 ---
-title: "nb env"
-description: "nb env command reference: manage NocoBase CLI envs, including add, inspect current env, check status, switch, authenticate, and remove."
-keywords: "nb env,NocoBase CLI,environment management,env,current env,authentication,OpenAPI"
+title: 'nb env'
+description: 'nb env command reference: manage NocoBase CLI envs, including adding, viewing the current env, checking status, switching, updating, generating proxy configs, authenticating, and removing.'
+keywords: 'nb env,NocoBase CLI,environment management,env,current env,proxy,authentication,OpenAPI'
 ---
 
 # nb env
 
-Manage saved NocoBase CLI envs. An env stores API URL, authentication info, local app paths, database config, and runtime command cache.
+Manage saved NocoBase CLI envs. An env stores connection and local runtime information such as the API address, authentication info, local app path, and database configuration.
 
-In the current model, the CLI separates two concepts:
+Starting from this version, the CLI separates two concepts:
 
-- `current env`: the env currently used by the active shell or agent runtime, isolated by `NB_SESSION_ID` when available
-- `last env`: the globally last-used env, used as a fallback when session mode is not enabled
+- `current env`: the env currently used by the current shell or agent runtime, isolated by `NB_SESSION_ID` when possible
+- `last env`: the last env used globally, used as a fallback when session mode is not enabled
 
 ## Usage
 
@@ -21,17 +21,18 @@ nb env <command>
 
 ## Subcommands
 
-| Command | Description |
-| --- | --- |
-| [`nb env add`](./add.md) | Save a NocoBase API endpoint and switch to that env |
-| [`nb env current`](./current.md) | Show the currently effective env |
-| [`nb env update`](./update.md) | Refresh OpenAPI Schema and runtime command cache from the app |
-| [`nb env list`](./list.md) | List configured envs |
-| [`nb env status`](./status.md) | Show status for the current env, one env, or all envs |
-| [`nb env info`](./info.md) | Show details for a single env |
-| [`nb env remove`](./remove.md) | Remove env configuration |
-| [`nb env auth`](./auth.md) | Run OAuth login for a saved env |
-| [`nb env use`](./use.md) | Switch current env |
+| Command                          | Description                                                                        |
+| -------------------------------- | ---------------------------------------------------------------------------------- |
+| [`nb env add`](./add.md)         | Save a NocoBase API endpoint and switch to this env                                |
+| [`nb env current`](./current.md) | View the currently effective env                                                   |
+| [`nb env update`](./update.md)   | Update a saved env configuration and automatically handle follow-up sync as needed |
+| [`nb env list`](./list.md)       | List configured envs                                                               |
+| [`nb env status`](./status.md)   | View the status of the current env, a specified env, or all envs                   |
+| [`nb env info`](./info.md)       | View detailed information for a single env                                         |
+| [`nb env proxy`](./proxy/index.md) | Show proxy provider subcommands and generate Nginx or Caddy configs for one managed env |
+| [`nb env remove`](./remove.md)   | Remove the env configuration after stopping the managed runtime                    |
+| [`nb env auth`](./auth.md)       | Perform OAuth login for a saved env                                                |
+| [`nb env use`](./use.md)         | Switch the current env                                                             |
 
 ## Examples
 
@@ -41,20 +42,21 @@ nb env current
 nb env list
 nb env status
 nb env info app1
+nb env proxy nginx --env app1
 nb env update app1
 nb env use app1
 nb env auth app1
 ```
 
-## Session mode
+## session mode
 
-Session mode is the default recommendation. It keeps `current env` isolated across different terminals, shells, and agent runtimes, so parallel work does not affect each other.
+Session mode is recommended by default. This allows the `current env` in different terminals, different shells, or different agent runtimes to stay isolated from each other without affecting one another in parallel.
 
-When session mode is not enabled, `nb env use` updates the global `last env`, and other sessions without isolation may also be affected.
+If session mode is not enabled, `nb env use` updates the global `last env`, and other sessions without session isolation will also be affected.
 
-See [`nb session setup`](../session/setup.md) to enable it.
+See [`nb session setup`](../session/setup.md) for how to enable it.
 
-## Related Commands
+## Related commands
 
 - [`nb init`](../init.md)
 - [`nb api`](../api/index.md)

package/dist/ai/docs/nocobase/api/cli/env/info.md

@@ -1,12 +1,12 @@
 ---
-title: "nb env info"
-description: "nb env info command reference: inspect app, database, API, and authentication config for a NocoBase CLI env."
-keywords: "nb env info,NocoBase CLI,environment details,configuration"
+title: 'nb env info'
+description: 'nb env info command reference: View the app, database, API, and authentication configuration of the specified NocoBase CLI env.'
+keywords: 'nb env info,NocoBase CLI,environment details,configuration'
 ---
 
 # nb env info
 
-Show details for a single env, including app, database, API, and authentication configuration.
+View detailed information for a single env, including app, database, API, and authentication configuration.
 
 ## Usage
 
@@ -16,21 +16,23 @@ nb env info [name] [flags]
 
 ## Parameters
 
-| Parameter | Type | Description |
-| --- | --- | --- |
-| `[name]` | string | Configured environment name to inspect; uses the current env if omitted |
-| `--json` | boolean | Output JSON |
-| `--show-secrets` | boolean | Show tokens, passwords, and other secrets in plain text |
+| Parameter        | Type    | Description                                                                                  |
+| ---------------- | ------- | -------------------------------------------------------------------------------------------- |
+| `[name]`         | string  | Name of the configured environment to view; uses the current env when omitted                |
+| `--json`         | boolean | Output JSON                                                                                  |
+| `--field`        | string  | Return only one field using a dot path, such as `app.url`, `app.appPath`, or `api.auth.type` |
+| `--show-secrets` | boolean | Show tokens, passwords, and other secrets in plain text                                      |
 
 ## Examples
 
 ```bash
 nb env info app1
 nb env info app1 --json
+nb env info app1 --field app.appPath
 nb env info app1 --show-secrets
 ```
 
-## Related Commands
+## Related commands
 
 - [`nb env list`](./list.md)
 - [`nb app start`](../app/start.md)

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

@@ -0,0 +1,108 @@
+---
+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

@@ -0,0 +1,54 @@
+---
+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

@@ -0,0 +1,104 @@
+---
+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)