@nocobase/plugin-ai 2.2.0-alpha.1 → 2.2.0-alpha.11

package/dist/ai/docs/nocobase/api/app/env.md

@@ -51,6 +51,35 @@ API_BASE_PATH=/api/
 
 ## API_BASE_URL
 
+## SERVER_REQUEST_WHITELIST
+
+Whitelist for outbound HTTP requests initiated by the server. It applies to server-side requests from features such as workflow request nodes, custom requests, and AI services.
+
+When this variable is not configured, NocoBase still allows `http` / `https` requests to keep existing deployments compatible. However, if the target is a loopback, private, link-local, or metadata address, or if a domain resolves to one of these addresses, the server logs a warning. Future versions may gradually tighten the default behavior. If your deployment needs to access internal services, configure an explicit whitelist in advance.
+
+When this variable is configured, the initial request and every redirect destination must match a whitelist entry. If a redirect points to a non-matching host, NocoBase stops before sending the redirected request.
+
+Supported entries include:
+
+- Exact IPv4 address, such as `192.168.1.10`
+- IPv4 CIDR range, such as `10.0.0.0/8`
+- Exact IPv6 address, such as `::1`
+- IPv6 CIDR range, such as `fc00::/7`
+- Exact domain, such as `api.example.com`
+- Single-level wildcard subdomain, such as `*.example.com`
+
+Use `,` to separate multiple targets:
+
+```bash
+SERVER_REQUEST_WHITELIST=api.example.com,*.trusted.com,10.0.0.0/8,127.0.0.1
+```
+
+:::warning Note
+
+If a domain is configured in the whitelist, the whitelist check uses the host in the request URL. In other words, after `internal.example.com` is configured, it is treated as explicitly allowed even if the domain resolves to `127.0.0.1` or a private address.
+
+:::
+
 ## CLUSTER_MODE
 
 > `v1.6.0+`
@@ -78,7 +107,7 @@ For example, to add the `hello` plugin to the `my-nocobase-app` project, the ful
 PLUGIN_PACKAGE_PREFIX can be configured as:
 
 ```bash
-PLUGIN_PACKAGE_PREFIX=@nocobase/plugin-,@nocobase-preset-,@my-nocobase-app/plugin-
+PLUGIN_PACKAGE_PREFIX=@nocobase/plugin-,@nocobase/preset-,@my-nocobase-app/plugin-
 ```
 
 Then the mapping between plugin names and package names is as follows:
