@nocobase/plugin-ai 2.3.0-alpha.1 → 2.3.0-beta.2

package/dist/ai/docs/nocobase/data-sources/main/mariadb.md

@@ -0,0 +1,59 @@
+---
+pkg: "@nocobase/plugin-data-source-manager"
+title: "Main data source - MariaDB"
+description: "Learn the supported version, plugin installation, usage, and field mapping for MariaDB as the NocoBase main database."
+keywords: "main data source,MariaDB,main database,field mapping,NocoBase"
+---
+
+# MariaDB
+
+## Introduction
+
+MariaDB can be used as the NocoBase main database. It stores NocoBase system-table data and business data in the main data source. Configure it when deploying NocoBase; it cannot be deleted after the application is running.
+
+| Setting | Description |
+| --- | --- |
+| Supported version | >= 10.9. |
+| Commercial editions | Community, Standard, Professional, and Enterprise. |
+| Database type | MariaDB. |
+
+MariaDB is similar to MySQL and is suitable as the main database for regular business systems.
+
+## Plugin installation
+
+MariaDB is built in and does not require a separate plugin.
+
+## Usage
+
+1. Select or enter MariaDB connection settings when deploying NocoBase.
+2. After NocoBase starts, open **Data source management**, select **Main**, and manage collections and fields in the main database.
+3. To connect tables that already exist in the database, use **Sync from database** on the main-database management page.
+4. When configuring fields, use [Collections](../data-modeling/collection.md) and [Collection fields](../data-modeling/collection-fields/index.md) to choose Field types and Field interfaces.
+
+## Field type mapping
+
+When you create a field in NocoBase, NocoBase creates the corresponding MariaDB column. When you synchronize an existing table, NocoBase maps the MariaDB column type to a suitable Field type and Field interface. You can adjust the display interface in field configuration.
+
+| MariaDB type | NocoBase Field type | Available Field interfaces |
+| --- | --- | --- |
+| `TINYINT`, `SMALLINT`, `MEDIUMINT` | `integer`, `boolean`, `sort` | Integer, Sort, Checkbox, Switch, Select, Radio group. |
+| `INT`, `INTEGER` | `integer`, `unixTimestamp`, `sort` | Integer, Sort, Unix timestamp, Select, Radio group. |
+| `BIGINT` | `bigInt`, `snowflakeId`, `unixTimestamp`, `sort` | Integer, Sort, Unix timestamp, Created at, Updated at. |
+| `FLOAT`, `DOUBLE` | `float` | Number, Percent. |
+| `DECIMAL` | `decimal` | Number, Percent, Currency. |
+| `CHAR`, `VARCHAR` | `string`, `uuid`, `nanoid`, `encryption` | Input, Email, Phone, Password, Color, Icon, Select, Radio group, UUID, Nano ID. |
+| `TINYTEXT`, `TEXT`, `MEDIUMTEXT`, `LONGTEXT` | `text` | Textarea, Markdown, Vditor, Rich text, URL. |
+| `DATE` | `dateOnly` | Date. |
+| `TIME` | `time` | Time. |
+| `DATETIME` | `datetimeNoTz`, `datetimeTz`, `date` | Date, Time, Created at, Updated at. |
+| `TIMESTAMP` | `datetimeTz`, `date` | Date, Time, Created at, Updated at. |
+| `YEAR` | `string`, `integer` | Input, Integer, Date. |
+| `JSON` | `json`, `array` | JSON. |
+
+:::warning Note
+
+Unsupported MariaDB types are shown separately in field configuration. They require development support before they can be used as normal NocoBase fields.
+
+:::
+
+For common configuration, see [Main database](./index.md).

package/dist/ai/docs/nocobase/data-sources/main/mysql.md

