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

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

@@ -0,0 +1,269 @@
+---
+title: "Migrate to S3 Pro"
+description: "Migrate files from public-only storage engines to S3 Pro, including maintenance windows, backups, object key mapping, record updates, and risk checks."
+keywords: "S3 Pro,storage migration,private access,file migration,Local Storage,S3,OSS,COS,NocoBase"
+---
+
+# Migrate to S3 Pro
+
+If you already use [Local Storage](./local.md), [Amazon S3](./amazon-s3.md), [Aliyun OSS](./aliyun-oss.md), or [Tencent COS](./tencent-cos.md), and later need private file access, you can migrate historical files to [S3 Pro](./s3-pro.md).
+
+This is not only a storage configuration change. A migration must handle three things: make the physical files or objects available from the new storage, update file records, and switch future uploads to the new storage.
+
+:::warning Note
+
+Run the migration once in a test environment first, and prepare restorable database and file backups. If users continue to upload or delete attachments during the migration, records can be missed, overwritten, or become inconsistent.
+
+:::
+
+## Scope
+
+This guide applies when migrating from these storage engines to S3 Pro:
+
+| Source storage engine | Historical file location |
+| --- | --- |
+| Local Storage | `<documentRoot>/<record.path>/<record.filename>` |
+| Amazon S3 | `join(record.path, record.filename)` in the source bucket |
+| Aliyun OSS | `join(record.path, record.filename)` in the source bucket |
+| Tencent COS | `join(record.path, record.filename)` in the source bucket |
+
+Here, `record.path` and `record.filename` come from the file record itself, including the built-in `attachments` table and other file collections.
+
+:::tip Note
+
+For Local Storage, `documentRoot` must come from `options.documentRoot` in the corresponding `storages` record. The default value is `storage/uploads`, but the final absolute path depends on the runtime storage directory of NocoBase.
+
+:::
+
+## Operation Steps
+
+### Step 1: Stop writes or enter a maintenance window
+
+Pause user uploads, updates, and deletions of attachments during the migration. You can use a maintenance window, temporarily disable entry points, or freeze related business flows.
+
+The goal is to keep file records and physical files stable. If users upload or delete files during migration, the migration script may no longer be working against the latest records.
+
+### Step 2: Back up the database and files
+
+Prepare at least two backups:
+
+1. Database backup
+2. File backup or object snapshot from the source storage
+
+For Local Storage, back up the directory pointed to by `documentRoot`. Historical files are usually stored at:
+
+```text
+<documentRoot>/<record.path>/<record.filename>
+```
+
+For Amazon S3, Aliyun OSS, and Tencent COS, confirm that objects in the source bucket are still readable, and record the source storage engine's `id`, `name`, `type`, `path`, `baseUrl`, and `options`.
+
+It is also recommended to export a migration manifest for rollback and manual review:
+
+```text
+collection
+id
+oldStorageId
+oldPath
+oldFilename
+oldUrl
+newKey
+size
+mimetype
+```
+
+### Step 3: Create and verify the S3 Pro storage
+
+Create a new `s3-compatible` storage according to [S3 Pro](./s3-pro.md). At least verify these settings:
+
+- bucket
+- endpoint
+- region
+- accessKey
+- secret
+- public / private
+- access endpoint
+- forcePathStyle
+- file size and MIME type rules
+
+Upload a test file with the new storage and confirm upload, preview, download, and deletion all work. If the target is private access, also confirm that the access URL is a temporary signed URL and that its expiration is expected.
+
+:::warning Note
+
+S3 Pro uses direct client upload. The target bucket must have CORS rules that allow uploads from the NocoBase site, otherwise new uploads will fail.
+
+:::
+
+### Step 4: Decide the object key mapping
+
+For historical files migrated to S3 Pro, it is recommended to continue using the old relative path as the S3 object key:
+
+```text
+oldKey = join(record.path, record.filename)
+```
+
+For example:
+
+```text
+record.path = "avatars"
+record.filename = "a-123.png"
+oldKey = "avatars/a-123.png"
+```
+
+For persisted file records, S3 Pro uses `file.filename` directly as the full object key when accessing the file. It does not append `file.path`. Therefore, migrated records should be updated to:
+
+```text
+storageId = <s3-pro-storage-id>
+filename = <oldKey>
+path = ""
+url = ""
+```
+
+Do not migrate to this shape:
+
+```text
+filename = "a-123.png"
+path = "avatars"
+```
+
+Otherwise S3 Pro may treat only `a-123.png` as the object key, causing historical files to fail to load.
+
+Use `/` as the separator when generating object keys. Do not use operating-system-specific path separators. If an old path starts with `/`, remove the leading slash.
+
+### Step 5: Move physical files or confirm object location
+
+Traverse all file records, including the built-in `attachments` table and other file collections. Only process records where `storageId = <old-storage-id>`.
+
+If the source is Local Storage, upload the local files to the bucket used by S3 Pro. If the source is already Amazon S3, Aliyun OSS, or Tencent COS, and the new S3 Pro storage points to the same bucket and endpoint, with credentials that can read the same objects, you usually do not need to copy objects. In that case, confirm that the `oldKey` generated in Step 4 is accessible through S3 Pro.
+
+| Source storage engine | Whether files need to be copied | Target object key |
+| --- | --- | --- |
+| Local Storage | Must be uploaded to the S3 Pro bucket | `join(record.path, record.filename)` |
+| Amazon S3 | Usually no copy if reusing the same bucket; copy is needed when changing bucket, account, or region | `join(record.path, record.filename)` |
+| Aliyun OSS | Usually no copy if reusing the same bucket; copy is needed when changing bucket, account, or region | `join(record.path, record.filename)` |
+| Tencent COS | Usually no copy if reusing the same bucket; copy is needed when changing bucket, account, or region | `join(record.path, record.filename)` |
+
+Files or objects still need to be copied in these cases:
+
+- Migrating from Local Storage to S3 Pro
+- Changing bucket, account, region, or cloud provider
+- Moving historical objects from a public bucket to a new private bucket
+- Renaming object keys or reorganizing directories
+- The source bucket policy is not suitable for S3 Pro signed access or direct client upload
+- S3 Pro cannot directly access the source objects with the current endpoint and credentials
+
+Before the real migration, run a dry-run. At least output:
+
+- Number of records to migrate
+- Total size to migrate
+- Number of missing local files or missing source objects
+- Number of duplicate object keys
+- Number of records with unrecognized `storageId`
+- List requiring manual handling
+
+If duplicate object keys appear, do not overwrite directly. Compare file size, ETag, or hash to confirm whether they point to the same file. If they are different files, generate a new key for one record and use that new key when updating the record.
+
+### Step 6: Verify target object accessibility
+
+After files are copied, or after confirming that the source cloud bucket can be reused, run S3 HEAD Object or an equivalent check for every migrated record. Confirm that S3 Pro can access the object through the target object key.
+
+Recommended output:
+
+- Success count
+- Missing source file count
+- Upload or copy failure count
+- Missing target object count
+- Duplicate key count
+- List requiring manual handling
+
+Do not rely only on the script exit code. Object storage can have partial failures, successful retries, same-key overwrites, or write-only-but-not-readable permission problems. The migration manifest and HEAD Object checks are more reliable.
+
+### Step 7: Update file records
+
+After confirming that all target objects exist, update the file records. Only update records in file collections, keep the original `id`, and do not update many-to-many junction tables generated by attachment fields.
+
+Core fields:
+
+| Field | Value after migration |
+| --- | --- |
+| `storageId` | New S3 Pro storage ID |
+| `filename` | `join(oldPath, oldFilename)` |
+| `path` | Empty string |
+| `url` | Empty string for private storage; public URL or empty string for public storage |
+
+If S3 Pro is private, `url` must be empty. S3 Pro also clears `url` before saving non-public storage records. File access will dynamically generate a temporary signed URL.
+
+:::warning Note
+
+Batch update records in a transaction if possible, and keep the migration manifest from Step 2 until after the migration is fully verified. Rollback needs that manifest to restore `storageId`, `path`, `filename`, and `url` to their old values.
+
+:::
+
+### Step 8: Switch future uploads to the new storage
+
+After historical records are updated, switch the target storage for new uploads.
+
+Check three types of configuration:
+
+1. Default storage engine: if attachment fields or file collections do not specify storage, uploaded files use the default storage. Set the new S3 Pro storage as the default.
+2. Attachment fields: if an attachment field is configured with `options.storage = <old-storage-name>`, change it to the new S3 Pro storage `name`.
+3. File collections: if a file collection is configured with the old storage engine, change it to the new S3 Pro storage `name`.
+
+Here, `name` is the storage engine name, not the storage ID. Historical file records use `storageId`.
+
+### Step 9: Restart or refresh storage cache
+
+The file manager caches `storages` configuration. If you update storage configuration through the NocoBase UI or resource API, `reloadStorages` is usually triggered. If you update the database directly, restart the application after migration or make sure the storage cache has been refreshed.
+
+If you directly changed attachment field metadata or file collection metadata, it is also recommended to restart the application so collection configuration, field configuration, and frontend cache all use the new storage.
+
+### Step 10: Sample-check and keep old files
+
+After migration, verify at least these scenarios:
+
+- View, preview, and download historical files in attachment fields
+- View, preview, and download historical files in file collections
+- Image thumbnails or preprocessing parameters
+- Office preview and other features that depend on external services reading file URLs
+- Save, preview, download, and delete newly uploaded files
+- Object deletion after deleting file records
+
+Do not delete files from the old storage immediately. Keep them until the business side confirms the migration, backup cycles have covered the new state, and access logs show no abnormal behavior.
+
+## Risks
+
+### Data inconsistency during writes
+
+If users can still upload or delete files during migration, objects may be copied after records are deleted, records may be updated while objects remain only in the old storage, or new uploads may not be included in the migration manifest. The default approach is to enter a maintenance window.
+
+### Different object key rules in S3 Pro
+
+After migration, `filename` should store the full object key and `path` should be empty. This differs from the historical record shape of Local Storage and built-in S3 / OSS / COS, and is the easiest place to make mistakes.
+
+### URL accessibility changes
+
+After migrating from public storage to private S3 Pro, historical public URLs may no longer remain valid. NocoBase dynamically generates temporary signed URLs for internal file access, but old URLs already saved in external systems are not automatically rewritten.
+
+If third-party systems, email templates, exported files, or rich text content directly stores old URLs, evaluate a separate replacement strategy.
+
+:::warning Note
+
+If Markdown (Vditor) field content already stores file URLs, handle those contents separately. Private S3 Pro access generates temporary signed URLs that expire, and currently these private links are not supported for long-term storage and use inside Markdown (Vditor) fields.
+
+If these fields must continue referencing files, keep publicly accessible file URLs for now.
+
+:::
+
+### Preview services and private files
+
+Some preview features depend on external services accessing file URLs. Private S3 Pro generates temporary signed URLs, which can usually be accessed, but they are affected by signature expiration, network reachability, bucket permissions, and server-side caching.
+
+If files are very sensitive, reassess whether external preview services should be allowed to read them.
+
+### Direct database changes do not trigger all hooks
+
+If you update `storages`, collection configuration, field configuration, and file records directly through SQL or a custom script, some NocoBase cache refreshes and save hooks are not triggered automatically. Restart the application after the update and verify storage configuration again.
+
+### Delete behavior points to the new storage
+
+After a file record's `storageId` is updated to S3 Pro, deleting that file record later will make NocoBase try to delete the object from the new bucket. Objects in the old storage will not be deleted automatically and need to be cleaned up separately.

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/file-manager/storage/tencent-cos.md

