@nocobase/plugin-ai 2.2.0-beta.8 → 2.2.0-beta.9

package/dist/ai/docs/nocobase/file-manager/storage/tencent-cos.md

@@ -2,6 +2,15 @@
 
 A storage engine based on Tencent Cloud COS. You need to prepare the relevant account and permissions before use.
 
+
+:::warning Note
+
+This engine does not support private access. After a file is uploaded, NocoBase generates a directly accessible URL, and anyone who has that URL can access the file.
+
+Even if the COS bucket itself is private, the built-in Tencent COS engine does not generate temporary signed URLs for file access. If you need private access, use [S3 Pro](./s3-pro). If historical files already exist, see [Migrate to S3 Pro](./migrate-to-s3-pro.md).
+
+:::
+
 ## Configuration Parameters
 
 

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

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

@@ -617,4 +617,97 @@ Open [http://localhost:13000](http://localhost:13000) in your browser. The initi
 
 After logging in for the first time, please change the default password promptly to ensure system security.
 
-:::
+:::
+
+## 5. Production deployment
+
+If you use the built-in Nginx image, it is usually better not to expose `13000` directly to the public internet. A more common setup is to keep the container port available only on the host and let the host Nginx handle the domain, HTTPS, and reverse proxy.
+
+### Proxy the root path with Nginx
+
+The following config proxies domain requests to `http://127.0.0.1:13000/`:
+
+```bash
+server {
+    listen 80;
+    server_name your_domain.com;  # Replace your_domain.com with your domain
+
+    location / {
+        proxy_pass http://127.0.0.1:13000/;
+        proxy_http_version 1.1;
+
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection $connection_upgrade;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $upstream_x_forwarded_proto;
+        proxy_set_header Host $final_host;
+        proxy_set_header Referer $http_referer;
+        proxy_set_header User-Agent $http_user_agent;
+
+        add_header Cache-Control "no-cache, no-store" always;
+        proxy_cache_bypass $http_upgrade;
+
+        proxy_connect_timeout 600;
+        proxy_send_timeout 600;
+        proxy_read_timeout 600;
+        send_timeout 600;
+        proxy_buffering off;
+    }
+}
+```
+
+If you also want to enable HTTPS, configure `443` and the certificate on the host Nginx. The NocoBase container does not need to handle certificates separately.
+
+### Subpath deployment
+
+If you want to deploy the app under a subpath, such as `https://your_domain.com/nocobase/`, configure the `APP_PUBLIC_PATH` environment variable first:
+
+```diff
+services:
+  app:
+    image: nocobase/nocobase:latest
+    environment:
++     - APP_PUBLIC_PATH=/nocobase/
+```
+
+Keep the leading and trailing `/` in the path. After this is configured, the app URL becomes `http://127.0.0.1:13000/nocobase/`.
+
+Then configure the host Nginx with the same subpath proxy:
+
+```bash
+server {
+    listen 80;
+    server_name your_domain.com;  # Replace your_domain.com with your domain
+
+    location /nocobase/ {
+        proxy_pass http://127.0.0.1:13000/nocobase/;
+        proxy_http_version 1.1;
+
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection $connection_upgrade;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $upstream_x_forwarded_proto;
+        proxy_set_header Host $final_host;
+        proxy_set_header Referer $http_referer;
+        proxy_set_header User-Agent $http_user_agent;
+
+        add_header Cache-Control "no-cache, no-store" always;
+        proxy_cache_bypass $http_upgrade;
+
+        proxy_connect_timeout 600;
+        proxy_send_timeout 600;
+        proxy_read_timeout 600;
+        send_timeout 600;
+        proxy_buffering off;
+    }
+}
+```
+
+The key point is that `APP_PUBLIC_PATH` and the path in `proxy_pass` must stay consistent. If either side misses `/nocobase/`, static assets and routing will usually not work correctly.
+
+### Other options
+
+If you do not want to use the built-in Nginx, you can also use one of these separate proxy setups:
+
+- [Docker Installation (External Nginx)](./docker-nginx.mdx)
+- [Docker Installation (External Caddy)](./docker-caddy.mdx)

package/dist/ai/docs/nocobase/get-started/installation/env.md

@@ -349,15 +349,17 @@ TELEMETRY_TRACE_PROCESSOR=console
 
 ### SERVER_REQUEST_WHITELIST
 
-Whitelist of allowed targets for server-initiated outbound HTTP requests, used to prevent SSRF (Server-Side Request Forgery) attacks. Accepts a comma-separated list of exact IPs, CIDR ranges, exact hostnames, and single-level wildcard subdomains.
+Whitelist of allowed targets for outbound HTTP requests initiated by the NocoBase server. Accepts a comma-separated list of exact IPs, CIDR ranges, exact hostnames, and single-level wildcard subdomains.
 
 ```bash
-SERVER_REQUEST_WHITELIST=1.2.3.4,10.0.0.0/8,api.example.com,*.trusted.com
+SERVER_REQUEST_WHITELIST=api.example.com,*.trusted.com,10.0.0.0/8,127.0.0.1
 ```
 
-**Applies to**: Workflow "HTTP Request" nodes and Custom Request action buttons. Relative-path requests (calls to the NocoBase API itself) are not affected.
+**Applies to**: Workflow "HTTP Request" nodes, Custom Request action buttons, AI services, and other server-side requests. Relative-path requests (calls to the NocoBase API itself) are not affected.
 
-**When not set**: All `http`/`https` outbound requests are allowed (existing behaviour). **When set**: Only requests whose host matches a whitelist entry are permitted; non-matching requests will raise an error.
+**When not set**: All `http` / `https` outbound requests are allowed to keep existing behavior. 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.
+
+**When set**: Only requests whose host matches a whitelist entry are permitted; non-matching requests will raise an error. Future versions may gradually tighten the default behavior. If your deployment needs to access internal services, configure an explicit whitelist in advance.
 
 Supported formats:
 
@@ -365,9 +367,17 @@ Supported formats:
 | --- | --- | --- |
 | Exact IPv4 | `1.2.3.4` | That IP only |
 | IPv4 CIDR | `10.0.0.0/8` | All IPs in the subnet |
+| Exact IPv6 | `::1` | That IP only |
+| IPv6 CIDR | `fc00::/7` | All IPs in the subnet |
 | Exact hostname | `api.example.com` | That hostname only |
 | Wildcard subdomain | `*.example.com` | One subdomain level, e.g. `foo.example.com`; does **not** match `example.com` or `a.b.example.com` |
 
+:::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.
+
+:::
+
 ## Experimental Environment Variables
 
 ### APPEND_PRESET_LOCAL_PLUGINS

package/dist/ai/docs/nocobase/ops-management/version-control/index.md

@@ -1,4 +1,5 @@
 ---
+pkg: '@nocobase/plugin-version-control'
 title: "Version control"
 description: "Version control plugin guide: automatically save versions during AI Builder sessions, create and restore versions manually, configure retention, set shortcuts, and include user collections in saved versions."
 keywords: "Version control,ops management,AI Builder,nocobase-revision,nb revision create,create version,restore version,NocoBase"