@@ -285,4 +314,4 @@ Enabled trace data processors, defaults to `console`. Other values should refer
 
 ```bash
 TELEMETRY_TRACE_PROCESSOR=console
-```
+```

package/dist/ai/docs/nocobase/api/cli/app/restart.md

@@ -35,6 +35,10 @@ If you explicitly pass `--env` and it differs from the current env, the CLI asks
 
 By default, when applicable, the CLI first runs `nb license plugins sync --skip-if-no-license` to synchronize the commercial plugins allowed by the current license. Then local envs automatically complete any required install or upgrade preparation before starting again, and Docker envs complete that step before recreating the container. Whenever the CLI needs to wait for readiness, it checks `__health_check`: it prints one waiting line first, then one progress line every 10 seconds until the app becomes available or times out.
 
+## Hook Scripts
+
+If the current env saved a hook with `nb init --hook-script`, `nb app restart` runs `afterAppStart(context)` once after the app restarts and passes `__health_check`. It uses `context.phase = 'app-start'` and `context.command = 'app:restart'`.
+
 ## Related Commands
 
 - [`nb app start`](./start.md)

package/dist/ai/docs/nocobase/api/cli/app/start.md

@@ -34,6 +34,13 @@ nb app start --env local-docker
 If you explicitly pass `--env` and it differs from the current env, the CLI asks for confirmation first. In non-interactive terminals or AI agent sessions, add `--yes` yourself or run `nb env use <name>` first and try again.
 
 By default, when applicable, the CLI first runs `nb license plugins sync --skip-if-no-license` to synchronize the commercial plugins allowed by the current license. Then local envs automatically complete any required install or upgrade preparation before starting, and Docker envs recreate the app container from saved env config. Whenever the CLI needs to wait for readiness, it checks `__health_check`: it prints one waiting line first, then one progress line every 10 seconds until the app becomes available or times out.
+
+## Hook Scripts
+
+If the current env saved a hook with `nb init --hook-script`, `nb app start` runs `afterAppStart(context)` after the app actually starts and passes `__health_check`. Installed envs use `context.phase = 'app-start'` and `context.command = 'app:start'`. If the app is already running, this command does not run the hook.
+
+For prepared envs created with `--prepare-only`, the first `nb app start` runs `beforeAppInstall(context)`, completes the first install and startup, then runs `afterAppStart(context)`. Both hooks receive `context.phase = 'init'` and `context.command = 'app:start'`.
+
 ## Related Commands
 
 - [`nb app stop`](./stop.md)

package/dist/ai/docs/nocobase/api/cli/app/upgrade.md

@@ -58,6 +58,12 @@ Step 4 automatically completes any required upgrade preparation for the current
 
 If the final `nb env update` step fails, the upgrade still counts as successful. The CLI prints a warning and tells you to run `nb env update <envName>` manually afterward.
 
+## Hook Scripts
+
+If the current env saved a hook with `nb init --hook-script`, `nb app upgrade` passes the upgrade lifecycle to the hook. For npm/Git source, source refresh runs `beforeDependencyInstall(context)` before dependency installation with `context.phase = 'upgrade'` and `context.command = 'app:upgrade'`.
+
+The app upgrade startup step then runs `beforeAppInstall(context)`, and after the app starts and passes `__health_check`, it runs `afterAppStart(context)`. Both hooks also use `context.phase = 'upgrade'` and `context.command = 'app:upgrade'`. Docker source does not run `beforeDependencyInstall`, but it does run the app-level hooks.
+
 ## Related Commands
 
 - [`nb source download`](../source/download.md)

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

@@ -1,7 +1,7 @@
 ---
-title: "nb config delete"
-description: "nb config delete command reference: delete an explicitly set CLI configuration item."
-keywords: "nb config delete,NocoBase CLI,delete configuration"
+title: 'nb config delete'
+description: 'nb config delete command reference: delete an explicitly set CLI configuration item.'
+keywords: 'nb config delete,NocoBase CLI,delete configuration'
 ---
 
 # nb config delete
@@ -16,9 +16,9 @@ nb config delete <key>
 
 ## Parameters
 
-| Parameter | Type | Description |
-| --- | --- | --- |
-| `<key>` | string | Configuration item name. See [`nb config`](./index.md) for supported values |
+| Parameter | Type   | Description                                                                 |
+| --------- | ------ | --------------------------------------------------------------------------- |
+| `<key>`   | string | Configuration item name. See [`nb config`](./index.md) for supported values |
 
 ## Examples
 
@@ -27,12 +27,15 @@ nb config delete locale
 nb config delete update.policy
 nb config delete docker.network
 nb config delete docker.container-prefix
+nb config delete nb-image-registry
+nb config delete nb-image-variant
 nb config delete proxy.nb-cli-root
 nb config delete proxy.upstream-host
 nb config delete proxy.nginx-driver
 nb config delete proxy.caddy-driver
 nb config delete bin.nginx
 nb config delete bin.git
+nb config delete bin.pnpm
 ```
 
 ## Related commands

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

@@ -1,7 +1,7 @@
 ---
-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"
+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
@@ -16,9 +16,9 @@ nb config get <key>
 
 ## Parameters
 
-| Parameter | Type | Description |
-| --- | --- | --- |
-| `<key>` | string | Configuration item name. See [`nb config`](./index.md) for supported values |
+| Parameter | Type   | Description                                                                 |
+| --------- | ------ | --------------------------------------------------------------------------- |
+| `<key>`   | string | Configuration item name. See [`nb config`](./index.md) for supported values |
 
 ## Examples
 
@@ -28,6 +28,8 @@ 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 nb-image-registry
+nb config get nb-image-variant
 nb config get proxy.nb-cli-root
 nb config get proxy.upstream-host
 nb config get proxy.nginx-driver

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

