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

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

@@ -0,0 +1,176 @@
+---
+title: "Docker Installation (External Nginx)"
+description: "Install NocoBase with Docker and use an external Nginx container as the entry point."
+keywords: "Docker,NocoBase,Nginx,installation,reverse proxy"
+---
+
+# Docker Installation (External Nginx)
+
+In this setup, the NocoBase app container and the Nginx container run separately. You can start with [Docker Installation (Built-in Nginx)](./docker.mdx) and then switch the entry service to an external Nginx container.
+
+## When to use this setup
+
+- You want to deploy NocoBase and the web server separately
+- You want to manage the Nginx config and exposed ports yourself
+- 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 Nginx 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=nginx
+      - NOCOBASE_PROXY_STORAGE_PATH=/app/nocobase/storage
+      - NOCOBASE_PROXY_UPSTREAM_HOST=app
+    volumes:
+      - ./storage:/app/nocobase/storage
+
+  nginx:
+    image: nginx:latest
+    restart: always
+    depends_on:
+      - app
+    networks:
+      - nocobase
+    volumes:
+      - ./storage:/app/nocobase/storage
+    command: >
+      /bin/sh -c '
+        while [ ! -f /app/nocobase/storage/.nocobase/proxy/nginx/nocobase.conf ]; do
+          echo "waiting for nocobase.conf..."
+          sleep 1
+        done
+        rm -f /etc/nginx/conf.d/default.conf
+        ln -sf /app/nocobase/storage/.nocobase/proxy/nginx/nocobase.conf /etc/nginx/conf.d/default.conf
+        nginx -g "daemon off;"
+      '
+    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=nginx` tells the app to generate Nginx config
+- `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`
+- 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
+
+If your Nginx 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=nginx
+      - 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 Nginx 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 Nginx config directory:
+
+```bash
+while [ ! -f ./storage/.nocobase/proxy/nginx/nocobase.conf ]; do
+  echo "waiting for nocobase.conf..."
+  sleep 1
+done
+
+sudo ln -sf "$(pwd)/storage/.nocobase/proxy/nginx/nocobase.conf" /etc/nginx/conf.d/nocobase.conf
+sudo nginx -t
+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.
+
+## Related links
+
+- [Docker Installation (Built-in Nginx)](./docker.mdx) — Start with the single-container setup
+- [Nginx Static Resource Proxy](../deployment/static-resource-proxy/nginx.md) — Learn more about the generated Nginx config

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

