@nocobase/plugin-ai 2.1.0-beta.43 → 2.1.0-beta.45

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

@@ -0,0 +1,163 @@
+---
+title: "Production Deployment"
+description: "Deploy NocoBase in production with two final steps: enable app autostart and configure a reverse proxy."
+keywords: "NocoBase,production deployment,nb app autostart,nb env proxy,Nginx,Caddy"
+---
+
+# Production Deployment
+
+If your NocoBase app is already running correctly on the server, production rollout usually only needs two more steps:
+
+1. Make sure the app starts automatically after the machine restarts
+2. Put a reverse proxy in front of the app for stable external access
+
+In the NocoBase CLI, the main commands are:
+
+- `nb app autostart`
+- `nb env proxy`
+
+This page gives the overall path first. For Nginx or Caddy details, continue to the corresponding subpages.
+
+## Step 1: Enable App Autostart
+
+In production, the first priority is not the domain name. The first priority is making sure the service can recover reliably after a reboot, container recreation, or routine maintenance.
+
+In the CLI, `nb app autostart` is a command group. The most commonly used commands are:
+
+- `nb app autostart enable`
+- `nb app autostart list`
+- `nb app autostart run`
+
+Enable autostart for the current env:
+
+```bash
+nb app autostart enable
+```
+
+If you want to target a different env explicitly:
+
+```bash
+nb app autostart enable --env app1 --yes
+```
+
+Then check which envs are marked for autostart:
+
+```bash
+nb app autostart list
+```
+
+After the system boots, run the following command to start every env that has autostart enabled:
+
+```bash
+nb app autostart run
+```
+
+If you want the underlying startup output for troubleshooting:
+
+```bash
+nb app autostart run --verbose
+```
+
+:::tip What this actually does
+
+`nb app autostart enable` marks a CLI-managed env as allowed to start automatically.  
+`nb app autostart run` is the command that actually starts all envs that were marked for autostart.
+
+In other words, in a real production setup you usually still need to wire `nb app autostart run` into your own system startup flow, such as `systemd`, a container platform startup script, or another host-level boot mechanism you already use.
+
+:::
+
+### Scope
+
+`nb app autostart` only applies to envs with a CLI-managed runtime on the current machine:
+
+- `local`
+- `docker`
+
+If the env is only a remote API connection, or the app is not managed locally by the CLI on this machine, these commands are not the right tool for autostart.
+
+## Step 2: Configure a Reverse Proxy
+
+Once the app can recover automatically, the next step is to handle the external entry point. In production, the reverse proxy usually takes care of:
+
+- binding the domain name or public port
+- forwarding HTTP and WebSocket traffic to NocoBase
+- handling HTTPS, certificates, caching, or access control
+
+In the NocoBase CLI, the recommended entry points are:
+
+- `nb env proxy nginx`
+- `nb env proxy caddy`
+
+### Default Approach
+
+If your app is already saved as a CLI env and is a `local` or `docker` env, letting the CLI generate the proxy config is usually enough:
+
+```bash
+nb env proxy nginx --env app1 --host app.example.com
+nb env proxy caddy --env app1 --host app.example.com
+```
+
+If the current env is already the target env, you can omit `--env`:
+
+```bash
+nb env proxy nginx --host app.example.com
+```
+
+The CLI helps cover details that are easy to miss in handwritten configs, such as:
+
+- WebSocket forwarding
+- entry and static asset paths for subpath deployments
+- SPA fallback pages
+- provider shared config files
+
+### When To Choose Nginx Or Caddy
+
+You can usually decide like this:
+
+| Scenario | Recommended |
+| --- | --- |
+| You already use Nginx for sites, caching, certificates, or access control | [Nginx](./reverse-proxy/nginx.md) |
+| You already have a domain and want HTTPS working quickly with less TLS maintenance | [Caddy](./reverse-proxy/caddy.md) |
+| You want the overall explanation of this command group first | [Production Reverse Proxy](./reverse-proxy/index.md) |
+
+If you change env settings that affect the proxy result, such as `app-port` or `app-public-path`, remember to rerun the corresponding proxy subcommand.
+
+## Recommended Rollout Path
+
+If you want the simplest production path, this order usually works well:
+
+1. Make sure the app can already start correctly on the server itself
+2. Run `nb app autostart enable`
+3. Add `nb app autostart run` to your system startup process
+4. Choose Nginx or Caddy and run the matching `nb env proxy` subcommand
+5. Verify external access through the final domain or public entry address
+
+## Quick Links
+
+| I want to... | Read this |
+| --- | --- |
+| Start with the overall reverse proxy explanation | [Production Reverse Proxy](./reverse-proxy/index.md) |
+| Keep using Nginx for the entry layer | [Nginx](./reverse-proxy/nginx.md) |
+| Use Caddy for a faster HTTPS setup | [Caddy](./reverse-proxy/caddy.md) |
+| Manage start, stop, logs, and upgrades | [Manage Apps](../operations/manage-app.md) |
+| Read the `nb env proxy` CLI reference | [`nb env proxy`](../../api/cli/env/proxy/index.md) |
+
+## Related Commands
+
+```bash
+# Enable autostart for one env
+nb app autostart enable --env app1 --yes
+
+# List autostart status
+nb app autostart list
+
+# Start all envs with autostart enabled
+nb app autostart run
+
+# Generate Nginx reverse proxy config
+nb env proxy nginx --env app1 --host app.example.com
+
+# Generate Caddy reverse proxy config
+nb env proxy caddy --env app1 --host app.example.com
+```