@@ -1,7 +1,7 @@
 ---
-title: "nb config"
-description: "nb config command reference: manage default configuration items for the NocoBase CLI."
-keywords: "nb config,NocoBase CLI,configuration,default configuration"
+title: 'nb config'
+description: 'nb config command reference: manage default configuration items for the NocoBase CLI.'
+keywords: 'nb config,NocoBase CLI,configuration,default configuration'
 ---
 
 # nb config
@@ -10,7 +10,8 @@ Manage default CLI configuration values. The currently supported keys are mainly
 
 - 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`
+- Official NocoBase images: `nb-image-registry`, `nb-image-variant`
+- External executables: `bin.docker`, `bin.caddy`, `bin.git`, `bin.nginx`, `bin.pnpm`, `bin.yarn`
 - Proxy generation: `proxy.nb-cli-root`, `proxy.upstream-host`, `proxy.nginx-driver`, `proxy.caddy-driver`
 
 Most projects only need a few of these keys. In practice, the most common ones are:
@@ -18,27 +19,32 @@ Most projects only need a few of these keys. In practice, the most common ones a
 - `update.policy`
 - `docker.network`
 - `docker.container-prefix`
+- `nb-image-registry`
+- `nb-image-variant`
 - `bin.nginx` or `bin.caddy`
 - `proxy.nginx-driver` or `proxy.caddy-driver`
 
 ## Common configuration keys
 
-| Key | Default | Description |
-| --- | --- | --- |
-| `locale` | resolved by the current CLI rules | Override the language used by the CLI |
-| `update.policy` | `prompt` | Startup update policy: `prompt`, `auto`, or `off` |
-| `license.pkg-url` | `https://pkg.nocobase.com/` | Override the download URL for commercial extension packages |
-| `docker.network` | `nocobase` | Default network for CLI-managed Docker apps |
-| `docker.container-prefix` | `nb` | Default prefix for CLI-managed Docker containers |
-| `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 | Override the root path visible to the generated proxy config when the proxy process and CLI do not see the same filesystem root |
-| `proxy.upstream-host` | `127.0.0.1` | Override the host used when the proxy forwards traffic back to the NocoBase app |
-| `proxy.nginx-driver` | `local` | Default runtime driver used by `nb proxy nginx` |
-| `proxy.caddy-driver` | `local` | Default runtime driver used by `nb proxy caddy` |
+| Key                       | Default                                             | Description                                                                                                                     |
+| ------------------------- | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| `locale`                  | resolved by the current CLI rules                   | Override the language used by the CLI                                                                                           |
+| `update.policy`           | `prompt`                                            | Startup update policy: `prompt`, `auto`, or `off`                                                                               |
+| `license.pkg-url`         | `https://pkg.nocobase.com/`                         | Override the download URL for commercial extension packages                                                                     |
+| `docker.network`          | `nocobase`                                          | Default network for CLI-managed Docker apps                                                                                     |
+| `docker.container-prefix` | `nb`                                                | Default prefix for CLI-managed Docker containers                                                                                |
+| `nb-image-registry`       | `dockerhub`                                         | Default registry family for official NocoBase images: `dockerhub` or `aliyun`                                                   |
+| `nb-image-variant`        | `full`                                              | Default tag variant for official NocoBase app images: `standard`, `no-nginx`, `full`, or `full-no-nginx`                        |
+| `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.pnpm`                | `pnpm`                                              | Override the pnpm executable path                                                                                               |
+| `bin.yarn`                | `yarn`                                              | Override the Yarn executable path                                                                                               |
+| `proxy.nb-cli-root`       | CLI root, usually the current user's home directory | Override the root path visible to the generated proxy config when the proxy process and CLI do not see the same filesystem root |
+| `proxy.upstream-host`     | `127.0.0.1`                                         | Override the host used when the proxy forwards traffic back to the NocoBase app                                                 |
+| `proxy.nginx-driver`      | `local`                                             | Default runtime driver used by `nb proxy nginx`                                                                                 |
+| `proxy.caddy-driver`      | `local`                                             | Default runtime driver used by `nb proxy caddy`                                                                                 |
 
 ## Usage
 
