@nocobase/plugin-ai 2.1.0-beta.46 → 2.1.0-beta.48

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

@@ -1,69 +1,94 @@
 ---
-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'
+title: "Reverse Proxy in Production"
+description: "Use nb proxy nginx and nb proxy caddy to generate and manage reverse-proxy configuration for CLI-managed NocoBase envs."
+keywords: "NocoBase,nb proxy nginx,nb proxy caddy,reverse proxy,Nginx,Caddy,production"
 ---
 
-# Reverse Proxy for Production
+# Reverse Proxy in Production
 
-In NocoBase CLI, there are two recommended entry points for putting a reverse proxy in front of a production app:
+In NocoBase CLI, the recommended production reverse-proxy entrypoints are:
 
-- `nb env proxy nginx`
-- `nb env proxy caddy`
+- `nb proxy nginx`
+- `nb 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.
+Where:
+
+- `proxy` manages the entry layer
+- `nginx` and `caddy` are the provider implementations
+- `docker` and `local` are the runtime drivers
+- `--env <name>` selects which CLI env to generate config for
+
+As long as your app has been saved as a CLI-managed env and the env is `local` or `docker`, letting the CLI generate and manage the reverse-proxy config is usually enough. That approach keeps WebSocket handling, subpaths, SPA fallback pages, and later updates aligned in one place.
 
-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.
+If the app is not CLI-managed, or you intentionally want to maintain the entire proxy configuration by hand, move on to the handwritten-config sections in the provider-specific pages.
 
-## Check whether this path fits your setup
+## Before you start
 
-- 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
+Make sure that:
 
-If the command says the env is missing `appPort`, run [`nb env update`](../../../api/cli/env/update.md) first and save it.
+- the app can already be reached internally, such as `http://127.0.0.1:13000`
+- the app has already been saved as a CLI env, and that env is `local` or `docker`
+- the env already has `appPort` saved
 
-If you later change settings such as `app-port` or `app-public-path` that affect proxy output, remember to rerun the matching proxy subcommand.
+If the command says the env is missing `appPort`, update it first with [`nb env update`](../../../api/cli/env/update.md).
 
-## Default path: let the CLI generate the config first
+If you later change settings such as `app-port` or `app-public-path` that affect proxy behavior, rerun the matching `generate` command.
 
-If you already know which entry provider you want to keep using, go straight to that subcommand:
+## Default workflow
+
+For Nginx:
 
 ```bash
-nb env proxy nginx --env demo --host demo.example.com
-nb env proxy caddy --env demo --host demo.example.com
+nb proxy nginx use docker
+nb proxy nginx generate --env test2 --host c.local.nocobase.com
+nb proxy nginx start
 ```
 
-If you have already switched to the current env, you can also omit `--env`:
+For Caddy:
 
 ```bash
-nb env proxy nginx --host demo.example.com
+nb proxy caddy use local
+nb proxy caddy generate --env test2 --host c.local.nocobase.com
+nb proxy caddy start
 ```
 
-Where:
+The roles are:
 