@@ -0,0 +1,59 @@
+---
+pkg: "@nocobase/plugin-data-source-manager"
+title: "Main data source - MySQL"
+description: "Learn the supported version, plugin installation, usage, and field mapping for MySQL as the NocoBase main database."
+keywords: "main data source,MySQL,main database,field mapping,NocoBase"
+---
+
+# MySQL
+
+## Introduction
+
+MySQL can be used as the NocoBase main database. It stores NocoBase system-table data and business data in the main data source. Configure it when deploying NocoBase; it cannot be deleted after the application is running.
+
+| Setting | Description |
+| --- | --- |
+| Supported version | >= 8.0.17. |
+| Commercial editions | Community, Standard, Professional, and Enterprise. |
+| Database type | MySQL. |
+
+MySQL is suitable as the main database for regular business systems.
+
+## Plugin installation
+
+MySQL is built in and does not require a separate plugin.
+
+## Usage
+
+1. Select or enter MySQL connection settings when deploying NocoBase.
+2. After NocoBase starts, open **Data source management**, select **Main**, and manage collections and fields in the main database.
+3. To connect tables that already exist in the database, use **Sync from database** on the main-database management page.
+4. When configuring fields, use [Collections](../data-modeling/collection.md) and [Collection fields](../data-modeling/collection-fields/index.md) to choose Field types and Field interfaces.
+
+## Field type mapping
+
+When you create a field in NocoBase, NocoBase creates the corresponding MySQL column. When you synchronize an existing table, NocoBase maps the MySQL column type to a suitable Field type and Field interface. You can adjust the display interface in field configuration.
+
+| MySQL type | NocoBase Field type | Available Field interfaces |
+| --- | --- | --- |
+| `TINYINT`, `SMALLINT`, `MEDIUMINT` | `integer`, `boolean`, `sort` | Integer, Sort, Checkbox, Switch, Select, Radio group. |
+| `INT`, `INTEGER` | `integer`, `unixTimestamp`, `sort` | Integer, Sort, Unix timestamp, Select, Radio group. |
+| `BIGINT` | `bigInt`, `snowflakeId`, `unixTimestamp`, `sort` | Integer, Sort, Unix timestamp, Created at, Updated at. |
+| `FLOAT`, `DOUBLE` | `float` | Number, Percent. |
+| `DECIMAL` | `decimal` | Number, Percent, Currency. |
+| `CHAR`, `VARCHAR` | `string`, `uuid`, `nanoid`, `encryption` | Input, Email, Phone, Password, Color, Icon, Select, Radio group, UUID, Nano ID. |
+| `TINYTEXT`, `TEXT`, `MEDIUMTEXT`, `LONGTEXT` | `text` | Textarea, Markdown, Vditor, Rich text, URL. |
+| `DATE` | `dateOnly` | Date. |
+| `TIME` | `time` | Time. |
+| `DATETIME` | `datetimeNoTz`, `datetimeTz`, `date` | Date, Time, Created at, Updated at. |
+| `TIMESTAMP` | `datetimeTz`, `date` | Date, Time, Created at, Updated at. |
+| `YEAR` | `string`, `integer` | Input, Integer, Date. |
+| `JSON` | `json`, `array` | JSON. |
+
+:::warning Note
+
+Unsupported MySQL types are shown separately in field configuration. They require development support before they can be used as normal NocoBase fields.
+
+:::
+
+For common configuration, see [Main database](./index.md).

package/dist/ai/docs/nocobase/data-sources/main/oceanbase.md