@@ -48,12 +54,12 @@ nb config <command>
 
 ## Subcommands
 
-| Command | Description |
-| --- | --- |
-| [`nb config get`](./get.md) | Read the effective value of a configuration key |
-| [`nb config set`](./set.md) | Set a configuration key |
-| [`nb config delete`](./delete.md) | Delete an explicitly set configuration key |
-| [`nb config list`](./list.md) | List the configuration keys that are currently set explicitly |
+| Command                           | Description                                                   |
+| --------------------------------- | ------------------------------------------------------------- |
+| [`nb config get`](./get.md)       | Read the effective value of a configuration key               |
+| [`nb config set`](./set.md)       | Set a configuration key                                       |
+| [`nb config delete`](./delete.md) | Delete an explicitly set configuration key                    |
+| [`nb config list`](./list.md)     | List the configuration keys that are currently set explicitly |
 
 ## Examples
 
@@ -68,14 +74,22 @@ nb config set proxy.nginx-driver docker
 nb config set proxy.caddy-driver local
 nb config get docker.network
 nb config set docker.network nocobase
+nb config get nb-image-registry
+nb config set nb-image-registry aliyun
+nb config set nb-image-variant full-no-nginx
 nb config set bin.nginx /usr/sbin/nginx
 nb config set bin.git /usr/bin/git
+nb config set bin.pnpm /usr/local/bin/pnpm
 nb config delete docker.container-prefix
 ```
 
 ## Notes
 
 - `bin.nginx` and `bin.caddy` only affect the `local` driver for `nb proxy nginx` and `nb proxy caddy`
+- `bin.pnpm` is used when commands need to run pnpm directly, such as updating a pnpm-managed global CLI install with `nb self update`
+- `nb-image-registry` only affects official NocoBase image defaults used by the CLI. `dockerhub` maps app images to `nocobase/nocobase`, while `aliyun` maps them to `registry.cn-shanghai.aliyuncs.com/nocobase/nocobase`
+- `nb-image-variant` only affects official NocoBase app image tags. With version tag `1.7.14`, the CLI resolves `standard` to `1.7.14`, `no-nginx` to `1.7.14-no-nginx`, `full` to `1.7.14-full`, and `full-no-nginx` to `1.7.14-full-no-nginx`
+- When `nb-image-registry=aliyun`, the CLI also switches the default built-in database images to the official Aliyun mirrors for PostgreSQL, MySQL, MariaDB, and Kingbase
 - `proxy.nginx-driver` and `proxy.caddy-driver` store the default driver used by each provider
 - `proxy.nb-cli-root` and `proxy.upstream-host` are advanced proxy overrides. Most CLI-managed `local` or `docker` envs can use the defaults directly
 - If you only want to switch the active proxy driver, using `nb proxy nginx use` or `nb proxy caddy use` is usually clearer than setting the config key manually

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

@@ -1,7 +1,7 @@
 ---
-title: "nb config set"
-description: "nb config set command reference: set a CLI configuration item."
-keywords: "nb config set,NocoBase CLI,set 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
@@ -16,10 +16,10 @@ nb config set <key> <value>
 
 ## Parameters
 
-| Parameter | Type | Description |
-| --- | --- | --- |
-| `<key>` | string | Configuration item name. See [`nb config`](./index.md) for supported values |
-| `<value>` | string | Configuration value, cannot 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
 
@@ -29,10 +29,15 @@ nb config set update.policy auto
 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 nb-image-registry dockerhub
+nb config set nb-image-registry aliyun
+nb config set nb-image-variant full
+nb config set nb-image-variant full-no-nginx
 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 bin.pnpm /usr/local/bin/pnpm
 nb config set proxy.nb-cli-root /workspace
 nb config set proxy.upstream-host host.docker.internal
 nb config set proxy.nginx-driver docker
@@ -42,7 +47,9 @@ nb config set bin.yarn yarn
 
 ## Notes
 
-`update.policy` supports `prompt`, `auto`, and `off`, and the default value is `prompt`.
+- `update.policy` supports `prompt`, `auto`, and `off`, and the default value is `prompt`
+- `nb-image-registry` supports `dockerhub` and `aliyun`, and the default value is `dockerhub`
+- `nb-image-variant` supports `standard`, `no-nginx`, `full`, and `full-no-nginx`, and the default value is `full`
 
 ## Related commands
 

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

@@ -1,17 +1,19 @@
 ---
 title: "nb env auth"
-description: "nb env auth command reference: run OAuth login for a saved NocoBase env."
-keywords: "nb env auth,NocoBase CLI,OAuth,login,authentication"
+description: "nb env auth command reference: authenticate a saved NocoBase env with basic, token, or OAuth authentication."
+keywords: "nb env auth,NocoBase CLI,basic,token,OAuth,login,authentication"
 ---
 
 # nb env auth
 
-Run OAuth login for a selected env. When the env name is omitted, the current env is used.
+Authenticate a saved NocoBase env again, or update the authentication information saved for it. When the env name is omitted, the current env is used.
+
+`nb env auth` supports three authentication methods: `basic`, `token`, and `oauth`. If `--auth-type` is omitted, the CLI first infers the method from the authentication options you pass. If it still cannot infer the method, it uses the authentication method already saved in the env.
 
 ## Usage
 
 ```bash
