@nocobase/plugin-ai 2.2.0-alpha.4 → 2.2.0-alpha.5

package/dist/ai/docs/nocobase/file-manager/storage/migrate-to-s3-pro.md

@@ -0,0 +1,269 @@
+---
+title: "Migrate to S3 Pro"
+description: "Migrate files from public-only storage engines to S3 Pro, including maintenance windows, backups, object key mapping, record updates, and risk checks."
+keywords: "S3 Pro,storage migration,private access,file migration,Local Storage,S3,OSS,COS,NocoBase"
+---
+
+# Migrate to S3 Pro
+
+If you already use [Local Storage](./local.md), [Amazon S3](./amazon-s3.md), [Aliyun OSS](./aliyun-oss.md), or [Tencent COS](./tencent-cos.md), and later need private file access, you can migrate historical files to [S3 Pro](./s3-pro.md).
+
+This is not only a storage configuration change. A migration must handle three things: make the physical files or objects available from the new storage, update file records, and switch future uploads to the new storage.
+
+:::warning Note
+
+Run the migration once in a test environment first, and prepare restorable database and file backups. If users continue to upload or delete attachments during the migration, records can be missed, overwritten, or become inconsistent.
+
+:::
+
+## Scope
+
+This guide applies when migrating from these storage engines to S3 Pro:
+
+| Source storage engine | Historical file location |
+| --- | --- |
+| Local Storage | `<documentRoot>/<record.path>/<record.filename>` |
+| Amazon S3 | `join(record.path, record.filename)` in the source bucket |
+| Aliyun OSS | `join(record.path, record.filename)` in the source bucket |
+| Tencent COS | `join(record.path, record.filename)` in the source bucket |
+
+Here, `record.path` and `record.filename` come from the file record itself, including the built-in `attachments` table and other file collections.
+
+:::tip Note
+
+For Local Storage, `documentRoot` must come from `options.documentRoot` in the corresponding `storages` record. The default value is `storage/uploads`, but the final absolute path depends on the runtime storage directory of NocoBase.
+
+:::
+
+## Operation Steps
+
+### Step 1: Stop writes or enter a maintenance window
+
+Pause user uploads, updates, and deletions of attachments during the migration. You can use a maintenance window, temporarily disable entry points, or freeze related business flows.
+
+The goal is to keep file records and physical files stable. If users upload or delete files during migration, the migration script may no longer be working against the latest records.
+
+### Step 2: Back up the database and files
+
+Prepare at least two backups:
+
+1. Database backup
+2. File backup or object snapshot from the source storage
+
+For Local Storage, back up the directory pointed to by `documentRoot`. Historical files are usually stored at:
+
+```text
+<documentRoot>/<record.path>/<record.filename>
+```
+
+For Amazon S3, Aliyun OSS, and Tencent COS, confirm that objects in the source bucket are still readable, and record the source storage engine's `id`, `name`, `type`, `path`, `baseUrl`, and `options`.
+
+It is also recommended to export a migration manifest for rollback and manual review:
+
+```text
+collection
+id
+oldStorageId
+oldPath
+oldFilename
+oldUrl
+newKey
+size
+mimetype
+```
+
+### Step 3: Create and verify the S3 Pro storage
+
+Create a new `s3-compatible` storage according to [S3 Pro](./s3-pro.md). At least verify these settings:
+
+- bucket
+- endpoint
+- region
+- accessKey
+- secret
+- public / private
+- access endpoint
+- forcePathStyle
+- file size and MIME type rules
+
+Upload a test file with the new storage and confirm upload, preview, download, and deletion all work. If the target is private access, also confirm that the access URL is a temporary signed URL and that its expiration is expected.
+
+:::warning Note
+
+S3 Pro uses direct client upload. The target bucket must have CORS rules that allow uploads from the NocoBase site, otherwise new uploads will fail.
+
+:::
+
+### Step 4: Decide the object key mapping
+
+For historical files migrated to S3 Pro, it is recommended to continue using the old relative path as the S3 object key:
+
+```text
+oldKey = join(record.path, record.filename)
+```
+
+For example:
+
+```text
+record.path = "avatars"
+record.filename = "a-123.png"
+oldKey = "avatars/a-123.png"
+```
+
+For persisted file records, S3 Pro uses `file.filename` directly as the full object key when accessing the file. It does not append `file.path`. Therefore, migrated records should be updated to:
+
+```text
+storageId = <s3-pro-storage-id>
+filename = <oldKey>
+path = ""
+url = ""
+```
+
+Do not migrate to this shape:
+
+```text
+filename = "a-123.png"
+path = "avatars"
+```
+
+Otherwise S3 Pro may treat only `a-123.png` as the object key, causing historical files to fail to load.
+
+Use `/` as the separator when generating object keys. Do not use operating-system-specific path separators. If an old path starts with `/`, remove the leading slash.
+
+### Step 5: Move physical files or confirm object location
+
+Traverse all file records, including the built-in `attachments` table and other file collections. Only process records where `storageId = <old-storage-id>`.
+
+If the source is Local Storage, upload the local files to the bucket used by S3 Pro. If the source is already Amazon S3, Aliyun OSS, or Tencent COS, and the new S3 Pro storage points to the same bucket and endpoint, with credentials that can read the same objects, you usually do not need to copy objects. In that case, confirm that the `oldKey` generated in Step 4 is accessible through S3 Pro.
+
+| Source storage engine | Whether files need to be copied | Target object key |
+| --- | --- | --- |
+| Local Storage | Must be uploaded to the S3 Pro bucket | `join(record.path, record.filename)` |
+| Amazon S3 | Usually no copy if reusing the same bucket; copy is needed when changing bucket, account, or region | `join(record.path, record.filename)` |
+| Aliyun OSS | Usually no copy if reusing the same bucket; copy is needed when changing bucket, account, or region | `join(record.path, record.filename)` |
+| Tencent COS | Usually no copy if reusing the same bucket; copy is needed when changing bucket, account, or region | `join(record.path, record.filename)` |
+
+Files or objects still need to be copied in these cases:
+
+- Migrating from Local Storage to S3 Pro
+- Changing bucket, account, region, or cloud provider
+- Moving historical objects from a public bucket to a new private bucket
+- Renaming object keys or reorganizing directories
+- The source bucket policy is not suitable for S3 Pro signed access or direct client upload
+- S3 Pro cannot directly access the source objects with the current endpoint and credentials
+
+Before the real migration, run a dry-run. At least output:
+
+- Number of records to migrate
+- Total size to migrate
+- Number of missing local files or missing source objects
+- Number of duplicate object keys
+- Number of records with unrecognized `storageId`
+- List requiring manual handling
+
+If duplicate object keys appear, do not overwrite directly. Compare file size, ETag, or hash to confirm whether they point to the same file. If they are different files, generate a new key for one record and use that new key when updating the record.
+
+### Step 6: Verify target object accessibility
+
+After files are copied, or after confirming that the source cloud bucket can be reused, run S3 HEAD Object or an equivalent check for every migrated record. Confirm that S3 Pro can access the object through the target object key.
+
+Recommended output:
+
+- Success count
+- Missing source file count
+- Upload or copy failure count
+- Missing target object count
+- Duplicate key count
+- List requiring manual handling
+
+Do not rely only on the script exit code. Object storage can have partial failures, successful retries, same-key overwrites, or write-only-but-not-readable permission problems. The migration manifest and HEAD Object checks are more reliable.
+
+### Step 7: Update file records
+
+After confirming that all target objects exist, update the file records. Only update records in file collections, keep the original `id`, and do not update many-to-many junction tables generated by attachment fields.
+
+Core fields:
+
+| Field | Value after migration |
+| --- | --- |
+| `storageId` | New S3 Pro storage ID |
+| `filename` | `join(oldPath, oldFilename)` |
+| `path` | Empty string |
+| `url` | Empty string for private storage; public URL or empty string for public storage |
+
+If S3 Pro is private, `url` must be empty. S3 Pro also clears `url` before saving non-public storage records. File access will dynamically generate a temporary signed URL.
+
+:::warning Note
+
+Batch update records in a transaction if possible, and keep the migration manifest from Step 2 until after the migration is fully verified. Rollback needs that manifest to restore `storageId`, `path`, `filename`, and `url` to their old values.
+
+:::
+
+### Step 8: Switch future uploads to the new storage
+
+After historical records are updated, switch the target storage for new uploads.
+
+Check three types of configuration:
+
+1. Default storage engine: if attachment fields or file collections do not specify storage, uploaded files use the default storage. Set the new S3 Pro storage as the default.
+2. Attachment fields: if an attachment field is configured with `options.storage = <old-storage-name>`, change it to the new S3 Pro storage `name`.
+3. File collections: if a file collection is configured with the old storage engine, change it to the new S3 Pro storage `name`.
+
+Here, `name` is the storage engine name, not the storage ID. Historical file records use `storageId`.
+
+### Step 9: Restart or refresh storage cache
+
+The file manager caches `storages` configuration. If you update storage configuration through the NocoBase UI or resource API, `reloadStorages` is usually triggered. If you update the database directly, restart the application after migration or make sure the storage cache has been refreshed.
+
+If you directly changed attachment field metadata or file collection metadata, it is also recommended to restart the application so collection configuration, field configuration, and frontend cache all use the new storage.
+
+### Step 10: Sample-check and keep old files
+
+After migration, verify at least these scenarios:
+
+- View, preview, and download historical files in attachment fields
+- View, preview, and download historical files in file collections
+- Image thumbnails or preprocessing parameters
+- Office preview and other features that depend on external services reading file URLs
+- Save, preview, download, and delete newly uploaded files
+- Object deletion after deleting file records
+
+Do not delete files from the old storage immediately. Keep them until the business side confirms the migration, backup cycles have covered the new state, and access logs show no abnormal behavior.
+
+## Risks
+
+### Data inconsistency during writes
+
+If users can still upload or delete files during migration, objects may be copied after records are deleted, records may be updated while objects remain only in the old storage, or new uploads may not be included in the migration manifest. The default approach is to enter a maintenance window.
+
+### Different object key rules in S3 Pro
+
+After migration, `filename` should store the full object key and `path` should be empty. This differs from the historical record shape of Local Storage and built-in S3 / OSS / COS, and is the easiest place to make mistakes.
+
+### URL accessibility changes
+
+After migrating from public storage to private S3 Pro, historical public URLs may no longer remain valid. NocoBase dynamically generates temporary signed URLs for internal file access, but old URLs already saved in external systems are not automatically rewritten.
+
+If third-party systems, email templates, exported files, or rich text content directly stores old URLs, evaluate a separate replacement strategy.
+
+:::warning Note
+
+If Markdown (Vditor) field content already stores file URLs, handle those contents separately. Private S3 Pro access generates temporary signed URLs that expire, and currently these private links are not supported for long-term storage and use inside Markdown (Vditor) fields.
+
+If these fields must continue referencing files, keep publicly accessible file URLs for now.
+
+:::
+
+### Preview services and private files
+
+Some preview features depend on external services accessing file URLs. Private S3 Pro generates temporary signed URLs, which can usually be accessed, but they are affected by signature expiration, network reachability, bucket permissions, and server-side caching.
+
+If files are very sensitive, reassess whether external preview services should be allowed to read them.
+
+### Direct database changes do not trigger all hooks
+
+If you update `storages`, collection configuration, field configuration, and file records directly through SQL or a custom script, some NocoBase cache refreshes and save hooks are not triggered automatically. Restart the application after the update and verify storage configuration again.
+
+### Delete behavior points to the new storage
+
+After a file record's `storageId` is updated to S3 Pro, deleting that file record later will make NocoBase try to delete the object from the new bucket. Objects in the old storage will not be deleted automatically and need to be cleaned up separately.

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,170 @@
+---
+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`.
+
+```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:
+      - "13000:80"
+
+  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. 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,172 @@
+---
+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`.
+
+```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:
+      - "13000:80"
+
+  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 the built-in Nginx image, the `app` container itself exposes the port with `ports: "13000:80"`
+- If you use an external Nginx container, let the `nginx` container handle the host port mapping, and do not expose the `app` service 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/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