-- 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`
+- `use docker|local`: choose the runtime driver for the current provider
+- `generate --env <name> --host <domain>`: generate reverse-proxy config for one env
+- `start`: start the local process or Docker container for the current provider
 
-If you want the CLI to also connect the shared config to the provider main config and reload it after validation, add:
+If you update the config later, `reload` is usually the first choice. Use `restart` when you need a full restart of the entry layer.
 
-```bash
-nb env proxy nginx --env demo --host demo.example.com --install --reload
-```
+## How the command group is split
+
+Using Nginx as the example:
+
+| Command | Purpose |
+| --- | --- |
+| `nb proxy nginx use docker` | Switch the Nginx runtime to Docker |
+| `nb proxy nginx use local` | Switch the Nginx runtime to a local process |
+| `nb proxy nginx current` | Show the current runtime driver |
+| `nb proxy nginx generate --env <name> --host <domain>` | Generate Nginx config for one env |
+| `nb proxy nginx start` | Start Nginx |
+| `nb proxy nginx reload` | Reload the Nginx config |
+| `nb proxy nginx restart` | Restart Nginx |
+| `nb proxy nginx stop` | Stop Nginx |
+| `nb proxy nginx status` | Show Nginx status |
+| `nb proxy nginx info` | Show the current config, paths, and runtime details |
 
-For the full command reference, see [`nb env proxy`](../../../api/cli/env/proxy/index.md).
+Caddy uses the same action set, but with a different provider implementation.
 
-## What the CLI keeps in sync for you
+## What the CLI maintains
 
-The CLI does more than generate one proxy snippet. It also maintains provider-specific helper files. The output shape differs between the two providers:
+The CLI does more than produce one proxy fragment. It also keeps the helper files and site entry structure aligned with the provider:
 
-- 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`
+- Nginx maintains shared `snippets`, `app.conf`, `public/index-v1.html`, and `public/index-v2.html`
+- Caddy maintains `nocobase.caddy`, `app.caddy`, `public/index-v1.html`, and `public/index-v2.html`, where `app.caddy` is the full site config for one env
 
 :::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.
+If you need to add site-level configuration, you usually edit `app.conf` for Nginx and use `app.caddy` as the base for Caddy. Do not edit the CLI-managed helper files directly. Also note that `app.caddy` is overwritten as a whole when you run `generate` again, while `nocobase.caddy` mainly serves as the provider-level entry file.
 
 :::
 
@@ -71,30 +96,24 @@ If you need to add site-level configuration, edit `app.conf` or `app.caddy`. Do
 
 | 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) |
+| Keep using Nginx for sites, certificates, caching, or access control | [Nginx](./nginx.md) |
+| Get HTTPS running quickly with fewer TLS details to maintain | [Caddy](./caddy.md) |
+| Adjust env settings that may affect proxy behavior, 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 the CLI](../../installation/cli.md) |
 
-## When the CLI-generated path is not the best fit
+## When the CLI path is not the right fit
 
-These cases are usually better served by the handwritten-config section in the provider pages:
+In these cases, the handwritten-config sections in the provider-specific pages are usually a better fit:
 
-- 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
+- the app is not CLI-managed
+- the env is only a remote API connection or an SSH env
+- you intentionally want to maintain the entire Nginx config or `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.
+As long as the app has been saved as a CLI env and its runtime is reachable from the current machine, using this command group is still the recommended default. It is usually much easier to maintain later when you need to change the domain, add site-level config, switch drivers, or regenerate the entry files.
 
 ## 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)
+- [Environment variables](../../installation/env.md)
+- [Install with the CLI](../../installation/cli.md)

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

@@ -1,166 +1,263 @@
+---
+title: "Nginx"
+description: "Use nb proxy nginx to generate and manage Nginx reverse-proxy configuration for CLI-managed NocoBase envs."
+keywords: "NocoBase,nb proxy nginx,reverse proxy,Nginx,production"
+---
+
 # 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 already use Nginx on the server to manage sites, or you still want to manage certificates, caching, and access control yourself, `nb proxy nginx` is the recommended path.
+
+If your goal is simply to get HTTPS working as quickly as possible and you do not want to maintain many proxy details yourself, [Caddy](./caddy.md) is usually the simpler option. But if Nginx is already part of your server setup, this page is the default path.
 
-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.
+## When Nginx is the better fit
 
-## Confirm these two things first
+In practice, Nginx is usually the better choice when:
 
-- 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
+- you already use Nginx to manage multiple sites on the same server
+- you still need to maintain certificates, caching, access control, or more custom rules yourself
+- you want the entry layer to stay aligned with your existing Nginx operations workflow
 
-Once those two things are clear, the next step is usually straightforward:
+If the only goal is to get HTTPS online quickly with less TLS work, [Caddy](./caddy.md) is usually the simpler route.
 
-- 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
+## Recommended order: choose a driver, generate config, then start
 
-## Default path: let the CLI generate the Nginx config
+For a CLI-managed env of type `local` or `docker`, the default order is:
 
-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.
+```bash
+nb proxy nginx use docker
+nb proxy nginx generate --env test2 --host c.local.nocobase.com
+nb proxy nginx start
+```
 
-Start by generating a config for a specific env:
+Or with a local process:
 
 ```bash