-nb env auth [name]
+nb env auth [name] [flags]
 ```
 
 ## Parameters
@@ -19,19 +21,65 @@ nb env auth [name]
 | Parameter | Type | Description |
 | --- | --- | --- |
 | `[name]` | string | Configured environment name to sign in to; uses the current env if omitted |
+| `--auth-type`, `-a` | string | Authentication method: `basic`, `token`, or `oauth` |
+| `--access-token`, `-t` | string | API key or access token used with `token` authentication |
+| `--username` | string | Username used with `basic` authentication; prompted in TTY when omitted |
+| `--password` | string | Password used with `basic` authentication; prompted in TTY when omitted |
+
+## Compatibility options
+
+| Option | Type | Description |
+| --- | --- | --- |
+| `--env`, `-e` | string | Environment name, equivalent to `[name]`. This hidden option is kept for compatibility with other commands; normally the positional argument is enough |
 
 ## Notes
 
-Internally, this command uses the PKCE flow: start a local callback server, open the browser for authorization, exchange the token, and save it to the config file.
+The authentication methods work as follows:
+
+- `basic`: sign in to NocoBase with a username and password, then save the returned access token and username
+- `token`: save the API key or access token passed through `--access-token`
+- `oauth`: start the browser authentication flow, then save the access token after authentication finishes
+
+In an interactive terminal, the CLI prompts for `--auth-type`, `--username`, `--password`, or `--access-token` when needed. In non-interactive mode, `basic` authentication requires both `--username` and `--password`.
+
+`oauth` authentication first tries Device Authorization Grant. When the OAuth server supports this flow, the command prints a verification URL and user code, then polls until the browser approval is complete. This works on remote or headless servers because it does not require a local callback listener.
+
+If the OAuth server does not expose a device authorization endpoint, the command falls back to the PKCE loopback flow: start a local callback server, open the browser for authorization, exchange the token, and save it to the config file.
+
+After authentication succeeds, the CLI automatically runs `nb env update <name>` to re-sync the env state.
+
+## Limits
+
+- `[name]` and `--env` cannot provide different environment names at the same time
+- `--access-token` cannot be used with `--username` or `--password`
+- `--auth-type oauth` cannot be used with `--access-token`, `--username`, or `--password`
+- `--auth-type token` cannot be used with `--username` or `--password`
+- `--auth-type basic` cannot be used with `--access-token`
+- `--access-token`, `--username`, and `--password` cannot be empty after they are provided
 
 ## Examples
 
 ```bash
+# Authenticate the current env with the saved authentication method
 nb env auth
+
+# Authenticate a specific env
 nb env auth prod