package/dist/ai/docs/nocobase/quickstart/production/reverse-proxy/caddy.md

@@ -0,0 +1,158 @@
+# Caddy
+
+If you already have a domain and want to get HTTPS running quickly, Caddy is usually the easiest choice. Compared with maintaining Nginx certificate config yourself, Caddy is more like the shortcut path for getting the entry layer online first.
+
+The default recommendation is to run `nb env proxy caddy` directly.
+
+## When Caddy is usually the better fit
+
+These cases usually favor Caddy first:
+
+- You already have a domain and want HTTPS quickly
+- You do not want to maintain too many certificate and TLS details yourself
+- You only need a simple and stable entry layer
+
+If you already use Nginx across the server to manage many sites, or you still need heavier caching, access control, and custom rules, [Nginx](./nginx.md) is usually the better fit.
+
+## Default path: let the CLI generate the Caddy config
+
+If your app has already been saved as a CLI env and the env type is `local` or `docker`, the default recommendation is still to let the CLI generate the config. That way, routing details related to NocoBase paths, WebSocket handling, and subpaths stay managed by the CLI, and you only need to care about the site entry itself.
+
+The most direct form is:
+
+```bash
+nb env proxy caddy --env demo --host demo.example.com
+```
+
+If you have already switched to the current env, you can also omit `--env`:
+
+```bash
+nb env proxy caddy --host demo.example.com
+```
+
+If you also want to specify the entry port, add it at the same time:
+
+```bash
+nb env proxy caddy --env demo --host demo.example.com --port 8080
+```
+
+`--host` is important here. Caddy decides whether to manage HTTPS based on the site address. In production, try to pass a domain that already resolves to the current server.
+
+### Which files the CLI generates
+
+If you do not pass `--output`, the Caddy provider keeps three layers of files under `~/.nocobase/proxy/caddy/<env>/`:
+
+| File | Purpose |
+| --- | --- |
+| `generated.caddy` | The actual reverse-proxy config managed by the CLI and overwritten every time you run `nb env proxy caddy` |
+| `app.caddy` | Editable site entry file where you can add site-level config |
+| `~/.nocobase/proxy/caddy/nocobase.caddy` | Shared main config that imports every env `app.caddy` |
+
+Where:
+
+- `generated.caddy` is only meant to be managed by the CLI and should not be edited manually
+- `app.caddy` is editable, but you should keep the generated import inserted by the CLI
+- `nocobase.caddy` is mainly used by `--install`
+
+:::warning Note
+
+If you need to add site-level Caddy config such as extra headers, authentication, rate limiting, or compression rules, edit `app.caddy`. `generated.caddy` will be overwritten the next time you run `nb env proxy caddy`.
+
+:::
+
+### Install the shared config into Caddy and reload it
+
+If you want the CLI to connect the shared config to the Caddy main config and immediately validate and reload Caddy, run:
+
+```bash
+nb env proxy caddy --env demo --host demo.example.com --install --reload
+```
+
+These flags are split like this:
+
+- `--install` connects `~/.nocobase/proxy/caddy/nocobase.caddy` to the Caddy main config
+- `--reload` validates the config first and then reloads Caddy
+
+If your Caddy executable is not on the default path, set the CLI config first:
+
+```bash
+nb config set bin.caddy /usr/bin/caddy
+```
+
+### When should you change `proxy.nb-cli-root`
+
+Most setups do not need to change `proxy.nb-cli-root`. You usually need it only when Caddy runs in another container, mount root, or path view and cannot see the current user's `~/.nocobase` path.
+
+For example, if Caddy sees that path as `/workspace/.nocobase/...` inside a container, set:
+
+```bash
+nb config set proxy.nb-cli-root /workspace
+nb env proxy caddy --env demo --install --reload
+```
+
+If you only want to preview the generated result, use:
+
+```bash
+nb env proxy caddy --env demo --print
+```
+
+If you want to write the generated route fragment to a custom file, use:
+
+```bash
+nb env proxy caddy --env demo --output ./generated.caddy
+```
+
+For the full parameter reference, see [`nb env proxy caddy`](../../../api/cli/env/proxy/caddy.md).
+
+## Handwritten config: what to do without the CLI
+
+If your app is not managed by the CLI, or you explicitly want to maintain the full `Caddyfile` yourself, start with this minimal version:
+
+```text
+your-domain.com {
+  encode zstd gzip
+  reverse_proxy 127.0.0.1:13000
+}
+```
+
+Where:
+
+- Replace `your-domain.com` with your domain
+- Replace `127.0.0.1:13000` with the real address your NocoBase app listens on
+
+If the domain already resolves to the current server correctly, Caddy usually handles HTTPS certificate issuance and renewal automatically.
+
+If you do not have a domain yet and only want to verify the reverse-proxy chain first, you can listen on a port:
+
+```text
+:80 {
+  reverse_proxy 127.0.0.1:13000
+}
+```
+
+In production, though, it is still better to switch to a domain-based site address as soon as possible so Caddy can also take over HTTPS.
+
+If your app is not mounted at `/` but under a subpath, handwritten Caddy config also means you need to confirm application variables such as `APP_PUBLIC_PATH` and `WS_PATH`. In that case, it is usually easier to go back to `nb env proxy caddy` and let the CLI generate the config.
+
+## Validate and reload the config
+
+```bash
+caddy validate --config /etc/caddy/Caddyfile
+systemctl reload caddy
+```
+
+If you do not manage Caddy with `systemd`, use your own startup and reload workflow.
+
+## Notes
+
+- `nb env proxy caddy` only works for CLI-managed envs whose runtime is reachable from the current machine, which means `local` or `docker`
+- If the command says the env is missing `appPort`, run `nb env update <name> --app-port <port>` first
+- `--output` and `--print` are useful for preview or custom integration, but they do not additionally create `app.caddy` or the shared main config
+- If you already have a domain that resolves correctly to the server, Caddy is often the fastest way to get HTTPS working
+
+## Related links
+
+- [`nb env proxy caddy`](../../../api/cli/env/proxy/caddy.md)
+- [Install with CLI (Recommended)](../../installation/cli.md)
+- [Install with Docker Compose](../../installation/docker-compose.md)
+- [App Environment Variables](../../installation/env.md)

