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

package/dist/ai/docs/nocobase/multi-app/multi-app/sub-app-api.md

@@ -0,0 +1,112 @@
+---
+pkg: '@nocobase/plugin-app-supervisor'
+title: 'Calling sub-app APIs'
+description: 'How to call sub-app APIs in multi-app: access sub-app APIs through the entry app and specify the target sub-app with a path prefix, request header, or query parameter.'
+keywords: 'multi-app,sub-app API,AppSupervisor,entry app,API call,NocoBase'
+---
+
+# Calling sub-app APIs
+
+In a multi-app setup, each sub-app has its own independent APIs. When calling a sub-app API, the entry app needs to know which sub-app the request should be routed to.
+
+For example, a main app API is usually:
+
+```bash
+GET /api/users:list
+```
+
+`/api` is the default API prefix and can be customized with the `API_BASE_PATH` environment variable.
+
+To call the same API in a sub-app, specify the sub-app name in the request.
+
+## Use a path prefix
+
+Use the `/api/__app/<appName>/` prefix to call sub-app APIs:
+
+```bash
+GET /api/__app/a_xxx/users:list
+```
+
+Where:
+
+- `a_xxx` is the sub-app name
+- `users:list` is the resource and action to call
+- `/api` is the current system's API base path
+
+Query parameters can be appended as usual:
+
+```bash
+GET /api/__app/a_xxx/users:list?page=1&pageSize=20
+```
+
+This approach is explicit and works well when sub-app APIs are accessed through the entry app in multi-environment deployments.
+
+## Specify the sub-app with a request header
+
+If the caller already uses a fixed `/api/...` address, specify the sub-app with the `X-App` request header:
+
+```bash
+curl \
+  -H "X-App: a_xxx" \
+  http://localhost:13003/api/users:list
+```
+
+This is suitable for backend service calls, or when a frontend request utility already centralizes API URLs and only needs an additional header.
+
+## Specify the sub-app with a query parameter
+
+You can also specify the sub-app with the `__appName` query parameter:
+
+```bash
+GET /api/users:list?__appName=a_xxx
+```
+
+If there are other query parameters, pass them together:
+
+```bash
+GET /api/users:list?__appName=a_xxx&page=1&pageSize=20
+```
+
+In general, the path prefix or request header is clearer because the target sub-app is more explicit.
+
+## API address in multi-environment deployments
+
+In multi-environment deployments, there is usually an entry app and multiple runtime environments.
+
+For example:
+
+- Entry app address: `http://localhost:13003`
+- Runtime environment address: `http://localhost:14000`
+
+When calling sub-app APIs, it is recommended to access them through the entry app:
+
+```bash
+GET http://localhost:13003/api/__app/a_xxx/users:list
+```
+
+The entry app routes the request to the corresponding sub-app according to the app configuration. If you clearly know which runtime environment to access, you can also call through that environment address.
+
+```bash
+GET http://localhost:14000/api/__app/a_xxx/users:list
+```
+
+## Sub-app custom domains
+
+If a sub-app has its own access domain, you can also call that sub-app's APIs directly through that domain:
+
+```bash
+GET https://app-example.example.com/api/users:list
+```
+
+If you want to go through the entry app uniformly, continue using the entry app's `/api/__app/<appName>/...` address.
+
+## Authentication
+
+When calling sub-app APIs, permission checks are still based on the target sub-app.
+
+This means:
+
+- A sign-in state or access token valid for the sub-app is required
+- The main app sign-in state does not automatically equal API permissions in the sub-app
+
+If the request does not carry valid authentication information, the sub-app returns an unauthenticated or unauthorized error according to its own authentication configuration.

package/dist/ai/docs/nocobase/plugin-development/client/appendix/faq.md

@@ -38,11 +38,11 @@ If client code changes don't hot reload, try refreshing the browser first.
 
 ### Registered page route is not accessible
 