+
+# Use OAuth browser login
+nb env auth prod --auth-type oauth
+
+# Sign in with username and password
+nb env auth prod --auth-type basic --username admin --password secret
+
+# Save an API key or access token
+nb env auth prod --auth-type token --access-token <api-key>
 ```
 
+For device authorization, follow the URL printed by the command and enter the displayed code in the browser.
+
 ## Related Commands
 
 - [`nb env add`](./add.md)
+- [`nb env info`](./info.md)
 - [`nb env update`](./update.md)

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

@@ -1,7 +1,7 @@
 ---
 title: 'NocoBase CLI'
-description: 'NocoBase CLI (`nb` command) reference: initialization, backup and restore, configuration, environment management, app runtime, source code, database, plugins, commercial license, API, CLI self-update, and Skills management.'
-keywords: 'NocoBase CLI,nb,command line,command reference,backup,restore,environment management,plugin management,commercial license,API'
+description: 'NocoBase CLI (`nb` command) reference: initialization, backup and restore, configuration, environment management, app runtime, portal, source code, database, plugins, commercial license, API, CLI self-update, and Skills management.'
+keywords: 'NocoBase CLI,nb,command line,command reference,backup,restore,environment management,Portal,plugin management,commercial license,API'
 ---
 
 # NocoBase CLI
@@ -39,6 +39,7 @@ The following command groups are shown in `nb --help`:
 | [`nb env`](./env/index.md)           | Manage NocoBase project environments, the current env, status, details, and runtime commands. |
 | [`nb license`](./license/index.md)   | Manage commercial licenses and licensed plugins.                                              |
 | [`nb plugin`](./plugin/index.md)     | Manage plugins in the selected NocoBase env.                                                  |
+| [`nb portal`](./portal/index.md)     | Manage portals: configure, create, develop, sync source, deploy, and destroy.                       |
 | [`nb scaffold`](./scaffold/index.md) | Generate scaffolding for NocoBase plugin development.                                         |
 | [`nb self`](./self/index.md)         | Check or update NocoBase CLI itself.                                                          |
 | [`nb session`](./session/index.md)   | Configure `NB_SESSION_ID` so the current env is isolated by shell or agent runtime.           |
@@ -70,6 +71,8 @@ nb backup --help
 nb config --help
 nb api resource --help
 nb license --help
+nb portal --help
+nb portal config --help
 ```
 
 ## Examples
@@ -127,6 +130,15 @@ nb license status -e app1
 nb license plugins list -e app1
 ```
 
+Create and develop a portal:
+
+```bash
+nb portal create customer -e app1 --yes
+nb portal config customer -e app1 --yes --source-storage git --git-repo git@github.com:nocobase/customer-portal.git
+nb portal dev customer -e app1 --yes
+nb portal deploy customer -e app1 --yes
+```
+
 Create and download a backup:
 
 ```bash

package/dist/ai/docs/nocobase/api/cli/init.md

@@ -42,7 +42,7 @@ nb init --env app1 --resume
 
 `--prepare-only` is intended for flows where the env should be prepared first, then the license is activated, and only after that the app is installed and started.
 
-If you want to save the env config, prepare the source files or image, and get the database ready first, but delay the actual app installation and first startup, you can use:
+If you want to save the env config and prepare the database first, while delaying dependency download, app installation, and first startup, you can use:
 
 ```bash
 nb init --env app1 --prepare-only
@@ -67,6 +67,7 @@ By default, the CLI organizes local files under `app-path` using the following c
 
 ```text
 <app-path>/
+├── .nb/      # CLI metadata for this env, such as hooks.mjs
 ├── source/   # Default directory for app source code or downloaded content
 ├── storage/  # Runtime data directory
 └── .env      # Optional app environment variable file
@@ -74,7 +75,8 @@ By default, the CLI organizes local files under `app-path` using the following c
 
 Typically:
 
-- `source/` mainly corresponds to the local app directory for npm / Git envs. For Docker envs, the CLI also keeps this default path derivation, but most of the time you do not need to care about it manually
+- `.nb/` stores CLI-managed metadata. A script passed with `--hook-script` is copied to `<app-path>/.nb/hooks.mjs`, so later `nb app upgrade` and local source restore can reuse it
+- `source/` mainly corresponds to the local app directory for npm / Git envs. For Docker envs, the CLI also keeps this default path derivation, but most of the time you do not need to care about it manually. Pay special attention during upgrades: the `source/` directory will be deleted and downloaded again, so do not put files you need to keep here
 - `storage/` is used for runtime data, such as built-in database data, plugins, logs, and more
 - `.env` is an optional app environment variable file. You only need to add it in `<app-path>/.env` when you want to customize environment variables; if this file exists, Docker, npm, and Git install sources will all read it by default
 
