@nocobase/plugin-ai 2.1.0-alpha.46 → 2.1.0-alpha.47

package/dist/ai/docs/nocobase/quickstart/operations/manage-app.md

@@ -0,0 +1,166 @@
+# 管理应用
+
+如果你已经把一个 NocoBase 应用保存成 CLI env，日常管理基本都在 `nb app` 这一组命令里完成：启动、停止、重启、查看日志、升级，以及清理本地运行资源。
+
+大多数时候，你不需要记住所有参数。先分清楚自己要做的是“把应用跑起来”“看日志排查问题”，还是“彻底清理这个 env”，再选对应命令就行。
+
+## 快速索引
+
+| 我想要…… | 用哪个命令 |
+| --- | --- |
+| 启动或恢复应用运行 | [`nb app start`](../../api/cli/app/start.md) |
+| 临时停止应用 | [`nb app stop`](../../api/cli/app/stop.md) |
+| 连同 CLI 托管的内置数据库一起停掉 | [`nb app stop --with-db`](../../api/cli/app/stop.md) |
+| 修改配置后重新拉起应用 | [`nb app restart`](../../api/cli/app/restart.md) |
+| 实时查看应用日志 | [`nb app logs`](../../api/cli/app/logs.md) |
+| 升级到新的源码或镜像版本 | [`nb app upgrade`](../../api/cli/app/upgrade.md) |
+| 移除 env 配置，但保留 storage 和本地 app 文件 | [`nb env remove`](../../api/cli/env/remove.md) |
+| 连同本机托管资源一起彻底清理 | [`nb env remove --purge`](../../api/cli/env/remove.md) |
+
+:::tip 先确认当前 env
+
+`nb app` 命令默认作用在当前 env 上。如果你同时维护多个环境，默认推荐先切到目标 env，再执行启动、升级或清理操作。
+
+```bash
+nb env current
+nb env use app1
+```
+
+如果你显式传入了不同的 `--env`，CLI 通常会要求确认。脚本或非交互场景里，可以加 `--yes` 跳过这一步。
+
+:::
+
+## 启动应用
+
+把应用拉起来，默认用 `nb app start` 就行：
+
+```bash
+nb app start
+```
+
+如果你要操作的不是当前 env，可以显式指定：
+
+```bash
+nb app start --env app1 --yes
+```
+
+另外几个比较常用的启动参数：
+
+```bash
+nb app start --no-daemon
+```
+
+- `nb app start` 默认会先自动完成必要的安装或升级准备，再把服务拉起来
+- `--no-daemon` 只在本地 env 下有明显意义——应用会以前台模式运行，方便你直接看控制台输出
+
+本地 npm/Git env 会启动本地应用进程，Docker env 会按已保存配置重建应用容器。详细参数见 [`nb app start`](../../api/cli/app/start.md)。
+
+## 停止和重启
+
+只想临时把应用停掉，用 `nb app stop`：
+
+```bash
+nb app stop
+```
+
+如果你刚改完配置、依赖或代码，通常来说直接 `nb app restart` 更省事：
+
+```bash
+nb app restart
+nb app restart --env app1 --yes
+```
+
+`nb app restart` 会先执行停止，再按 `start` 的方式重新启动，所以它也支持 `--no-daemon` 这类启动参数。详细用法见 [`nb app stop`](../../api/cli/app/stop.md) 和 [`nb app restart`](../../api/cli/app/restart.md)。
+
+## 查看日志
+
+排查问题时，通常先看日志：
+
+```bash
+nb app logs
+```
+
+如果你只想多看一点最近输出，或者不想持续跟随日志，可以这样用：
+
+```bash
+nb app logs --tail 200
+nb app logs --no-follow
+nb app logs --env app1 --yes
+```
+
+本地 npm/Git env 读取的是 pm2 日志，Docker env 读取的是容器日志。默认情况下，`nb app logs` 会持续跟随新日志输出。详细参数见 [`nb app logs`](../../api/cli/app/logs.md)。
+
+## 升级应用
+
+升级命令是 `nb app upgrade`：
+
+```bash
+nb app upgrade
+```
+
+这个命令做的不只是“下载新版本”。默认流程通常包括：
+
+1. 停止当前应用
+2. 下载并替换已保存的源码或镜像
+3. 同步商业插件
+4. 升级并启动应用
+5. 刷新 env runtime 信息
+
+如果你已经提前更新好了源码或镜像，只想基于当前内容继续执行升级并启动应用，可以加 `--skip-download`：
+
+```bash
+nb app upgrade --skip-download
+```
+
+如果你想显式指定目标版本，也可以加 `--version`：
+
+```bash
+nb app upgrade --version beta
+```
+
+:::warning 注意
+
+`nb app upgrade` 在真正开始前通常还会要求你确认一次。脚本、CI 或其他非交互场景里，需要显式传入 `--force`。如果同时还是跨 env 操作，通常要一起带上 `--yes`。
+
+```bash
+nb app upgrade --env app1 --yes --force
+```
+
+:::
+
+更完整的参数说明见 [`nb app upgrade`](../../api/cli/app/upgrade.md)。
+
+## 清理运行资源和销毁 env
+
+这几种场景最容易混淆。可以先记住一个默认建议：
+
+- 只是想把应用停掉，用 `nb app stop`
+- 也想把当前机器上的内置数据库运行时一起停掉，用 `nb app stop --with-db`
+- 确定这个 env 不再需要了，但想先保留 storage 和本地 app 文件，用 `nb env remove`
+- 连本机托管资源也一起清理掉，再用 `nb env remove --purge`
+
+如果你只是想停掉应用和 CLI 托管的内置数据库，直接这样写就行：
+
+```bash
+nb app stop --env app1 --with-db
+```
+
+如果你要移除这个 env，但还想保留 storage 和本地 app 文件：
+
+```bash
+nb env remove app1 --force
+```
+
+如果你确实要把这个 env 的本机托管内容也一起清理掉，那么加上 `--purge`：
+
+```bash
+nb env remove app1 --purge --force
+```
+
+对于 CLI 下载管理的本地 npm/Git env，`--purge` 还会删除 CLI 托管的本地应用文件。对于 HTTP 或 SSH env，它只会删除 CLI 里保存的 env 配置，不会去删除外部服务本身。
+
+## 相关链接
+
+- [多环境管理](./multi-environment.md)
+- [`nb app` 命令参考](../../api/cli/app/index.md)
+- [`nb env` 命令参考](../../api/cli/env/index.md)