-nb env proxy nginx --env demo
+nb proxy nginx use local
+nb proxy nginx generate --env test2 --host c.local.nocobase.com
+nb proxy nginx start
 ```
 
-If you have already switched to the current env, you can also omit `--env`:
+Common follow-up commands are:
 
 ```bash
-nb env proxy nginx
+nb proxy nginx current
+nb proxy nginx status
+nb proxy nginx info
+nb proxy nginx reload
+nb proxy nginx restart
+nb proxy nginx stop
 ```
 
-If you already know the public domain or entry port, you can write them at generation time:
+In most cases:
+
+- `current` is the quickest way to confirm the active runtime driver
+- `status` shows whether Nginx is currently running normally
+- `info` shows the current config path, runtime root, and related runtime details
+- after regenerating config, `reload` is usually the first command to use
+- use `restart` when you need a full restart
+
+## What `generate` needs as input
+
+The most common form is:
 
 ```bash
-nb env proxy nginx --env demo --host demo.example.com
-nb env proxy nginx --env demo --host demo.example.com --port 8080
+nb proxy nginx generate --env test2 --host c.local.nocobase.com
 ```
 
-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`.
+If you also want to specify the entry port:
 
-### Which files the CLI generates
+```bash
+nb proxy nginx generate --env test2 --host c.local.nocobase.com --port 8080
+```
+
+Where:
+
+- `--env`: which CLI env to generate config for
+- `--host`: the public domain name
+- `--port`: the proxy entry port, not the app's own `appPort`
 
-The Nginx provider keeps these files under `~/.nocobase/proxy/nginx/`:
+The upstream application port comes from the saved `appPort` of that env. If the command says the env is missing `appPort`, save it first with:
+
+```bash
+nb env update test2 --app-port 56575
+```
 
-| File | Purpose |
+If you later change settings such as `app-port` or `app-public-path` that affect proxy behavior, rerun `generate`.
+
+## Files maintained by the CLI
+
+Using `test2` as an example, the Nginx workflow usually maintains:
+
+| Path | 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 |
+| `NB_CLI_ROOT/.nocobase/proxy/nginx/snippets` | Shared Nginx snippets directory |
+| `NB_CLI_ROOT/.nocobase/proxy/nginx/test2/app.conf` | Editable site entry config |
+| `NB_CLI_ROOT/.nocobase/proxy/nginx/test2/public/index-v1.html` | v1 SPA fallback page |
+| `NB_CLI_ROOT/.nocobase/proxy/nginx/test2/public/index-v2.html` | v2 SPA fallback page |
+| `NB_CLI_ROOT/test2/storage/dist-client` | Frontend build output for the current app |
+| `NB_CLI_ROOT/test2/storage/uploads` | Uploads directory for the current app |
 
 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
