@nocobase/plugin-ai 2.1.19 → 2.1.21

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,6 +27,8 @@ 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

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,6 +10,7 @@ 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`
+- 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`
 
@@ -18,28 +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.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` |
+| 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
 
@@ -49,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
 
@@ -69,6 +74,9 @@ 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
@@ -79,6 +87,9 @@ nb config delete docker.container-prefix
 
 - `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,6 +29,10 @@ 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
@@ -43,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/file-manager/storage/local.md

@@ -9,6 +9,8 @@ Local Storage does not support private access. After a file is uploaded, NocoBas
 
 If you need to store contracts, identity documents, internal materials, or other files that should not be public, use [S3 Pro](./s3-pro). If historical files already exist, see [Migrate to S3 Pro](./migrate-to-s3-pro.md).
 
+If you are not using Docker or the official nginx configuration and access local uploaded files through a custom proxy, make sure the `/storage/uploads/` path sets `X-Content-Type-Options: nosniff` and returns active content files such as `html`, `svg`, `xhtml`, and `pdf` as attachments. For details, see [Security guide: File storage](../../security/guide.md#file-storage).
+
 :::
 
 ## Configuration Parameters
@@ -26,4 +28,4 @@ This section only introduces parameters specific to the local storage engine. Fo
 Represents both the relative path for file storage on the server and the URL access path. For example, "`user/avatar`" (without leading or trailing slashes) represents:
 
 1. The relative path on the server where uploaded files are stored: `/path/to/nocobase-app/storage/uploads/user/avatar`.
-2. The URL prefix for accessing the files: `http://localhost:13000/storage/uploads/user/avatar`.
+2. The URL prefix for accessing the files: `http://localhost:13000/storage/uploads/user/avatar`.

package/dist/ai/docs/nocobase/get-started/installation/docker-caddy.mdx

@@ -0,0 +1,175 @@
+---
+title: "Docker Installation (External Caddy)"
+description: "Install NocoBase with Docker and use an external Caddy container as the entry point."
+keywords: "Docker,NocoBase,Caddy,installation,reverse proxy"
+---
+
+# Docker Installation (External Caddy)
+
+In this setup, the NocoBase app container and the Caddy container run separately. You can start with [Docker Installation (Built-in Nginx)](./docker.mdx) and then switch the entry service to an external Caddy container.
+
+## When to use this setup
+
+- You want to deploy NocoBase and the web server separately
+- You want to simplify reverse proxy and HTTPS configuration with Caddy
+- You want to expose only the proxy container to the public network
+
+## docker-compose.yml example
+
+If you need the `full` image, replace `latest-no-nginx` with `latest-full-no-nginx`.
+
+The `13000:80` mapping is only for convenient local testing, so it does not occupy the standard host ports directly. In production, you usually do not keep using `13000:80`; instead, let the external Caddy container map directly to the host `80` and `443` ports.
+```yml
+networks:
+  nocobase:
+    driver: bridge
+
+services:
+  app:
+    image: nocobase/nocobase:latest-no-nginx
+    restart: always
+    depends_on:
+      - postgres
+    networks:
+      - nocobase
+    environment:
+      - APP_KEY=your-secret-key
+      - DB_DIALECT=postgres
+      - DB_HOST=postgres
+      - DB_PORT=5432
+      - DB_DATABASE=nocobase
+      - DB_USER=nocobase
+      - DB_PASSWORD=nocobase
+      - TZ=Etc/UTC
+      - NOCOBASE_EXTRACT_CLIENT_ASSETS=true
+      - NOCOBASE_PROXY_PROVIDER=caddy
+      - NOCOBASE_PROXY_STORAGE_PATH=/app/nocobase/storage
+      - NOCOBASE_PROXY_UPSTREAM_HOST=app
+    volumes:
+      - ./storage:/app/nocobase/storage
+
+  caddy:
+    image: caddy:2
+    restart: always
+    depends_on:
+      - app
+    networks:
+      - nocobase
+    volumes:
+      - ./storage:/app/nocobase/storage
+    command: >
+      /bin/sh -c '
+        while [ ! -f /app/nocobase/storage/.nocobase/proxy/caddy/nocobase.caddy ]; do
+          echo "waiting for nocobase.caddy..."
+          sleep 1
+        done
+        ln -sf /app/nocobase/storage/.nocobase/proxy/caddy/nocobase.caddy /etc/caddy/Caddyfile
+        caddy run --config /etc/caddy/Caddyfile --adapter caddyfile
+      '
+    ports:
+      # This is only a local testing example.
+      - "13000:80"
+      # In production, usually change it to:
+      # - "80:80"
+      # - "443:443"
+
+  postgres:
+    image: postgres:16
+    restart: always
+    command: postgres -c wal_level=logical
+    environment:
+      POSTGRES_USER: nocobase
+      POSTGRES_DB: nocobase
+      POSTGRES_PASSWORD: nocobase
+    volumes:
+      - ./storage/db/postgres:/var/lib/postgresql/data
+    networks:
+      - nocobase
+```
+
+## Key points
+
+- `NOCOBASE_EXTRACT_CLIENT_ASSETS=true` extracts client assets and generates proxy config
+- `NOCOBASE_PROXY_PROVIDER=caddy` tells the app to generate Caddy config
+- `NOCOBASE_PROXY_UPSTREAM_HOST=app` lets the Caddy container reach the `app` service through the Compose network
+- `./storage` must be mounted into both the `app` and `caddy` containers so they can share proxy config, static assets, and uploaded files
+- The `caddy` container should wait until `nocobase.caddy` is generated, then link it to `/etc/caddy/Caddyfile` with `ln -sf`
+- Expose only the Caddy container port to the host. For testing, you can start with `13000:80`; in production, you usually expose the host `80` and `443` ports directly, while the `app` service does not need to expose its port to the host
+
+## If you use a local host Caddy
+
+If your Caddy is installed directly on the host instead of running in a Docker container, it is better to use a separate `docker-compose.yml`. In this setup, the `app` service must expose a host port directly, and the proxy-related environment variables should use host-side values.
+
+You can use a `docker-compose.yml` like this:
+
+```yml
+networks:
+  nocobase:
+    driver: bridge
+
+services:
+  app:
+    image: nocobase/nocobase:latest-no-nginx
+    restart: always
+    depends_on:
+      - postgres
+    networks:
+      - nocobase
+    environment:
+      - APP_KEY=your-secret-key
+      - DB_DIALECT=postgres
+      - DB_HOST=postgres
+      - DB_PORT=5432
+      - DB_DATABASE=nocobase
+      - DB_USER=nocobase
+      - DB_PASSWORD=nocobase
+      - TZ=Etc/UTC
+      - NOCOBASE_EXTRACT_CLIENT_ASSETS=true
+      - NOCOBASE_PROXY_PROVIDER=caddy
+      - NOCOBASE_PROXY_STORAGE_PATH=/path/to/your-project/storage
+      - NOCOBASE_PROXY_UPSTREAM_HOST=127.0.0.1
+      - NOCOBASE_PROXY_UPSTREAM_PORT=13000
+    volumes:
+      - ./storage:/app/nocobase/storage
+    ports:
+      - "13000:13000"
+
+  postgres:
+    image: postgres:16
+    restart: always
+    command: postgres -c wal_level=logical
+    environment:
+      POSTGRES_USER: nocobase
+      POSTGRES_DB: nocobase
+      POSTGRES_PASSWORD: nocobase
+    volumes:
+      - ./storage/db/postgres:/var/lib/postgresql/data
+    networks:
+      - nocobase
+```
+
+In this variant:
+
+- `NOCOBASE_PROXY_STORAGE_PATH` should be the absolute host path of your `storage` directory
+- `NOCOBASE_PROXY_UPSTREAM_HOST` should be `127.0.0.1`
+- The `app` service must keep `ports`, so the local Caddy can reach the app through `127.0.0.1:13000`
+
+After the `app` container starts, wait for the config file to be generated, then link it into the local Caddy config path:
+
+```bash
+while [ ! -f ./storage/.nocobase/proxy/caddy/nocobase.caddy ]; do
+  echo "waiting for nocobase.caddy..."
+  sleep 1
+done
+
+sudo ln -sf "$(pwd)/storage/.nocobase/proxy/caddy/nocobase.caddy" /etc/caddy/Caddyfile
+sudo caddy validate --config /etc/caddy/Caddyfile --adapter caddyfile
+sudo systemctl reload caddy
+```
+
+If your host Caddy does not use `/etc/caddy/Caddyfile`, replace the link target with your own config path. Usually it is safer to keep `nocobase.caddy` as the main entry file instead of copying its content manually.
+
+## Related links
+
+- [Docker Installation (Built-in Nginx)](./docker.mdx) — Start with the single-container setup
+- [Caddy Static Resource Proxy](../deployment/static-resource-proxy/caddy.md) — Learn more about the generated Caddy config

package/dist/ai/docs/nocobase/get-started/installation/docker-nginx.mdx

@@ -0,0 +1,176 @@
+---
+title: "Docker Installation (External Nginx)"
+description: "Install NocoBase with Docker and use an external Nginx container as the entry point."
+keywords: "Docker,NocoBase,Nginx,installation,reverse proxy"
+---
+
+# Docker Installation (External Nginx)
+
+In this setup, the NocoBase app container and the Nginx container run separately. You can start with [Docker Installation (Built-in Nginx)](./docker.mdx) and then switch the entry service to an external Nginx container.
+
+## When to use this setup
+
+- You want to deploy NocoBase and the web server separately
+- You want to manage the Nginx config and exposed ports yourself
+- You want to expose only the proxy container to the public network
+
+## docker-compose.yml example
+
+If you need the `full` image, replace `latest-no-nginx` with `latest-full-no-nginx`.
+
+The `13000:80` mapping is only for convenient local testing, so it does not occupy the standard host ports directly. In production, you usually do not keep using `13000:80`; instead, let the external Nginx container map directly to the host `80` and `443` ports.
+```yml
+networks:
+  nocobase:
+    driver: bridge
+
+services:
+  app:
+    image: nocobase/nocobase:latest-no-nginx
+    restart: always
+    depends_on:
+      - postgres
+    networks:
+      - nocobase
+    environment:
+      - APP_KEY=your-secret-key
+      - DB_DIALECT=postgres
+      - DB_HOST=postgres
+      - DB_PORT=5432
+      - DB_DATABASE=nocobase
+      - DB_USER=nocobase
+      - DB_PASSWORD=nocobase
+      - TZ=Etc/UTC
+      - NOCOBASE_EXTRACT_CLIENT_ASSETS=true
+      - NOCOBASE_PROXY_PROVIDER=nginx
+      - NOCOBASE_PROXY_STORAGE_PATH=/app/nocobase/storage
+      - NOCOBASE_PROXY_UPSTREAM_HOST=app
+    volumes:
+      - ./storage:/app/nocobase/storage
+
+  nginx:
+    image: nginx:latest
+    restart: always
+    depends_on:
+      - app
+    networks:
+      - nocobase
+    volumes:
+      - ./storage:/app/nocobase/storage
+    command: >
+      /bin/sh -c '
+        while [ ! -f /app/nocobase/storage/.nocobase/proxy/nginx/nocobase.conf ]; do
+          echo "waiting for nocobase.conf..."
+          sleep 1
+        done
+        rm -f /etc/nginx/conf.d/default.conf
+        ln -sf /app/nocobase/storage/.nocobase/proxy/nginx/nocobase.conf /etc/nginx/conf.d/default.conf
+        nginx -g "daemon off;"
+      '
+    ports:
+      # This is only a local testing example.
+      - "13000:80"
+      # In production, usually change it to:
+      # - "80:80"
+      # - "443:443"
+
+  postgres:
+    image: postgres:16
+    restart: always
+    command: postgres -c wal_level=logical
+    environment:
+      POSTGRES_USER: nocobase
+      POSTGRES_DB: nocobase
+      POSTGRES_PASSWORD: nocobase
+    volumes:
+      - ./storage/db/postgres:/var/lib/postgresql/data
+    networks:
+      - nocobase
+```
+
+## Key points
+
+- `NOCOBASE_EXTRACT_CLIENT_ASSETS=true` extracts client assets and generates proxy config
+- `NOCOBASE_PROXY_PROVIDER=nginx` tells the app to generate Nginx config
+- `NOCOBASE_PROXY_UPSTREAM_HOST=app` lets the Nginx container reach the `app` service through the Compose network
+- `./storage` must be mounted into both the `app` and `nginx` containers so they can share proxy config, static assets, and uploaded files
+- The `nginx` container should wait until `nocobase.conf` is generated, then link it to `/etc/nginx/conf.d/default.conf` with `ln -sf`
+- If you use an external Nginx container, let the `nginx` container handle the host port mapping. For testing, you can start with `13000:80`; in production, you usually expose the host `80` and `443` ports directly, while the `app` service does not need to expose its port to the host
+
+## If you use a local host Nginx
+
+If your Nginx is installed directly on the host instead of running in a Docker container, it is better to use a separate `docker-compose.yml`. In this setup, the `app` service must expose a host port directly, and the proxy-related environment variables should use host-side values.
+
+You can use a `docker-compose.yml` like this:
+
+```yml
+networks:
+  nocobase:
+    driver: bridge
+
+services:
+  app:
+    image: nocobase/nocobase:latest-no-nginx
+    restart: always
+    depends_on:
+      - postgres
+    networks:
+      - nocobase
+    environment:
+      - APP_KEY=your-secret-key
+      - DB_DIALECT=postgres
+      - DB_HOST=postgres
+      - DB_PORT=5432
+      - DB_DATABASE=nocobase
+      - DB_USER=nocobase
+      - DB_PASSWORD=nocobase
+      - TZ=Etc/UTC
+      - NOCOBASE_EXTRACT_CLIENT_ASSETS=true
+      - NOCOBASE_PROXY_PROVIDER=nginx
+      - NOCOBASE_PROXY_STORAGE_PATH=/path/to/your-project/storage
+      - NOCOBASE_PROXY_UPSTREAM_HOST=127.0.0.1
+      - NOCOBASE_PROXY_UPSTREAM_PORT=13000
+    volumes:
+      - ./storage:/app/nocobase/storage
+    ports:
+      - "13000:13000"
+
+  postgres:
+    image: postgres:16
+    restart: always
+    command: postgres -c wal_level=logical
+    environment:
+      POSTGRES_USER: nocobase
+      POSTGRES_DB: nocobase
+      POSTGRES_PASSWORD: nocobase
+    volumes:
+      - ./storage/db/postgres:/var/lib/postgresql/data
+    networks:
+      - nocobase
+```
+
+In this variant:
+
+- `NOCOBASE_PROXY_STORAGE_PATH` should be the absolute host path of your `storage` directory
+- `NOCOBASE_PROXY_UPSTREAM_HOST` should be `127.0.0.1`
+- The `app` service must keep `ports`, so the local Nginx can reach the app through `127.0.0.1:13000`
+
+After the `app` container starts, wait for the config file to be generated, then link it into the local Nginx config directory:
+
+```bash
+while [ ! -f ./storage/.nocobase/proxy/nginx/nocobase.conf ]; do
+  echo "waiting for nocobase.conf..."
+  sleep 1
+done
+
+sudo ln -sf "$(pwd)/storage/.nocobase/proxy/nginx/nocobase.conf" /etc/nginx/conf.d/nocobase.conf
+sudo nginx -t
+sudo systemctl reload nginx
+```
+
+If your host Nginx does not use the `conf.d` directory, replace the link target with your own config path. Usually it is safer to keep `nocobase.conf` as a file included from the `http {}` context instead of copying its content manually.
+
+## Related links
+
+- [Docker Installation (Built-in Nginx)](./docker.mdx) — Start with the single-container setup
+- [Nginx Static Resource Proxy](../deployment/static-resource-proxy/nginx.md) — Learn more about the generated Nginx config