-NocoBase v2 routes automatically add a `/v2` prefix. For example, if you registered `path: '/hello'`, the actual URL is `/v2/hello`:
+NocoBase v2 routes automatically add a `/v` prefix. For example, if you registered `path: '/hello'`, the actual URL is `/v/hello`:
 
 ```ts
 this.router.add('hello', {
-  path: '/hello', // actual URL -> /v2/hello
+  path: '/hello', // actual URL -> /v/hello
   componentLoader: () => import('./pages/HelloPage'),
 });
 ```
@@ -285,7 +285,7 @@ NocoBase's build system maintains an [external list](../../dependency-management
 ## Related Links
 
 - [Plugin](../plugin) — Plugin entry and lifecycle
-- [Router](../router) — Route registration and the `/v2` prefix
+- [Router](../router) — Route registration and the `/v` prefix
 - [FlowEngine Overview](../flow-engine/index.md) — FlowModel basics
 - [FlowEngine - Block Extension](../flow-engine/block) — BlockModel, TableBlockModel, filterCollection
 - [FlowEngine - Field Extension](../flow-engine/field) — FieldModel, bindModelToInterface

package/dist/ai/docs/nocobase/plugin-development/client/component/index.md

@@ -118,7 +118,7 @@ const msg = ctx.t('Save success', { ns: '@my-project/plugin-hello' });
 Use `ctx.router.navigate()` for page navigation:
 
 ```tsx
-ctx.router.navigate('/some-page'); // -> /v2/some-page
+ctx.router.navigate('/some-page'); // -> /v/some-page
 ```
 
 Get current route parameters:

package/dist/ai/docs/nocobase/plugin-development/client/ctx/common-capabilities.md

@@ -316,7 +316,7 @@ Navigate between pages in components via `ctx.router.navigate()`:
 
 ```tsx
 const ctx = useFlowContext();
-ctx.router.navigate('/hello'); // -> /v2/hello
+ctx.router.navigate('/hello'); // -> /v/hello
 ```
 
 ### Route Information (ctx.route)