package/dist/ai/docs/nocobase/quickstart/production/reverse-proxy/index.md

@@ -0,0 +1,100 @@
+---
+title: 'Reverse Proxy for Production'
+description: 'Use nb env proxy nginx and nb env proxy caddy to generate reverse-proxy configs for CLI-managed NocoBase envs.'
+keywords: 'NocoBase,nb env proxy nginx,nb env proxy caddy,reverse proxy,Nginx,Caddy,production'
+---
+
+# Reverse Proxy for Production
+
+In NocoBase CLI, there are two recommended entry points for putting a reverse proxy in front of a production app:
+
+- `nb env proxy nginx`
+- `nb env proxy caddy`
+
+As long as your app has already been saved as a CLI env and the env type is `local` or `docker`, letting the CLI generate the config is usually enough. That way, the CLI keeps tricky details such as WebSocket handling, subpaths, SPA fallback pages, and later updates in sync. You only need to decide whether the entry layer should keep using Nginx or move to Caddy.
+
+If your app is not managed by the CLI, or if you explicitly want to handwrite the full proxy config, go straight to the handwritten-config section in the provider pages.
+
+## Check whether this path fits your setup
+
+- Your app is already reachable through an internal address such as `http://127.0.0.1:13000`
+- The app has already been saved as a CLI env, and the env type is `local` or `docker`
+- The env already has `appPort` saved
+
+If the command says the env is missing `appPort`, run [`nb env update`](../../../api/cli/env/update.md) first and save it.
+
+If you later change settings such as `app-port` or `app-public-path` that affect proxy output, remember to rerun the matching proxy subcommand.
+
+## Default path: let the CLI generate the config first
+
+If you already know which entry provider you want to keep using, go straight to that subcommand:
+
+```bash
+nb env proxy nginx --env demo --host demo.example.com
+nb env proxy caddy --env demo --host demo.example.com
+```
+
+If you have already switched to the current env, you can also omit `--env`:
+
+```bash
+nb env proxy nginx --host demo.example.com
+```
+
+Where:
+
+- If you already use Nginx to manage sites, caching, access control, or certificates, start with [`nb env proxy nginx`](../../../api/cli/env/proxy/nginx.md)
+- If you want HTTPS running quickly and do not want to maintain many TLS details yourself, start with [`nb env proxy caddy`](../../../api/cli/env/proxy/caddy.md)
+- `--port` is the proxy entry port, not the app `appPort`
+
+If you want the CLI to also connect the shared config to the provider main config and reload it after validation, add:
+
+```bash
+nb env proxy nginx --env demo --host demo.example.com --install --reload
+```
+
+For the full command reference, see [`nb env proxy`](../../../api/cli/env/proxy/index.md).
+
+## What the CLI keeps in sync for you
+
+The CLI does more than generate one proxy snippet. It also maintains provider-specific helper files. The output shape differs between the two providers:
+
+- Nginx keeps `app.conf`, `public/index-v1.html`, `public/index-v2.html`, the shared `nocobase.conf`, and the shared `snippets/`
+- Caddy keeps `generated.caddy`, `app.caddy`, and the shared `nocobase.caddy`
+
+:::warning Note
+
+If you need to add site-level configuration, edit `app.conf` or `app.caddy`. Do not manually edit CLI-managed helper files, because they will be overwritten the next time you run the command.
+
+:::
+
+## Which page should you open first
+
+| I want to... | Go here |
+| --- | --- |
+| Keep using Nginx to manage sites, certificates, caching, or access control | [Nginx](./nginx.md) |
+| Get HTTPS running quickly and maintain fewer certificate and TLS details | [Caddy](./caddy.md) |
+| Review the command tree and choose a provider first | [`nb env proxy`](../../../api/cli/env/proxy/index.md) |
+| See the Nginx subcommand options, output files, and examples first | [`nb env proxy nginx`](../../../api/cli/env/proxy/nginx.md) |
+| See the Caddy subcommand options, output files, and examples first | [`nb env proxy caddy`](../../../api/cli/env/proxy/caddy.md) |
+| Adjust env settings that may affect proxy output, such as `app-port` or `app-public-path` | [`nb env update`](../../../api/cli/env/update.md) |
+| Install the app as a CLI-managed env first | [Install with CLI (Recommended)](../../installation/cli.md) |
+
+## When the CLI-generated path is not the best fit
+
+These cases are usually better served by the handwritten-config section in the provider pages:
+
+- Your app is not managed by the CLI
+- The env only has a remote API connection, or it is an SSH env
+- You explicitly want to maintain the full Nginx config or full `Caddyfile` yourself
+
+As long as the app has already been saved as a CLI env and the current machine can reach its runtime, the default recommendation is still to start with these commands. It makes later domain changes, site-level adjustments, and regeneration much easier to manage.
+
+## Related links
+
+- [`nb env proxy`](../../../api/cli/env/proxy/index.md)
+- [`nb env proxy nginx`](../../../api/cli/env/proxy/nginx.md)
+- [`nb env proxy caddy`](../../../api/cli/env/proxy/caddy.md)
+- [Nginx](./nginx.md)
+- [Caddy](./caddy.md)
+- [App Environment Variables](../../installation/env.md)
+- [Install with CLI (Recommended)](../../installation/cli.md)

