@nocobase/plugin-ai 2.2.0-beta.12 → 2.2.0-beta.14

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/get-started/deployment/production.md

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

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

@@ -94,6 +94,7 @@ services:
 - `NOCOBASE_PROXY_UPSTREAM_HOST=app` lets the Caddy container reach the `app` service through the Compose network
 - `./storage` must be mounted into both the `app` and `caddy` containers so they can share proxy config, static assets, and uploaded files
 - The `caddy` container should wait until `nocobase.caddy` is generated, then link it to `/etc/caddy/Caddyfile` with `ln -sf`
+- The generated config forwards both the `/files/` route under `APP_PUBLIC_PATH` and the root-level `/files/` route to NocoBase for authenticated file previews and downloads
 - Expose only the Caddy container port to the host. For testing, you can start with `13000:80`; in production, you usually expose the host `80` and `443` ports directly, while the `app` service does not need to expose its port to the host
 
 ## If you use a local host Caddy
@@ -169,6 +170,8 @@ sudo systemctl reload caddy
 
 If your host Caddy does not use `/etc/caddy/Caddyfile`, replace the link target with your own config path. Usually it is safer to keep `nocobase.caddy` as the main entry file instead of copying its content manually.
 
+If you maintain Caddy yourself instead of using the generated config, make sure `/files/*` and the corresponding route under `APP_PUBLIC_PATH` are forwarded to NocoBase before the SPA fallback rules. See [Caddy Reverse Proxy](../../nocobase-cli/production/reverse-proxy/caddy.md) for a complete example.
+
 ## Related links
 
 - [Docker Installation (Built-in Nginx)](./docker.mdx) — Start with the single-container setup

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

@@ -95,6 +95,7 @@ services:
 - `NOCOBASE_PROXY_UPSTREAM_HOST=app` lets the Nginx container reach the `app` service through the Compose network
 - `./storage` must be mounted into both the `app` and `nginx` containers so they can share proxy config, static assets, and uploaded files
 - The `nginx` container should wait until `nocobase.conf` is generated, then link it to `/etc/nginx/conf.d/default.conf` with `ln -sf`
+- The generated config forwards both the `/files/` route under `APP_PUBLIC_PATH` and the root-level `/files/` route to NocoBase for authenticated file previews and downloads
 - If you use an external Nginx container, let the `nginx` container handle the host port mapping. For testing, you can start with `13000:80`; in production, you usually expose the host `80` and `443` ports directly, while the `app` service does not need to expose its port to the host
 
 ## If you use a local host Nginx
@@ -170,6 +171,8 @@ sudo systemctl reload nginx
 
 If your host Nginx does not use the `conf.d` directory, replace the link target with your own config path. Usually it is safer to keep `nocobase.conf` as a file included from the `http {}` context instead of copying its content manually.
 
+If you maintain Nginx yourself instead of using the generated config, make sure `/files/` and the corresponding route under `APP_PUBLIC_PATH` are forwarded to NocoBase before the SPA fallback rules. See [Nginx Reverse Proxy](../../nocobase-cli/production/reverse-proxy/nginx.md) for a complete example.
+
 ## Related links
 
 - [Docker Installation (Built-in Nginx)](./docker.mdx) — Start with the single-container setup

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

@@ -627,7 +627,7 @@ If you use the built-in Nginx image, it is usually better not to expose `13000`
 
 The following config proxies domain requests to `http://127.0.0.1:13000/`:
 
-```bash
+```nginx
 server {
     listen 80;
     server_name your_domain.com;  # Replace your_domain.com with your domain
@@ -658,6 +658,8 @@ server {
 
 If you also want to enable HTTPS, configure `443` and the certificate on the host Nginx. The NocoBase container does not need to handle certificates separately.
 
+The `location /` block in this root-path configuration also proxies `/api/`, `/ws`, and `/files/`. If you split static assets from application routes, make sure `/files/` is still forwarded to NocoBase and is not handled as a static directory.
+
 ### Subpath deployment
 
 If you want to deploy the app under a subpath, such as `https://your_domain.com/nocobase/`, configure the `APP_PUBLIC_PATH` environment variable first:
@@ -674,7 +676,7 @@ Keep the leading and trailing `/` in the path. After this is configured, the app
 
 Then configure the host Nginx with the same subpath proxy:
 
-```bash
+```nginx
 server {
     listen 80;
     server_name your_domain.com;  # Replace your_domain.com with your domain
@@ -700,10 +702,32 @@ server {
         send_timeout 600;
         proxy_buffering off;
     }
+
+    # Keep compatibility with root-level file access URLs.
+    location ^~ /files/ {
+        proxy_pass http://127.0.0.1:13000;
+        proxy_http_version 1.1;
+
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $upstream_x_forwarded_proto;
+        proxy_set_header Host $final_host;
+        proxy_set_header Referer $http_referer;
+        proxy_set_header User-Agent $http_user_agent;
+
+        add_header Cache-Control "no-cache, no-store" always;
+
+        proxy_connect_timeout 600;
+        proxy_send_timeout 600;
+        proxy_read_timeout 600;
+        send_timeout 600;
+    }
 }
 ```
 
-The key point is that `APP_PUBLIC_PATH` and the path in `proxy_pass` must stay consistent. If either side misses `/nocobase/`, static assets and routing will usually not work correctly.
+Keep these points in mind:
+
+- `APP_PUBLIC_PATH` and the path in `proxy_pass` must stay consistent. If either side misses `/nocobase/`, static assets and routing will usually not work correctly
+- `/nocobase/files/` is forwarded by `location /nocobase/`; the compatible root-level `/files/` route must be forwarded to NocoBase separately
 
 ### Other options
 

package/dist/ai/docs/nocobase/get-started/installation/env.md

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

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

@@ -28,7 +28,7 @@ features:
         link: /ai/install-nocobase-app
       - title: Tutorials
         details: Step-by-step tutorials to build real projects with NocoBase from scratch.
-        link: /tutorials/v2/
+        link: /tutorials/
 
   - title: AI
     details: An AI-powered new way to get started - use natural language to build, use, and develop.

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/nocobase-cli/production/index.md

@@ -69,6 +69,16 @@ 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.
 
+:::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.