@@ -2,6 +2,15 @@
 
 A storage engine based on Tencent Cloud COS. You need to prepare the relevant account and permissions before use.
 
+
+:::warning Note
+
+This engine does not support private access. After a file is uploaded, NocoBase generates a directly accessible URL, and anyone who has that URL can access the file.
+
+Even if the COS bucket itself is private, the built-in Tencent COS engine does not generate temporary signed URLs for file access. If you need private access, use [S3 Pro](./s3-pro). If historical files already exist, see [Migrate to S3 Pro](./migrate-to-s3-pro.md).
+
+:::
+
 ## Configuration Parameters
 
 

package/dist/ai/docs/nocobase/get-started/deployment/how-to-deploy-nocobase-faster.mdx

@@ -116,7 +116,7 @@ When users access NocoBase, requests go directly to your server. An appropriate
 - Disadvantages: This method is simple but performs poorly when handling high concurrency or static files; suitable for development and testing only.
 - Recommendation: Please avoid this method if possible.
 
-> Reference "[Installation Documentation](https://v2.docs.nocobase.com/get-started/quickstart)"
+> Reference "[Installation Documentation](https://docs.nocobase.com/get-started/quickstart)"
 
 Without a reverse proxy, homepage loading takes about 6.1 seconds
 ![20250409131357](https://static-docs.nocobase.com/20250409131357.png)
@@ -126,7 +126,7 @@ Without a reverse proxy, homepage loading takes about 6.1 seconds
 - Advantages: Reverse proxy servers can efficiently handle concurrent connections, serve static files, implement load balancing, and make HTTP/2 configuration simple.
 - Recommendation: In production environments, after application deployment (source code deployment / create-nocobase-app / Docker image), use Nginx or Caddy as a reverse proxy.
 
-> Reference "[Deployment Documentation](https://v2.docs.nocobase.com/get-started/deployment/production)"
+> Reference "[Deployment Documentation](https://docs.nocobase.com/get-started/deployment/production)"
 
 With Nginx proxy, homepage loading takes about 3-4 seconds
 ![20250409131541](https://static-docs.nocobase.com/20250409131541.png)

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/how-nocobase-works.mdx

@@ -3,4 +3,11 @@
 <video controls width="100%" poster="https://static-docs.nocobase.com/video-cover-home.png">
   <source src="https://static-docs.nocobase.com/nocobase-2-main-1080p-en-v2.mp4" type="video/mp4" />
   Your browser does not support video playback.
-</video>
+</video>
+
+## What's Next
+
+If you've finished the video and want to start right away, there are usually two common paths:
+
+1. If you want to compare installation methods and version channels first, continue with [Installation and Version Comparison](/ai/quickstart)
+2. If you want to install the app right away, continue with [Install NocoBase App](/ai/install-nocobase-app)

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

@@ -0,0 +1,178 @@
+---
+title: "Docker Installation (External Caddy)"
+description: "Install NocoBase with Docker and use an external Caddy container as the entry point."
+keywords: "Docker,NocoBase,Caddy,installation,reverse proxy"
+---
+
+# Docker Installation (External Caddy)
+
+In this setup, the NocoBase app container and the Caddy container run separately. You can start with [Docker Installation (Built-in Nginx)](./docker.mdx) and then switch the entry service to an external Caddy container.
+
+## When to use this setup
+
+- You want to deploy NocoBase and the web server separately
+- You want to simplify reverse proxy and HTTPS configuration with Caddy
+- You want to expose only the proxy container to the public network
+
+## docker-compose.yml example
+
+If you need the `full` image, replace `latest-no-nginx` with `latest-full-no-nginx`.
+
+The `13000:80` mapping is only for convenient local testing, so it does not occupy the standard host ports directly. In production, you usually do not keep using `13000:80`; instead, let the external Caddy container map directly to the host `80` and `443` ports.
+```yml
+networks:
+  nocobase:
+    driver: bridge
+
+services:
+  app:
+    image: nocobase/nocobase:latest-no-nginx
+    restart: always
+    depends_on:
+      - postgres
+    networks:
+      - nocobase
+    environment:
+      - APP_KEY=your-secret-key
+      - DB_DIALECT=postgres
+      - DB_HOST=postgres
+      - DB_PORT=5432
+      - DB_DATABASE=nocobase
+      - DB_USER=nocobase
+      - DB_PASSWORD=nocobase
+      - TZ=Etc/UTC
+      - NOCOBASE_EXTRACT_CLIENT_ASSETS=true
+      - NOCOBASE_PROXY_PROVIDER=caddy
+      - NOCOBASE_PROXY_STORAGE_PATH=/app/nocobase/storage
+      - NOCOBASE_PROXY_UPSTREAM_HOST=app
+    volumes:
+      - ./storage:/app/nocobase/storage
+
+  caddy:
+    image: caddy:2
+    restart: always
+    depends_on:
+      - app
+    networks:
+      - nocobase
+    volumes:
+      - ./storage:/app/nocobase/storage
+    command: >
+      /bin/sh -c '
+        while [ ! -f /app/nocobase/storage/.nocobase/proxy/caddy/nocobase.caddy ]; do
+          echo "waiting for nocobase.caddy..."
+          sleep 1
+        done
+        ln -sf /app/nocobase/storage/.nocobase/proxy/caddy/nocobase.caddy /etc/caddy/Caddyfile
+        caddy run --config /etc/caddy/Caddyfile --adapter caddyfile
+      '
+    ports:
+      # This is only a local testing example.
+      - "13000:80"
+      # In production, usually change it to:
+      # - "80:80"
+      # - "443:443"
+
+  postgres:
+    image: postgres:16
+    restart: always
+    command: postgres -c wal_level=logical
+    environment:
+      POSTGRES_USER: nocobase
+      POSTGRES_DB: nocobase
+      POSTGRES_PASSWORD: nocobase
+    volumes:
+      - ./storage/db/postgres:/var/lib/postgresql/data
+    networks:
+      - nocobase
+```
+
+## Key points
+
+- `NOCOBASE_EXTRACT_CLIENT_ASSETS=true` extracts client assets and generates proxy config
+- `NOCOBASE_PROXY_PROVIDER=caddy` tells the app to generate Caddy config
+- `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
+
+If your Caddy is installed directly on the host instead of running in a Docker container, it is better to use a separate `docker-compose.yml`. In this setup, the `app` service must expose a host port directly, and the proxy-related environment variables should use host-side values.
+
+You can use a `docker-compose.yml` like this:
+
+```yml
+networks:
+  nocobase:
+    driver: bridge
+
+services:
+  app:
+    image: nocobase/nocobase:latest-no-nginx
+    restart: always
+    depends_on:
+      - postgres
+    networks:
+      - nocobase
+    environment:
+      - APP_KEY=your-secret-key
+      - DB_DIALECT=postgres
+      - DB_HOST=postgres
+      - DB_PORT=5432
+      - DB_DATABASE=nocobase
+      - DB_USER=nocobase
+      - DB_PASSWORD=nocobase
+      - TZ=Etc/UTC
+      - NOCOBASE_EXTRACT_CLIENT_ASSETS=true
+      - NOCOBASE_PROXY_PROVIDER=caddy
+      - NOCOBASE_PROXY_STORAGE_PATH=/path/to/your-project/storage
+      - NOCOBASE_PROXY_UPSTREAM_HOST=127.0.0.1
+      - NOCOBASE_PROXY_UPSTREAM_PORT=13000
+    volumes:
+      - ./storage:/app/nocobase/storage
+    ports:
+      - "13000:13000"
+
+  postgres:
+    image: postgres:16
+    restart: always
+    command: postgres -c wal_level=logical
+    environment:
+      POSTGRES_USER: nocobase
+      POSTGRES_DB: nocobase
+      POSTGRES_PASSWORD: nocobase
+    volumes:
+      - ./storage/db/postgres:/var/lib/postgresql/data
+    networks:
+      - nocobase
+```
+
+In this variant:
+
+- `NOCOBASE_PROXY_STORAGE_PATH` should be the absolute host path of your `storage` directory
+- `NOCOBASE_PROXY_UPSTREAM_HOST` should be `127.0.0.1`
+- The `app` service must keep `ports`, so the local Caddy can reach the app through `127.0.0.1:13000`
+
+After the `app` container starts, wait for the config file to be generated, then link it into the local Caddy config path:
+
+```bash
+while [ ! -f ./storage/.nocobase/proxy/caddy/nocobase.caddy ]; do
+  echo "waiting for nocobase.caddy..."
+  sleep 1
+done
+
+sudo ln -sf "$(pwd)/storage/.nocobase/proxy/caddy/nocobase.caddy" /etc/caddy/Caddyfile
+sudo caddy validate --config /etc/caddy/Caddyfile --adapter caddyfile
+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
+- [Caddy Static Resource Proxy](../deployment/static-resource-proxy/caddy.md) — Learn more about the generated Caddy config