@@ -351,7 +351,7 @@ interface RouteOptions {
 ```tsx
 const ctx = useFlowContext();
 
-console.log(ctx.location.pathname); // '/v2/hello'
+console.log(ctx.location.pathname); // '/v/hello'
 console.log(ctx.location.search);   // '?page=1'
 console.log(ctx.location.hash);     // '#section'
 ```

package/dist/ai/docs/nocobase/plugin-development/client/ctx/index.md

@@ -85,7 +85,7 @@ async load() {
 ```tsx
 // In component: page navigation
 const ctx = useFlowContext();
-ctx.router.navigate('/hello'); // -> /v2/hello
+ctx.router.navigate('/hello'); // -> /v/hello
 ```
 
 ## Common Capabilities Provided by Context

package/dist/ai/docs/nocobase/plugin-development/client/router.md

@@ -15,7 +15,7 @@ Route registration is typically done in the plugin's `load()` method. See [Plugi
 
 :::warning Note
 
-For NocoBase v2 plugins, registered routes automatically get a `/v2` prefix. You need to include this prefix when accessing the routes.
+For NocoBase v2 plugins, registered routes automatically get a `/v` prefix. You need to include this prefix when accessing the routes.
 
 :::
 
@@ -25,9 +25,9 @@ NocoBase has the following default routes registered:
 
 | Name           | Path                  | Component           | Description               |
 | -------------- | --------------------- | ------------------- | ------------------------- |
-| admin          | /v2/admin/\*          | AdminLayout         | Admin pages               |
-| admin.page     | /v2/admin/:name       | AdminDynamicPage    | Dynamically created pages |
-| admin.settings | /v2/admin/settings/\* | AdminSettingsLayout | Plugin settings pages     |
+| admin          | /v/admin/\*          | AdminLayout         | Admin pages               |
+| admin.page     | /v/admin/:name       | AdminDynamicPage    | Dynamically created pages |
+| admin.settings | /v/admin/settings/\* | AdminSettingsLayout | Plugin settings pages     |
 
 ## Page Routes
 
@@ -55,7 +55,7 @@ class MyPlugin extends Plugin {
   async load() {
     this.router.add('hello', {
       path: '/hello',
-      // Lazy loading: the module is loaded only when /v2/hello is visited
+      // Lazy loading: the module is loaded only when /v/hello is visited
       componentLoader: () => import('./pages/HelloPage'),
     });
   }
@@ -103,12 +103,12 @@ class MyPlugin extends Plugin {
 
     // Child route, using componentLoader for lazy loading
     this.router.add('root.home', {
-      path: '/', // -> /v2/
+      path: '/', // -> /v/
       componentLoader: () => import('./pages/HomePage'),
     });
 
     this.router.add('root.about', {
-      path: '/about', // -> /v2/about
+      path: '/about', // -> /v/about
       componentLoader: () => import('./pages/AboutPage'),
     });
   }
@@ -121,7 +121,7 @@ Route paths support dynamic parameters:
 
 ```tsx
 this.router.add('root.user', {
-  path: '/user/:id', // -> /v2/user/:id
+  path: '/user/:id', // -> /v/user/:id
   componentLoader: () => import('./pages/UserPage'),
 });
 ```
@@ -176,7 +176,7 @@ export class HelloPlugin extends Plugin<any, Application> {
 }
 ```
 
-After registration, the access path is `/admin/settings/hello`. When there is only one page under the menu, the top tab bar is automatically hidden.
+After registration, the access path is `/v/admin/settings/hello`. When there is only one page under the menu, the top tab bar is automatically hidden.
 
 ### Multi-Tab Settings Page
 
@@ -194,7 +194,7 @@ class HelloPlugin extends Plugin<any, Application> {
       icon: 'ApiOutlined',
     });
 
-    // Tab 1: General settings (key 'index' maps to /admin/settings/hello)
+    // Tab 1: General settings (key 'index' maps to /v/admin/settings/hello)
     this.pluginSettingsManager.addPageTabItem({
       menuKey: 'hello',
       key: 'index',
@@ -202,7 +202,7 @@ class HelloPlugin extends Plugin<any, Application> {
       componentLoader: () => import('./settings/GeneralPage'),
     });
 
-    // Tab 2: Advanced settings (maps to /admin/settings/hello/advanced)
+    // Tab 2: Advanced settings (maps to /v/admin/settings/hello/advanced)
     this.pluginSettingsManager.addPageTabItem({
       menuKey: 'hello',
       key: 'advanced',

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

@@ -0,0 +1,27 @@
+# 快速开始
+
+NocoBase 的快速开始主要解决三件事：先把应用装起来，再把插件装起来，最后把应用稳定地跑起来。你不需要一次把所有文档都看完，按你当前所在的阶段往下走就够了。
+
+如果你还没决定用哪种方式安装，默认先看 [使用 CLI 安装（推荐）](./installation/cli.md)。如果你更习惯直接在服务器上用容器跑起来，继续看 [通过 Docker Compose 安装](./installation/docker-compose.md)。
+
+## 快速索引
+
+| 我想要…… | 去哪里看 |
+| --- | --- |
+| 直接安装一个新的 NocoBase 应用 | [使用 CLI 安装（推荐）](./installation/cli.md) |
+| 把旧的安装方式逐步迁移到 CLI | [从旧方式迁移到 CLI](./installation/migration.md) |
+| 用 Docker Compose 在服务器上部署 | [通过 Docker Compose 安装](./installation/docker-compose.md) |
+| 在无法访问公网的环境里安装 | [内网安装](./installation/airgap.md) |
+| 先确认应用运行需要的关键环境变量 | [应用环境变量](./installation/env.md) |
+| 激活商业插件或安装第三方插件 | [商业插件激活与升级](../api/cli/license/index.md) / [第三方插件安装与升级](./plugins/third-party.md) |
+| 给生产环境加上反向代理 | [Nginx](./production/reverse-proxy/nginx.md) / [Caddy](./production/reverse-proxy/caddy.md) |
+| 查看应用、切换环境、备份还原 | [管理应用](./operations/manage-app.md) / [多环境管理](./operations/multi-environment.md) / [备份还原](./operations/backup-restore.md) |
+
+## 默认路径
+
+如果你不确定该怎么选，通常来说按下面这条路径走最省心：
+
+1. 先看 [使用 CLI 安装（推荐）](./installation/cli.md)。
+2. 应用跑起来后，再确认 [应用环境变量](./installation/env.md)。
+3. 如果要正式上线，再补上 [Nginx](./production/reverse-proxy/nginx.md) 或 [Caddy](./production/reverse-proxy/caddy.md)。
+4. 后续日常维护时，再看 [管理应用](./operations/manage-app.md) 和 [备份还原](./operations/backup-restore.md)。

package/dist/ai/docs/nocobase/quickstart/installation/airgap.md

@@ -0,0 +1,67 @@
+# 内网安装
+
+如果你的服务器无法访问公网，安装方式就要提前准备好离线所需的镜像、依赖和插件包。默认推荐先用 Docker 方式，路径最短，也最容易复现。
+
+## 默认推荐：离线准备 Docker 镜像
+
+在一台可以访问公网的机器上，先把应用镜像和数据库镜像拉下来：
+
+```bash
+docker pull registry.cn-shanghai.aliyuncs.com/nocobase/nocobase:latest-full
+docker pull registry.cn-shanghai.aliyuncs.com/nocobase/postgres:16
+```
+
+然后导出为离线文件：
+
+```bash
+docker save -o nocobase-app.tar \
+  registry.cn-shanghai.aliyuncs.com/nocobase/nocobase:latest-full
+
+docker save -o nocobase-postgres.tar \
+  registry.cn-shanghai.aliyuncs.com/nocobase/postgres:16
+```
+
+如果你还需要商业插件，也建议在外网环境先准备好插件包，再一起带入内网。
+
+## 把文件拷贝到内网服务器
+
+至少准备这些文件：
+
+- `nocobase-app.tar`
+- `nocobase-postgres.tar`
+- `docker-compose.yml`
+- `.env` 或你自己的部署说明
+
+## 在内网服务器导入镜像
+
+```bash
+docker load -i nocobase-app.tar
+docker load -i nocobase-postgres.tar
+```
+
+## 启动应用
+
+准备好 `docker-compose.yml` 后，直接启动：
+
+```bash
+docker compose up -d
+docker compose logs -f app
+```
+
+如果你还没写 compose 文件，先看 [通过 Docker Compose 安装](./docker-compose.md)，把里面的示例保存到本地即可。
+
+## 不能使用 Docker 怎么办
+
+如果你的内网环境不能使用 Docker，也可以在外网环境先用 `create-nocobase-app` 创建完整项目、安装依赖并打包，再把整个项目拷贝到内网服务器。
+
+这条路径会更长，不过在没有容器能力的环境里更实用。整体流程通常是：
+
+1. 在外网环境创建项目并安装依赖。
+2. 把项目目录打包。
+3. 拷贝到内网服务器。
+4. 在内网解压、补齐 `.env` 后启动应用。
+
+## 下一步去哪里看
+
+- 如果你还没确认应用配置，继续看 [应用环境变量](./env.md)
+- 如果你准备把应用正式开放给业务用户，继续看 [Nginx](../production/reverse-proxy/nginx.md) 或 [Caddy](../production/reverse-proxy/caddy.md)

package/dist/ai/docs/nocobase/quickstart/installation/cli.md

@@ -0,0 +1,205 @@
+# 使用 CLI 安装（推荐）
+
+NocoBase 2.1.0 之后，官方提供了基于 CLI 的安装和管理方式。你可以用它完成安装、连接、升级和日常维护，也可以顺手给 AI Agent 准备一个可连接、可操作的环境。
+
+## 安装 NocoBase CLI
+
+仅在第一次安装 CLI 时执行。
+
+先全局安装 CLI：
+
+```bash
+npm install -g @nocobase/cli@beta
+nb --version
+```
+
+:::tip 建议先开启 session mode
+
+如果你会同时开多个终端、多个 shell，或者要让 AI Agent 和你自己并行操作，默认推荐先执行一次 [`nb session setup`](../../api/cli/session/setup.md)。这样每个会话都能维护自己的 `current env`，不容易互相影响。
+
+```bash
+nb session setup
+```
+
+:::
+
+如果你打算长期用中文界面，通常来说先把 locale 设好就够了：
+
+```bash
+nb config set locale zh-CN
+```
+
+CLI 默认会检查自更新。你可以按自己的习惯调整更新策略：
+
+- `prompt`：发现新版本时提示
+- `auto`：自动更新
+- `off`：关闭自动更新
+
+```bash
+nb config set update.policy prompt
+nb config set update.policy auto
+nb config set update.policy off
+```
+
+如果你准备把 NocoBase 部署到服务器上，并且希望从远程浏览器打开 `nb init --ui` 向导，建议先把 CLI 的默认 host 改成当前服务器 IP：
+
+```bash
+nb config set default-ui-host <server-ip>
+nb config set default-api-host <server-ip>
+```
+
+将 `<server-ip>` 替换为当前服务器对你可访问的实际 IP。
+
+`nb config` 是 CLI 的全局配置。通常只需要设置一次，后续再次运行 `nb init --ui` 时会自动沿用这些默认值，不需要每次重复配置。
+
+通常来说：
+
+- `default-ui-host` 用于 `nb init --ui` 启动向导页面时的默认监听地址
+- `default-api-host` 用于新安装时默认生成的 API 地址
+
+如果是在服务器上部署，这两个值通常都应该改成当前服务器可访问的 IP，而不是继续使用默认的本机地址。
+
+:::warning 这只是安装向导或临时访问方式，不是生产环境推荐入口
+
+把 `default-ui-host` / `default-api-host` 设成服务器 IP，主要是为了让你能从远程浏览器打开 `nb init --ui`，或者在安装完成后临时验证服务是否可访问。
+
+这不代表生产环境应该长期使用 `IP + port` 对外提供服务。正式部署时，仍然推荐使用域名，并通过 Nginx 或 Caddy 这类反向代理统一接入，再启用 HTTPS。
+
+:::
+
+## 安装 NocoBase
+
+### 方式一：通过 UI 向导安装
+
+这是默认推荐的入口。你只需要运行：
+
+```bash
+nb init --ui
+```
+
+如果你想给向导页面指定一个固定端口，可以直接加上 `--ui-port`，例如：
+
+```bash
+nb init --ui --ui-port 3000
+```
+
+![nb init UI 向导](https://static-docs.nocobase.com/2026-06-03-20-54-01.png)
+
+向导会根据当前场景，带你一步一步完成安装或连接所需的配置。
+
+### 方式二：通过终端交互
+
+如果你更习惯在终端里一步一步输入，可以直接运行：
+
+```bash
+nb init
+```
+
+![2026-06-03-21-36-33](https://static-docs.nocobase.com/2026-06-03-21-36-33.png)
+
+### 方式三：通过非交互命令
+
+如果你在脚本、CI/CD 或其他非交互环境里运行，直接用 `--yes` 就行。这个模式下必须显式传 `--env`，没有显式指定的参数会按默认值处理。
+
+最短的默认写法是：
+
+```bash
+nb init --yes --env app1
+```
+
+具体到不同安装来源、版本选择、`basic` 认证、CI/CD 连接已有应用，以及数据库命名这类常见组合，直接看 [`nb init` 命令参考的示例](../../api/cli/init.md#示例) 就行。
+
+## 安装完成后先确认什么
+
+`--env` 是 CLI 里的环境名。通常来说，安装完成后你接下来做的事都围绕这个 env 展开。
+
+通常建议先确认这 3 件事：
+
+1. env 是否已经创建并保存成功
+2. 应用是否可以正常启动、日志是否正常
+3. 如果准备正式对外开放，是否已经规划好生产环境入口，而不是继续直接使用 `IP + port`
+
+### 安装目录
+
+如果你刚用 `nb init --env app1` 新装了一个本地应用，可以通过 `nb env info app1 --field app.appPath` 查看完整路径。
+
+默认情况下，CLI 会在 `app-path` 下按下面这套约定组织本地文件：
+
+```text
+<app-path>/
+├── source/   # 应用源码或下载内容对应的默认目录
+├── storage/  # 运行时数据目录
+└── .env      # 可选的应用环境变量文件
+```
+
+通常来说：
+
+- `source/` 主要对应 npm / Git env 的本地应用目录。对于 Docker env，CLI 也会保留这套默认路径推导，不过大多数时候你不需要手动关心它
+- `storage/` 用来放运行时数据，比如内置数据库数据、插件、日志等内容
+- `.env` 是可选的应用环境变量文件。只有当你需要自定义环境变量时，才需要在 `<app-path>/.env` 里添加它；如果这个文件存在，Docker、npm 和 Git 这几种安装来源默认都会读取它
+
+更完整的说明见 [`nb init` 命令参考](../../api/cli/init.md)。
+
+### 生产环境部署提醒
+
+如果你现在只是刚装完，想先验证安装结果，那么用 `IP + port` 打开页面通常没有问题。
+
+但如果这个 env 接下来要正式对外提供服务，需要特别注意：
+
+- `nb init --ui` 本身只是安装向导的临时页面，用来完成安装或初始化，不是应用正式对外服务入口
+- 通过 `nb init` 安装完成后，应用当前暴露出来的 `IP + port` 更适合调试阶段、验证阶段或内网临时访问
+- 生产环境不建议直接把 NocoBase 应用端口暴露给公网长期使用
+- 正式对外访问时，推荐使用域名，并通过 Nginx 或 Caddy 反向代理到 NocoBase
+- 生产环境应优先启用 HTTPS，而不是长期使用裸露的 `http://IP:port`
+
+也就是说，`default-ui-host` 和 `default-api-host` 只是为了让安装向导和默认地址生成更方便，并不代表最终生产环境的访问入口。
+
+如果这个 env 准备正式上线，建议把“接入反向代理并启用 HTTPS”视为安装完成后的下一步，而不是可选优化项。
+
+如果你现在就准备继续做正式部署，建议先从 [生产环境部署](../production/index.md) 开始，再按需要继续看 [Nginx](../production/reverse-proxy/nginx.md) 或 [Caddy](../production/reverse-proxy/caddy.md) 的反向代理配置。
+
+### 日常操作
+
+你可以先确认这个 env 是否已经保存成功：
+
+```bash
+nb env current
+nb env list
+nb env status
+nb env info app1
+nb env info app1 --json
+```
+
+如果你想继续做安装后的后续操作，可以按下面这个索引往下看：
+
+| 我想要…… | 去哪里看 |
+| --- | --- |
+| 如果你准备把这个 env 正式对外开放，给它接上生产环境反向代理，并使用域名和 HTTPS 暴露服务。 | [Nginx](../production/reverse-proxy/nginx.md) / [Caddy](../production/reverse-proxy/caddy.md)。 |
+| 确认 env 是否保存成功、查看当前用了哪个 env、在多个 env 之间切换。 | [`nb env`](../../api/cli/env/index.md)、[多环境管理](../operations/multi-environment.md)。 |
+| 启动、停止、重启应用，查看日志，或者继续升级应用。 | [`nb app`](../../api/cli/app/index.md)、[管理应用](../operations/manage-app.md)。 |
+| 检查数据库连接、查看内置数据库状态，或者排查数据库容器问题。 | [`nb db`](../../api/cli/db/index.md)。 |
+| 查看已安装插件，启用或停用插件。 | [`nb plugin`](../../api/cli/plugin/index.md)。 |
+| 激活商业授权、查看授权状态、同步商业插件。 | [`nb license`](../../api/cli/license/index.md)。 |
+| 管理本地源码工程，比如下载源码、启动开发模式、构建或测试。这个通常用于 npm / Git env。 | [`nb source`](../../api/cli/source/index.md)。 |
+
+如果你刚装完一个本地应用，通常可以先跑这几条命令：
+
+```bash
+nb env use app1
+nb app start
+nb app logs
+nb plugin list
+```
+
+如果你同时维护多个 env，后续切换和查看状态的方式见 [多环境管理](../operations/multi-environment.md)。
+
+如果你后续要升级应用，直接看 [管理应用](../operations/manage-app.md) 和 [`nb app upgrade` 命令参考](../../api/cli/app/upgrade.md) 就行。
+
+## 相关链接
+
+- [`nb init` 命令参考](../../api/cli/init.md)
+- [`nb env info` 命令参考](../../api/cli/env/info.md)
+- [生产环境反向代理：Nginx](../production/reverse-proxy/nginx.md) / [Caddy](../production/reverse-proxy/caddy.md)
+- [从旧方式迁移到 CLI](./migration.md)
+- [多环境管理](../operations/multi-environment.md)
+- [管理应用](../operations/manage-app.md)

package/dist/ai/docs/nocobase/quickstart/installation/docker-compose.md

@@ -0,0 +1,123 @@
+# 通过 Docker Compose 安装
+
+如果你希望直接在服务器上把 NocoBase 跑起来，`docker compose` 仍然是最直接的方式。大部分场景用一份 `docker-compose.yml` 就够了。
+
+不过生产环境里，建议固定具体版本号，不要长期直接使用 `latest`。这样升级时更可控。
+
+## 前提条件
+
+- 已安装 Docker 和 Docker Compose
+- 确保 Docker 服务已经启动
+- 已准备好一个要对外开放的端口，比如 `13000`
+
+## 第一步：创建项目目录
+
+```bash
+mkdir my-nocobase-app
+cd my-nocobase-app
+```
+
+## 第二步：创建 `docker-compose.yml`
+
+下面这个示例使用 PostgreSQL，也是默认最省心的一种组合：
+
+```yml
+networks:
+  nocobase:
+    driver: bridge
+
+services:
+  app:
+    image: registry.cn-shanghai.aliyuncs.com/nocobase/nocobase:latest-full
+    restart: always
+    networks:
+      - nocobase
+    depends_on:
+      - postgres
+    environment:
+      - APP_KEY=replace-with-your-secret-key
+      - DB_DIALECT=postgres
+      - DB_HOST=postgres
+      - DB_PORT=5432
+      - DB_DATABASE=nocobase
+      - DB_USER=nocobase
+      - DB_PASSWORD=nocobase
+      - TZ=Asia/Shanghai
+    volumes:
+      - ./storage:/app/nocobase/storage
+    ports:
+      - '13000:80'
+
+  postgres:
+    image: registry.cn-shanghai.aliyuncs.com/nocobase/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
+```
+
+其中：
+
+- `APP_KEY` 记得改成你自己的随机字符串
+- `13000:80` 代表把主机的 `13000` 端口映射到容器的 `80` 端口
+- 如果你已经有数据库服务，可以删掉 `postgres` 这一段，并把 `DB_HOST` 改成现有数据库地址
+
+如果你使用 MySQL 或 MariaDB，记得把 `DB_DIALECT` 改成对应类型，并补上：
+
+```bash
+DB_UNDERSCORED=true
+```
+
+## 第三步：启动应用
+
+```bash
+docker compose up -d
+```
+
+查看日志：
+
+```bash
+docker compose logs -f app
+```
+
+## 第四步：访问应用
+
+应用启动完成后，打开：
+
+```text
+http://<服务器IP>:13000
+```
+
+如果是第一次启动，按页面提示初始化管理员账号即可。
+
+## 常用命令
+
+启动或更新容器：
+
+```bash
+docker compose up -d
+```
+
+停止应用：
+
+```bash
+docker compose down
+```
+
+查看日志：
+
+```bash
+docker compose logs -f app
+```
+
+## 下一步去哪里看
+
+- 如果你要调整密钥、端口、数据库等配置，继续看 [应用环境变量](./env.md)
+- 如果你准备正式上线，继续看 [Nginx](../production/reverse-proxy/nginx.md) 或 [Caddy](../production/reverse-proxy/caddy.md)
+- 如果你后续要备份数据，继续看 [备份还原](../operations/backup-restore.md)