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

package/dist/ai/docs/nocobase/interface-builder/ui-layout/mobile.md

@@ -0,0 +1,133 @@
+---
+title: "Mobile Layout"
+description: "Learn about NocoBase mobile navigation, page building, desktop preview, subpage interactions, routes, and permissions."
+keywords: "mobile layout,mobile pages,bottom navigation,mobile preview,mobile routes,UI Editor,NocoBase"
+---
+
+# Mobile Layout
+
+In NocoBase, the **mobile layout** is used to build dedicated navigation and pages for mobile devices. It is available at `/mobile` by default and uses a bottom tab bar as its primary navigation, making it more suitable for data entry, lookup, approval, and task processing on a phone.
+
+The mobile and desktop layouts use the same data sources and business data, but their menus, routes, and page content are configured separately. This lets you reorganize pages around mobile workflows without being constrained by the desktop page structure.
+
+<!-- Add a full-page screenshot of the mobile layout on a physical device -->
+
+## Open and preview the mobile layout
+
+By default, you can click 「Mobile」 in Settings to open the layout, or visit `/mobile` directly.
+
+It is best to build pages in a desktop browser. The desktop view provides a mobile preview area and a toolbar at the top:
+
+- 「UI Editor」 turns UI building mode on or off.
+- 「Tablet preview」 checks the display on wider mobile devices.
+- 「Mobile preview」 restores the phone-sized preview area.
+- 「QR code」 opens the current mobile URL on a phone.
+
+![20260715221712](https://static-docs.nocobase.com/20260715221712.png)
+
+After building the pages on a computer, scan the QR code and check them on a physical device. Pay particular attention to navigation, scrolling, form input, pop-up pages, and safe areas.
+
+## Build mobile navigation
+
+The mobile layout uses a bottom tab bar as its primary navigation. Primary navigation currently supports mainly pages and links.
+
+### Add a page
+
+1. Open 「UI Editor」.
+2. Click the add button on the right side of the bottom tab bar.
+3. Select 「Page」.
+4. Enter a page title and select an icon.
+5. Submit the form to open the new page, then continue adding page content.
+
+![20260715221823_rec_](https://static-docs.nocobase.com/20260715221823_rec_.gif)
+
+### Add a link
+
+To open an internal or external URL, select 「Link」 and configure its title, icon, and URL.
+
+A link can open in the current window or a new window, depending on its configuration.
+
+![20260715221950](https://static-docs.nocobase.com/20260715221950.png)
+
+### Arrange navigation
+
+In UI building mode, drag bottom tabs to reorder them. You can also edit a tab's title and icon, configure linkage rules, copy its UID, or delete it.
+
+To view, show, hide, or delete mobile routes in one place, open 「Settings / Routes / Mobile routes」.
+
+![20260715222113_rec_](https://static-docs.nocobase.com/20260715222113_rec_.gif)
+
+## Build a mobile page
+
+Create and open a mobile page before adding blocks to it. The approach to building page content is essentially the same as on desktop: use [blocks](../blocks/index.md), [fields](../fields/index.md), and [actions](../actions/index.md) to organize business content. However, mobile navigation and some component interactions are adjusted for smaller screens.
+
+### Add page content
+
+1. Open the mobile page you want to build.
+2. Make sure 「UI Editor」 is enabled.
+3. Click 「Add block」 on the page.
+4. Select a table, form, details, filter, or another block.
+5. Continue configuring fields, actions, and block settings.
+
+![20260715222230_rec_](https://static-docs.nocobase.com/20260715222230_rec_.gif)
+
+### Use page tabs
+
+A mobile page can also use tabs. If multiple pieces of content belong under the same navigation entry but remain relatively independent, place them in separate tabs.
+
+1. Open the page settings and enable 「Enable page tabs」. You can also edit the page under 「Settings / Routes / Mobile routes」 and select 「Enable page tabs」.
+2. Turn on 「UI Editor」.
+3. Click 「Add tab」 on the right side of the page tab bar.
+4. Add the tab, then configure its name and page content.
+
+If a mobile page contains only a small amount of content, use a single page. You do not need to enable tabs.
+
+![20260715222354_rec_](https://static-docs.nocobase.com/20260715222354_rec_.gif)
+
+### Mobile interactions for common components
+
+Common components adjust their arrangement and interactions for the mobile layout. For instance, multi-column content automatically switches to a single column that is easier to browse vertically; selection and date-time fields use mobile-friendly pickers; and filters, associated record selection, and subpages use interfaces designed for touch interaction.
+
+Tables remain tables on mobile, with horizontal scrolling for columns that extend beyond the screen. Any additional mobile behavior depends on the support provided by each block.
+
+## Pages and subpages
+
+Content opened from view, edit, associated record selection, and similar actions appears as a mobile subpage. The subpage provides a back button that returns you to the previous page.
+
+When you open a deeper subpage, the bottom tab bar is hidden to leave more room for the current content. It reappears when you close the subpage or return to the previous level.
+
+When switching between bottom tabs, the state of open pages is preserved, making it easier to move between mobile tasks.
+
+![20260715222828_rec_](https://static-docs.nocobase.com/20260715222828_rec_.gif)
+
+## Manage routes and permissions
+
+Mobile routes can be maintained in the [Route Manager](../../routes/index.md). Open 「Settings / Routes / Mobile routes」 to add, edit, delete, show, or hide pages and links, or to configure tabs for a page.
+
+Mobile route access permissions are configured separately from desktop permissions. Under role permissions, open 「Mobile routes」 and select the pages the current role can access. See [Permission configuration](../../users-permissions/acl/permissions.md) for details.
+
+![20260715223016_rec_](https://static-docs.nocobase.com/20260715223016_rec_.gif)
+
+![20260715223106_rec_](https://static-docs.nocobase.com/20260715223106_rec_.gif)
+
+## Relationship with the desktop layout
+
+You can build separate desktop and mobile pages from the same data table. For instance, a desktop page may use a table with many fields for data processing, while a mobile page may use a simpler list or form for on-site data entry.
+
+The two layouts do not synchronize pages automatically. Changes to desktop pages, menus, or routes do not update the mobile configuration, and mobile changes do not affect desktop pages.
+
+:::tip Recommendation
+
+If mobile users only need occasional access to desktop pages, try the responsive [desktop layout](./desktop.md) first. Build a separate mobile layout only when you need dedicated navigation and page workflows for mobile devices.
+
+:::
+
+## Related links
+
+- [UI layout overview](./index.md) — Compare desktop and mobile layout use cases
+- [Desktop layout](./desktop.md) — Use the default desktop layout and its narrow-screen responsiveness
+- [Blocks](../blocks/index.md) — Add business content to mobile pages
+- [Fields](../fields/index.md) — Configure mobile forms and data display fields
+- [Actions](../actions/index.md) — Configure actions on mobile pages
+- [Route Manager](../../routes/index.md) — Manage mobile pages, links, and tabs
+- [Permission configuration](../../users-permissions/acl/permissions.md) — Control which mobile routes each role can access

package/dist/ai/docs/nocobase/multi-app/multi-app-vs-multi-portal-vs-multi-space.md

@@ -0,0 +1,159 @@
+# Multi-portal, Multi-app, and Multi-space
+
+NocoBase provides three capabilities: Multi-portal, Multi-app, and Multi-space.
+
+They solve problems at different levels. They can be used independently or together.
+
+## Key differences
+
+| Capability | Multi-portal | Multi-app | Multi-space |
+|------|------|------|------|
+| What problem it solves | Provides multiple access entries | Splits business into multiple systems | Isolates business data |
+| Core focus | Where users enter | How the system is divided | Who the data belongs to |
+| Data | Shared | Independent by default | Isolated |
+| Pages and menus | Independent | Independent | Shared |
+| Plugin configuration | Shared | Independent | Shared |
+| User system | Shared | Can be shared through SSO | Shared |
+| Typical scenarios | Different roles need different entries | Different businesses need independent management | Multiple organizations, stores, or tenants |
+| Can be combined | Yes | Yes | Yes |
+
+## Multi-portal
+
+Multi-portal provides multiple access entries within the same application.
+
+For example:
+
+```text
+ERP App
+
+├─ Admin Portal (/v/admin)
+├─ Store Portal (/v/store)
+├─ Distributor Portal (/v/dealer)
+└─ Mobile Portal (/v/mobile)
+```
+
+Features:
+
+- Uses the same application
+- Shares the same data
+- Shares plugin configuration
+- Pages and menus can be configured independently
+
+Suitable for scenarios where different roles need different access entries, such as:
+
+- Administrators
+- Employees
+- Customers
+- Distributors
+
+## Multi-app
+
+Multi-app splits business into multiple independent applications.
+
+For example:
+
+```text
+Group System
+
+├─ CRM
+├─ ERP
+├─ OA
+└─ Analytics
+```
+
+Features:
+
+- Each app is managed independently
+- Independent plugin configuration
+- Independent database connection
+- Independent upgrade and maintenance
+
+Suitable for:
+
+- Splitting large business systems
+- Multi-team collaborative development
+- Batch creation of apps for SaaS platforms
+- Independent apps for different customers
+
+## Multi-space
+
+Multi-space isolates business data within the same application.
+
+For example:
+
+```text
+Store Management App
+
+Spaces
+├─ Beijing Store
+├─ Shanghai Store
+└─ Shenzhen Store
+```
+
+Features:
+
+- Shared pages
+- Shared menus
+- Shared workflows
+- Shared configuration
+- Isolated data
+
+For tables that have a space field enabled, the system automatically filters data according to the current space.
+
+From the user's perspective:
+
+- The Beijing store can only see Beijing store data
+- The Shanghai store can only see Shanghai store data
+- The Shenzhen store can only see Shenzhen store data
+
+But all stores still use the same system.
+
+## Relationship among the three
+
+These three capabilities do not conflict. They work on different dimensions.
+
+They can be used together:
+
+```text
+Group System
+
+CRM App
+├─ Admin Portal
+├─ Sales Portal
+└─ Customer Portal
+
+Spaces
+├─ Beijing Branch
+├─ Shanghai Branch
+└─ Shenzhen Branch
+```
+
+Conceptually:
+
+```text
+Portal
+    ↓
+Where users enter the system
+
+App
+    ↓
+How the system is divided
+
+Space
+    ↓
+Who the data belongs to
+```
+
+## How to choose
+
+If you only want to provide different entries for different roles, choose **Multi-portal**.
+
+If you want to split business into multiple independent systems, choose **Multi-app**.
+
+If you want to isolate data for different organizations or tenants within the same system, choose **Multi-space**.
+
+In real projects, these three capabilities are usually combined rather than used as substitutes for one another.
+
+In one sentence:
+
+> Multi-portal solves entry points, Multi-app solves system splitting, and Multi-space solves data isolation.

package/dist/ai/docs/nocobase/multi-app/multi-portal/index.md

@@ -0,0 +1,195 @@
+---
+title: "Multi-portal"
+description: "Learn the concept, use cases, configuration, and relationship between Multi-portal, Multi-app, and Multi-space in NocoBase."
+keywords: "workspace, portal, multi-portal, NocoBase"
+pkg: "@nocobase/plugin-multi-portal"
+---
+
+# Multi-portal
+
+## What is a portal
+
+A portal is used to provide multiple access entries within the same application.
+
+Each portal can have its own:
+
+- Pages
+- Menus
+- Navigation structure
+- Layout
+- Permission settings
+
+The Multi-portal plugin provides the following capabilities:
+
+- Portal management
+- Portal switching
+- Portal permission control
+
+With these capabilities, you can provide different experiences for different roles while sharing the same data and business capabilities.
+
+## Why use portals
+
+In real business scenarios, different roles often need different interfaces.
+
+For example, in a retail management system:
+
+```text
+Retail Management System
+
+├─ Headquarters Portal
+├─ Store Portal
+├─ Distributor Portal
+└─ Mobile Portal
+```
+
+Headquarters staff focus on:
+
+- Product management
+- Inventory management
+- Data analysis
+
+Store staff focus on:
+
+- Cashiering
+- Stocktaking
+- Order processing
+
+Distributors focus on:
+
+- Purchasing
+- Reconciliation
+- Shipment status
+
+Although everyone uses the same system, different roles do not need to see the same menus and pages.
+
+That is exactly the problem portals solve.
+
+## Relationship between portals and menus
+
+Each portal has its own menu tree.
+
+Menus in different portals do not affect each other.
+
+For example:
+
+```text
+Headquarters Portal
+├─ Product Management
+├─ Supply Chain Management
+└─ Data Analysis
+
+Store Portal
+├─ Cashiering
+├─ Order Management
+└─ Stocktaking
+```
+
+## Relationship between portals and pages
+
+Pages belong to their respective portals.
+
+The same page can also be shown only in specific portals.
+
+This makes it possible to design completely different workflows for different roles.
+
+## Relationship between portals and permissions
+
+Portals themselves can be configured with access permissions.
+
+Only authorized users can access the corresponding portal.
+
+Unauthorized portals:
+
+- Do not appear in the switcher list
+- Cannot be accessed directly
+
+## Portal management
+
+After enabling the Multi-portal plugin, the system provides two built-in portals by default:
+
+| Portal | Path | Purpose |
+|----------|----------|----------|
+| Desktop | `/v/admin` | Desktop entry |
+| Mobile | `/v/mobile` | Mobile entry |
+
+### Built-in portals
+
+![2026-07-10-08-01-50](https://static-docs.nocobase.com/2026-07-10-08-01-50.png)
+
+### Desktop portal
+
+Access path:
+
+```text
+/v/admin
+```
+
+![2026-07-10-08-03-12](https://static-docs.nocobase.com/2026-07-10-08-03-12.png)
+
+### Mobile portal
+
+Access path:
+
+```text
+/v/mobile
+```
+
+![2026-07-10-08-04-59](https://static-docs.nocobase.com/2026-07-10-08-04-59.png)
+
+## Create a portal
+
+In addition to the built-in portals, you can create more portals based on business needs.
+
+For example:
+
+- Store portal
+- Distributor portal
+- Customer service portal
+- Data analysis portal
+
+After creation, you can configure:
+
+- Pages
+- Menus
+- Permissions
+- Navigation
+
+![2026-07-10-08-06-15](https://static-docs.nocobase.com/2026-07-10-08-06-15.png)
+
+## Switch portals
+
+Users can quickly switch between portals through the portal switcher.
+
+### Switch portals within a single app
+
+Add it to the portal switcher panel in the upper-left corner
+
+![2026-07-10-08-20-41](https://static-docs.nocobase.com/2026-07-10-08-20-41.png)
+
+Add it to the action panel block
+
+![2026-07-10-08-21-15](https://static-docs.nocobase.com/2026-07-10-08-21-15.png)
+
+### Switch portals across apps
+
+After enabling Multi-app and configuring SSO, users can also switch between portals across different apps through the portal switcher.
+
+Add it to the portal switcher panel in the upper-left corner
+
+![2026-07-10-08-25-19](https://static-docs.nocobase.com/2026-07-10-08-25-19.png)
+
+Add it to the action panel block
+
+![2026-07-10-08-25-50](https://static-docs.nocobase.com/2026-07-10-08-25-50.png)
+
+## Portal permissions
+
+You can control which portals a user can access through role permissions.
+
+Unauthorized portals do not appear in the portal switcher list, and users cannot access those entries directly.
+
+![2026-07-10-08-29-22](https://static-docs.nocobase.com/2026-07-10-08-29-22.png)
+
+## Related links
+
+For the differences and combination patterns among Multi-portal, Multi-app, and Multi-space, see: [Multi-portal, Multi-app, and Multi-space](../multi-app-vs-multi-portal-vs-multi-space.md).

package/dist/ai/docs/nocobase/{quickstart → nocobase-cli}/index.md

@@ -1,4 +1,4 @@
-# Quick start
+# NocoBase CLI Overview
 
 If this is your first time using this CLI, you don’t need to memorize all the commands at the beginning. Use `nb init --ui` to install an application first, and then continue looking at the rest according to the scenario.
 
@@ -20,7 +20,7 @@ Keep this in mind first, and the subsequent documents will be much smoother.
 
 If you're not sure where to start, it's usually easiest to follow this path:
 
-1. First read [Installation using CLI (recommended)](./installation/cli.md) and complete `nb init` once.
+1. First read [Install using CLI](./installation/cli.md) and complete `nb init` once.
 2. After the application is saved as env, look at [Multiple Environment Management](./operations/multi-environment.md) to confirm the current env, switch env, and check the status.
 3. For daily startup, stop, log and upgrade, continue to see [Manage Application](./operations/manage-app.md).
 4. Before making upgrades, migrations or important changes, see [Backup and Restore](./operations/backup-restore.md).
@@ -32,8 +32,8 @@ The first three steps cover most usage scenarios.
 
 | I want... | Where to look |
 | --- | --- |
-| There is no application yet, first install a new NocoBase and save it as CLI env | [Install using CLI (recommended)](./installation/cli.md) |
-| Already have a running NocoBase and want to access CLI management | [Install using CLI (recommended)](./installation/cli.md) |
+| There is no application yet and you want to install a new NocoBase and save it as a CLI env | [Install using CLI](./installation/cli.md) |
+| You already have a running NocoBase and want to bring it under CLI management | [Install using CLI](./installation/cli.md) |
 | Gradually migrate old installation methods to CLI | [Migrate from old installation methods to CLI](./installation/migration.md) |
 | See which envs are saved locally, switch the current env, and check the status | [Multiple environment management](./operations/multi-environment.md) |
 | Start, stop, restart the application, view logs, or continue the upgrade | [Manage Application](./operations/manage-app.md) |
@@ -44,11 +44,11 @@ The first three steps cover most usage scenarios.
 
 ## When to look at the command reference
 
-This set of quick start documents is more "what do I want to do now". If you already know which command you want to execute and just want to continue to see the complete parameters, just go to [NocoBase CLI Command Reference](../api/cli/index.md).
+This set of quick start documents is more about "what do I want to do now". If you already know which command you want to run and only want the full parameters, go straight to [NocoBase CLI Command Reference](../api/cli/index.md).
 
 The default suggestions are:
 
-- First use the Quick Start document to establish a sense of path
+- First use this overview and the quick start documents to establish a sense of path
 - Then check the parameter details on the specific command page
 
 This makes it easier to get started than reading the complete command tree at first glance.

package/dist/ai/docs/nocobase/{quickstart → nocobase-cli}/installation/cli.md

@@ -1,4 +1,4 @@
-# Install using CLI (recommended)
+# Install using CLI
 
 After NocoBase 2.1.0, the official CLI-based installation and management method is provided. You can use it to complete installation, connection, upgrade and daily maintenance, and you can also prepare a connectable and operable environment for AI Agent.
 
@@ -9,7 +9,7 @@ Only executed when installing the CLI for the first time.
 First install the CLI globally:
 
 ```bash
-npm install -g @nocobase/cli@beta
+npm install -g @nocobase/cli
 nb --version
 ```
 
@@ -23,12 +23,6 @@ nb session setup
 
 :::
 
-If you plan to use the Chinese interface for a long time, it is usually enough to set the locale first:
-
-```bash
-nb config set locale zh-CN
-```
-
 The CLI checks for self-updates by default. You can adjust the update strategy according to your own habits:
 
 - `prompt`: Prompt when a new version is found
@@ -41,6 +35,8 @@ nb config set update.policy auto
 nb config set update.policy off
 ```
 
+Self-update is only supported when the CLI is managed by a standard global npm, pnpm, or yarn install. If you are running from source or from a local project dependency tree, use [`nb self check`](../../api/cli/self/check.md) to see the detected install method and update that parent project instead.
+
 If you are going to deploy NocoBase to the server and want to open the `nb init --ui` wizard from a remote browser, it is recommended to first change the CLI's default host to the current server IP:
 
 ```bash
@@ -54,7 +50,7 @@ Replace `<server-ip>` with the actual IP of the current server that is accessibl
 
 Generally speaking:
 
-- `default-ui-host` is used for the default listening address of `nb init --ui` when starting the wizard page
+- `default-ui-host` is used to generate the browser-accessible URL for the `nb init --ui` wizard; the wizard service itself always listens on `0.0.0.0`
 - `default-api-host` for the API address generated by default on new installations
 
 If deployed on a server, both values ​​should usually be changed to IPs accessible to the current server, rather than continuing to use the default local address.

package/dist/ai/docs/nocobase/{quickstart → nocobase-cli}/installation/env.md

@@ -2,7 +2,7 @@
 
 This page only applies to applications created or hosted via the NocoBase CLI.
 
-If you have just finished reading [Installation using CLI (recommended)](./cli.md) and have seen the "Installation Directory" section, then the most common problems you will encounter are usually the following:
+If you have just finished reading [Install using CLI](./cli.md) and have seen the "Installation Directory" section, then the most common problems you will encounter are usually the following:
 
 - Where is the `.env` file placed?
 - Which configurations are still suitable to be written into `.env`
@@ -17,7 +17,7 @@ Let’s talk about the conclusion first:
 
 ## Find `app-path` first
 
-In [Install using CLI (recommended)](./cli.md#Installation directory), the default directory structure of CLI env is as follows:
+In [Install using CLI](./cli.md#Installation directory), the default directory structure of CLI env is as follows:
 
 ```text
 <app-path>/
@@ -148,6 +148,6 @@ This is also the mentality that this page most wants to help you build:
 
 ## Where to look next
 
-- If you have not confirmed the application directory structure, first go back to [Install using CLI (recommended)](./cli.md#Installation directory)
+- If you have not confirmed the application directory structure, first go back to [Install using CLI](./cli.md#Installation directory)
 - If you want to modify basic configurations such as ports, time zones, database connections, and public access paths, continue to see [`nb env update`](../../api/cli/env/update.md)
 - If you want to start, restart or view application logs, continue to see [Manage Application](../operations/manage-app.md)

package/dist/ai/docs/nocobase/{quickstart → nocobase-cli}/installation/migration.md

@@ -99,5 +99,5 @@ By default, it is enough to migrate the test environment first. Only migrate the
 
 ## Where to look next
 
-- If you are ready to install and manage applications in a new way, continue to [Installation using CLI (recommended)](./cli.md)
+- If you are ready to install and manage applications in a new way, continue to [Install using CLI](./cli.md)
 - If you just continue to use the original installation method, just go back to the installation and upgrade document entry above.

package/dist/ai/docs/nocobase/{quickstart → nocobase-cli}/production/index.md

@@ -69,7 +69,17 @@ If you happen to be stuck here "Why do you need `nb app autostart`", just contin
 - If you are going to connect to the reverse proxy, `appPort` has been saved in env
 - If you are ready to officially open it to the outside world, you have already planned the domain name, entrance port and HTTPS solution.
 
-If you have not completed the CLI installation or env initialization, go back to [Installation using CLI (recommended)](../installation/cli.md).
+:::warning Note
+
+Use a different `hostname`, such as a separate subdomain, for each independent NocoBase service. Do not distinguish services only by port. Browser cookies are not isolated by port, so services under the same `hostname` may overwrite login state and affect [stable URL](../../file-manager/stable-url.md) authorization.
+
+Sub-apps within the same NocoBase deployment are distinguished by app name and do not need separate hostnames. However, if another independent 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.
+
+For example, use `app1.example.com` and `app2.example.com` instead of `example.com:13000` and `example.com:14000`.
+
+:::
+
+If you have not completed the CLI installation or env initialization, go back to [Install using CLI](../installation/cli.md).
 
 If the command prompts that env is missing `appPort`, first execute [`nb env update`](../../api/cli/env/update.md) to fill it in.
 

package/dist/ai/docs/nocobase/{quickstart → nocobase-cli}/production/reverse-proxy/caddy.md

@@ -124,7 +124,7 @@ If you want to make up for Caddy site-level configuration, such as additional he
 
 If your application is not CLI hosted, or you explicitly want to maintain the complete Caddy configuration yourself, you can also write it by hand.
 
-However, for NocoBase, the production environment entry is usually not just a simple `reverse_proxy`. In addition to forwarding API requests to the backend application, a complete and working Caddy configuration usually also needs to handle the upload directory, front-end static resources, `.well-known` routing, WebSocket, and SPA fallback page.
+However, for NocoBase, the production environment entry is usually not just a simple `reverse_proxy`. In addition to forwarding API requests to the backend application, a complete and working Caddy configuration usually also needs to handle the upload directory, front-end static resources, the `/files/` file access route, `.well-known` routing, WebSocket, and SPA fallback pages.
 
 Taking `test2` as an example, key directories related to Caddy usually include:
 
@@ -139,6 +139,7 @@ In other words, handwritten configuration usually needs to cover at least the fo
 - `dist`: Expose the front-end build product directory
 - `oauth well-known`: Handle OAuth discovery paths
 - `openid well-known`: Handle OpenID discovery paths
+- `files`: Forward file access requests under `/files/` to the backend application
 - `api`: forward `/api/` request to the backend application
 - `ws`: forward WebSocket requests to the backend application
 - `spa v2`: Provides front-end entry and return page for `/v/`
@@ -187,6 +188,10 @@ c.local.nocobase.com {
         reverse_proxy host.docker.internal:56575
     }
 
+    handle /files/* {
+        reverse_proxy host.docker.internal:56575
+    }
+
     handle /api/* {
         reverse_proxy host.docker.internal:56575
     }
@@ -249,7 +254,15 @@ A more prudent approach is usually:
 2. Confirm the routing structure and actual path based on the generated results.
 3. Then make manual adjustments according to your domain name, running mode and mounting path.
 
-This is usually less likely to miss details related to WebSockets, static resources, upload directories, `.well-known` routes, or SPA fallback pages than handwriting a configuration from scratch.
+This is usually less likely to miss details related to `/files/`, WebSockets, static resources, upload directories, `.well-known` routes, or SPA fallback pages than handwriting a configuration from scratch.
+
+:::warning Note
+
+`/files/` is an application route that must pass through NocoBase authorization. Do not handle it as a static directory or let it fall through to the SPA fallback. Forward it to the NocoBase backend and place the rule before `handle_path /*` and other front-end fallback rules.
+
+If `APP_PUBLIC_PATH=/nocobase/` is configured, also forward `/nocobase/files/*`. Keep the root-level `/files/*` rule for compatibility with existing file URLs.
+
+:::
 
 ## Check and reload configuration
 
@@ -290,6 +303,6 @@ nb proxy caddy status
 
 - [Production environment reverse proxy](./index.md)
 - [Nginx](./nginx.md)
-- [Install using CLI (recommended)](../../installation/cli.md)
+- [Install using CLI](../../installation/cli.md)
 - [Application configuration with `.env`](../../installation/env.md)
 - [`nb proxy caddy` Command Reference](../../../api/cli/proxy/caddy/index.md)