@@ -617,4 +617,97 @@ Open [http://localhost:13000](http://localhost:13000) in your browser. The initi
 
 After logging in for the first time, please change the default password promptly to ensure system security.
 
-:::
+:::
+
+## 5. Production deployment
+
+If you use the built-in Nginx image, it is usually better not to expose `13000` directly to the public internet. A more common setup is to keep the container port available only on the host and let the host Nginx handle the domain, HTTPS, and reverse proxy.
+
+### Proxy the root path with Nginx
+
+The following config proxies domain requests to `http://127.0.0.1:13000/`:
+
+```bash
+server {
+    listen 80;
+    server_name your_domain.com;  # Replace your_domain.com with your domain
+
+    location / {
+        proxy_pass http://127.0.0.1:13000/;
+        proxy_http_version 1.1;
+
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection $connection_upgrade;
+        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_cache_bypass $http_upgrade;
+
+        proxy_connect_timeout 600;
+        proxy_send_timeout 600;
+        proxy_read_timeout 600;
+        send_timeout 600;
+        proxy_buffering off;
+    }
+}
+```
+
+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.
+
+### 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:
+
+```diff
+services:
+  app:
+    image: nocobase/nocobase:latest
+    environment:
++     - APP_PUBLIC_PATH=/nocobase/
+```
+
+Keep the leading and trailing `/` in the path. After this is configured, the app URL becomes `http://127.0.0.1:13000/nocobase/`.
+
+Then configure the host Nginx with the same subpath proxy:
+
+```bash
+server {
+    listen 80;
+    server_name your_domain.com;  # Replace your_domain.com with your domain
+
+    location /nocobase/ {
+        proxy_pass http://127.0.0.1:13000/nocobase/;
+        proxy_http_version 1.1;
+
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection $connection_upgrade;
+        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_cache_bypass $http_upgrade;
+
+        proxy_connect_timeout 600;
+        proxy_send_timeout 600;
+        proxy_read_timeout 600;
+        send_timeout 600;
+        proxy_buffering off;
+    }
+}
+```
+
+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.
+
+### Other options
+
+If you do not want to use the built-in Nginx, you can also use one of these separate proxy setups:
+
+- [Docker Installation (External Nginx)](./docker-nginx.mdx)
+- [Docker Installation (External Caddy)](./docker-caddy.mdx)

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

@@ -349,15 +349,17 @@ TELEMETRY_TRACE_PROCESSOR=console
 
 ### SERVER_REQUEST_WHITELIST
 
-Whitelist of allowed targets for server-initiated outbound HTTP requests, used to prevent SSRF (Server-Side Request Forgery) attacks. Accepts a comma-separated list of exact IPs, CIDR ranges, exact hostnames, and single-level wildcard subdomains.
+Whitelist of allowed targets for outbound HTTP requests initiated by the NocoBase server. Accepts a comma-separated list of exact IPs, CIDR ranges, exact hostnames, and single-level wildcard subdomains.
 
 ```bash
-SERVER_REQUEST_WHITELIST=1.2.3.4,10.0.0.0/8,api.example.com,*.trusted.com
+SERVER_REQUEST_WHITELIST=api.example.com,*.trusted.com,10.0.0.0/8,127.0.0.1
 ```
 
-**Applies to**: Workflow "HTTP Request" nodes and Custom Request action buttons. Relative-path requests (calls to the NocoBase API itself) are not affected.
+**Applies to**: Workflow "HTTP Request" nodes, Custom Request action buttons, AI services, and other server-side requests. Relative-path requests (calls to the NocoBase API itself) are not affected.
 
-**When not set**: All `http`/`https` outbound requests are allowed (existing behaviour). **When set**: Only requests whose host matches a whitelist entry are permitted; non-matching requests will raise an error.
+**When not set**: All `http` / `https` outbound requests are allowed to keep existing behavior. However, if the target is a loopback, private, link-local, or metadata address, or if a domain resolves to one of these addresses, the server logs a warning.
+
+**When set**: Only requests whose host matches a whitelist entry are permitted; non-matching requests will raise an error. Future versions may gradually tighten the default behavior. If your deployment needs to access internal services, configure an explicit whitelist in advance.
 
 Supported formats:
 
@@ -365,9 +367,17 @@ Supported formats:
 | --- | --- | --- |
 | Exact IPv4 | `1.2.3.4` | That IP only |
 | IPv4 CIDR | `10.0.0.0/8` | All IPs in the subnet |
+| Exact IPv6 | `::1` | That IP only |
+| IPv6 CIDR | `fc00::/7` | All IPs in the subnet |
 | Exact hostname | `api.example.com` | That hostname only |
 | Wildcard subdomain | `*.example.com` | One subdomain level, e.g. `foo.example.com`; does **not** match `example.com` or `a.b.example.com` |
 
+:::warning Note
+
+If a domain is configured in the whitelist, the whitelist check uses the host in the request URL. In other words, after `internal.example.com` is configured, it is treated as explicitly allowed even if the domain resolves to `127.0.0.1` or a private address.
+
+:::
+
 ## Experimental Environment Variables
 
 ### APPEND_PRESET_LOCAL_PLUGINS

package/dist/ai/docs/nocobase/get-started/quickstart.md

@@ -55,4 +55,9 @@ You can install NocoBase in different ways.
 | **Scenarios** | No-code users; users who want to quickly deploy to a server. | Front-end/full-stack developers; team projects; low-code development. | Technical developers; users who want to try unreleased versions. |
 | **Technical Requirement** | ★☆☆☆☆ | ★★★☆☆ | ★★★★★ |
 | **Upgrade Method** | Pull the latest image and restart the container. | Update dependencies with yarn. | Synchronize updates through Git. |
-| **Tutorials** | [<code>Installation</code>](#) [<code>Upgrade</code>](#) [<code>Deployment</code>](#) | [<code>Installation</code>](#) [<code>Upgrade</code>](#) [<code>Deployment</code>](#) | [<code>Installation</code>](#) [<code>Upgrade</code>](#) [<code>Deployment</code>](#) |
+
+![2026-06-11-20-09-54](https://static-docs.nocobase.com/2026-06-11-20-09-54.png)
+
+## What's Next
+
+If you've already picked an installation method, the next step is [Install NocoBase App](/ai/install-nocobase-app). It walks you through installing NocoBase CLI and finishing the app installation and initialization.

package/dist/ai/docs/nocobase/get-started/system-requirements.md

@@ -11,6 +11,14 @@ Except for functionality validation or purely experimental scenarios, **we stron
 
 The system configuration and capacity planning of those services must be evaluated and tuned separately based on the **actual data size, workload, and concurrency level**.
 
+## Operating System
+
+For production environments, Linux servers are recommended, such as Ubuntu LTS, Debian, Rocky Linux, or AlmaLinux. Docker, reverse proxy, process management, logging, and backup workflows are more mature on Linux and are easier to integrate with common cloud server environments.
+
+NocoBase can also be installed on Windows Server. If you choose Windows Server, confirm Node.js, database, reverse proxy, process supervision, backup, file permissions, firewall, and related operations based on your actual deployment method.
+
+macOS is usually more suitable for local development and testing, and is not recommended as a production server. If you are setting up NocoBase locally for development or AI Agent usage, see [Local Development Setup](../ai/local-development-setup.md).
+
 ## Single-Node Deployment Mode
 
 Single-node deployment mode means the NocoBase application service runs on a single server or container instance.
@@ -85,4 +93,4 @@ In cluster mode, the recommended hardware configuration for each application nod
 Recommendations for production environments:
 
 - Adjust the node count dynamically based on monitoring metrics (CPU, memory, request latency, and so on).
-- Reserve a resource buffer to handle traffic spikes.
+- Reserve a resource buffer to handle traffic spikes.

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

@@ -11,21 +11,21 @@ hero:
   actions:
     - theme: brand
       text: Get Started
-      link: /get-started/how-nocobase-works
+      link: /ai/how-nocobase-works
     - theme: alt
       text: GitHub
       link: https://github.com/nocobase/nocobase
 
 features:
   - title: Start
-    details: Get started with NocoBase the traditional way - install, configure, and explore step by step.
+    details: Get started with NocoBase quickly - install, configure, and explore step by step.
     items:
-      - title: NocoBase Getting Started
+      - title: How NocoBase Works
         details: Understand NocoBase's core concepts and basic operations.
-        link: /get-started/how-nocobase-works
-      - title: Install App
-        details: Quickly install and manage applications.
-        link: /get-started/installation/docker
+        link: /ai/how-nocobase-works
+      - title: Install NocoBase App
+        details: Use NocoBase CLI to install an application quickly.
+        link: /ai/install-nocobase-app
       - title: Tutorials
         details: Step-by-step tutorials to build real projects with NocoBase from scratch.
         link: /tutorials/v2/
@@ -33,9 +33,6 @@ features:
   - title: AI
     details: An AI-powered new way to get started - use natural language to build, use, and develop.
     items:
-      - title: Quick Start
-        details: Install NocoBase CLI, configure AI Skills, and connect your AI Agent, preparing for AI building, using, and developing NocoBase.
-        link: /ai/quick-start
       - title: AI Builder
         details: Build NocoBase applications from scratch with AI, covering the full process from data modeling, UI configuration, workflows to release management.
         link: /ai-builder

package/dist/ai/docs/nocobase/interface-builder/blocks/data-blocks/gantt.md

@@ -0,0 +1,204 @@
+---
+pkg: '@nocobase/plugin-gantt'
+title: 'Gantt Block'
+description: 'The Gantt block displays record start and end dates and progress on a timeline. It is suitable for project planning, task scheduling, and milestone tracking, and supports title fields, date fields, progress fields, color fields, time scale, the left table, and event popup settings.'
+keywords: 'Gantt block,Gantt,project planning,task scheduling,timeline,progress management,UI building,NocoBase'
+---
+
+# Gantt Block
+
+## Introduction
+
+The Gantt block displays record start and end dates and progress on a timeline. It is suitable for project planning, task scheduling, milestone tracking, and other scenarios where you need to view task duration by time.
+
+![](https://static-docs.nocobase.com/Project-tasks-06-11-2026_11_30_AM.png)
+
+## Installation
+
+This block is a built-in plugin and does not require additional installation.
+
+## Add Block
+
+After selecting the Gantt block and choosing a data table, configure the fields required by the Gantt block in the popup:
+
+1. Select the title field, which is used to display the task name
+2. Select the start date field, which is used to determine the task start time
+3. Select the end date field, which is used to determine the task end time
+4. Optionally select the progress field, which is used to display and drag to update task progress
+5. Optionally select the color field, which is used to distinguish different tasks
+6. Select the time scale, which controls the granularity of the timeline
+
+After completing the configuration, you can create the Gantt block.
+
+![](<https://static-docs.nocobase.com/Project-tasks-06-11-2026_11_27_AM%20(1).png>)
+
+![](https://static-docs.nocobase.com/Project-tasks-06-11-2026_11_27_AM.png)
+
+## Block Settings
+
+![](https://static-docs.nocobase.com/Project-tasks-06-11-2026_11_28_AM.png)
+
+### Gantt Fields
+
+Gantt fields determine how records are mapped to timeline tasks.
+
+They include:
+
+- The title field determines the name displayed on the task bar
+- The start date field determines where the task bar starts
+- The end date field determines where the task bar ends
+- The progress field determines the progress displayed inside the task bar
+- The color field determines the task bar color
+- The time scale determines whether the timeline is displayed by hour, day, week, month, and so on
+
+### Title Field
+
+Used to display the task name. Usually, you can select a string field such as task name, project name, or title.
+
+### Start Date Field
+
+Used to specify the task start time. The Gantt block uses this field to place the task on the timeline.
+
+### End Date Field
+
+Used to specify the task end time. When the start date and end date are the same, the task is displayed as a shorter time range.
+
+### Progress Field
+
+Used to display task completion progress, and supports updating it by dragging the progress handle on the task bar.
+
+The progress field uses a float field. Data is stored from `0` to `1`, and displayed as a percentage in the Gantt block. For example, `0.6` is displayed as `60%`.
+
+### Color Field
+
+Used to set the task bar color, making it easier to distinguish different task types, statuses, or priorities.
+
+The color field supports:
+
+- Single select field
+- Color field
+
+If a single select field is used, the Gantt block will prioritize the color configured for the selected option.
+
+### Time Scale
+
+Used to control the timeline display granularity.
+
+Currently supported:
+
+- Hour
+- Quarter of day
+- Half of day
+- Day
+- Week
+- Month
+- Year
+- Quarter
+
+For short task spans, use hour, half-day, or day. For longer task spans, use week, month, quarter, or year.
+
+### Show Table
+
+When enabled, the Gantt block displays a table area on the left. You can configure table columns to show key task attributes.
+
+When disabled, the block only displays the timeline on the right. This is suitable when page space is limited or you only need to view scheduling.
+
+### Table Width
+
+Used to set the width of the left table area. This setting only appears when Show table is enabled.
+
+If there are many table fields, increase the table width. If only a few fields are kept, reduce the width and leave more space for the timeline.
+
+### Enable Drag to Reschedule
+
+When enabled, you can drag task bars on the timeline to adjust start and end dates.
+
+Details:
+
+- Drag the whole task bar to adjust both the start date and end date
+- Drag the handles on both sides of the task bar to adjust the start date or end date
+- Drag the progress handle to update the progress field
+
+If you do not want users to modify schedules directly in the Gantt block, disable this option.
+
+### Scroll to Today on First Display
+
+When enabled, the Gantt block automatically scrolls to today when it is first displayed.
+
+This option is suitable for projects with long task spans. When the page opens, users can first see tasks near the current date.
+
+### Event Popup Settings
+
+Used to configure how a task bar opens after being clicked.
+
+You can configure:
+
+- Open mode, such as drawer, dialog, or page
+- Popup size
+- Popup template
+
+After clicking a task bar, NocoBase opens the current record according to this configuration, making it convenient to view or edit task details.
+
+### Data Scope
+
+Used to limit the data displayed in the Gantt block.
+
+For example: only show tasks under the current project, or only show unfinished tasks.
+
+For more details, refer to [Data Scope](../block-settings/data-scope).
+
+### Page Size
+
+Used to control the number of records loaded per page. When there are many records, users can switch pages to view more tasks.
+
+### Show Row Numbers
+
+When enabled, the left table displays row numbers, making it easier to locate records when there are many tasks.
+
+### Tree Table
+
+If the current data table is a tree table, the Gantt block can enable tree table mode. After enabling it, the left table displays records by parent-child hierarchy, and the timeline on the right displays tasks in the same hierarchy.
+
+In tree table mode, you can also configure Expand all rows by default.
+
+## Configure Fields
+
+The left table area uses table columns to display record fields.
+
+![](https://static-docs.nocobase.com/Project-tasks-06-11-2026_11_29_AM.png)
+
+### Add Fields
+
+After Show table is enabled, you can add field columns to the left table. Field settings can refer to [Table Column](../../fields/generic/table-column).
+
+### Actions Column
+
+The Gantt block includes an actions column by default. You can add record actions such as view, edit, and delete to the actions column.
+
+If Event popup settings have already been configured, you can also click the task bar on the right to open record details.
+
+## Configure Actions
+
+The Gantt block supports configuring global actions at the top. Available action types depend on the enabled capabilities in the current environment.
+
+![](<https://static-docs.nocobase.com/Project-tasks-06-11-2026_11_29_AM%20(1).png>)
+
+### Built-in Actions
+
+- Today: quickly scroll to today
+- Expand/Collapse: expand or collapse all rows in tree table mode
+
+### Global Actions
+
+- [Add New](../../actions/types/add-new)
+- [Popup](../../actions/types/pop-up)
+- [Link](../../actions/types/link)
+- [Refresh](../../actions/types/refresh)
+- [Filter](../../actions/types/filter)
+- [Bulk Edit](../../actions/types/bulk-edit)
+- [Bulk Update](../../actions/types/bulk-update)
+- [Trigger Workflow](../../actions/types/trigger-workflow)
+- [Custom Request](../../actions/types/custom-request)
+- [JS Item](../../actions/types/js-item)
+- [JS Action](../../actions/types/js-action)
+- [AI Employee](../../actions/types/ai-employee)