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

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

@@ -17,30 +17,6 @@ Currently, NocoBase has built-in support for the following engine types:
 - [S3 Pro](./s3-pro)
 
 The system automatically adds a local storage engine during installation, which can be used directly. You can also add new engines or edit the parameters of existing ones.
-
-
-If you are already using a storage engine that only supports public access and want to migrate historical files to S3 Pro, see [Migrate to S3 Pro](./migrate-to-s3-pro.md).
-
-## File Accessibility
-
-Different storage engines support different file access controls. Before configuring a storage engine, confirm whether your files need private access:
-
-| Storage engine | File accessibility |
-| --- | --- |
-| [Local Storage](./local) | Only public access is supported; private access is not supported |
-| [Amazon S3](./amazon-s3) | Only public access is supported; private access is not supported |
-| [Aliyun OSS](./aliyun-oss) | Only public access is supported; private access is not supported |
-| [Tencent COS](./tencent-cos) | Only public access is supported; private access is not supported |
-| [S3 Pro](./s3-pro) | Private access is supported through temporary signed URLs |
-
-:::warning Note
-
-Local Storage, Amazon S3, Aliyun OSS, and Tencent COS do not perform login authentication for file access and do not generate temporary signed URLs. After a file is uploaded, anyone who has the file access URL can access it directly.
-
-If you need to store contracts, identity documents, internal materials, or other files that should not be public, use [S3 Pro](./s3-pro) and enable private access.
-
-:::
-
 ## Common Parameters
 
 In addition to the specific parameters for different engine types, the following are common parameters (using local storage as an example):
@@ -82,11 +58,75 @@ When checked, this is set as the system's default storage engine. When an attach
 When checked, the uploaded file in the storage engine will be kept even when the data record in the attachment or file collection is deleted. By default, this is not checked, meaning the file in the storage engine will be deleted along with the record.
 
 :::info{title=Tip}
-After a file is uploaded, the final access path is constructed by concatenating several parts:
+When Original URL is selected, the final storage address is constructed from several parts:
 
 ```
 <Public URL prefix>/<Path>/<Filename><Extension>
 ```
 
 For example: `https://cdn.nocobase.com/app/user/avatar/20240529115151.png`.