package/dist/ai/docs/nocobase/quickstart/operations/multi-environment.md

@@ -0,0 +1,171 @@
+# 多环境管理
+
+如果你同时维护 `dev`、`test`、`staging`、`prod` 等多个 NocoBase 应用，可以把它们分别保存成 CLI env。之后大多数 `nb` 命令都会默认作用在当前 env 上，所以在执行 `nb app`、`nb api`、`nb db` 这类命令前，先确认自己正在用哪个 env 很重要。
+
+CLI 从这一版开始把概念拆成了 `current env` 和 `last env`。你通常只需要关心 `current env`——也就是当前 shell 或 agent runtime 正在使用的环境。只有在没有开启 session mode 时，CLI 才会回退到全局 `last env`。
+
+## 快速索引
+
+| 我想要…… | 用哪个命令 |
+| --- | --- |
+| 新建一个本地 env，并顺手完成初始化 | [`nb init`](../../api/cli/init.md) |
+| 把一个已有应用登记成 CLI env | [`nb env add`](../../api/cli/env/add.md) |
+| 看本地保存了哪些 env | [`nb env list`](../../api/cli/env/list.md) |
+| 检查所有 env 的连通性和认证状态 | [`nb env status --all`](../../api/cli/env/status.md) |
+| 切换后续命令要使用的 env | [`nb env use`](../../api/cli/env/use.md) |
+| 确认当前命令会落到哪个 env | [`nb env current`](../../api/cli/env/current.md) 和 [`nb env status`](../../api/cli/env/status.md) |
+| 查看某个 env 保存了哪些详细配置 | [`nb env info`](../../api/cli/env/info.md) |
+| 更新已保存的 env 配置，必要时让 CLI 重新同步当前状态 | [`nb env update`](../../api/cli/env/update.md) |
+| 登录态过期后重新认证，或者改用新的认证方式 | [`nb env auth`](../../api/cli/env/auth.md) |
+| 删除不用的 env 配置，必要时连本机托管资源一起清理 | [`nb env remove`](../../api/cli/env/remove.md) |
+
+:::tip 建议先开启 session mode
+
+默认推荐先执行一次 [`nb session setup`](../../api/cli/session/setup.md)。这样不同终端、不同 shell，或者不同 agent runtime 可以各自维护自己的 `current env`，并行操作时不容易互相影响。
+
+如果没有开启 session mode，那么 `nb env use` 会回退到更新全局 `last env`。这种情况下，一个终端切走环境，另一个终端也可能跟着受影响。
+
+```bash
+nb session setup
+```
+
+:::
+
+## 创建多个环境
+
+如果你要新建或恢复一个本地应用，用 `nb init` 就行。它会完成初始化，并把结果保存成一个新的 CLI env。
+
+```bash
+nb init --env dev
+nb init --env test
+```
+
+如果应用已经存在，只是想把它接入 CLI，通常来说用 `nb env add` 更直接：
+
+```bash
+nb env add staging --api-base-url http://staging.example.com/api --auth-type oauth
+nb env add prod --api-base-url https://api.example.com/api --auth-type token --access-token <token>
+```
+
+前者偏“初始化一个环境”，后者偏“登记一个已有环境”。如果你只是连接已有应用，默认用 `nb env add` 就行。
+
+## 查看已经配置的环境
+
+先用 `nb env list` 看看本地已经保存了哪些 env：
+
+```bash
+nb env list
+```
+
+这个命令只展示配置本身，不主动检查应用状态。想同时看连通性和认证状态时，用 `nb env status --all`：
+
+```bash
+nb env status --all
+```
+
+你通常会看到 `ok`、`auth failed`、`unreachable` 这类状态值。
+
+## 切换当前环境
+
+切换环境用 `nb env use`：
+
+```bash
+nb env use dev
+```
+
+切换完成后，后续省略 `--env` 的命令都会默认使用这个 env。
+
+## 查看当前环境
+
+如果你不确定当前命令会落到哪个环境上，先执行这两个命令：
+
+```bash
+nb env current
+nb env status
+```
+
+`nb env current` 用来看名称，`nb env status` 用来看当前 env 是否可访问、认证是否正常。
+
+## 查看单个 env 的详细信息
+
+想看某个 env 保存了哪些配置，用 `nb env info`：
+
+```bash
+nb env info dev
+nb env info dev --json
+nb env info dev --field app.url
+nb env info dev --show-secrets
+```
+
+其中，`--field` 适合在脚本里只取一个值。`--show-secrets` 会明文显示 token、密码这类敏感信息，只有在你明确需要排查时再用。
+
+## 更新 env 配置
+
+`nb env update` 用来调整一个已保存 env 的配置。比如 API 地址、认证方式、源码来源、应用端口和数据库参数。更新完成后，CLI 会根据变更自动处理后续事宜。
+
+如果你只是想让 CLI 按当前 env 的最新状态重新同步，直接这样写就行：
+
+```bash
+nb env update
+nb env update prod
+```
+
+如果你要修改这个 env 保存的连接信息或本地配置，可以显式带上参数：
+
+```bash
+nb env update prod --api-base-url https://api.example.com/api
+nb env update prod --access-token <token>
+nb env update dev --app-port 13080 --timezone Asia/Shanghai
+```
+
+这里可以先记住一个默认判断：
+
+- 要修改 env 保存的连接信息或本地配置，用 `nb env update`
+- 应用接口、插件或 CLI 可用能力刚发生变化，也可以再执行一次 `nb env update`
+- 登录态过期了，或者要重新走一遍认证流程，用 `nb env auth`
+- 只是想看当前保存了什么，用 `nb env info`
+
+如果你改的是 `app-port`、`timezone`、`db-*` 这类本地运行配置，`update` 只会改保存值，不会自动重启应用。通常来说后续还要再执行 `nb app restart --env <name>`；如果变更涉及 CLI 托管的内置数据库，则用 `nb app restart --env <name> --with-db`。
+
+## 重新认证
+
+如果 env 已经保存，只是登录态过期了，或者你想切换认证方式，可以重新认证：
+
+```bash
+nb env auth
+nb env auth prod
+nb env auth prod --auth-type oauth
+nb env auth prod --auth-type basic --username admin --password secret
+nb env auth prod --auth-type token --access-token <api-key>
+```
+
+省略环境名时，CLI 会使用当前 env。认证完成后，CLI 会自动处理后续同步。
+
+## 移除环境
+
+如果你只想移除保存的 env 配置：
+
+```bash
+nb env remove staging
+```
+
+如果是本地或 Docker 托管的 env，并且你还想一起清理本机上的运行资源和 storage 数据，可以加上 `--purge`：
+
+```bash
+nb env remove test --purge
+```
+
+在非交互模式下，`nb env remove` 需要显式传入 `--force`：
+
+```bash
+nb env remove test --purge --force
+```
+
+`--purge` 只会清理当前机器上的 CLI 托管资源。对于远程 API env，它不会去删除远端服务本身。
+
+## 相关链接
+
+- [`nb env` 命令参考](../../api/cli/env/index.md)
+- [`nb env update`](../../api/cli/env/update.md)
+- [`nb session` 命令参考](../../api/cli/session/index.md)
+- [管理应用](./manage-app.md)