@@ -0,0 +1,62 @@
+---
+pkg: "@nocobase/plugin-data-source-oceanbase"
+title: "Main data source - OceanBase"
+description: "Learn the supported version, plugin installation, usage, and field mapping for OceanBase as the NocoBase main database."
+keywords: "main data source,OceanBase,main database,field mapping,NocoBase"
+---
+
+# OceanBase
+
+## Introduction
+
+OceanBase can be used as the NocoBase main database. It stores NocoBase system-table data and business data in the main data source. Configure it when deploying NocoBase; it cannot be deleted after the application is running.
+
+| Setting | Description |
+| --- | --- |
+| Supported version | >= 4.3. |
+| Commercial editions | Enterprise. |
+| Database type | MySQL compatibility mode. |
+
+:::warning Note
+
+OceanBase is supported as the main database only in MySQL compatibility mode.
+
+:::
+
+## Plugin installation
+
+OceanBase is provided by `@nocobase/plugin-data-source-oceanbase` and requires a commercial license.
+
+## Usage
+
+1. Select or enter OceanBase connection settings when deploying NocoBase.
+2. After NocoBase starts, open **Data source management**, select **Main**, and manage collections and fields in the main database.
+3. To connect tables that already exist in the database, use **Sync from database** on the main-database management page.
+4. When configuring fields, use [Collections](../data-modeling/collection.md) and [Collection fields](../data-modeling/collection-fields/index.md) to choose Field types and Field interfaces.
+
+## Field type mapping
+
+When you create a field in NocoBase, NocoBase creates the corresponding OceanBase column. When you synchronize an existing table, NocoBase uses MySQL-compatible mapping to select a suitable Field type and Field interface. You can adjust the display interface in field configuration.
+
+| OceanBase type | NocoBase Field type | Available Field interfaces |
+| --- | --- | --- |
+| `TINYINT`, `SMALLINT`, `MEDIUMINT` | `integer`, `boolean`, `sort` | Integer, Sort, Checkbox, Switch, Select, Radio group. |
+| `INT`, `INTEGER` | `integer`, `unixTimestamp`, `sort` | Integer, Sort, Unix timestamp, Select, Radio group. |
+| `BIGINT` | `bigInt`, `snowflakeId`, `unixTimestamp`, `sort` | Integer, Sort, Unix timestamp, Created at, Updated at. |
+| `FLOAT`, `DOUBLE` | `float` | Number, Percent. |
+| `DECIMAL` | `decimal` | Number, Percent, Currency. |
+| `CHAR`, `VARCHAR` | `string`, `uuid`, `nanoid`, `encryption` | Input, Email, Phone, Password, Color, Icon, Select, Radio group, UUID, Nano ID. |
+| `TEXT` | `text` | Textarea, Markdown, Vditor, Rich text, URL. |
+| `DATE` | `dateOnly` | Date. |
+| `TIME` | `time` | Time. |
+| `DATETIME` | `datetimeNoTz`, `datetimeTz`, `date` | Date, Time, Created at, Updated at. |
+| `TIMESTAMP` | `datetimeTz`, `date` | Date, Time, Created at, Updated at. |
+| `JSON` | `json`, `array` | JSON. |
+
+:::warning Note
+
+Unsupported OceanBase types are shown separately in field configuration. They require development support before they can be used as normal NocoBase fields.
+
+:::
+
+For common configuration, see [Main database](./index.md).

package/dist/ai/docs/nocobase/data-sources/main/postgresql.md