@@ -101,7 +103,7 @@ If you are following the local UI wizard step by step, you can first use the tab
 | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `Getting started`         | `--env`、`--yes`、`--ui`、`--locale`、`--verbose`、`--skip-skills`、`--resume`                                                                                                                                    |
 | `App environment`         | `--lang`、`--app-path`、`--app-port`、`--force`                                                                                                                                                                   |
-| `App source and version`  | `--source`、`--version`、`--skip-download`、`--git-url`、`--docker-registry`、`--docker-platform`、`--npm-registry`、`--replace`、`--dev-dependencies`、`--output-dir`、`--docker-save`、`--build`、`--build-dts` |
+| `App source and version`  | `--source`、`--version`、`--skip-download`、`--git-url`、`--docker-registry`、`--docker-platform`、`--npm-registry`、`--replace`、`--dev-dependencies`、`--output-dir`、`--docker-save`、`--build`、`--build-dts`、`--hook-script` |
 | `Configure the database`  | `--builtin-db`、`--db-dialect`、`--builtin-db-image`、`--db-host`、`--db-port`、`--db-database`、`--db-user`、`--db-password`、`--db-schema`、`--db-table-prefix`、`--db-underscored`                             |
 | `Create an admin account` | `--root-username`、`--root-email`、`--root-password`、`--root-nickname`                                                                                                                                           |
 | `Remote connection`       | `--api-base-url`、`--auth-type`、`--access-token`、`--username`、`--password`、`--skip-auth`                                                                                                                      |
@@ -121,7 +123,7 @@ The “Default” below means the value or behavior that `nb init` usually uses
 | `--ui`          | boolean | `false`                                                                      | Open the local browser wizard; cannot be used with `--yes` or `--resume`               |
 | `--verbose`     | boolean | `false`                                                                      | Show detailed command output                                                           |
 | `--skip-skills` | boolean | `false`                                                                      | Skip syncing NocoBase AI coding skills                                                 |
-| `--ui-host`     | string  | `127.0.0.1`                                                                  | Bind address for the `--ui` local service                                              |
+| `--ui-host`     | string  | `127.0.0.1`                                                                  | Browser-accessible host shown in the `--ui` wizard URL; the local service always listens on `0.0.0.0` |
 | `--ui-port`     | integer | `0`                                                                          | Port for the `--ui` local service; `0` means automatic assignment                      |
 | `--locale`      | string  | Follows `NB_LOCALE`, CLI config, or system locale; final fallback is `en-US` | Language for CLI prompts and the local setup UI: `en-US` or `zh-CN`                    |
 | `--resume`      | boolean | `false`                                                                      | Continue the last unfinished initialization and reuse the saved workspace env config   |
@@ -184,6 +186,7 @@ The “Default” below means the value or behavior that `nb init` usually uses
 | `--npm-registry`                                     | string  | Empty                                                                                            | Registry used for npm/Git download and dependency installation                           |
 | `--build` / `--no-build`                             | boolean | `true`                                                                                           | Whether to build after installing npm/Git dependencies                                   |
 | `--build-dts`                                        | boolean | `false`                                                                                          | Whether to generate TypeScript declaration files during npm/Git builds                   |
+| `--hook-script`                                      | string  | None                                                                                             | Copy the specified hook module to `<app-path>/.nb/hooks.mjs` and save it in the env config; supports the `beforeDependencyInstall`, `beforeAppInstall`, and `afterAppStart` lifecycle hooks |
 
 ## Examples
 
