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

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

@@ -0,0 +1,179 @@
+---
+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`
+- The generated config forwards both the `/files/` route under `APP_PUBLIC_PATH` and the root-level `/files/` route to NocoBase for authenticated file previews and downloads
+- 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.
+
+If you maintain Nginx yourself instead of using the generated config, make sure `/files/` and the corresponding route under `APP_PUBLIC_PATH` are forwarded to NocoBase before the SPA fallback rules. See [Nginx Reverse Proxy](../../nocobase-cli/production/reverse-proxy/nginx.md) for a complete example.
+
+## 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,121 @@ 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/`:
+
+```nginx
+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.
+
+The `location /` block in this root-path configuration also proxies `/api/`, `/ws`, and `/files/`. If you split static assets from application routes, make sure `/files/` is still forwarded to NocoBase and is not handled as a static directory.
+
+### 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:
+
+```nginx
+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;
+    }
+
+    # Keep compatibility with root-level file access URLs.
+    location ^~ /files/ {
+        proxy_pass http://127.0.0.1:13000;
+        proxy_http_version 1.1;
+
+        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_connect_timeout 600;
+        proxy_send_timeout 600;
+        proxy_read_timeout 600;
+        send_timeout 600;
+    }
+}
+```
+
+Keep these points in mind:
+
+- `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
+- `/nocobase/files/` is forwarded by `location /nocobase/`; the compatible root-level `/files/` route must be forwarded to NocoBase separately
+
+### 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

@@ -86,6 +86,39 @@ API_BASE_PATH=/api/
 
 ### API_BASE_URL
 