@@ -0,0 +1,61 @@
+---
+pkg: "@nocobase/plugin-data-source-manager"
+title: "Main data source - PostgreSQL"
+description: "Learn the supported version, plugin installation, usage, and field mapping for PostgreSQL as the NocoBase main database."
+keywords: "main data source,PostgreSQL,main database,field mapping,NocoBase"
+---
+
+# PostgreSQL
+
+## Introduction
+
+PostgreSQL can be used as the NocoBase main database. It stores NocoBase system-table data and business data in the main data source. Configure the main database when deploying NocoBase; it cannot be deleted after the application is running.
+
+| Setting | Description |
+| --- | --- |
+| Supported version | >= 10. |
+| Commercial editions | Community, Standard, Professional, and Enterprise. |
+| Database type | PostgreSQL. |
+
+PostgreSQL supports inheritance collections, which are suitable for data models that need inheritance.
+
+## Plugin installation
+
+PostgreSQL is built in and does not require a separate plugin.
+
+## Usage
+
+1. Select or enter PostgreSQL connection settings when deploying NocoBase.
+2. After NocoBase starts, open **Data source management**, select **Main**, and manage collections and fields in the main database.
+3. To connect tables that already exist in the database, use **Sync from database** on the main-database management page.
+4. When configuring fields, use [Collections](../data-modeling/collection.md) and [Collection fields](../data-modeling/collection-fields/index.md) to choose Field types and Field interfaces.
+
+## Field type mapping
+
+When you create a field in NocoBase, NocoBase creates the corresponding PostgreSQL column. When you synchronize an existing table, NocoBase maps the PostgreSQL column type to a suitable Field type and Field interface. You can adjust the display interface in field configuration.
+
+| PostgreSQL type | NocoBase Field type | Available Field interfaces |
+| --- | --- | --- |
+| `BOOLEAN` | `boolean` | Checkbox, Switch. |
+| `SMALLINT`, `INTEGER`, `SERIAL`, `SMALLSERIAL` | `integer`, `boolean`, `sort` | Integer, Sort, Checkbox, Switch, Select, Radio group. |
+| `BIGINT`, `BIGSERIAL` | `bigInt`, `sort` | Integer, Sort, Checkbox, Switch, Select, Radio group, Unix timestamp, Created at, Updated at. |
+| `REAL` | `float` | Number, Percent. |
+| `DOUBLE PRECISION` | `double` | Number, Percent. |
+| `DECIMAL`, `NUMERIC` | `decimal` | Number, Percent, Currency. |
+| `VARCHAR`, `CHAR` | `string`, `password`, `uuid`, `nanoid` | Input, Email, Phone, Password, Color, Icon, Select, Radio group, UUID, Nano ID. |
+| `TEXT` | `text`, `json` | Textarea, Markdown, Vditor, Rich text, URL, JSON. |
+| `UUID` | `uuid` | UUID. |
+| `JSON`, `JSONB` | `json` | JSON. |
+| `TIMESTAMP` | `date` | Date, Time, Created at, Updated at. |
+| `DATE` | `dateOnly` | Date. |
+| `TIME` | `time` | Time. |
+| `POINT`, `LINESTRING`, `POLYGON`, `CIRCLE` | `point`, `lineString`, `polygon`, `circle` | Point, Line string, Polygon, Circle, JSON. |
+| `ARRAY` | `array` | Multiple select, Checkbox group. |
+
+:::warning Note
+
+Unsupported PostgreSQL types are shown separately in field configuration. They require development support before they can be used as normal NocoBase fields.
+
+:::
+
+For common configuration, see [Main database](./index.md).

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

@@ -8,12 +8,53 @@ For file types that do not support native preview, you can enable preview functi
 
 Currently, NocoBase provides the following file preview plugins:
 
-* [Office File Preview Plugin](../file-preview/ms-office.md)
+- [Office File Preview Plugin](./ms-office.md)
 
-## PDF preview with external storage
+## PDF preview mechanism
 
-NocoBase previews PDFs through a browser iframe. Some browsers or PDF readers may support scripts, forms, or other interactive content inside PDF files. If the previewed file comes from an untrusted source, pay attention to the security boundary for script execution.
+NocoBase selects the PDF preview method according to whether the file URL has the same origin as the current page:
+
+| File URL | Common storage type | Preview method | CORS requirement |
+| --- | --- | --- | --- |
+| Same origin as NocoBase | Local storage | NocoBase reads the file and renders it with the built-in PDF.js viewer | No cross-origin CORS involved |
+| Cross-origin | Third-party storage such as OSS, S3, COS, or a CDN | The browser opens the file URL in an iframe | The iframe preview itself does not require CORS |
+
+:::tip What determines the preview method
+
+The preview method depends on whether the file URL is same-origin, not directly on the storage engine name. Local storage served from a separate file domain is treated as cross-origin. Third-party storage accessed through a same-origin NocoBase proxy is treated as same-origin.
+
+:::
+
+### Local storage or a same-origin URL
+
+Local storage URLs usually start with `/storage/uploads/` and have the same origin as the NocoBase page. During preview, NocoBase reads the PDF data and passes it to the built-in PDF.js viewer to render pages and text.
+
+This method does not depend on the browser's built-in PDF reader. Even if the file response uses `Content-Disposition: attachment` for security, NocoBase can still read and render the file in the preview component. The file URL must remain accessible with the current login state.
+
+### Third-party storage or a cross-origin URL
+
+Third-party storage such as OSS, S3, COS, and CDNs usually uses a separate domain. NocoBase places this PDF URL in an iframe, so the browser and the storage service's response headers determine the result.
+
+To open a PDF in the iframe, the storage service should normally return `Content-Type: application/pdf` and must not force a download with `Content-Disposition: attachment`. If the response requests a download, the browser downloads the file directly and NocoBase cannot override that behavior in the frontend.
+
+Loading a cross-origin PDF in an iframe does not itself require CORS. However, the download button in the preview component reads the file with `fetch` and creates a Blob, so cross-origin downloads still require the storage service to allow CORS requests from the NocoBase site.
+
+### Notes for Aliyun OSS
+
+In some cases, the default Aliyun OSS domain forces a download by returning `Content-Disposition: attachment` and `x-oss-force-download: true`. Images may still preview normally, while a PDF placed in an iframe is downloaded.
+
+You can usually resolve this by binding a custom domain to the bucket and configuring NocoBase to access files through that domain. See [Aliyun OSS troubleshooting](../storage/aliyun-oss.md#common-issues) for configuration and diagnostic steps.
+
+### Security boundary for cross-origin previews
+
+Some browsers or PDF readers may support scripts, forms, or other interactive content inside PDF files. If the previewed file comes from an untrusted source, pay attention to the security boundary for script execution.
 
 We recommend isolating the file access domain from the NocoBase site and API domains. For example, serve files from OSS, S3, COS, or a CDN through a dedicated domain, instead of sharing the same origin with the NocoBase frontend or API.
 
 If the file domain is different from the API domain, and the API does not enable CORS access for the file domain, scripts running in the PDF preview environment are usually restricted by the browser's same-origin policy. They cannot directly read the NocoBase page, browser storage, or API responses.
+
+## Related links
+
+- [Office File Preview Plugin](./ms-office.md)
+- [Aliyun OSS](../storage/aliyun-oss.md)
+- [S3 Pro](../storage/s3-pro.md)

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

@@ -7,7 +7,7 @@ A storage engine based on Aliyun OSS. Before use, you need to prepare the releva
 
 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 OSS bucket itself is private, the built-in Aliyun OSS 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).