-:::
+
+When NocoBase URL is selected, the file record returns a NocoBase path in the `/files/...` format. The configuration above is still used when accessing the storage service.
+:::
+
+## File URLs and access control
+
+A storage engine can return either a NocoBase URL or the storage service's original URL. NocoBase URL is the default. Select Original URL only when an external service must use the storage address directly.
+
+This configuration applies per storage engine. After it is saved, both existing files and newly uploaded files under that engine return URLs in the selected form. Files are not moved or uploaded again.
+
+![File URL configuration](https://static-docs.nocobase.com/20260723221234.png)
+
+### NocoBase URL
+
+The file record returns an access path provided by NocoBase, for example:
+
+```text
+/files/main/main/attachments/1.png
+```
+
+Requests to this URL first pass through NocoBase and follow the view permissions configured for the corresponding file record. NocoBase reads the file or redirects to the address generated by the storage service only after the permission check succeeds.
+
+This is the recommended default. The file record returns a NocoBase path, so callers do not need to know whether local or cloud storage is being used.
+
+### Original URL
+
+The file record directly returns the address generated by the storage service, for example:
+
+```text
+https://storage.example.com/path/to/file.png
+```
+
+This URL does not pass through NocoBase and does not check the file record's view permissions. For local storage, it is a local static file address. For cloud storage, it is usually an object storage or CDN address.
+
+Select Original URL only when Markdown, an external page, or a third-party service must use the storage address directly.
+
+:::warning Note
+
+After Original URL is selected, anyone with a valid URL can bypass NocoBase permission checks and access the file. If the URL has no signature or expiration, make sure the bucket and file allow public read access.
+
+:::
+
+### Allow public access
+
+Allow public access only takes effect when NocoBase URL is selected. When checked, the storage engine still returns a NocoBase URL, but NocoBase no longer checks the file record's permissions when the URL is accessed. Anyone with the URL can access the file.
+
+This option does not change the storage service's own public-read configuration. It only controls whether NocoBase checks file record permissions.
+
+### How to choose
+
+| Use case | File URL | Allow public access |
+| --- | --- | --- |
+| Files must follow role and data permissions | NocoBase URL | Unchecked |
+| A publicly shareable NocoBase file address is required | NocoBase URL | Checked |
+| Markdown, an external page, or a third-party service must read the storage address directly | Original URL | Not applicable |
+
+:::warning Note
+
+[Local Storage](./local), [Amazon S3](./amazon-s3), [Aliyun OSS](./aliyun-oss), and [Tencent COS](./tencent-cos) do not generate temporary signed URLs. Even when NocoBase URL and file record permissions are enabled, anyone who has already obtained the storage service's original address can still access the file directly.
+
+For contracts, identity documents, internal materials, or other files that should not be public, use [S3 Pro](./s3-pro) and refer to its dedicated access-control configuration.
+
+:::
+
+If you are already using a public storage engine and want to migrate existing files to S3 Pro, see [Migrate to S3 Pro](./migrate-to-s3-pro.md).

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

@@ -12,7 +12,7 @@ Building on the File Manager plugin, this adds support for S3 protocol-compatibl
 
 1. Client-side upload: The file upload process does not go through the NocoBase server, but directly connects to the file storage service, providing a more efficient and faster upload experience.
     
-2. Private access: When accessing files, all URLs are signed temporary authorized addresses, ensuring the security and timeliness of file access.
+2. Private access: Signed URLs with an expiration are used by default. Unsigned URLs can also be generated for public buckets.
 
 
 ## Use Cases
@@ -39,6 +39,57 @@ Building on the File Manager plugin, this adds support for S3 protocol-compatibl
 
 ![](https://static-docs.nocobase.com/20250413190828536.png)
 
+## URL Configuration
+
+In addition to the File Manager's common NocoBase URL, Original URL, and Allow public access options, S3 Pro lets you configure upload and access URL formats separately and choose whether to use signed URLs. See [Storage Engine Overview](./index.md#file-urls-and-access-control) for the common options.
+
+These options control different stages:
+
+- NocoBase URL / Original URL controls which address the file record returns
+- Allow public access controls whether file record view permissions are checked when a NocoBase URL is accessed
+- Do not use signed URL controls whether the object storage service validates a URL signature
+
+These settings can be combined independently. The recommended default is NocoBase URL, Allow public access unchecked, and signed URLs enabled.
+
+![S3 Pro URL configuration](https://static-docs.nocobase.com/20260723221441.png)
+
+### How to choose
+
+| Use case | File URL | Allow public access | Do not use signed URL |
+| --- | --- | --- | --- |
+| Files must follow role and data permissions while the bucket remains private | NocoBase URL | Unchecked | Unchecked |
+| A public NocoBase file address is required while the bucket remains private | NocoBase URL | Checked | Unchecked |
+| An external service needs temporary access to the storage address | Original URL | Not applicable | Unchecked; configure Access URL expiration |
+| A public bucket or CDN requires an unsigned original address | Original URL | Not applicable | Checked |
+
+### Upload URL format
+
+Upload URL format controls the S3 URL used by the client when uploading files. Select the format supported by your storage service. The configuration form displays an example based on the current Endpoint, Bucket, and path:
+
+- Bucket as subdomain: `https://bucket-name.s3.example.com/path/to/object`
+- Bucket as subpath: `https://s3.example.com/bucket-name/path/to/object`
+- Ignore bucket: `https://upload.example.com/path/to/object`
+
+### Access URL format
+
+Access URL format controls whether the Bucket appears in the domain, in the path, or not at all when S3 Pro generates a file access address. It provides the same three formats as Upload URL format, but can be configured separately—for example, uploads can use an S3 Endpoint while access uses a CDN domain that does not include the Bucket.
+
+This option affects Original URLs and the storage address that a NocoBase URL ultimately redirects to, but it does not change the NocoBase URL format itself.
+
+### Do not use signed URL
+
+S3 Pro uses signed URLs by default. A generated Original URL includes signature parameters, for example:
+
+```text
+https://bucket-name.s3.example.com/path/to/object?X-Amz-Signature=xxxx
+```
+
+The signed URL remains valid for the configured Access URL expiration, and the bucket can remain private. When NocoBase URL is used, NocoBase generates or redirects to a signed address after the permission check succeeds.
+
+When Do not use signed URL is checked, S3 Pro generates an address without signature parameters. The bucket and uploaded objects must then allow public read access, and Access URL expiration no longer takes effect.
+
+Do not use signed URL only controls whether the storage service validates a signature; it does not change NocoBase file record permissions. If NocoBase URL is selected and Allow public access is unchecked, the request must still pass the NocoBase permission check first.
+
 
 
 ## Service Provider Configuration
@@ -146,9 +197,9 @@ Building on the File Manager plugin, this adds support for S3 protocol-compatibl
 ![](https://static-docs.nocobase.com/file-storage-s3-pro-1735355971345.png)
 
 
-#### Public Access (Optional)
+#### Unsigned Public Access (Optional)
 
-This is an optional configuration. Configure it when you need to make uploaded files completely public.
+Configure this only when unsigned URLs are required, because the Bucket and uploaded objects must allow public read access. If you only need to share a public NocoBase URL, check Allow public access and keep signed URLs enabled; the Bucket does not need to be public.
 
 1. Go to the Permissions panel, scroll down to Object Ownership, click edit, and enable ACLs.
 
@@ -162,7 +213,7 @@ This is an optional configuration. Configure it when you need to make uploaded f
 ![](https://static-docs.nocobase.com/file-storage-s3-pro-1735355971668.png)
 
 
-3. Check Public access in NocoBase.
+3. Check Do not use signed URL in NocoBase.
 
 
 #### Thumbnail Configuration (Optional)
@@ -193,7 +244,7 @@ This configuration is optional and is used to optimize image preview size or eff
 5. In the NocoBase configuration, there are several points to note:
    1. `Thumbnail rule`: Fill in image processing-related parameters, for example, `?width=100`. For details, refer to the [AWS documentation](https://docs.aws.amazon.com/solutions/latest/serverless-image-handler/use-supported-query-param-edits.html).
    2. `Access endpoint`: Fill in the value of Outputs -> ApiEndpoint after deployment.
-   3. `Full access URL style`: You need to check **Ignore** (because the bucket name was already filled in during configuration, it is no longer needed for access).
+   3. Access URL format: Select **Ignore bucket** because the bucket name is already included in the configuration and is not needed in the access URL.
    
    
 ![](https://static-docs.nocobase.com/20250414152135514.png)
@@ -312,7 +363,7 @@ This configuration is optional and should only be used when you need to optimize
 
 1. Fill in the `Thumbnail rule` related parameters. For specific parameter settings, refer to [Image Processing Parameters](https://www.alibabacloud.com/help/en/object-storage-service/latest/process-images).
 
-2. `Full upload URL style` and `Full access URL style` can be kept the same.
+2. Upload URL format and Access URL format can use the same setting.
 
 #### Configuration Example
 
@@ -357,7 +408,7 @@ This configuration is optional and should only be used when you need to optimize
    - **AccessKey ID** and **AccessKey Secret** are the values saved in the previous step.
    - **Region**: A self-hosted MinIO does not have the concept of a Region, so it can be configured as "auto".
    - **Endpoint**: Fill in the domain name or IP address of your deployment.
-   - Full access URL style must be set to Path-Style.
+   - Set Access URL format to Bucket as subpath.
 
 #### Configuration Example
 

package/dist/ai/docs/nocobase/get-started/deployment/production.md

@@ -2,12 +2,34 @@
 
 When deploying NocoBase in a production environment, installing dependencies can be cumbersome due to differences in build methods across various systems and environments. For a complete functional experience, we recommend deploying with **Docker**. If your system environment cannot use Docker, you can also deploy using **create-nocobase-app**.
 
-:::warning
+:::warning Note
 
 It is not recommended to deploy directly from source code in a production environment. The source code has many dependencies, is large in size, and a full compilation has high CPU and memory requirements. If you must deploy from source code, it is recommended to first build a custom Docker image and then deploy it.
 
 :::
 
+:::warning Note
+
+If you deploy multiple independent NocoBase services, use a different `hostname` for each service, such as separate subdomains. Do not distinguish services only by port, for example `https://example.com:13000` and `https://example.com:14000`.
+
+NocoBase uses cookies to maintain login state and [file access permissions](../../file-manager/stable-url.md). Browsers do not isolate cookies by port, so services on different ports under the same `hostname` may share cookies with the same name. This can overwrite login state or cause file preview and download authorization failures.
+
+Sub-apps within the same NocoBase deployment are outside this restriction. Login cookies are distinguished by app name, so the main app and differently named sub-apps can share one `hostname`.
+
+However, independent services still need isolation. If another NocoBase service runs on a different port under the same `hostname` and contains a main app or sub-app with the same name, its cookies may still conflict.
+
+Use addresses such as `app1.example.com` and `app2.example.com`, then route them to different NocoBase services through Nginx or Caddy.
+
+:::
+
+## Separated Frontend / Cross-Origin API Access
+
+Prefer keeping the pages and the API on the same origin: use a reverse proxy under one domain to forward `${APP_PUBLIC_PATH}api/` and `${APP_PUBLIC_PATH}files/` to the NocoBase service, and leave `API_BASE_URL` empty.
+
+If the pages must access the API cross-origin (with `API_BASE_URL` pointing to another origin), add the page origin to `CORS_ORIGIN_WHITELIST`. Otherwise the browser ignores `Set-Cookie` in API responses, the login cookie is never stored, and preview and download through stable file URLs fail authorization.
+
+Also note that cookies are stored per `hostname`: when the pages and the API use entirely different domains, requests to `/files/` from the page domain will not carry the login cookie stored under the API domain. Such deployments should switch to a same-origin reverse proxy. See [Environment Variables](../installation/env.md#api_base_url).
+
 ## Deployment Process
 
 For production environment deployment, you can refer to the existing installation and upgrade steps.
@@ -39,4 +61,4 @@ In a production environment, it is recommended to manage static assets with a pr
 Depending on the installation method, you can use the following commands to manage the NocoBase process:
 
 - [docker compose](./common-commands/docker-compose.md)
-- [pm2](./common-commands/pm2.md)
+- [pm2](./common-commands/pm2.md)

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

@@ -94,6 +94,7 @@ services:
 - `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`
+- 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
 - 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
@@ -169,6 +170,8 @@ 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.
 
+If you maintain Caddy 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 [Caddy Reverse Proxy](../../nocobase-cli/production/reverse-proxy/caddy.md) for a complete example.
+
 ## Related links
 
 - [Docker Installation (Built-in Nginx)](./docker.mdx) — Start with the single-container setup

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

@@ -95,6 +95,7 @@ services:
 - `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
@@ -170,6 +171,8 @@ 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

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

@@ -627,7 +627,7 @@ If you use the built-in Nginx image, it is usually better not to expose `13000`
 
 The following config proxies domain requests to `http://127.0.0.1:13000/`:
 
-```bash
+```nginx
 server {
     listen 80;
     server_name your_domain.com;  # Replace your_domain.com with your domain
@@ -658,6 +658,8 @@ server {
 
 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:
@@ -674,7 +676,7 @@ Keep the leading and trailing `/` in the path. After this is configured, the app
 
 Then configure the host Nginx with the same subpath proxy:
 
-```bash
+```nginx
 server {
     listen 80;
     server_name your_domain.com;  # Replace your_domain.com with your domain
@@ -700,10 +702,32 @@ server {
         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;
+    }
 }
 ```
 
-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.
+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
 

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:

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.