package/dist/ai/docs/nocobase/quickstart/plugins/third-party.md

@@ -0,0 +1,86 @@
+# 第三方插件安装与升级
+
+如果你拿到的是第三方插件包，通常来说先把它导入目标应用的 `storage/plugins`，然后先重启应用，再继续启用或验证插件是否生效。
+
+## 快速索引
+
+| 我想要…… | 去哪里看 |
+| --- | --- |
+| 先切到目标 env，再开始导入或重启插件 | [先确认目标环境](#先确认目标环境) |
+| 从远程压缩包、本地压缩包或 npm 导入第三方插件 | [用 `nb plugin import` 导入插件包](#用-nb-plugin-import-导入插件包) |
+| 导入完成后让应用重新加载插件目录 | [`nb app restart`](../../api/cli/app/restart.md) |
+| 第一次安装后正式启用插件 | [`nb plugin enable`](../../api/cli/plugin/enable.md) |
+| 想确认插件是否已经出现在当前应用里 | [`nb plugin list`](../../api/cli/plugin/list.md) |
+| 目标机器不能直接联网，只能手动上传 `.tgz` 再导入 | [不能直接联网时](#不能直接联网时) |
+
+## 先确认目标环境
+
+如果你本地管理了多个应用，先切到目标 env 再操作：
+
+```bash
+nb env use app1
+```
+
+## 用 `nb plugin import` 导入插件包
+
+`nb plugin import` 支持三类来源：远程压缩包、本地压缩包、npm 包名。这个命令只负责把插件导入 `storage/plugins`，不会自动启用插件。
+
+如果你已经拿到了插件包下载地址、本地文件路径，或者插件已经发布到 npm，可以执行：
+
+```bash
+# 远程压缩包
+nb plugin import https://github.com/nocobase/plugin-auth-cas/releases/download/v1.4.0/plugin-auth-cas-1.4.0.tgz
+
+# 本地压缩包
+nb plugin import /your/path/plugin-auth-cas-1.4.0.tgz
+
+# npm 包名或 tag
+nb plugin import @my-scope/plugin-auth-cas@beta
+```
+
+如果你用的是私有 npm 源，通常来说先登录，再指定 registry：
+
+```bash
+npm login --registry=https://registry.example.com
+nb plugin import @my-scope/plugin-auth-cas@beta --npm-registry=https://registry.example.com
+```
+
+## 导入之后先重启
+
+导入完成后，先重启目标应用：
+
+```bash
+nb app restart
+```
+
+如果你没有先切换当前 env，也可以在命令里显式传入 `-e <env>`。
+
+## 重启之后再启用或验证
+
+如果这是第一次安装，重启后再启用插件：
+
+```bash
+nb plugin enable @nocobase/plugin-auth-cas
+```
+
+第一次启用时会自动完成安装。
+
+如果插件已经启用，而你这次只是更新压缩包或重新导入一个新版本，通常来说重启完成后就可以继续验证插件是否正常工作，不需要再用 `upgrade` 的做法。
+
+
+## 不能直接联网时
+
+如果目标机器不能直接访问插件下载地址，可以先把 `.tgz` 文件上传到目标机器的任意目录，再在目标机器执行本地导入。
+
+比如：
+
+```bash
+nb plugin import /your/path/plugin-auth-cas-1.4.0.tgz
+nb app restart
+```
+
+:::warning 注意
+
+这里不需要手动解压到 `storage/plugins`。`nb plugin import` 会自动把插件放到正确目录。
+
+:::

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
+```