+Even if the OSS bucket itself is private, the built-in Aliyun OSS engine does not generate temporary signed URLs for file access. If you need private access, use [S3 Pro](./s3-pro.md). If historical files already exist, see [Migrate to S3 Pro](./migrate-to-s3-pro.md).
 
 :::
 
@@ -18,9 +18,13 @@ Even if the OSS bucket itself is private, the built-in Aliyun OSS engine does no
 
 
 :::info{title=Note}
-This section only introduces the specific parameters for the Aliyun OSS storage engine. For general parameters, please refer to [General Engine Parameters](./index#引擎通用参数).
+This section only introduces the specific parameters for the Aliyun OSS storage engine. For general parameters, see [General Engine Parameters](./index.md#common-parameters).
 :::
 
+### Base URL
+
+Enter the file access URL prefix, such as a custom domain bound to the current bucket: `https://oss.example.com`. Accessing PDFs through the default Aliyun OSS domain may cause the browser to download them. We recommend binding a custom domain first. See [Common issues](#common-issues) below for details.
+
 ### Region
 
 Enter the region of the OSS storage, for example: `oss-cn-hangzhou`.
@@ -43,4 +47,97 @@ Enter the name of the OSS bucket.
 
 ### Timeout
 
-Enter the timeout for uploading to Aliyun OSS, in milliseconds. The default is `60000` milliseconds (i.e., 60 seconds).
+Enter the timeout for uploading to Aliyun OSS, in milliseconds. The default is `60000` milliseconds (i.e., 60 seconds).
+
+## Common issues
+
+### A PDF is downloaded instead of previewed
+
+NocoBase previews cross-origin PDFs in an iframe. The browser accesses the OSS file URL directly, so the OSS response headers determine whether the file is displayed or downloaded.
+
+If a PDF is downloaded from the iframe, inspect the file request in the browser developer tools. A typical problematic response looks like this:
+
+```http
+Content-Type: application/pdf
+Content-Disposition: attachment
+x-oss-force-download: true
+```
+
+`Content-Type: application/pdf` identifies the file correctly, but `Content-Disposition: attachment` instructs the browser to download it. The default Aliyun OSS domain forces downloads in some cases. See the official Aliyun documentation: [How do I configure a PDF file to be previewed instead of downloaded?](https://help.aliyun.com/zh/oss/user-guide/how-do-i-configure-an-object-to-be-previewed-instead-of-downloaded).
+
+We recommend the following configuration:
+
+1. Follow [Access OSS resources through a custom domain](https://help.aliyun.com/zh/oss/user-guide/access-buckets-via-custom-domain-names) to bind a custom domain to the bucket
+2. Configure DNS and the HTTPS certificate, then verify that the custom domain can access the file directly
+3. Configure the access URL for the NocoBase storage engine in use
+
+For step 3:
+
+- With the built-in **Aliyun OSS** engine, set **Base URL** to the bound custom domain, such as `https://oss.example.com`
+- With [S3 Pro](./s3-pro.md) connected to Aliyun OSS, the upload endpoint can continue to use the regional OSS endpoint; set the access endpoint to the custom domain and set `Full access URL style` to `Ignore`
+
+Upload a new PDF to verify the configuration. If an existing file record stores a complete URL, also make sure that the URL returned to the frontend now uses the custom domain.
+
+:::tip Check the response headers
+
+Previewing a cross-origin PDF in an iframe does not itself require CORS. Whether the PDF can be displayed inline primarily depends on `Content-Type` and `Content-Disposition`. This is separate from the CORS requirement for the download button described below.
+
+:::
+
+### An image previews correctly, but the download button reports a CORS error
+
+Images are usually previewed with `<img>`, and cross-origin PDFs are previewed with an iframe. Both can display resources without CORS response headers. The download button, however, reads the file with `fetch` and creates a Blob for the browser to download. This request is subject to the browser's same-origin policy.
+
+The following console error means that OSS did not return `Access-Control-Allow-Origin` for the current NocoBase site:
+
+```text
+Access to fetch at 'https://oss.example.com/path/to/file.jpg' from origin
+'https://example.com' has been blocked by CORS policy:
+No 'Access-Control-Allow-Origin' header is present on the requested resource.
+```
+
+Follow the official Aliyun guide [Configure cross-origin resource sharing](https://help.aliyun.com/zh/oss/user-guide/configure-cross-origin-resource-sharing) and create a CORS rule for the bucket. For downloads from the preview component, use values like these:
+
+| Setting | Recommended value |
+| --- | --- |
+| Allowed Origins | The complete NocoBase origin, such as `https://example.com` |
+| Allowed Methods | `GET`, `HEAD` |
+| Allowed Headers | `*` |
+| Expose Headers | `ETag`, `Content-Disposition` |
+| MaxAgeSeconds | `600` |
+
+If S3 Pro also uploads files directly from the browser, add methods such as `PUT` and `POST` according to the actual upload requests shown in the browser Network panel, or create a separate upload rule.
+
+After saving the rule, request the file again with the NocoBase site origin. The response should include at least:
+
+```http
+Access-Control-Allow-Origin: https://example.com
+Access-Control-Allow-Methods: GET, HEAD
+```
+
+The browser may already have cached the response used for the image preview. That request did not include an `Origin` header, and the cached response may not contain `Access-Control-Allow-Origin`. If downloading still fails after you configure CORS, clear the browser cache for the file or select **Disable cache** in the developer tools and try again.
+
+### Verify the response headers
+
+Use `curl` to simulate a cross-origin request from the NocoBase site. Replace the example origin, file URL, and signature parameters with the actual values:
+
+```bash
+curl -sS -D - -o /dev/null \
+  -H 'Origin: https://example.com' \
+  'https://oss.example.com/path/to/file.pdf?<signed-query>'
+```
+
+Check the following results:
+
+- PDF preview returns `Content-Type: application/pdf` without `Content-Disposition: attachment`
+- Cross-origin download returns an `Access-Control-Allow-Origin` matching the NocoBase site
+- The actual file URL uses the custom domain instead of the default `*.oss-cn-*.aliyuncs.com` domain
+
+It is normal for a request without an `Origin` header to omit CORS response headers. Keep the `Origin` header in the example when verifying CORS.
+
+## Related links
+
+- [File Preview](../file-preview/index.md)
+- [S3 Pro](./s3-pro.md)
+- [Migrate to S3 Pro](./migrate-to-s3-pro.md)
+- [Storage Engines](./index.md)

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