@@ -233,6 +236,40 @@ nb init --env app1 --yes --source git --version latest \
   --git-url https://gitee.com/nocobase/nocobase.git
 ```
 
+### Extend the install flow with a hook script
+
+If you need to prepare extra content during installation, pass a local ESM module with `--hook-script`:
+
+```bash
+nb init --env app1 --yes --source git --hook-script ./hooks.mjs
+```
+
+The CLI copies this file to `<app-path>/.nb/hooks.mjs` and saves `hookScript: ".nb/hooks.mjs"` in the env config. Later `nb app start`, `nb app restart`, and `nb app upgrade` reuse it from that location.
+
+The hook file must default-export an object. Implement only the methods you need:
+
+```js
+export default {
+  beforeDependencyInstall: async (context) => {
+    // Runs after git clone / npm scaffold and before yarn install.
+  },
+  beforeAppInstall: async (context) => {
+    // Runs before the app-level install or upgrade command.
+  },
+  afterAppStart: async (context) => {
+    // Runs after the app actually starts and passes the health check.
+  },
+};
+```
+
+- `beforeDependencyInstall` only applies to npm/Git source and runs right before the real `yarn install`; Docker source does not run it
+- `beforeAppInstall` runs before app-level install or upgrade commands, and applies to npm/Git/Docker source
+- `afterAppStart` runs after the app actually starts and passes `__health_check`; `nb app start`, `nb app restart`, and `nb app upgrade` may all trigger it
+
+`--prepare-only` only saves the env config and copies the hook file. It does not execute hooks. When you later run `nb app start` for the first time, the CLI runs the first-install hooks with `context.phase` set to `init` and `context.command` set to `app:start`.
+
+`context` includes lifecycle information such as `phase`, `command`, `source`, `version`, `appPath`, `sourcePath`, `storagePath`, `hookScript`, and `envConfig`. If a hook throws, the current CLI command fails. Because `afterAppStart` can run repeatedly during start, restart, and upgrade flows, keep it idempotent.
+
 ### Quick install and use basic authentication
 
 If you want to quickly install a local app in non-interactive mode and directly save `basic` authentication after installation, you can also write it like this. This way, you do not need to open a browser to complete OAuth.

package/dist/ai/docs/nocobase/api/cli/plugin/import.md

@@ -71,4 +71,4 @@ You do not need to extract anything into `storage/plugins` by hand. `nb plugin i
 
 - [`nb app restart`](../app/restart.md)
 - [`nb plugin enable`](./enable.md)
-- [`Install and upgrade third-party plugins`](../../../quickstart/plugins/third-party.md)
+- [`Install and upgrade third-party plugins`](../../../nocobase-cli/plugins/third-party.md)

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

@@ -0,0 +1,44 @@
+---
+title: "nb portal config"
+description: "nb portal config command reference: update source storage and Git source configuration for a portal."
+keywords: "nb portal config,NocoBase CLI,Portal"
+---
+
+# nb portal config
+
+Update the local portal source configuration and sync it to the remote portal record when possible
+
+## Usage
+
+```bash
+nb portal config <portal> [flags]
+```
+
+## Flag
+
+| Flag | Type | Description |
+| --- | --- | --- |
+| `<portal>` | string | Portal name or slug |
+| `--env`, `-e` | string | CLI env name. If omitted, the current env is used. |
+| `--yes`, `-y` | boolean | Skip cross-env confirmation. |
+| `--source-storage` | `nocobase` \| `git` | Where portal source code is managed. |
+| `--git-repo` | string | Git repository URL used with `--source-storage=git`. |
+| `--git-branch` | string | Git branch used with `--source-storage=git`. |
+| `--git-path` | string | Directory inside the Git repository; defaults to the repository root (`.`). |
+
+## Examples
+
+```bash
+nb portal config customer --source-storage nocobase
+nb portal config customer --source-storage git --git-repo git@github.com:nocobase/customer-portal.git
+nb portal config customer --git-branch main --git-path portals/customer
+```
+
+## Notes
+
+Pass at least one configuration flag. The local workspace must already exist; use `nb portal create` or `nb portal pull` first. If the remote portal record exists, the configuration is synced to it; otherwise only `portal.config.json` is updated locally.
+
+## Related Commands
+
+- [`nb portal`](./index.md)
+- [`nb env`](../env/index.md)