+Base URL the frontend uses to access the NocoBase API. Empty by default, which means the same-origin `${APP_PUBLIC_PATH}api/` is used.
+
+```bash
+API_BASE_URL=
+```
+
+Only set it to the full API address when the pages and the API service are on different origins (different protocol, domain, or port):
+
+```bash
+API_BASE_URL=https://api.example.com/api/
+```
+
+:::warning{title="Cross-origin deployments"}
+NocoBase uses cookies to maintain login state and to authorize [stable file URLs](../../file-manager/stable-url.md). When `API_BASE_URL` points to a different origin than the pages:
+
+- The page origin must be added to [`CORS_ORIGIN_WHITELIST`](#cors_origin_whitelist). Otherwise the browser ignores `Set-Cookie` in API responses, the login cookie is never stored, and cookie-dependent features such as file preview and download fail with `403`.
+- Cookies are stored per `hostname`. If the pages and the API use entirely different domains, requests to `/files/` stable URLs from the page domain will not carry the login cookie stored under the API domain, so file access still fails.
+
+Prefer serving the pages and the API from the same origin through a reverse proxy and leaving `API_BASE_URL` empty.
+:::
+
+### CORS_ORIGIN_WHITELIST
+
+Whitelist of origins allowed to access the API cross-origin with credentials (cookies). Multiple origins are separated by commas. Empty by default.
+
+```bash
+CORS_ORIGIN_WHITELIST=https://www.example.com,https://admin.example.com
+```
+
+- When not configured, only same-origin requests are treated as trusted; cross-origin requests can still call the API anonymously, but the browser is not allowed to read or write cookies for them.
+- When configured, whitelisted origins receive an exact `Access-Control-Allow-Origin` echo and `Access-Control-Allow-Credentials: true`, which lets the browser send and store login cookies on cross-origin requests.
+- The sign-in API validates the request `Origin` / `Referer`; cross-origin sign-in requests from origins outside the whitelist are rejected with `403`.
+
 ### CLUSTER_MODE
 
 > `v1.6.0+`
@@ -113,7 +146,7 @@ For example, to add the `hello` plugin to the `my-nocobase-app` project, the plu
 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-
 ```
 
 The correspondence between plugin name and package name is as follows:
@@ -349,15 +382,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**: The initial request and every redirect destination must match a whitelist entry; non-matching requests will raise an error before the next request is sent. 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 +400,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/get-started/quickstart.md

@@ -55,4 +55,9 @@ You can install NocoBase in different ways.
 | **Scenarios** | No-code users; users who want to quickly deploy to a server. | Front-end/full-stack developers; team projects; low-code development. | Technical developers; users who want to try unreleased versions. |
 | **Technical Requirement** | ★☆☆☆☆ | ★★★☆☆ | ★★★★★ |
 | **Upgrade Method** | Pull the latest image and restart the container. | Update dependencies with yarn. | Synchronize updates through Git. |
-| **Tutorials** | [<code>Installation</code>](#) [<code>Upgrade</code>](#) [<code>Deployment</code>](#) | [<code>Installation</code>](#) [<code>Upgrade</code>](#) [<code>Deployment</code>](#) | [<code>Installation</code>](#) [<code>Upgrade</code>](#) [<code>Deployment</code>](#) |
+
+![2026-06-11-20-09-54](https://static-docs.nocobase.com/2026-06-11-20-09-54.png)
+
+## What's Next
+
+If you've already picked an installation method, the next step is [Install NocoBase App](/ai/install-nocobase-app). It walks you through installing NocoBase CLI and finishing the app installation and initialization.

package/dist/ai/docs/nocobase/get-started/system-requirements.md

@@ -11,6 +11,14 @@ Except for functionality validation or purely experimental scenarios, **we stron
 
 The system configuration and capacity planning of those services must be evaluated and tuned separately based on the **actual data size, workload, and concurrency level**.
 
+## Operating System
+
+For production environments, Linux servers are recommended, such as Ubuntu LTS, Debian, Rocky Linux, or AlmaLinux. Docker, reverse proxy, process management, logging, and backup workflows are more mature on Linux and are easier to integrate with common cloud server environments.
+
+NocoBase can also be installed on Windows Server. If you choose Windows Server, confirm Node.js, database, reverse proxy, process supervision, backup, file permissions, firewall, and related operations based on your actual deployment method.
+
+macOS is usually more suitable for local development and testing, and is not recommended as a production server. If you are setting up NocoBase locally for development or AI Agent usage, see [Local Development Setup](../ai/local-development-setup.md).
+
 ## Single-Node Deployment Mode
 
 Single-node deployment mode means the NocoBase application service runs on a single server or container instance.
@@ -85,4 +93,4 @@ In cluster mode, the recommended hardware configuration for each application nod
 Recommendations for production environments:
 
 - Adjust the node count dynamically based on monitoring metrics (CPU, memory, request latency, and so on).
-- Reserve a resource buffer to handle traffic spikes.
+- Reserve a resource buffer to handle traffic spikes.

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

@@ -11,31 +11,28 @@ hero:
   actions:
     - theme: brand
       text: Get Started
-      link: /get-started/how-nocobase-works
+      link: /ai/how-nocobase-works
     - theme: alt
       text: GitHub
       link: https://github.com/nocobase/nocobase
 
 features:
   - title: Start
-    details: Get started with NocoBase the traditional way - install, configure, and explore step by step.
+    details: Get started with NocoBase quickly - install, configure, and explore step by step.
     items:
-      - title: NocoBase Getting Started
+      - title: How NocoBase Works
         details: Understand NocoBase's core concepts and basic operations.
-        link: /get-started/how-nocobase-works
-      - title: Install App
-        details: Quickly install and manage applications.
-        link: /get-started/installation/docker
+        link: /ai/how-nocobase-works
+      - title: Install NocoBase App
+        details: Use NocoBase CLI to install an application quickly.
+        link: /ai/install-nocobase-app
       - title: Tutorials
         details: Step-by-step tutorials to build real projects with NocoBase from scratch.
-        link: /tutorials/v2/
+        link: /tutorials/
 
   - title: AI
     details: An AI-powered new way to get started - use natural language to build, use, and develop.
     items:
-      - title: Quick Start
-        details: Install NocoBase CLI, configure AI Skills, and connect your AI Agent, preparing for AI building, using, and developing NocoBase.
-        link: /ai/quick-start
       - title: AI Builder
         details: Build NocoBase applications from scratch with AI, covering the full process from data modeling, UI configuration, workflows to release management.
         link: /ai-builder

package/dist/ai/docs/nocobase/interface-builder/blocks/data-blocks/comment.md

@@ -0,0 +1,107 @@
+---
+pkg: "@nocobase/plugin-block-comment"
+title: "Comment Block"
+description: "Comment block: view and create comments in record details, pop-ups, and similar scenarios, with field mapping, pagination, data scope, default sorting, and auto jump to last page."
+keywords: "Comment Block,CommentBlock,comment collection,field mapping,data scope,default sorting,interface builder,NocoBase"
+---
+
+# Comment Block
+
+## Introduction
+
+The Comment block adds commenting capabilities to business records. You can add it to detail pages or pop-ups for tasks, articles, tickets, customers, and other records, so users can view, reply to, and create comments around the current record.
+
+![](https://static-docs.nocobase.com/Comments-07-01-2026_12_02_PM.png)
+
+:::tip
+
+The Comment block does not create a collection by itself. Before using it, prepare a collection for storing comments and configure fields such as comment content, commenter, comment owner, and comment time.
+
+:::
+
+## Add a block
+
+The Comment block is usually added to the detail page or pop-up of a business record.
+
+![](https://static-docs.nocobase.com/Comments-07-01-2026_12_03_PM.png)
+
+1. Open the target record detail page or pop-up
+2. Click "Add block"
+3. Select "Comment"
+4. Select the collection used to store comments
+5. Complete field mapping as prompted
+
+If the Comment block is created from an association, NocoBase will try to automatically identify the comment owner field and the current record value based on the current association. In this case, "Comment owner field" and "Comment owner field value" are filled automatically, and usually do not need manual configuration.
+
+![](https://static-docs.nocobase.com/Comments-07-01-2026_12_04_PM.png)
+
+If the block is created directly from the comment collection, you need to manually configure the comment owner field and value.
+
+![](https://static-docs.nocobase.com/Comments-07-01-2026_12_03_PM%20(1).png)
+
+## Field mapping
+
+The Comment block uses "Field mapping" to know how each comment should be displayed and saved.
+
+| Configuration | Description |
+| --- | --- |
+| Comment content field | Select the field used to store the comment body. |
+| Commenter field | Select a many-to-one field associated with the users collection. |
+| Comment owner field | Select the field used to store the current business record identifier. |
+| Comment owner field value | Specify the current business record value, such as `{{ ctx.popup.record.id }}`. |
+| Comment date field | Select the comment time field, used for display and default sorting. |
+
+### Comment owner field
+
+"Comment owner field" is used to filter comments for the current record, and is also written when a new comment is created.
+
+When selected manually, the dropdown only shows ordinary scalar fields and does not show association fields. Common configurations are:
+
+| Business collection | Owner field in comment collection | Comment owner field value |
+| --- | --- | --- |
+| Tasks | `taskId` | `{{ ctx.popup.record.id }}` |
+| Articles | `postId` | `{{ ctx.popup.record.id }}` |
+| Tickets | `ticketId` | `{{ ctx.popup.record.id }}` |
+
+If the current record uses a unique identifier other than `id`, change "Comment owner field value" to the corresponding field, such as `{{ ctx.popup.record.uuid }}`.
+
+### Automatic mapping from associations
+
+If the block is created from an association of the business record, the Comment block prioritizes the foreign key field of that association as the comment owner field, and uses the current record value as the comment owner field value.
+
+![](https://static-docs.nocobase.com/Comments-07-01-2026_12_04_PM.png)
+
+For example, if there is a one-to-many association between the task collection and the task comment collection, and the foreign key field in the task comment collection is `taskId`, then when you add a Comment block from the association in the task detail page, the block automatically uses:
+
+- Comment owner field: `taskId`
+- Comment owner field value: the identifier of the current task record
+
+This approach is suitable for most scenarios and reduces manual configuration errors.
+
+## Block settings
+
+![](https://static-docs.nocobase.com/Comments-07-01-2026_12_07_PM.png)
+
+### Page size
+
+Set how many comments are displayed on each page. Available values include `5`, `10`, `20`, `50`, `100`, and `200`.
+
+### Data scope
+
+Set the data filtering scope for the comment list. You can add more conditions here, such as showing only comments that match certain status or permission conditions.
+
+For more details, see [Set data scope](../block-settings/data-scope.md).
+
+### Default sorting rule
+
+Set the default sorting rule for the comment list. Usually, you can sort by the comment date field in ascending or descending order.
+
+If no default sorting rule is configured separately, the Comment block prioritizes the "Comment date field" as the default sorting field.
+
+For more details, see [Set sorting rule](../block-settings/sorting-rule.md).
+
+### Auto jump to last page
+
+Disabled by default. When disabled, the Comment block stays on the first page after opening.
+
+When enabled, the Comment block jumps to the last page on first load. This is suitable when you want users to see the latest comments first.