package/dist/ai/docs/nocobase/quickstart/production/reverse-proxy/nginx.md

@@ -0,0 +1,166 @@
+# Nginx
+
+If you already use Nginx on the server to manage sites, or you still want to manage certificates, caching, or access control yourself, staying with Nginx is the most direct path. For CLI-managed NocoBase envs, this is also the default recommendation.
+
+If you mainly want to get HTTPS running quickly and do not want to maintain many proxy details yourself, [Caddy](./caddy.md) is the easier path. But if Nginx is already part of your stack, this page is the default place to start.
+
+## Confirm these two things first
+
+- NocoBase is already reachable through an internal address such as `http://127.0.0.1:13000`
+- You know whether this deployment is a CLI-managed env or a fully handwritten setup
+
+Once those two things are clear, the next step is usually straightforward:
+
+- If the app has already been saved as a CLI env and the env type is `local` or `docker`, use `nb env proxy nginx`
+- If the app is not managed by the CLI, or you explicitly want to maintain the full Nginx config yourself, handwrite the `server` block
+
+## Default path: let the CLI generate the Nginx config
+
+If your app was installed, adopted, or saved through NocoBase CLI as a `local` or `docker` env, the default recommendation is to run `nb env proxy nginx`. The CLI maintains the editable entry file, SPA fallback pages, shared main config, and shared snippets together, which makes it much less likely to miss WebSocket handling, subpaths, or later updates.
+
+Start by generating a config for a specific env:
+
+```bash
+nb env proxy nginx --env demo
+```
+
+If you have already switched to the current env, you can also omit `--env`:
+
+```bash
+nb env proxy nginx
+```
+
+If you already know the public domain or entry port, you can write them at generation time:
+
+```bash
+nb env proxy nginx --env demo --host demo.example.com
+nb env proxy nginx --env demo --host demo.example.com --port 8080
+```
+
+Here, `--port` is the proxy entry port, not the port the NocoBase app itself listens on. The upstream app port comes from the saved env `appPort`.
+
+### Which files the CLI generates
+
+The Nginx provider keeps these files under `~/.nocobase/proxy/nginx/`:
+
+| File | Purpose |
+| --- | --- |
+| `~/.nocobase/proxy/nginx/<env>/app.conf` | Editable site entry file. The CLI refreshes the managed block inside it, and you can add site-level config around that block |
+| `~/.nocobase/proxy/nginx/<env>/public/index-v1.html` | v1 SPA fallback page generated from the current active client's `index.html` |
+| `~/.nocobase/proxy/nginx/<env>/public/index-v2.html` | v2 SPA fallback page generated from the current active client's `v/index.html` |
+| `~/.nocobase/proxy/nginx/nocobase.conf` | Shared main config that includes every env `app.conf` |
+| `~/.nocobase/proxy/nginx/snippets/` | Shared snippets directory copied from built-in templates |
+
+Where:
+
+- `app.conf` is editable, but you should keep the managed block between `# BEGIN NocoBase managed config` and `# END NocoBase managed config`
+- `index-v1.html` and `index-v2.html` automatically rewrite asset URLs according to the current env subpath, active client version, and `CDN_BASE_URL`
+- `nocobase.conf` is mainly used by `--install`
+- Files under `snippets/` and `public/` are usually not meant to be edited manually and will be resynced the next time you run the command
+
+:::warning Note
+
+If you need to add site-level Nginx config such as rate limits, extra headers, or access control, edit `app.conf`. Managed files under `public/` and `snippets/` will be overwritten the next time you run `nb env proxy nginx`.
+
+:::
+
+### Install the shared config into Nginx and reload it
+
+If you want the CLI to connect the shared config to the Nginx main config and immediately validate and reload Nginx, run:
+
+```bash
+nb env proxy nginx --env demo --host demo.example.com --install --reload
+```
+
+These flags are split like this:
+
+- `--install` connects `~/.nocobase/proxy/nginx/nocobase.conf` to the Nginx main config
+- `--reload` validates the config first and then reloads Nginx
+
+If your Nginx executable is not on the default path, set the CLI config first:
+
+```bash
+nb config set bin.nginx /usr/sbin/nginx
+```
+
+### When should you change `proxy.nb-cli-root`
+
+Most setups do not need to change `proxy.nb-cli-root`. You usually need it only when Nginx runs in another container, mount root, or path view and cannot see the current user's `~/.nocobase` path.
+
+For example, if Nginx sees that path as `/workspace/.nocobase/...` inside a container, set:
+
+```bash
+nb config set proxy.nb-cli-root /workspace
+nb env proxy nginx --env demo --install --reload
+```
+
+If you only want to preview the rendered `app.conf`, you can also use:
+
+```bash
+nb env proxy nginx --env demo --print
+```
+
+The Nginx provider does not support `--output`. For the full parameter reference, see [`nb env proxy nginx`](../../../api/cli/env/proxy/nginx.md).
+
+## Handwritten config: what to do without the CLI
+
+If your app is not managed by the CLI, or you explicitly want to maintain the full Nginx config yourself, start with this minimal version. In most cases, one `server` block is enough.
+
+Create a config file on the server, for example `/etc/nginx/conf.d/nocobase.conf`:
+
+```nginx
+server {
+    listen 80;
+    server_name your-domain.com;
+
+    client_max_body_size 100m;
+
+    location / {
+        proxy_pass http://127.0.0.1:13000;
+        proxy_http_version 1.1;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection "upgrade";
+    }
+}
+```
+
+Where:
+
+- Replace `server_name` with your domain
+- Replace `127.0.0.1:13000` with the real address your NocoBase app listens on
+- Adjust `client_max_body_size` to match your upload needs
+
+If your app is not mounted at `/` but under a subpath such as `/app/`, handwritten configs also need you to confirm application variables such as `APP_PUBLIC_PATH` and `WS_PATH`. In that case, it is usually easier to go back to `nb env proxy nginx` and let the CLI handle the routing details.
+
+## Validate and reload the config
+
+```bash
+nginx -t
+systemctl reload nginx
+```
+
+If you do not manage Nginx with `systemd`, use your own reload workflow.
+
+## How to handle HTTPS
+
+If you have already decided to stay with Nginx, you can keep handling HTTPS there as well. A common next step is to expand `listen 80` into dual `80/443` entry points and add your certificate paths and TLS config.
+
+But if you mainly want working HTTPS as quickly as possible and do not want to deal with certificate issuance and renewal yourself, switching to [Caddy](./caddy.md) is usually easier.
+
+## Notes
+
+- `nb env proxy nginx` only works for CLI-managed envs whose runtime is reachable from the current machine, which means `local` or `docker`
+- If the command says the env is missing `appPort`, run `nb env update <name> --app-port <port>` first
+- `nb env proxy nginx` does not support `--output`. If you only want to preview the entry file, use `--print`
+- If you already have a large custom Nginx main config, the CLI-generated config usually fits best as a site fragment that you include, not as a replacement for the whole main config
+
+## Related links
+
+- [`nb env proxy nginx`](../../../api/cli/env/proxy/nginx.md)
+- [Install with CLI (Recommended)](../../installation/cli.md)
+- [Install with Docker Compose](../../installation/docker-compose.md)
+- [App Environment Variables](../../installation/env.md)

package/dist/ai/docs/nocobase/quickstart/release-management.md

@@ -0,0 +1 @@
+# 发布管理