+- files under `NB_CLI_ROOT/.nocobase/proxy/nginx/...` are CLI-managed proxy helper files
+- files under `NB_CLI_ROOT/test2/storage/...` belong to the application itself
+- `app.conf` can be edited, but the NocoBase-managed block must stay intact
+- `index-v1.html` and `index-v2.html` are rewritten according to the current env's subpath, active client version, and `CDN_BASE_URL`
 
 :::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`.
+If you need site-level Nginx config such as rate limiting, extra headers, or access control, edit `app.conf`. The CLI-managed helper files are updated again when you regenerate the config.
 
 :::
 
-### Install the shared config into Nginx and reload it
+## Handwritten config: when you are not using the CLI
 
-If you want the CLI to connect the shared config to the Nginx main config and immediately validate and reload Nginx, run:
+If the app is not CLI-managed, or you intentionally want to maintain the complete Nginx config yourself, you can still write it by hand.
 
-```bash
-nb env proxy nginx --env demo --host demo.example.com --install --reload
-```
+For NocoBase, though, a production reverse proxy is usually more than a single `proxy_pass`. In addition to forwarding API requests to the backend app, a complete config usually needs to handle uploads, frontend assets, WebSocket, `.well-known` routes, and SPA fallback pages together.
 
-These flags are split like this:
+Using `test2` as the example, these are the key Nginx-related files and directories:
 
-- `--install` connects `~/.nocobase/proxy/nginx/nocobase.conf` to the Nginx main config
-- `--reload` validates the config first and then reloads Nginx
+- Nginx snippets: `NB_CLI_ROOT/.nocobase/proxy/nginx/snippets`
+- Editable entry config: `NB_CLI_ROOT/.nocobase/proxy/nginx/test2/app.conf`
+- SPA fallback page for v1: `NB_CLI_ROOT/.nocobase/proxy/nginx/test2/public/index-v1.html`
+- SPA fallback page for v2: `NB_CLI_ROOT/.nocobase/proxy/nginx/test2/public/index-v2.html`
+- Frontend build output: `NB_CLI_ROOT/test2/storage/dist-client`
+- Uploads directory: `NB_CLI_ROOT/test2/storage/uploads`
 
-If your Nginx executable is not on the default path, set the CLI config first:
+In other words, a handwritten config usually needs to cover at least these entry areas:
 
-```bash
-nb config set bin.nginx /usr/sbin/nginx
+- `uploads`
+- `dist`
+- `well-known`
+- `api`
+- `ws`
+- `spa`
+
+So a complete Nginx config is usually more than a generic reverse proxy such as:
+
+```nginx
+location / {
+    proxy_pass http://127.0.0.1:13000;
+}
 ```
 
-### When should you change `proxy.nb-cli-root`
+For a CLI-managed app such as `test2`, a more realistic deployment structure usually looks closer to this:
 
-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.
+```nginx
+server {
+    listen 80;
+    server_name c.local.nocobase.com;
 
-For example, if Nginx sees that path as `/workspace/.nocobase/...` inside a container, set:
+    # Add custom directives or locations above the managed block as needed.
 
-```bash
-nb config set proxy.nb-cli-root /workspace
-nb env proxy nginx --env demo --install --reload
-```
+    client_max_body_size 0;
 
-If you only want to preview the rendered `app.conf`, you can also use:
+    include NB_CLI_ROOT/.nocobase/proxy/nginx/snippets/mime-types.conf;
+    include NB_CLI_ROOT/.nocobase/proxy/nginx/snippets/gzip.conf;
 
-```bash
-nb env proxy nginx --env demo --print
-```
+    location /storage/uploads/ {
+        alias NB_CLI_ROOT/test2/storage/uploads/;
+        include NB_CLI_ROOT/.nocobase/proxy/nginx/snippets/uploads-location.conf;
+    }
 
-The Nginx provider does not support `--output`. For the full parameter reference, see [`nb env proxy nginx`](../../../api/cli/env/proxy/nginx.md).
+    location ^~ /dist/ {
+        alias NB_CLI_ROOT/test2/storage/dist-client/;
+        include NB_CLI_ROOT/.nocobase/proxy/nginx/snippets/dist-location.conf;
+    }
 
-## Handwritten config: what to do without the CLI
+    location ~ ^/\\.well-known/(?<well_known>oauth-authorization-server|openid-configuration)/(?<resource_path>.+)$ {
+        rewrite ^ /$resource_path/.well-known/$well_known break;
+        proxy_pass http://127.0.0.1:56575;
+        include NB_CLI_ROOT/.nocobase/proxy/nginx/snippets/proxy-location.conf;
+    }
 
-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.
+    location ^~ /api/ {
+        proxy_pass http://127.0.0.1:56575;
+        include NB_CLI_ROOT/.nocobase/proxy/nginx/snippets/proxy-location.conf;
+    }
 
-Create a config file on the server, for example `/etc/nginx/conf.d/nocobase.conf`:
+    location = /ws {
+        proxy_pass http://127.0.0.1:56575;
+        include NB_CLI_ROOT/.nocobase/proxy/nginx/snippets/proxy-location.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";
+    location = /v {
+        return 302 /v/$is_args$args;
+    }
+
+    location ^~ /v/ {
+        alias NB_CLI_ROOT/.nocobase/proxy/nginx/test2/public/;
+        try_files $uri /index-v2.html =404;
+        include NB_CLI_ROOT/.nocobase/proxy/nginx/snippets/spa-location.conf;
+    }
+
+    location ^~ / {
+        alias NB_CLI_ROOT/.nocobase/proxy/nginx/test2/public/;
+        try_files $uri /index-v1.html =404;
+        include NB_CLI_ROOT/.nocobase/proxy/nginx/snippets/spa-location.conf;
     }
+
+    # Add custom directives or locations below the managed block as needed.
 }
 ```
 
