@nocobase/plugin-ai 2.2.0-beta.9 → 3.0.0-alpha.1

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/stable-url.md

@@ -0,0 +1,87 @@
+---
+pkg: '@nocobase/plugin-file-manager'
+title: "Stable URL (proxy URL)"
+description: "Explains NocoBase stable file URLs, access permissions, redirects, temporary Office preview URLs, and behavior across file-related features."
+keywords: "stable URL,proxy URL,permanent URL,file access,file permissions,Office preview,NocoBase"
+---
+
+# Stable URL
+
+Files managed by a NocoBase storage engine are accessed through a **stable URL**. The URL first reaches NocoBase, where the file record and access permissions are checked, and then redirects to the actual URL generated by the storage engine.
+
+## URL format
+
+```text
+/files/<app>/<dataSource>/<collection>/<id><extname>
+```
+
+For example:
+
+```text
+/files/main/main/attachments/42.pdf
+```
+
+When `APP_PUBLIC_PATH=/nocobase` is configured, the URL starts with `/nocobase/files/`. The path identifies the app, data source, file collection, record ID, and extension. The ID and extension cannot be changed after creation, which keeps the URL stable for the lifetime of the record.
+
+## URL variants
+
+| Purpose | URL | Behavior |
+|---|---|---|
+| Open or embed | `/files/.../42.pdf` | Checks permission and redirects to the actual file URL |
+| Preview | `/files/.../42.png?preview=1` | Redirects to the preview or thumbnail URL |
+| Download | `/files/.../42.pdf?download=1` | Redirects with download semantics |
+| Office preview | `/files/.../42.xlsx?temporaryAccessToken=...` | Allows Microsoft Office Online Viewer to fetch one file for a short time |
+
+:::tip
+
+Use the `url` and `preview` values returned by NocoBase. Application code normally should not construct `/files` URLs or their query parameters.
+
+:::
+
+## Behavior across NocoBase
+
+- Attachment fields and file collections return stable URLs after upload and when records are queried
+- [HTTP API](./http-api.md) responses no longer expose local paths, storage domains, or presigned download URLs
+- Markdown uploads store the stable URL, including files in private S3, OSS, COS, or S3 Pro storage
+- Attachment URL fields store a stable URL for managed uploads, while manually entered external URLs remain unchanged
+- Image, PDF, audio, video, and text previews use the stable URL and the current NocoBase login session
+- Public forms grant limited access to files uploaded in the current public-form browser session; this does not create a generally public link
+
+## Office preview
+
+Microsoft Office Online Viewer fetches the file from Microsoft servers and cannot use the user's NocoBase cookie. When the user opens an Office preview, NocoBase first checks the user's file permission and then issues a temporary URL for that file.
+
+The URL is valid for 10 minutes by default. `TEMPORARY_FILE_ACCESS_EXPIRES_IN` may be set from 5 to 10 minutes. It is requested again when the preview is reopened and must never be saved in an attachment field, Markdown content, or a business record.
+
+## Permissions and redirects
+
+Logged-in requests use the current app credentials and role. After permission is granted, NocoBase responds with `302` and redirects to the local or object-storage URL.
+
+Stable URLs support `GET` and `HEAD`. Other methods return `405`. A command-line client must follow redirects, for example:
+
+```bash
+curl -L \
+  -H "Authorization: Bearer <JWT>" \
+  "https://example.com/files/main/main/attachments/42.pdf"
+```
+
+## Important notes
+
+- Stable does not mean public; recipients still need permission to view the file
+- Deleting the record or changing its app, data source, or collection context invalidates the old URL
+- Do not persist `temporaryAccessToken` or use it as a sharing link
+- Do not cache the `302 Location` as a permanent URL because storage signatures can expire
+- Do not rewrite the app, data source, collection, ID, or extension in the path
+- Reverse proxies must forward the `/files/` route under `APP_PUBLIC_PATH` to NocoBase. For subpath deployments, keep a compatible root-level `/files/` route as well. Configurations generated by the NocoBase CLI include both routes automatically
+- Deployments where the pages access the API cross-origin (with `API_BASE_URL` pointing to another origin) must add the page origin to `CORS_ORIGIN_WHITELIST`; otherwise the login cookie is never stored and stable URLs return `403` for lack of credentials. See [Environment Variables](../get-started/installation/env.md#api_base_url)
+- Use a different `hostname` for each independent NocoBase service instead of separating services only by port. Browser cookies are not isolated by port; see [Production Environment Deployment](../get-started/deployment/production.md)
+- Sub-apps in the same NocoBase deployment are distinguished by app name and do not need separate hostnames. However, an independent service on another port still needs hostname isolation if it contains a main app or sub-app with the same name
+- Custom `fetch()` code may also need object-storage CORS after following the redirect
+- Use a dedicated sharing or public-access feature when a long-lived public link is required
+
+## Related links
+
+- [HTTP API](./http-api.md) — Upload and query files through the API
+- [File preview](./file-preview/index.md) — Preview behavior for supported file types
+- [Office file preview](./file-preview/ms-office.md) — Configure Microsoft Office Online Viewer
+- [Storage engines](./storage/index.md) — Configure local and object storage

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/local.md

@@ -9,6 +9,8 @@ Local Storage does not support private access. After a file is uploaded, NocoBas
 
 If you need to store contracts, identity documents, internal materials, or other files that should not be public, use [S3 Pro](./s3-pro). If historical files already exist, see [Migrate to S3 Pro](./migrate-to-s3-pro.md).
 
+If you are not using Docker or the official nginx configuration and access local uploaded files through a custom proxy, make sure the `/storage/uploads/` path sets `X-Content-Type-Options: nosniff` and returns active content files such as `html`, `svg`, `xhtml`, and `pdf` as attachments. For details, see [Security guide: File storage](../../security/guide.md#file-storage).
+
 :::
 
 ## Configuration Parameters
@@ -26,4 +28,4 @@ This section only introduces parameters specific to the local storage engine. Fo
 Represents both the relative path for file storage on the server and the URL access path. For example, "`user/avatar`" (without leading or trailing slashes) represents:
 
 1. The relative path on the server where uploaded files are stored: `/path/to/nocobase-app/storage/uploads/user/avatar`.
-2. The URL prefix for accessing the files: `http://localhost:13000/storage/uploads/user/avatar`.
+2. The URL prefix for accessing the files: `http://localhost:13000/storage/uploads/user/avatar`.

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