-Where:
+Two details matter here:
+
+- files under `NB_CLI_ROOT/.nocobase/proxy/nginx/...` are CLI-managed proxy helper files
+- files under `NB_CLI_ROOT/test2/storage/...` belong to the application's own build output and uploads
+
+If the app uses subpath deployment, or if frontend assets, uploads, and the reverse proxy do not share the same path view, handwritten config becomes easier to get wrong. In those cases, it is usually safer to generate the config first with:
+
+```bash
+nb proxy nginx generate --env test2 --host c.local.nocobase.com
+```
 
-- 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
+Then use the generated result as the baseline for manual adjustments.
 
-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.
+The safer workflow is usually:
+
+1. let the CLI generate the Nginx config first
+2. use the generated output to confirm the routing structure and real filesystem paths
+3. then adjust it for your own domain, runtime driver, and mount layout
+
+That is usually less error-prone than writing the full config from scratch.
 
 ## Validate and reload the config
 
+If you write or adjust Nginx config manually, validate it first and then reload:
+
 ```bash
 nginx -t
 systemctl reload nginx
 ```
 
-If you do not manage Nginx with `systemd`, use your own reload workflow.
+If you are not using `systemd` to manage Nginx, replace that with your own reload workflow.
+
+If you manage the entry layer through `nb proxy nginx`, the usual first choice is:
+
+```bash
+nb proxy nginx reload
+```
 
 ## 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.
+If you have already decided to keep using Nginx, you can keep HTTPS there as well. A common pattern is to extend `listen 80` into a `80/443` setup and then add certificate paths and TLS settings.
 
-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.
+If the goal is simply to get usable HTTPS quickly without managing certificate issuance and renewal yourself, switching to [Caddy](./caddy.md) is usually simpler.
 
-## Notes
+## Common 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
+- `nb proxy nginx generate` 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
+- if you already have a large top-level Nginx config, the CLI-generated config is usually better used as a site fragment than as a replacement for the entire main config
+- if you later change settings such as `app-port` or `app-public-path` that affect proxy behavior, rerun `generate`
 
 ## Related links
 
-- [`nb env proxy nginx`](../../../api/cli/env/proxy/nginx.md)
-- [Install with CLI (Recommended)](../../installation/cli.md)
+- [Reverse Proxy in Production](./index.md)
+- [Caddy](./caddy.md)
+- [Install with the CLI](../../installation/cli.md)
 - [Install with Docker Compose](../../installation/docker-compose.md)
-- [App Environment Variables](../../installation/env.md)
+- [Environment variables](../../installation/env.md)